Re: CSS in the User's Guide (was:Updating dll info...)

[Robert Collins <rbcollins at cygwin dot com>]

On Fri, 2002-08-23 at 23:00, Joshua Daniel Franklin wrote:

> Lately I have been exploring some options to 
> make the documentation more accessible. I'd rather not give details since they
> could be misinterpreted about what will be happening in the near future
> (by anyone reading this list, not you specifically). 

I'd be interested in hearing about this - off list if necessary. I've
used docbook a reasonable amount, in both commercial and open source
contexts - I may be able to help. There are folk more experienced than
me here too...
 
> I believe I mentioned before that I realize the HTML produced is ugly (not in
> the browser, the code). 

The HTML is both ugly and not HTML conformant. (It doesn't adhere to
it's stated DTD). Getting SGML docbook to adhere to the HTML DTD is a
non-trivial exercise. XML Docbook however, can generate HTML or XHTML
trivially via the xslt stylesheets, and that works nicely. This only has
an impact on rendering if you have standards compliant browsers - which
we are starting to get :}.

> The CLASS tags exist in the DocBook source and are used to
> decide what type of HTML to turn it into. For example, use <tt> for FILENAME,
> <b> for COMMAND, etc. 

A technical nit: The docbook 'tags' become HTML class 'attributes'. (Not
CLASS tags). (<foo /> is a tag called foo. <foo bar="value"> is foo with
an attribute 'bar'). 

> At the present time, there is no reason these tags should
> be left in the HTML since they are not used. However, I don't feel that it
> would be worth the effort at the present time to figure out how to either:

Actually can be used by anyone that wants to -> they should be left
there. An obvious example: User foo has a user defined stylesheet to
format web pages. foo will get a fully structured and stylised UG.
Removing the tags will thus hurt foo.
 
> 1) remove them
> 2) do something with them

Ah, this is easy. First off, visit http://nwalsh.com. 
Secondly read http://www.docbook.org/tdg/en/html/docbook.html
(Not all at once!). The core to grok is this:
SGML->DSSSL Stylesheet=HTML content.
HTML content->CSS (in user browser) = presentation.

So, all you need to do to use the class attributes is to create a CSS1
(Not CSS2, to hard to get compatible browsers) stylesheet that makes the
changes you want. You need to link this in on every page, with via the
HTTP Link: header (I'm not sure if IE supports this), or via a META tag.
See http://www.w3.org/TR/html4/present/styles.html#h-14.3.2 for more
details. The stylesheet classes to tweak are those whose appearance you
dont like. A review of CSS1 would also help you - you can do a huge
amount very very easily once you've done that.

Frankly, the UG presentation looks fine to me. It's readable, and thats
the key thing. It'd be nice if it validated against a HTML DTD, but that
would be asking you to put a lot of effort in for fairly unexciting
results. (I can offer guidance if you *want* to put that effort in).

What could be done easly is to create pdf and plain text or even
postscript output from docbook (this can all be done in cygwin with the
authoring tools now available). 

Rob

Attachment: signature.asc
Description: This is a digitally signed message part