[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"> </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]