Re: [docbook-apps] (long) thoughts on creating a publishing infrastructure

["Juan R. Migoya" <jmigoya@telefonica.net>]

Hello Robert and all in the list:

Robert P. J. Day wrote: (only relevant sections here)

>* 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).
>  
>
I have done this, following differents approaches:

Usually, for a manual with chapters (and apendix and the like) I put all 
the stuff in subdirectories
below the "manual main subdirectory". As I write the chapters, I can 
test them from the main
subdirectoy whit a test.xml document wich bassically does nothing but 
import the chapter using the
ENTITY mechanism.
For the whole manual I build a main xml document in the main manual 
subdirectoy, that uses ENTITY
to define the chapters, apendix,  etc. to be included (and read form 
their own subdirectory). So, this
main document rarelly has some content, just &entities;.
For the graphics: I put them in the correspondent subdirectoy and make a 
link to it in the form
of fileref=chapter_subdirectoy/graphic_filename.
In can use the same graphics in diferents chapters, just using this 
fileref with the aproppiate
chapter_subdirectoy.

This is not an strict procedure. Sometimes, a section has a heavy 
content and I do prefer to
maintain it in a separate file (I think it is easier to maintain a large 
part of the manual keeping it
separately). In this case, my main doc will appear something like this:

&chapter1;
&chapter2;
<chapter>
    <title>Some title</title>
    &sect31;
    &sect32;
    &sect33;
</chapter>
&chapter4;
.....
Obviously, &sect31...etc should be sections. You cannot play much more 
here :(

Now, if you need to reuse this information for several manuals (as I 
do), you can
put those reusable parts in some docbook structure that will fit you 
needs in order
to put them wherever you want. Doing so, you are forced to adapt your 
main document
to allow for such estructure. For example, perhaps you need to replace 
&sect32; with
the following:
    <section>
       <title>Section title</tile>
       &NotReusable1;
       &Reusable;
       &NotReusable2;
    </section>

In this case, each entity should fit inside a section tag (in this 
example is section).
My experience is that for well localized parts this is not very 
troublesome. In fact, you
rarely need to modify the main document.

Another approach I have taken with documents sharing a lot of 
information is by means
of a "condition" atribute. For example, you could have "Linux Security" 
and  "Linux Network Administration"
as a one manual made up from subdirectories. Now you only want the 
"Linux Security" manual.
I put a condition="onlysecurity" in the parts relating to the "Linux 
Security" part, and condition ="onlyNetwork"
in the parts relating to the "network administration" part. Then I use a 
parameter in the command line
cond="onlysecurity". My stylesheet check for the existence of this 
parameter. If it doesn't exist,
all the manual is rendered. If this parameter does exist, only those 
parts with condition=<valueofparameter>
and those which don't have this atribute at all, are rendered. (of 
course, the condition atribute
is applied to all the childrens).
This way you can have:
    A large manual with security included.
    A manual only about security
    A manual only about network.
It is obvious that this method only has sense if those parts are 
interlaced, ie. there are some parts
that must be included in both manuals. Wouldn't be this way, you could 
use just diferents main docs
for them.

I have worked with documentations with very diferents structures, and 
normally I needed some
type of dedicated solution. For some of them, I use Perl extensivelly.

This is just my experience (I beg your perdon if not very well 
explained). I have little hope
that it can be of some use to the expertise people I found in this list, 
but
<emphasis>I hope</emphasis> I will learn a lot of from your commentaries.

Thanks in advance and regards,
Juan R. Migoya
Spain