[PATCH libX11 1/2] nls: restructure charts as a single article with sections

[Gaetan Nadon]

On Tue, 2011-07-26 at 18:21 -0700, Alan Coopersmith wrote:

> On 07/17/11 09:01, Gaetan Nadon wrote:
> > Looks more like a real article with a toc rather than individual
> > web pages. Looks nicer in pdf.
> > 
> > Each locale is a "section" rather than an "article".
> > Using XInclude to aggregate xml source files gets you the toc for free.
> > 
> > The single document is over 600 pages while there were 62 separate
> > documents previously. FOP version 1.0 is required to handle missing
> > character like capital sharp s.
> 
> Is a 600 page document harder for users to handle, since generally they
> just want to know the ones for their locale, not every locale?

There is no difference that I can see for the end user of installed
docs. There is a toc and they click on the locale they want. The
underlying plumbing is changed, the appearance is more consistent with
other docs and we can olink. Maybe I don't see what you mean, but read
on as I have a suggestion to improve on it.

> 
> (Though with all the cross linking between locales, maybe we'll get it
>  down to just en_US.UTF-8 and then a few variants on it someday.)
> 

While playing around with css styling and analyzing several book
structures, it looks to me the larger ones should be chunked html. This
would bring the best of both worlds. We would have olinks from/to
locales docs (with a properly formed docbook) and discrete html files
which allows for  better navigation in the browser.

Same goes for libX11 (500 pages). I found having hundreds of unindented
pages of text much harder to read than a book. The show stopper so far
was that having both a single and a chunked version did not allow other
docs to olink as it cannot have a dual target. The solution is to simply
offer either single or chunked html but not both. It looks like we have
a small number of large docs and a large number of small ones.

The docbook guide uses chunked html and seems much easier to consult:
http://www.sagehill.net/docbookxsl/Rootid.html
The key here is easy navigation in the browser rather than discrete
files which is an implementation detail.

Another method to make large documents easier to read is to number the
sub sections as in Apache:
http://uima.apache.org/d/uimaj-2.3.1/overview_and_setup.html#ugr.project_overview

I'll experiment with chunking as it is a bit more complicated to install
and clean the output format and the target dbs for olinks. 

Thanks for your feedback. After the wholesale docs conversion, we are at
the stage where we can make more enlightened choices on a case by case
basis.



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.x.org/archives/xorg-devel/attachments/20110727/a007b05b/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
URL: <http://lists.x.org/archives/xorg-devel/attachments/20110727/a007b05b/attachment-0001.pgp>