RE: cygwin faq ready for presentation review.

["Harold Hunt" <huntharo at msu dot edu>]

> None of them discuss why they have the layout they have - thus they are
> not relevant except as examples of one style of layout.

They are perfectly relevant to me.  DocBook, as you said, is designed for
customization, yet several project with many more members than our own chose
to refrain from customization, or they customized but did not include site
navigation.

> Why XSL? I've already addressed this - "Why XSL? The XSL support was a
> critical step. The DSSSL/SGML stylesheets are at end of life. They will
> be deprecated in docbook 5.0 (the next release). The XML/DSSSL variant
> produced non-validatable HTML. However XML with XSL is working very
> nicely."

Right, and you seemed to have missed my point: the Linux Documentation
Project has not yet switched to XSL.  Producing valid HTML, as decreed by
http://w3.org is not the utmost goal of documentation.  Here are several
supporting examples of documentation that are not "valid" HTML:
http://www.linuxdoc.org/FAQ/Linux-FAQ/index.html
http://www.linuxdoc.org/FAQ/Linux-RAID-FAQ/index.html
http://www.linuxdoc.org/HOWTO/PPP-HOWTO/index.html
http://www.linuxdoc.org/LDP/LDP-Author-Guide/index.html
http://gnome.org/faqs/users-faq/index.html
http://gnome.org/faqs/gnome-foundation-faq/index.html

You know, it will be nice when some DocBook processor produces "valid" HTML,
but I'm not going to switch to an immature toolset for solely that reason.
HTML validation just isn't that important.

> Why a customisation driver for the stylesheets? There are three reasons.
> One is that the docbook stylesheets are a lowest common denominator.
> They are not intended to be use unmodified, except for the simplest
> projects.

Not intended to be used unmodified?  Right, and we use modifications,
namely, IIRC, the Cygnus modifications that produce the output in files
named after the section ids.

> The second reason is that there are bugs in the stylesheets,
> and until those bugs are rolled back into the next stable release, and
> we upgrade to that release, there is a need for bug-fixing drivers. The
> easiest way is to put those customisations in driver files, not in the
> main stylesheets - this is due to the Docbook design. The only changes
> that have been made to the actual docbook stylesheets are to add hooks
> for pre and post navigation content insertion.

Once again, I don't seem HTML validation as a big problem, and I don't like
having extraneous navigation information when I am reading a long document.

Furthermore, changes were not restricted to pre and post navigation content
insertion.  I can see, at first sight, the following changes:
1) Titles are centered, they used to be left justified
2) Blockquotes have the citation in the blockquote, rather than one line
above it
3) <quote> has been changed from " to '
4) The font has changed
5) <tip> and <note> are no longer inline, rather they are segmented by a
centered title heading larger than a faq division heading
6) Bibliography markup is incorrect.  Every division of information in the
biblio is marked with a period, rather than commas for the major divisions
and a colon for the title-subtitle division
7) Revision history is in a table with borders rather than an unadorned
table

In short, the XSL stylesheets are either not finished, or they have been
extensively overridden.

> Thirdly we already have a
> look and feel for the website, established by Suhaib and tweaked a bit
> by me. It works. It's similar to other projects, and should be easy to
> read and navigate. Having part of the _website_ switch to a different
> look and feel is bad practice from a user design point of view. It's
> inconsistent. It also means that folk who link straight into the faq (ie
> because they did a google search) will have to guess at where the rest
> of the website is. And frankly, losting 2cm of screen space - 150
> pixels - is hardly an issue on the smallest of desktop screens.

Of course, having one format (HTML) of a document being entirely different
than the other formats (PDF, PS, RTF, DVI, etc.) is perfectly acceptable.

> In respect to 1) - don't worry I'm not offended - there are two angles.
> One of the angles is that you don't know my background, and may well be
> worrying needlessly. The second angle is this is a project being done
> for the community. IMO that means that "everyone" needs to buy into the
> result before it gets implemented. This is not a minor change. So you
> have the opportunity to compare the resulting web pages to content
> presentation guidelines and best practice recommendations, and we can
> work together to get it right.

Right, and I don't by into the result.  I have stated several times that I
want to stick with the standard stylesheets.  I don't have time to "compare
the resulting web pages to content presentation guidelines and best practive
recommendations".  I have essentially put my trust in respect to those
issues in DocBook and that's the last I want to have to think about it.

> I think this is a moot point due to the reasons I've presented above.
> This project is currently focused on the presentation stage, and on
> delivering a minimal change to the website. AFAICT each LDP document is
> built from it's own source, and they are not in a book set. That makes
> building a surroinding stylesheet more challenging. And they have a lot
> of doco! We are a green field in this sense, and able to set direction
> more easily. We are able to have different stylesheets for different
> targets, and that is appropriate (Ie website vs home reference vs man
> page vs pdf). Lastly, you are not creating the stylesheet. I am. You are
> welcome to critique it, and point out it's problems, but I have no
> expectation that other folk will jump in to develop it. Once it's done,
> I do expect that changes will be on a "scratch your own itch" basis.

Requests of the author as to how his/her documentation should be presented
are not moot points.

> The second angle is this is a project being done
> for the community. IMO that means that "everyone" needs to buy into the
> result before it gets implemented.

If the intention is really to wait until "everyone" agrees, then the changes
to the stylesheet had better be very sparse (with the 7 points above
addressed) and there had better not be a navigation bar, otherwise, I'm
going to be a stick in the mud on this one.  I love standard DocBook markup,
as do all my friends (which makes this important to me), as it is simple,
unadorned, non-flashy, and unencumbered by non-essential information.

Harold