This is the mail archive of the
docbook-apps@lists.oasis-open.org
mailing list .
[docbook-apps] interested in feedback on my current strategy for writing manuals
- From: "Robert P. J. Day" <rpjday at mindspring dot com>
- To: docbook apps list <docbook-apps at lists dot oasis-open dot org>
- Date: Mon, 19 May 2003 15:12:51 -0400 (EDT)
- 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"> </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