* One big file or lots of little files?
Given the variety of manuals to be written, an obvious approach
is to store one manual per DocBook XML file, or perhaps even one
chapter per file (really modular) and store the files across several
subdirectories.
However, there's also the possibility of storing sets of manuals
in one humongous single text file. The reason for this is that I've
set up the emacs editor to edit a manual using emacs' "outline"
mode, where I can expand and collapse chapters and sections quickly,
and it's convenient to be able to move around an entire manual
quickly this way, which also allows easy cut/copy/paste of information
across sections, chapters and perhaps manuals.
But there's a bigger issue in deciding how to store the actual
DocBook XML.
* Creating modular manuals (the big issue)
For flexibility, rather than create a fixed outline of topics for
the manuals, we'd like to write chapters and/or sections independently,
and be able to custom-build a manual by just grabbing the chapters or
sections we want and including them in a new manual. This gives us the
flexibility to custom-build a manual for any individual client. (This
will obviously require careful design to make sure such a manual still
seems to flow smoothly, but that's another issue and is not related
to the publishing infrastructure.)
This naturally suggests keeping chapters in individual files and
including them through ENTITYs -- pretty simple -- but as I've already
said, it's really appealing to keep the manuals in one big file to
allow convenient editing (cut and paste).
* Issues related to modular manuals
Given that we're going to go with a modular style of manual
publishing, we have to design the infrastructure to allow a manual
to be created that still follows the original intended design
(bunch of top-level chapters, containing sections and so on).
So what's the catch here?
Regardless of how we choose to store the "building blocks" of
future manuals, they have to be includable in any hierarchy and
still match the general output format. That is, depending on how
we include a topic, in one manual it might represent a chapter;
in another manual, it might just be a section of a larger chapter.
And chapter and section structure should still be correct.
As an example, if we write a module on the Reiser filesystem,
in one manual, it might represent an entire chapter and show up
that way in the final PDF.
In another manual, it might just be a section in a larger chapter
on journalling filesystems. And it should show up properly there as
as a section in that larger chapter. You get the idea.
And if we choose to store all of these "modules" in a single
text file, the only reasonable way to extract any of these modules
would seem to be to give each one a unique ID and pull them out
based on that (which seems fairly easy).