On 5/23/06, Max Bowsher <maxb1@ukf.net> wrote:
> 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.
You're right that there are two separate issues here; but I feel that
(2) is as important as (1) in this case.
Granted, there are advantages and disadvantages both ways. I find
the single file much easier to edit (and don't have navigation problems
-- this may just be a matter of taste), and also easier to remember
URLs in, i.e., "See subversion.tigris.org/design.html#bubble-up",
something that I could say at least once a week to someone :-).
Single-file is much easier to search in, from the browser. That is
probably one reason why both svnbook and (e.g.) my book both
offer a monolithic version as well as a chunked version. And as
far as I know, the *only* reason they offer a chunked version is
to save on load time -- something that's not a factor for design.html,
since it's so much smaller. Were it not for that, I at least would
only offer the monolithic version.
IMHO, part of the problem with the status quo in our design docs is the
XML, but part of it is also the multi-filedness.
The multi-file advantages you listed either do not exist for me or are
not compelling to me; I'm not sure there's much I can say beyond
that. (I don't deny that they are real for you, of course.) One reason
I listed the searchability advantage is that it's fairly objective: it's not
really a matter of taste or navigation style -- there's no browser in
the world that can do a Find-style search across a multi-file document.
That one factor alone is important enough to dominate all the others,
IMHO.
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue May 23 23:38:33 2006