[TOS] textbook: referential integrity

Karsten Wade kwade at redhat.com
Fri Mar 19 05:33:50 UTC 2010


On Fri, Mar 19, 2010 at 12:43:01AM -0400, Greg DeKoenigsberg wrote:
> 
> Karsten, I see that you've stripped out the section numbers in the svn 
> chapter.  Which is fine, since hand-coding section numbers that way is 
> probably horrible.
> 
> What's our mechanism, though, to ensure internal referential integrity? 
> When we want to refer in the text to "exercise 3.2.2" or "figure 5.4.1", 
> how do we do that?

There is DocBook magic for that.

First, use a consistent structure that doesn't presume the person can
see, e.g. "for blah foo refer to [unique title]".  The unique title
part doesn't have to be as accurate as the refer to, because we'll be
searching the XML for "refer to".

At each "refer to" we'll replace the link with <xref
linkend="Section_unique_ID">.  Publican has as specific format for the
unique ID of a section, which is based on the section title, e.g.:

A link to chapter "Building the Code" section "Exercise - Building
your developer workstation" becomes:

<section id="sn_Building_the_Code_Exercises_-_Building_your_developer_workstation">
<title>Exercise - Building your developer workstation</title>
...
</section>

And when you call it, looks like this:

<para>
... then refer to <xref
linkend="sn_Building_the_Code_Exercises_-_Building_your_developer_workstation"/>.\
</para>

It looks nastier than it is.  If you manage to get the unique title
correct, we can do search and replace in all locations, to make it a
bit faster.  There aren't more than a few dozen cross links that I
recall seeing, nor many more required.

- Karsten
-- 
name:  Karsten 'quaid' Wade, Sr. Community Gardener
team:                Red Hat Community Architecture 
uri:               http://TheOpenSourceWay.org/wiki
gpg:                                       AD0E0C41
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://teachingopensource.org/pipermail/tos/attachments/20100318/a7256bcf/attachment.asc>


More information about the tos mailing list