[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] Function prototype comments
Russell Shaw <rjshaw@netspace.net.au> writes:
> How evolving is the docbook standard? Could new things be added like:
>
> <funcprototype>
> <paramdef>char *<parameter>a</parameter>[]</paramdef>/* comment */
> <paramdef>char *<parameter>a</parameter>[]</paramdef><para>/* para
> comment */</para>
> </funcprototype>
New things do still get added. But in this case, if something were
added to Funcprototype for marking up inline comments in
synopsese, it would need to be inline element -- for example,
Lineannotation -- instead of Para or some other block element. So
you might do:
<funcprototype>
<paramdef>char *<parameter>a</parameter>[]</paramdef><lineannotation>/* para comment */</lineannotation>
</funcprototype>
Lineannotation is an existing element in DocBook -
http://docbook.org/tdg/en/html/lineannotation-x.html
I took a quick shot at writing a stylesheet customization layer to
implement support for generating HTML output for Lineannotation in
Funcprototype. It's pasted in below and also at:
http://docbook.sourceforge.net/outgoing/custom-funcprototype.xsl
It seems to work OK in the limited testing I did with it. Please
try it and let me know if it works for you.
Of course you still have the problem of the DocBook DTD not
actually allowing Lineannotation with Funcprototype. So your docs
won't validate against the "standard" DocBook DTD. To work around
that, the easiest thing to do is to use the following DOCTYPE
declaration in all your doc instances (instead of the standard
DocBook DOCTYPE).
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd";[
<!ENTITY % funcprototype.element "IGNORE">
<!ELEMENT funcprototype
(modifier*,funcdef,
(void|varargs|
((paramdef,lineannotation?)+,varargs?)),
modifier*)>
]>
I think docs with Lineannotion within Funcprototype will validate
OK with that.
Anyway, the long-term solution, if you really want to get this
supported in standard DocBook, is to convince the DocBook TC to
add it. The way to get that started is for you to submit a
DocBook RFE here
http://sourceforge.net/tracker/?atid=384107&group_id=21935&func=browse
The DocBook TC would then discuss it during their next (or maybe
next-next) monthly meeting.
--Mike
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version='1.0'>
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
<!-- ==================================================================== -->
<!-- * for Lineannotation in Funcprototype output in synopsis part of -->
<!-- * Funcsynopses in K&R-style output, put a non-breaking space for -->
<!-- * the Lineannotation, then wrap it in a Code section in output. -->
<xsl:template match="funcprototype/lineannotation" mode="kr-funcsynopsis-mode">
<xsl:text> </xsl:text>
<code class="lineannotation">
<xsl:apply-templates/>
</code>
</xsl:template>
<!-- * ignore all other instances of Lineannotation in Funcprototype -->
<xsl:template match="funcprototype/lineannotation" mode="kr-tabular"/> <!-- default -->
<xsl:template match="funcprototype/lineannotation" mode="kr-nontabular"/>
<xsl:template match="funcprototype/lineannotation" mode="ansi-tabular"/>
<xsl:template match="funcprototype/lineannotation" mode="ansi-nontabular"/>
<!-- ==================================================================== -->
<!-- * process Lineannotation in synopsis part of K&R-style -->
<!-- * Funcsynopsis (both tabular and nontabuler -->
<xsl:template match="paramdef" mode="kr-tabular-funcsynopsis-mode"> <!-- default -->
<tr>
<xsl:choose>
<xsl:when test="type and funcparams">
<td>
<xsl:apply-templates select="type" mode="kr-tabular-funcsynopsis-mode"/>
<xsl:text> </xsl:text>
</td>
<td>
<xsl:apply-templates select="type/following-sibling::node()"
mode="kr-tabular-funcsynopsis-mode"/>
</td>
</xsl:when>
<xsl:when test="funcparams">
<td colspan="2">
<xsl:apply-templates mode="kr-tabular-funcsynopsis-mode"/>
</td>
</xsl:when>
<xsl:otherwise>
<td>
<xsl:apply-templates select="parameter/preceding-sibling::node()[not(self::parameter)]"
mode="kr-tabular-funcsynopsis-mode"/>
<xsl:text> </xsl:text>
</td>
<td>
<xsl:apply-templates select="parameter"
mode="kr-tabular"/>
<xsl:apply-templates select="parameter/following-sibling::node()[not(self::parameter)]"
mode="kr-tabular-funcsynopsis-mode"/>
<xsl:text>;</xsl:text>
<xsl:apply-templates select="following-sibling::*[1][self::lineannotation]"
mode="kr-funcsynopsis-mode"/>
</td>
</xsl:otherwise>
</xsl:choose>
</tr>
</xsl:template>
<xsl:template match="paramdef" mode="kr-funcsynopsis-mode">
<xsl:if test="preceding-sibling::paramdef"><br/></xsl:if>
<xsl:apply-templates mode="kr-funcsynopsis-mode"/>
<xsl:text>;</xsl:text>
<xsl:apply-templates select="following-sibling::*[1][self::lineannotation]"
mode="kr-funcsynopsis-mode"/>
</xsl:template>
<!-- ==================================================================== -->
<!-- * prevent Lineannotation from being considered as a sibling when -->
<!-- * trying to determine if this Paramdef is the final child of a -->
<!-- * Funcprotype -->
<xsl:template match="paramdef" mode="kr-nontabular">
<xsl:apply-templates select="parameter" mode="kr-nontabular"/>
<xsl:choose>
<xsl:when test="following-sibling::*[not(self::lineannotation)]">
<xsl:text>, </xsl:text>
</xsl:when>
<xsl:otherwise>
<code>)</code>
<xsl:text>;</xsl:text>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template match="paramdef" mode="kr-tabular">
<td>
<xsl:apply-templates select="parameter" mode="kr-tabular"/>
<xsl:choose>
<xsl:when test="following-sibling::*[not(self::lineannotation)]">
<xsl:text>, </xsl:text>
</xsl:when>
<xsl:otherwise>
<code>)</code>
<xsl:text>;</xsl:text>
</xsl:otherwise>
</xsl:choose>
</td>
<td> </td>
</xsl:template>
<xsl:template match="paramdef" mode="ansi-nontabular">
<xsl:apply-templates mode="ansi-nontabular"/>
<xsl:choose>
<xsl:when test="following-sibling::*[not(self::lineannotation)]">
<xsl:text>, </xsl:text>
</xsl:when>
<xsl:otherwise>
<code>)</code>
<xsl:text>;</xsl:text>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template match="paramdef" mode="ansi-tabular">
<xsl:choose>
<xsl:when test="type and funcparams">
<td>
<xsl:apply-templates select="type" mode="kr-tabular-funcsynopsis-mode"/>
<xsl:text> </xsl:text>
</td>
<td>
<xsl:apply-templates select="type/following-sibling::node()"
mode="kr-tabular-funcsynopsis-mode"/>
</td>
</xsl:when>
<xsl:otherwise>
<td>
<xsl:apply-templates select="parameter/preceding-sibling::node()[not(self::parameter)]"
mode="ansi-tabular"/>
<xsl:text> </xsl:text>
</td>
<td>
<xsl:apply-templates select="parameter"
mode="ansi-tabular"/>
<xsl:apply-templates select="parameter/following-sibling::node()[not(self::parameter)]"
mode="ansi-tabular"/>
<xsl:choose>
<xsl:when test="following-sibling::*[not(self::lineannotation)]">
<xsl:text>, </xsl:text>
</xsl:when>
<xsl:otherwise>
<code>)</code>
<xsl:text>;</xsl:text>
</xsl:otherwise>
</xsl:choose>
</td>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>
--
Michael Smith
http://sideshowbarker.net/
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]