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: RE: [docbook-apps] interested in feedback on my current strategy for writing manuals

My only suggestion is to try to remove steps (1) and (3).  I don't see any
reason why you can't go from 

directly to


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

can probably be re-written as
    <xsl:template match="chapter/section">
     <fo:block break-after="page">&#160;</fo:block>

to be able to go directly from DocBook to FO.

Once you've gotten that far, there's a Saxon extension (if you're using
Saxon, otherwise disregard) called 'next-in-chain' that allows you to chain
stylesheets such that the output of one stylesheet (your Pidgen -> DocBook
stylesheet) becomes the input of another stylesheet (Docbook -> FO).  This
would effectively collapse out another step.  If you then configure FOP to
use Saxon as the XSLT processor and pass source XML and XSLT to FOP instead
of FO, you could possibly cut this all the way down to one step.

> -----Original Message-----
> From: Robert P. J. Day [mailto:rpjday@mindspring.com]
> Sent: Monday, May 19, 2003 3:13 PM
> To: docbook apps list
> Subject: [docbook-apps] 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
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: 
> docbook-apps-help@lists.oasis-open.org

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