Relationships and related links

[Norman Walsh <ndw@nwalsh.com>]

Hi folks,

I'm still trying to get my head around how relationships in an
assembly and inline relatedlink elements work. Here's my attempt to
work through a simple example. (I've toyed with the syntax here and
there, in an attempt to narrow the focus, sorry if that's a
distraction.)

Let's suppose I have a simple assembly:

<assembly xmlns="http://docbook.org/ns/docbook";>
  <resources>
    <resource xml:id="syntax" fileref="syntax.xml"/>
    <resource xml:id="properties" fileref="properties.xml"
              xpointer="element(reference)"/>
    <resource xml:id="examples" fileref="examples.xml"/>
    <resource xml:id="troubleshooting" fileref="trouble.xml"/>
  </resources>

  <structure xml:id="book" type="book">
    <output format="pdf" renderas="book"/>
    <supplement>
      <info>
        <title>Book Title</title>
      </info>
    </supplement>
    <module resourceref="syntax" renderas="chapter"/>
    <module resourceref="properties" renderas="chapter"/>
    <module resourceref="examples" renderas="chapter"/>
  </structure>

  <relationship xml:id="r1" type="seealso">
    <instance linkend="syntax"/>
    <instance linkend="properties"/>
    <instance linkend="troubleshooting"/>
  </relationship>
</assembly>

Let's further suppose that this is the content of syntax.xml:

<topic xml:id="s.syntax">
<title>Syntax</title>
<para>This paragraph describes the syntax.
<relatedlink targetdoc="examples.xml" targetptr="s.examples" type="seealso"/>
<relatedlink targetdoc="properties.xml" type="seealso"/>
<relatedlink targetdoc="properties.xml" targetptr="reference" type="seealso"/>
</para>
</topic>

And this is the content of properties.xml:

<chapter xml:id="s.properties">
<title>Properties</title>
<para>This paragraph describes the properties.</para>
<section xml:id="reference">
<title>Property Reference</title>
<para>This is the reference.</para>
</section>
</chapter>

And for completeness, here's examples.xml:

<topic xml:id="s.examples">
<title>Examples</title>
<para>This paragraph describes the examples.</para>
</topic>

What is the processor expected to do when it is assembling the book.

1. It builds the assembled document by pulling together all the
modules in the selected structure. (There's only one structure, so
it's selected.)

2. It encounters the first module:

   <module resourceref="syntax" renderas="chapter"/>

This module has a resourceref so it grabs the referenced resource:

   <resource xml:id="syntax" fileref="syntax.xml"/>

3. This resource is (trivially) transformed into a chapter and
inserted into the assembled document.

4. It looks to see if the resource participates in any relationships.

5. It constructs the intersection of the inline relatedlinks that are
the descendants of the resource and any relationships that contain the
resource.

The relatedlinks are

  <relatedlink targetdoc="examples.xml" targetptr="s.examples" type="seealso"/>
  <relatedlink targetdoc="properties.xml" type="seealso"/>
  <relatedlink targetdoc="properties.xml" targetptr="reference" type="seealso"/>

The "r1" relationship points to this resource, so it's included.
It contributes two links (excluding itself):

  <instance linkend="properties"/>
  <instance linkend="troubleshooting"/>

Those point to

  <resource fileref="properties.xml" xpointer="element(reference)"/>
  <resource fileref="trouble.xml"/>

The type of r1 is "seealso", so the union of the relationship
links is:

  <relatedlink targetdoc="examples.xml" targetptr="s.examples" type="seealso"/>
  <relatedlink targetdoc="properties.xml" type="seealso"/>
  <relatedlink targetdoc="properties.xml" targetptr="reference" type="seealso"/>
  <resource fileref="properties.xml" xpointer="element(reference)"/>
  <resource fileref="trouble.xml"/>

and their intersection is

  <relatedlink targetdoc="examples.xml" targetptr="s.examples" type="seealso"/>
  <relatedlink targetdoc="properties.xml" type="seealso"/>
  <resource fileref="properties.xml" xpointer="element(reference)"/>
  <resource fileref="trouble.xml"/>

6. It removes documents that aren't part of this assembly.

  <relatedlink targetdoc="examples.xml" targetptr="s.examples" type="seealso"/>
  <relatedlink targetdoc="properties.xml" type="seealso"/>
  <resource fileref="properties.xml" xpointer="element(reference)"/>

7. It creates some kind of list markup and inserts it as the last child
of the resource.

Is that right?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | One should never make one's debut
http://www.oasis-open.org/docbook/ | with a scandal. One should reserve
Chair, DocBook Technical Committee | that to give interest to one's old
                                   | age.--Oscar Wilde

PGP signature