<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 TRANSITIONAL//EN"> <HTML> <HEAD> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=UTF-8"> <META NAME="GENERATOR" CONTENT="GtkHTML/3.32.2"> </HEAD> <BODY> On Tue, 2011-07-26 at 18:21 -0700, Alan Coopersmith wrote: <BLOCKQUOTE TYPE=CITE> <PRE> 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? </PRE> </BLOCKQUOTE> 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. <BLOCKQUOTE TYPE=CITE> <PRE> (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.) </PRE> </BLOCKQUOTE> 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: <A HREF="http://www.sagehill.net/docbookxsl/Rootid.html">http://www.sagehill.net/docbookxsl/Rootid.html</A> 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: <A HREF="http://uima.apache.org/d/uimaj-2.3.1/overview_and_setup.html#ugr.project_overview">http://uima.apache.org/d/uimaj-2.3.1/overview_and_setup.html#ugr.project_overview</A> 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. </BODY> </HTML>