[vox-tech] docbook question

[Micah Cowan]

On Tue, Jan 15, 2002 at 06:52:48PM -0800, Peter Jay Salzman wrote:
> how do i reference a previous section in a docbook document?
> 
> 
> <sect1><title>A lesson in logic</title>
> 
> 	<para> ish bibleo outen doten baba ba deeten datten.  hin dickey
> 	wah-wah. </para>
> 
> </sect1>
> 
> 
> 
> <sect1><title>How to apply logic</title>
> 
> 	<para> In section ??? we learned a lesson in logic.  In this section
> 	we learn how to apply logic. </para>
> 
> </sect1>
> 
> 
> 
> how do i make a reference to the first section from the second section?
> 
> pete

Well, I very much prefer <section> to <sect1> or <sect2>, because you
can nest it as deeply as you want (that's been supported since DocBook
3.x - we're at 4.x now, and if you don't have <section> you really
oughta upgrade).

Anyway, you just make sure that you fill in the id attribute for the
section (or figure or example) in question:

  <section id="my-section">
  </section>

And then refer to it using <xref>:

  In section <xref linkend="my-section"/>

The trailing '/' is of course for XML docs - if you're using SGML, the
"recommended practice" is to add a space before that '/', but I still
get parse errors from SGML parsers in that case, so you'd do best to
simply remove it.  If you are using SGML but plan on switching to XML
(I switched only recently - using Apache's Xalan and FOP processors to
convert DocBook to PDF docs.  Unfortunately Norman Walsh's XSLT
stylesheets suck worse than his DSSSL ones), leave 'em in and write a
sed/awk/perl script to remove 'em for ya.

In recent versions of DocBook, you also have the <link> element, which
will produce hyperlinks for you:

  <link linkend="my-section">Click here for more info</link>

HTH,
Micah