Karl Fogel wrote:
> Our main design doc is currently in doc/design/*.xml. It consists of
> multiple XML files that compile (via the usual DocBook compilation
> process) to HTML, PDF, etc.
>
> I would like to convert it to a single HTML file, www/design.html. I
> believe that almost everyone reads it as HTML anyway, and that it
> would be both more maintainable and more easily referable-into as a
> single HTML file. In fact, I already have converted it, and
> www/design.html is sitting in my working copy. (I had content changes
> to make, and felt impeded by the current format and compilation
> process, so I pushed stack and did the conversion first.)
>
> I have not committed the conversion, because maxb prefers that the
> doc remain multifile XML. We had a long discussion in IRC about it
> (involving also madan, davidjames, rooneg, and malcomr). Max and I
> did not persuade each other, but I promised him I'd post here before
> committing the conversion.
>
> Below is the IRC transcript. I believe it lays out all the arguments
> on both sides. Comments welcome. If no one comments, I will go with
> the apparent majority in IRC and commit the conversion (maxb I hope
> agrees that that's a fair approach). Note that my content changes are
> *not* in this commit; they would of course be a separate commit --
> this first commit would just be the straight conversion.
I'd like to emphasize that there are two separate conversions involved here:
1) XML -> HTML
2) multi-file -> monolithic single file
Regarding the first, I acquiesce to consensus, if there's no-one else
who'd prefer to stay DocBook.
Regarding the second, I feel strongly that multi-file documents are
easier to read, since the navigation through the logical structure of
the document is more clearly defined, rather than depending solely on
the scroll position. I find that in single-file book-like documents,
there is a strong feel of the material being in one single chunk: huge
and daunting to find what you need.
Max.
Received on Tue May 23 21:43:44 2006