[TOS] textbook: referential integrity

Greg DeKoenigsberg gdk at redhat.com
Fri Mar 19 05:44:11 UTC 2010

On Thu, 18 Mar 2010, Karsten Wade wrote:

> 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.

I thought I recalled something like this, so thanks.  :)


Educational materials should be high-quality, collaborative, and free.
Visit http://opensource.com/education and join the conversation.

More information about the tos mailing list