cygwin faq ready for presentation review.

Robert Collins robert.collins@itdomain.com.au
Tue May 29 15:57:00 GMT 2001


----- Original Message -----
From: "Harold Hunt" <huntharo@msu.edu>
To: "cygx" <cygwin-xfree@cygwin.com>
Sent: Wednesday, May 30, 2001 2:55 AM
Subject: RE: cygwin faq ready for presentation review.


> > To be honest.. I dislike having the index (Cygwin home,
Cygwin/xfree86
> > home, development.. ) to the left (right too) of a long text.. it
> > steals margin - if you scroll down a bit you have a white left
> > margin..
>
> I'm with Andrew on this.  When you are reading a long document, you
are
> reading a long document.  You are not navigating a web site.  I've
gotten
> this opinion from reading the FAQs of other projects:
> http://www.kde.org/documentation/faq/index.html
> http://i18n.kde.org/teams/en/FAQ.html
> http://gnome.org/faqs/users-faq/
> http://cygwin.com/faq/
> http://www.xfree86.org/FAQ/

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 may not be
happy about that themselves!. Counter examples exist with navigation of
one sort or another. IMO the fact that all those projects have the exact
same layout is due to them all using docbook :].  That's not a bad
thing, but customising stylesheets isn't something that you do just
because you want to. However: docbook is _designed_ for customisation.

> As far as XSL processing versus DSSSL, I have to believe that the
Linux
> Documentation Project ( http://www.linuxdoc.org/ ) would be using XSL if
it
> were stable; however, the LDP is still using DSSSL.  If we really want
to
> use a modified stylesheet I think we should consider using the LDP
> stylesheet, rather than rolling our own.

XSL vs DSSSL is not the same question as customised vs uncustomised.
I'll answer both points separately.

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

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

We can easily create non-encapsulated versions, for local use and for
downloading, in the future. However today, my first goal is to replace
the current html authoring system for the FAQ with something that will
allow marked up authoring, auto number of questions etc, which Docbook
does well, and then we can get onto reviewing the draft content you have
created.

> Creating a stylesheet for documentation is not something to be taken
> lightly, there are all sorts of issues and conventions involved that
we mere
> mortals cannot grasp.

I'm not sure what you are saying here. Are you saying 1) "Rob, you don't
know enough to make a stylesheet that doesn't break document authoring
conventions" or are you saying 2)"Custom appearance is bad, there are
too many things that can go wrong so lets look homogenous?".

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.

In respent to 2) - I disagree very strongly with this sentiment.
Authoring systems are _designed_ to separate content from presentation.
Taking the stance that the default presentation is "just fine" _removes_
the whole benefit of separating the content. The reason the content is
separated is to allow the type of thing I am doing here. Presentation
and content are very important to get right, and play a large part in
the public appearance of a project. In that context, writing a
stylesheet is absolutely the correct thing to do.

> I really want to stick with either the default DocBook stylesheet
using
> DSSSL, the LDP stylesheet (which appears to only be available as
DSSSL), or
> the stylesheet from some other reputable documentation project.  I do
not
> want to be creating our own stylesheet.

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.

Rob

>
> Harold
>
>



More information about the Cygwin-xfree mailing list