[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: (long) thoughts on creating a publishing infrastructure
[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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]