Re: cygwin faq ready for presentation review.

["Robert Collins" <robert dot collins at itdomain dot com dot au>]

----- Original Message -----
From: "Harold Hunt" <huntharo@msu.edu>

> > 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

Invalid HTML does not render properly cross platform. In some cases it
does not  render at all. (I.E. netscape with a broken css stylesheet
link). Documentation is meant to be usable and readable. Valid HTML is
needed for reliable parsing by user tools - ie for the visually impaired
with text->speech.

> 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.

I disagree. I will noit back any documentation system for the xfree86
website that cannot produce valid HTML.
===
If it's HTML, then I believe we follow the spec. If we don't want HTML,
thats fine. We can produce text or pdf files and have those available
for download.
===

> > 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.

Uhmm, actually that chunk naming behaviour is part of the standard
docbook stylesheet - theres a parameter that activates that behaviour.
And that we use a driver stylesheet (website.dsl for the DSSSL
processor) _is my point_.

> > 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.

I didn't menation HTML validation there. The content I'm inserting can
be done on the DSSSL stylesheets as well. The issues are orthogonal.

Also, navigation is not extraneous. This is part of the website. I agree
that a copy for a user on their PC would not need navigation.

> Furthermore, changes were not restricted to pre and post navigation
content
> insertion.  I can see, at first sight, the following changes:

By changes to the stylesheet, I mean edits to stylesheets/docbookxsl/*,
not driver files, the xfree86 web site stylesheet or the default
differences between the XSL and DSSSL stylesheets.

> 1) Titles are centered, they used to be left justified

xfree86.css.

> 2) Blockquotes have the citation in the blockquote, rather than one
line
> above it

I changed the xml file here, not the stylesheet. I've emailed the
docbook-apps list as this is a bug in the stylesheet (both DSSSL and
XSL) IMO.

> 3) <quote> has been changed from " to '

Not a change I introduced.

> 4) The font has changed

xfree86.css

> 5) <tip> and <note> are no longer inline, rather they are segmented by
a
> centered title heading larger than a faq division heading

I'm not sure where you're referring to. But the cause is likely to be
one of - xfree86.css, or the difference between the DSSSL and XSL
stylesheets.

> 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

I don't know where the fault is coming from, but I'd guess that this is
an XSL bug.

> 7) Revision history is in a table with borders rather than an
unadorned
> table

Again, this is likely a XSL stylesheets defaults issue.

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

If you check the source, you will see that the amount of overriding is
minimal.

> > 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.

Exactly.

> > 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.

So don't think about it. Let me/Suhaib/David if he's got time 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.

Maybe I've miscommunicated in the past? You are offering content for the
xfree86 website. Thats good. You are also saying "The current layout is
wrong". It should "default docbook". Thats a separate question. Please
choose which question you are addressing.

Secondly, The reason I want to avoid _content_ discussion is that
achieving the current standard of presentation is a precursor to
updating the content from a new source format.

Have you heard of egoless programming? If not I suggest you read up on
it.

Lastly, Harold, if you publish a book, the publisher dictates most of
the presentation, and even overrides a large chunk of the content. Thats
called editing.

> > 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.

That sounds like a gauntlet being thrown. If I have been
confrontational, I apologise. I'm trying to be very clear about where I
am coming from, and what I'm trying to achieve. I'm not interested in
picking up that gauntlet.

->If you sit back and look at the situation, I think you'll see that
what you've just said translates as "You may have a FAQ now, but if you
want a new one you have to throw out the site layout or not use my
content".
Answer: I'm not interested in throwing out the site content. I'm happy
to address all the processing concerns: the missing Contents, the broken
links, the stuffed up xrefs and so on to produce an environment that
keeps everything together, nice and neat and will let contributors such
as yourself easily add content.

There is no timeframe on this. Ultimatums are not necessary. I've not
ever got out and said "This has to be in place next week", nor IIRC has
anyone else.

Harold, If you raise the concerns, clearly, and point to how it should
be, I think you'll find that most of the concerns _I agree with_. Some I
won't.

For example: the font is the xfree86 web site font. And they _are not_
going to be different.
-->I will consider changing the font across the whole website.
2nd example: The xfree86 website has a navigation bar. The FAQ will have
a navigation bar that is consistent and fits in.
--> I will consider moving the navigation bar to a page title style bar,
rather than a left hand side.

In a nutshell: The contribution is welcomed, I'm doing what I can to
make it acceptable. I'm not going to get up and critique the default
docbook output, because you can easily look at how different the
standard docbook output is to the current FAQ.

Rob



>
> Harold
>
>