Re: Custom tags in Docbook

[Stephane Bortzmeyer <bortzmeyer@nic.fr>]

On Tue, Jan 22, 2008 at 12:30:41AM +0000,
 Oscar Pereira <oscar.pereira@anubisnetworks.com> wrote 
 a message of 32 lines which said:

> I have some experience using LaTeX, and one of the first things you
> learn is how to define commands for specific things

I have a similar prior experience with LaTeX and my advice would be to
forget LaTeX, which has a quite different model. If you try to do
LaTeX in DocBook, you will be disappointed.

> Making the transition from commands to tags,

The correct word is "element" or "element names".

> I was hoping there would some equally simpler way of defining tags
> that could be applied to custom classes of data.

Unfortunately, there is no generic way to make "macros" in XML. I
regret it.

> This way, instead of writing <emphasis>search</emphasis>, I would
> like to write something like <guibutton>search</guibutton>.

It typically involves a custom schema. Let me explain an example from
what I do at work. I often need to refer to RFC
(http://www.rfc-editor.org/) so I want a custom element such as <rfc
num="4084"/>.

I create a custom schema (using DTD but, if you start now, it may be
more sensible to use RelaxNG), defining an empty <rfc> element with a
"num" attribute:

<!ELEMENT rfc EMPTY>
<!ATTLIST rfc num CDATA #IMPLIED>

<!ENTITY % local.para.char.mix
        "|rfc">

That way, <rfc> elements are accepted in paragraphs ( | is "or"). I
can validate.

Now, to render this element (which is obviously ignored by standard
stylesheets), I write XSLT code like this one (for HTML rendition):

<xsl:template match="rfc">
    <xsl:variable name="href">
      <xsl:text>http://www.ietf.org/rfc/rfc</xsl:text><xsl:value-of select="@num"/><xsl:text>.txt</xsl:text>
    </xsl:variable>
     <a href="{$href}"><xsl:text>RFC </xsl:text><xsl:value-of
        select="@num"/><xsl:text></xsl:text></a><xsl:if
        test="not(preceding::rfc)"> (RFC signifie Request For
        Comments. Ce sont les textes fondamentaux de
        l'Internet. Toutes les normes Internet sont des RFC, l'inverse
        n'est pas forcément vrai. Tous les RFC sont
        librement disponibles en ligne sur le <a
        href="http://www.ietf.org/";>serveur de l'IETF</a>, l'organisme
        qui les édite. Plus de détails sont accessibles sur le <a
        href="http://www.rfc-editor.org/";>serveur de l'éditeur des RFC</a>.)</xsl:if>
</xsl:template>

or DSSSL code like:

(element rfc
  (let (
        (num (attribute-string "num"))
        )
    (if num
          (literal (string-append
                    "RFC "
                    num
                    ))
          (literal "RFC UNKNOWN")
    )))

Integrating this in your tools depend on the tools you use (and it is
off-topic for this list, you should move to docbook-apps) so I keep it
for a further message.