documentation cleanup

[Dimitrie O. Paun]

OK,

This should explain a bit more what I meant to say with this
silly .dsl files. First, use the standard ones when building
HTML and PS. This means that the docu will be build with
the user's L&F which is the right thing to do IMO. If we don't
do that, we might as well give up on SGML, it creates problems
for no benefits.

Once this patch is applied, we can:
  -- move default.dsl and print.dsl into the tools/ module
     where they belong (and where make_winehq needs them)
  -- remove make_winehq from our documentation dir,
     as it's been made obsolete by tools/make_winehq

This should result in no change as how we build the documentation.

BTW, this patch does not conflict with Francois' patch, in
that his changes can be applied to default.dsl before we
move it to tools/.

ChangeLog
    Dimitrie O. Paun 
    Do not force our presentation for the users who want to
    build their documentation.

Index: documentation/Makefile.in
===================================================================
RCS file: /var/cvs/wine/documentation/Makefile.in,v
retrieving revision 1.32
diff -u -r1.32 Makefile.in
--- documentation/Makefile.in	23 Jun 2003 19:51:21 -0000	1.32
+++ documentation/Makefile.in	12 Sep 2003 15:44:44 -0000
@@ -87,10 +87,10 @@
 .SUFFIXES: .sgml /index.html .pdf .ps

.sgml/index.html:
-	$(DB2HTML) -d $(SRCDIR)/default.dsl -o $* $<
+	$(DB2HTML) -o $* $<

.sgml.pdf:
-	$(DB2PDF) -d $(SRCDIR)/print.dsl $< >/dev/null
+	$(DB2PDF) $< >/dev/null

.sgml.ps:
    $(DB2PS) $< >/dev/null

[Alexandre Julliard]

"Dimitrie O. Paun"  writes:
> Once this patch is applied, we can:
>   -- move default.dsl and print.dsl into the tools/ module
>      where they belong (and where make_winehq needs them)
>   -- remove make_winehq from our documentation dir,
>      as it's been made obsolete by tools/make_winehq
>
> This should result in no change as how we build the documentation.

Well, it will change the documentation I generate when making a
release. It may not be a big deal, but I'm not sure it's worth the
trouble. Or you will need to tell me how I should configure my system
to still use the correct dsl files by default...

[Dimitrie O. Paun]

On Mon, 15 Sep 2003, Alexandre Julliard wrote:
> Well, it will change the documentation I generate when making a
> release. It may not be a big deal, but I'm not sure it's worth the
> trouble. Or you will need to tell me how I should configure my system
> to still use the correct dsl files by default...

Right, it's a bit more convoluted than I thought. Ohhh, I hate these
SGML tools! I'll look into it, they have so many catalongs and
indirections going on, that there's got to be a way to do it :)

[Francois Gouget]

On Mon, 15 Sep 2003, Alexandre Julliard wrote:
> "Dimitrie O. Paun"  writes:
> > Once this patch is applied, we can:
> >   -- move default.dsl and print.dsl into the tools/ module
> >      where they belong (and where make_winehq needs them)
> >   -- remove make_winehq from our documentation dir,
> >      as it's been made obsolete by tools/make_winehq
> >
> > This should result in no change as how we build the documentation.
>
> Well, it will change the documentation I generate when making a
> release. It may not be a big deal, but I'm not sure it's worth the
> trouble. Or you will need to tell me how I should configure my system
> to still use the correct dsl files by default...

I guess this means you like the current format better than the default
db2html/db2ps output. In that case it's probably best to just keep
default.dsl and print.dsl in the Wine CVS.

We can still delete winehq.dsl and make_winehq from the Wine CVS though.
I notice that you did not apply my patches to use CSS or cleanup
default.dsl. Any particular reason?

[Alexandre Julliard]

Francois Gouget  writes:
> I guess this means you like the current format better than the default
> db2html/db2ps output. In that case it's probably best to just keep
> default.dsl and print.dsl in the Wine CVS.

print.dsl doesn't seem to have much effect on my machine so I guess we
could remove it. default.dsl is needed at least to have reasonable
file names.
> We can still delete winehq.dsl and make_winehq from the Wine CVS though.
> I notice that you did not apply my patches to use CSS or cleanup
> default.dsl. Any particular reason?

I applied the cleanup one I think. I frankly don't see any reason for
the CSS one.

[Francois Gouget]

On Mon, 15 Sep 2003, Alexandre Julliard wrote:
[...]
> print.dsl doesn't seem to have much effect on my machine so I guess we
> could remove it.

Maybe you just compared the PostScript files? Our Makefile does not use
print.dsl for generating the PostScript files which I think is a bug!

print.dsl has the following effect:
 1. show only two section in the table of content
 2. don't print the section numbers for level 3 items
 3. removes the list of tables
 4. removes the section numbers (so section titles are "Overview/About"
not "1.1. Overview/About")
 5. less spacing after titles and between paragraphs
 6. change title (or paragraph) indentation

When actually used, the effect is the same on PostScript files and on
the PDF ones.

Part of the effect of print.dsl is to make the documentation use fewer
pages (67 pages for wine-user instead of 85). There are only two
settings I would object to: 2 and 4. Removing the section number makes
it harder to find the relevant section in the documentation.

[...]
> I applied the cleanup one I think.

Sorry, I see that now. I had missed the CVS commit.
> I frankly don't see any reason for the CSS one.

Currently we generate HTL code that looks like this:

<BODY CLASS="CHAPTER" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#a50d0d"
VLINK="#505050" ALINK="#a50d0d">
and
<TABLE BORDER="0" BGCOLOR="#E0D0D0" WIDTH="100%">

In other words we hard-code the link, table and body colors. This
overrides any settings that the user may have and can be changed only by
regenerating the files from the SGML source.

IMO this is wrong because:
 * it overrides the user settings

* it's not flexible, users cannot change the presentation

* we already have all we need in the generated HTML code to let CSS set
the look

* it's not extensible and maintainable. We already specify some colors
so why not specify that FAQ questions should be in bold and have a
separator just before them. IMHO this would makes the FAQ much more
readable. But I have no idea how to do that from the dsl file, the DSL
documentation is complex and unclear, and nobody in the Wine community
seems to know how to tweak the DSL file. In comparison, it's pretty
easy to understand how CSS files work, and for the above example all
we need is the following line:
  .question { border-top: dashed thin; font-weight: bolder; }

* the DSL file is not meant to be used to hard-code colors and stuff
like that in the generated HTML

So we have three options before us:
 1. keep the current situation
    -> ugly hacks in default.dsl

2. remove the 'hard-code color hacks' from default.dsl
    -> we lose the color customization

3. remove the 'hard-code color hacks' from default.dsl and reference a
winedoc.css file
    -> preserves the current look
    -> the doc look becomes more flexible and maintainable

I'd be happy with either 2 or 3.

[Alexandre Julliard]

Francois Gouget  writes:
> Maybe you just compared the PostScript files? Our Makefile does not use
> print.dsl for generating the PostScript files which I think is a bug!

No I checked the pdf, all I could see was some spacing differences. I
don't think it's a big problem.
> So we have three options before us:
> -
>
> keep the current situation
> -> ugly hacks in default.dsl
> -
>
> remove the 'hard-code color hacks' from default.dsl
> -> we lose the color customization
> -
>
> remove the 'hard-code color hacks' from default.dsl and reference a
>
> winedoc.css file
>     -> preserves the current look
>     -> the doc look becomes more flexible and maintainable
>
> I'd be happy with either 2 or 3.

I'm happy with 1. It works, and the doc looks good enough. I haven't
ever heard anybody complain about not being able to change the colors
of the html, I don't think that's an issue at all. As for the ugliness
of default.dsl, IMO the whole docbook stuff is one big ugly mess, so
that's lost in the noise <g>

[Steven Edwards]

This is semi-offtopic but it would be nice if we could get WINE, ReactOS 
and Mingw to use the same docbook format and tools. There are parts of the 
WINE docs such as the regression test stuff that would be off use to us and 
other stuff in mingw. What do you guys think about a move to a common system 
for after wine 1.0?

Thanks
Steven

--- Alexandre Julliard  wrote:
> I'm happy with 1. It works, and the doc looks good enough. I haven't
> ever heard anybody complain about not being able to change the colors
> of the html, I don't think that's an issue at all. As for the ugliness
> of default.dsl, IMO the whole docbook stuff is one big ugly mess, so
> that's lost in the noise <g>

__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free, easy-to-use web site design software
http://sitebuilder.yahoo.com