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

[Bob Stayton <bobs at sco dot com>]

Have you looked at using XIncludes instead of entities?
If you use an XInclude processor that handles the XPointer
syntax (like xsltproc), XIncludes could solve your problem of
turning a <chapter> module into a <section>.

For example, you write a module that looks like this:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>
<chapter id="mychapter">
<title >My Module Title</title>
<para>This module does ...</para>
...
</chapter>

Then your master book document could pull its content
into a section container, excluding the <chapter> container:

...
<section id="mysection">
<xi:include  href="mymodule.xml#xpointer(/chapter/*)"  
             xmlns:xi="http://www.w3.org/2001/XInclude"; />
</section>
...

The resolved document (in memory) is then:

...
<section id="mysection">
<title >My Module Title</title>
<para>This module does ...</para>
...
</section>
...


With the XPointer syntax in XIncludes, you could pick
whole modules or any addressable part of a module
to include in a book.  And each module could be
a document that could be validated and edited
with any XML editing tool.  Entities can't
be validated because they can't have a DOCTYPE.


Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com

On Sat, Aug 30, 2003 at 05:42:34AM -0400, Robert P. J. Day wrote:
> 
>   [NOTE: i wrote up the following for a couple colleagues as we're 
> debating setting up a publishing infrastructure for a collection of
> manuals.  So I thought I'd dump it out here, and see if anyone has
> gone through something like this and wants to add any advice or offer
> any guidance.  If you've gone through something like this, I'd
> be happy to hear from you.]
> 
> 
> * The goal
> 
>     The goal is to write a sizable number of courseware manuals
>   all related to Linux/open source/security/programming.  These
>   manuals will be written using standard DocBook, and will be used
>   along with some stylesheet customizations to generate the final
>   PDF output that will be bound and used by the students.
> 
>     A small sample of the upcoming manuals:
> 
>       Fundamentals of Linux
>       Basic Linux System Administration
>       Advanced Linux Workshop
>       Linux Security
>       Linux Network Administration
> 
>       Programming in Perl
>       Programming in POSIX Shell
> 
>   and so on.  As you can see, there will be "groups" of closely-
>   related manuals, which may affect how the writing and publishing
>   is done.
>   
>     The rest of this proposal will discuss more specific requirements
>   for the manuals and how we'll build the entire writing/publishing
>   "infrastructure" to make designing, writing and producing the manuals
>   as easy and as flexible as possible.
> 
>     In addition to generating the PDF output, it would be nice if the
>   same DocBook content could be used, with alternate stylesheets, to
>   generate HTML outlines for the web page, PDF course outlines for the
>   brochure, and so on, but that's a lower priority for now.
> 
> * The manual output format
> 
>     The manuals themselves won't be overly fancy.  They should
>   all start with:
> 
>      - title page
>      - boilerplate book info (legalnotice, copyright, author info
>        and so on)
>      - ToC
> 
>     After that, every manual will consist of a number of <chapter>s,
>   containing sections, subsections and so on.  DocBook markup will
>   be fairly straightforward --  simple paragraphs, inline markup, 
>   lists, lots of <screen>s and <programlisting>s, and <imageobject>s 
>   (mostly PNGs).  And that's about it -- nothing fancy.
> 
> * 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).
> 
> * Final thoughts
> 
>     I'm sure there's plenty I'm forgetting, but you can see the
>   basic requirements.
> 
>     Thoughts?
> 
> 
> rday
> 
> 
> To unsubscribe from this list, send a post to docbook-apps-unsubscribe@lists.oasis-open.org.
> 
> 

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com

To unsubscribe from this list, send a post to docbook-apps-unsubscribe@lists.oasis-open.org.