[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-apps] (long) thoughts on creating a publishing infrastructure
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> §31; §32; §33; </chapter> &chapter4; ..... Obviously, §31...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 §32; 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]