OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: interested in feedback on my current strategy for writing manuals


 
  after much agonizing about the most effective way to enter hundreds of 
pages of docbook, i've decided to just do it with vi or emacs, and design
some pre-processor steps to make my life simple, so i'm interested in what
the experts here think, and whether i'm making life far too complicated.

  basically, i've designed a list of "pidgin" docbook elements and a
pseudo-identity transform to turn that into real docbook.  as an
example, i want to be able to type:

<p>this is a new para blah blah
 <il>           # for <itemizedlist>
  <e>....</e>   # what i'm calling list "elements"
  <e>....</e>
 </il>
</p>

you get the idea -- it makes typing fairly quick, but in order to support
this and turn my pidgin stuff into PDF, i've designed *four* (gack!)
transformation steps.

1) the first transformation is to transform pre-pidgin into pidgin.
   for example, i can define <e> to really mean <li><p> (for 
   <listitem><para>, so i can write lists as

   <il>
    <e>elt1</e>
    <e>elt2</e>
   </il>

   and the first pseudo-identity transform will turn this into

   <il>
    <li><p>elt1</p></li>
    <li><p>elt2</p></li>
   </il>

   in short, compressed pidgin to normal pidgin.  note that i can't really
   validate against a DTD since there *is* no such DTD, and i'm way too 
   lazy to write one, so i just count on the fact that i don't make any
   typing mistakes, but when it's this simple, it's not hard to see 
   errors.

2) once that's done, the next step is to transform pidgin to real docbook,
   so i use a stylesheet which maps things like:

   il -> itemizedlist
   ol -> orderedlist
   p -> para

   you get the idea.  pidgin goes in, real docbook comes out.  note that i 
   *still* can't validate the input, but that's ok -- if the original
   input was valid, it's really difficult to generate invalid docbook 
   here.

3) the third transform will take real docbook and "massage" it to add
   some formatting.  here's a  template to take *this* docbook
   and produce customized docbook:

   <xsl:template match="chapter/section">
    <xsl:element name="beginpage"/>
    <xsl:element name="section">
     <xsl:apply-templates/>
    </xsl:element>
   </xsl:template>

   so, just docbook -> docbook, but i get to start customizing what i want
   certain elements to look like.  *and* this is the first place i can 
   actually validate against the docbook DTD, if i want.  which brings us
   to the final transform:

4) docbook -> FO, where i apply a bunch of FO stylesheet fragments to take
   the output from 3) and generate the FO.   for instance, i can define 
   the <beginpage> element in terms of the FO output:

   <xsl:template match="beginpage">
    <fo:block break-after="page">&#160;</fo:block>
   </xsl:template>

5) FO -> PDF, using FOP.


  originally, i was a bit overwhelmed with how many steps this took, but
thinking about it, each step really is doing something different from the
others, and the final result is that i can write in a text editor really
incredibly quickly.

  so, i'm open to feedback.  is there something that already does 
something like this i could have used?  always looking to make my life
simpler.


rday





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]