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

["Robert P. J. Day" <rpjday at mindspring dot com>]

  [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.