Mailing-List: contact cygwin-help AT cygwin DOT com; run by ezmlm
Sender: cygwin-owner AT cygwin DOT com
Mail-Followup-To: cygwin AT cygwin DOT com
Subject: Re: CSS in the User's Guide (was:Updating dll info...)
From: Robert Collins <rbcollins AT cygwin DOT com>
To: Joshua Daniel Franklin <joshuadfranklin AT yahoo DOT com>
Cc: cygwin AT cygwin DOT com
In-Reply-To: <20020823130030.56368.qmail@web20009.mail.yahoo.com>
References: <20020823130030 DOT 56368 DOT qmail AT web20009 DOT mail DOT yahoo DOT com>
Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature";
	boundary="=-02YaCZ7VKKK4RH5CYQaE"
Date: 24 Aug 2002 01:08:04 +1000
Message-Id: <1030115284.8462.78.camel@lifelesswks>
Mime-Version: 1.0

--=-02YaCZ7VKKK4RH5CYQaE
Content-Type: text/plain
Content-Transfer-Encoding: quoted-printable

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

> Lately I have been exploring some options to=20
> 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).=20

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...
=20
> I believe I mentioned before that I realize the HTML produced is ugly (no=
t in
> the browser, the code).=20

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 FILEN=
AME,
> <b> for COMMAND, etc.=20

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

> 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 i=
t
> 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.
=20
> 1) remove them
> 2) do something with them

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

Rob


--=-02YaCZ7VKKK4RH5CYQaE
Content-Type: application/pgp-signature; name=signature.asc
Content-Description: This is a digitally signed message part

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)

iD8DBQA9Zk/TI5+kQ8LJcoIRAuwXAJ91+I2NENtZp0nthznZ43beqbHa5ACeIdPV
2MeXHZQU4DKOO+6aNBS2Imo=
=XMVo
-----END PGP SIGNATURE-----

--=-02YaCZ7VKKK4RH5CYQaE--