Re: DOCBOOK: Alternatives to CalloutList

[Bob Stayton <bobs at caldera dot com>]

On Wed, Mar 13, 2002 at 09:40:41AM -0800, Jason Diamond wrote:
> Hi, I'm working on an article where I have programlisting elements
> interleaved with para elements where the paragraphs describe various
> constructs in the preceding listing. I thought that using callouts would
> help me refer to specific lines within the listings to help make things more
> clear for the reader so I started experimenting with programlistingco. It
> looks like, however, that you can only refer to a callout from within a
> calloutlist which gets rendered like a table. I'd rather refer the callouts
> inline in my paragraphs (like referencing a footnote).
> 
> The only "solution" that I could come up with was to omit the calloutlist
> from my programlistingco and use inlinegraphic elements in my paragraphs to
> render the image of the number of the line I'm referring to. But this smells
> too much like HTML. Is there a better way to do this? I tried looking for
> something like a coref or colink that could be included anywhere in a
> paragraph but wasn't successful in finding one.

Not a current solution, but the DocBook Technical Committee
voted to adopt a new coref element to do exactly what you
want.  It was approved in Nov 2001, and will be in the
final Docbook 4.2 DTD, which is currently only in beta1
(and not even included there yet).  Stylesheet support probably
won't come until after the DTD is released, so you can't
use this yet.

So Jirka's solution of using an xref element pointing to
the id of the <co> element will automatically generate the
proper bug in your callout reference text.  

In another upcoming change, I updated the XSL template for
<co> in CVS so that if it has a linkends attribute with one
idref value, then the <co> bug becomes a hot link to
that id.  That provides the two-way linking that is
described in The Definitive Guide for callouts, but
was not yet implemented in XSL.  The limitation to one
idref value is simply that HTML doesn't support
multi-targeted links.  This new feature will still work
with your <xref>-style callout references if the
xref element has the id.

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com