documentation cleanup

Tue Sep 16 09:52:01 CDT 2003

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.

-- 
Francois Gouget         fgouget at free.fr        http://fgouget.free.fr/
                     f u kn rd ts, ur wy 2 gky 4 ur wn gd.