DocBook macros?

Question

Is there any way of defining macros (like tex macros o latex defines) in DocBook documents?

DocBook is very verbose, and macros would help a lot. I didn't find them in quickstart tutorials.

If so, could anyone provide a simple example or a link to?

Thanks

Answer 1

Not sure, if this is exactly what you want / if it full fills your requirements, but I'm thinking of ENTITYs. You can define them at the top (of your XML document, so general XML, nothing DocBook specific). As seen here for the 'doc.release.number' and 'doc.release.date'. But they can also be included through an separate file. As seen in the 3th ENTITY row. Here the SYSTEM means, comming from another file 'entities.ent'.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

  <!ENTITY  doc.release.number                 "1.0.0.beta-1"       >
  <!ENTITY  doc.release.date                   "April 2010"         >

  <!ENTITY  %   entities  SYSTEM  "entities.ent" >

  %entities;

]>

<!--  This document is based on http://readyset.tigris.org/nonav/templates/userguide.html  -->
<article  lang="en">
  <articleinfo>
    <title>&project.impl.title; - User Manual</title>
    <subtitle></subtitle>
    <date>&project.impl.release.date;</date>
    <copyright>
      <year>doc.release.year</year>
      <holder>Team - &project.impl.title;</holder>
    </copyright>
    <releaseinfo>&doc.release.number;</releaseinfo>
  </articleinfo>

  <section>
    <title>Introduction</title>
    <para>
    The &project.impl.title; has been created to clean up (X)HTML and XML documents as part of 


    </para>
  <section>
</article>

In the document you reference the entities through a starting & and ending ; as in &project.impl.title;

In the file 'entities.ent' you specify the ENTITY elements in a similar way:

<?xml version="1.0" encoding="UTF-8"?>

<!ENTITY  project.impl.title            'Maven Tidy Plug-in'    >
<!ENTITY  project.impl.group-id         'net.sourceforge.docbook-utils.maven-plugin'    >
<!ENTITY  project.impl.artifact-id      'maven-tidy-plugin'     >
<!ENTITY  project.impl.release.number   '1.0.0.beta-1'          >
<!ENTITY  project.impl.release.date     'April 2010'            >
<!ENTITY  project.impl.release.year     '2010'                  >
<!ENTITY  project.impl.url              '../'                   >
<!ENTITY  project.spec.title            ''  >
<!ENTITY  project.spec.release.number   ''  >
<!ENTITY  project.spec.release.date     ''  >
<!ENTITY  doc.release.year              '2010'                  >  

Answer 2

Not exactly what you asked for, but perhaps helpful for some of your cases: you can define templates in your wrapper stylesheet where you define fo commands. Some examples:

Code:

<xsl:template match="symbolchar">
  <fo:inline font-family="Symbol">
    <xsl:choose>
      <xsl:when test=".='ge'">&#x2265;</xsl:when>
      <xsl:when test=".='le'">&#x2264;</xsl:when>
      <xsl:when test=".='sqrt'">&#x221A;</xsl:when>
      <xsl:otherwise>?!?</xsl:otherwise>
    </xsl:choose>
  </fo:inline>
</xsl:template>

Usage:

<symbolchar>le</symbolchar>

Code:

<xsl:template match="processing-instruction('linebreak')">
  <fo:block/>
</xsl:template>

Usage:

<?linebreak?>

Answer 3

Have you considered generating DocBook from another format (like reStructuredText?)

I found it quite nice for documentation.

Also, you could probably write a macro preprocessor (or look into m4) pretty quickly. If you are using the XML version of DocBook, a simple XSLT will do. Just make up some tags and transform them. Have boilerplate stuff added automatically. And get ready to be really angry at XSLT. For not being all it could be. For making your thinking warp.