Re: [docbook-apps] customize <exmaple> to use the attribute of label as caption

Hi Sherwood,

This is certainly possible, but not as simple as it 
might be.

 

Without any customization, the label attribute in 
DocBook can be used to override just the number, not the entire "Example 3: Blah 
Blah".  So you could set label="Listing 1", and the result would be 
"Example Listing 1: Blah Blah", which is probably not what you 
want.

 

Normally I would suggest using example with a role 
attribute to distinguish your two kinds of examples:

 

   <example><title>A regular 
example</title>

 

or

 

   <example 
role="listing"><title>A programlisting</title>

 

Then you would customize templates to select one or 
the other kind of example:

 

    match="example[@role = 
'listing']"

 

or

 

    match="example[not(@role) or 
@role != 'listing']"

 

The problem is that in the DocBook stylesheets, the 
number and title can appear in more places than just the title on the 
example.  For example, if you turn on a List of Examples in the Table of 
Contents, or if you cross reference to an example.  This means there are 
several templates that would need customization to distinguish between the two 
kinds of example elements.  You are also creating a separate numbering 
scheme, so those numbers have to be kept separate as well.   Another 
complication is that the word "Example" is generated text, and so it is handled 
by the templates that handle localized text.

 

I might suggest a simpler approach if you don't 
want to get into all that.  You could instead put a <lineannotation> 
element at the start of your programlisting, and customize a template to handle 
that.

 

<programlisting><lineannotation 
role="listingtitle">PHP Program Code</lineannotation># First line of 
code

...

</programlisting>

 

With this approach, you don't get into the Example 
templates at all, so you can avoid all those complications.  You can simply 
define a template that formats the title the way you want, including generating 
a count.  Something like this:

 

<xsl:template match="lineannotation[@role = 
'listingtitle']">
  <fo:block 
xsl:use-attribute-sets="listing.title.properties">
    
<xsl:text>Listing </xsl:text>
    <xsl:number 
count="lineannotation[@role = 'listingtitle']" 
level="any"/>
    <xsl:text>: 
</xsl:text>
    <xsl:apply-templates/>
  
</fo:block>
</xsl:template>

 

<xsl:attribute-set 
name="listing.title.properties">
  <xsl:attribute 
name="font-family"><xsl:value-of
      
select="$title.fontset"/></xsl:attribute>
  <xsl:attribute 
name="font-size">12pt</xsl:attribute>
  <xsl:attribute 
name="font-weight">bold</xsl:attribute>
  <xsl:attribute 
name="space-after">6pt</xsl:attribute>
</xsl:attribute-set>

 

Some caveats: If you want to cross reference to 
such programlisting elements, then you'll need to do more.  If you 
translate your content, then you won't want to hardcode "Listing" in the 
stylesheet.  And then, if you do syntax highlighting or automatic line 
numbering in your programlistings, all bets are off.  8^)

 

Bob Stayton
Sagehill Enterprises


 

 

  
----- Original Message ----- 

  
From: 
  Sherwood 
  Hu 

  
To:  
  

  
Sent: Thursday, August 20, 2009 2:41 
  PM

  
Subject: [docbook-apps] customize 
  <exmaple> to use the attribute of label as caption

  

  

  
Hi,

  
 

  
We publish technical articles which often contain blocks of 
  source code. We are currently using <programlisting> for the source 
  code. 

  
<programlisting>

  
…

  
</programlisting>

  
 

  
Now we want to add a title (with auto numbering) like 
  Listing 1. Imagedisplay.php. I looked at docbook documentation, and the 
  closest tag I can find is <example>

  
 

  
<example><title>…</title><programlisting>..</programlisting>

  
 

  
The problem is that it displays Example. We can go into the 
  XSL to change all of them to Listing, but doing this will conflict with 
  existing <example> block. 

  
 

  
I noticed that <example> has an attribute of label. 
  So is it possible to change the caption of example to the value of label 
  attribute? 

  
 

  
I just started to learn XSLT. Thanks.