Forum OpenACS Q&A: Re: New package documentation

3: Re: New package documentation (response to 1)

Posted by Lars Pind on 02/24/03 05:58 PM

Still talking just to myself, I find that writing documentation in docbook format distracts way too much from the content, and forces me to put all my effort into the form.

I've found a way out, however, namely W2XML, a thing that can convert Word documents to XML using a specific stylesheet, most notably DocBook.

So now I can use MS Word to write the doc, then convert it to DocBook. Neat. (Thanks, Mark, for the tip.)

Now the problem is that that converter only uses <section> tags, and not the <sect1>, <sect2>, etc., tags, that we tend to use.

Checking the reference at

http://www.docbook.org/tdg/en/html/section.html

it's clear that this should be just as fine. However, using our setup, each section gets the same size header, and the table of contents doesn't work.

Anybody have any idea why that would be and how to fix it?

/Lars

9: Re: New package documentation (response to 3)

Posted by Kurt Martin on 02/25/03 03:44 PM

Greetings,

It is very simple to modify the Docbook XSLT in W@XML to make <sect1> vs <section> tags. Simply modify the XSLT. Changing the section tags to sect1 tags is easy. Simply replace the following:

<xsl:template match="h:div[parent::h:body]">
    <section>
      <xsl:apply-templates />
    </section>
</xsl:template>

With:

<xsl:template match="h:div[parent::h:body]">
    <sect1>
      <xsl:apply-templates />
    </sect1>
</xsl:template>

You may have to add a named style in word to pick up nested "sections", and detect this as a class attribute in the exported XML. For example, if you wanted to capture a style named "Heading4ArialNarrow" as your sect2's, then add the following to the Docbook XSLT:

<xsl:template match="h:p[attribute::class = 'Heading4ArialNarrow']">
    <sect2>
      <xsl:apply-templates />
    </sect2>
</xsl:template>

The standard output from W2XML captures each style name and adds it as a class attribute value. It is easy to capture this and modify however you wish.

HTH