notes from DocBook linking meeting

["Bob Stayton" <bobs@sagehill.net>]

These are my notes from the separate meeting we
had to discuss linking in modular DocBook.



Modular DocBook Linking meeting notes
--------------------------------------
15 December 2009
Bob Stayton
bobs@sagehill.net


The meeting focused on related links for modular
DocBook.

Related links can be indicated in the source
content or in an assembly.

Any relatedlink that does not resolve at build
time is ignored.  One option that was discussed
prior to this meeting was adding an attribute
that indicates a relatedlink is required and
so it generates an error message if it is not
resolved.

A relatedlink element in source content is either
inline or in info.  Stylistically it should
not be part of a sentence as it may disappear
in output.

A relatedlink in an assembly is expressed in
the relationships element. The relationships
element can express many kinds of relationships,
of which relatedlinks is one.  In the end,
we did not settle the markup for relatedlinks
in relationships.

During the assembly process, related links are
collected from the assembly's relationships
element and from relatedlink elements in the
source content.  They are grouped, sorted,
uniqued, and formatted.

Norm suggested that the assembly process be
responsible for omitting unresolved links,
so that the stylesheet just has to format
working links.

It is up to the formatting stylesheet to express
the relatedlinks in output.  This could be done
at the end of each HTML chunk, for example,
or at the end of each section within a chunk.

As for markup, an inline relatedlink element
is empty.  That means its linking text must be
generated by the output stylesheet.

A relatedlink element allows these attributes:

  targetdoc targetptr xlink:href endterm
  xrefstyle

When linking to a target contained in the
current structure, a relatedlink can have just
a targetptr, whose value is the xml:id of the
target element.  Note that targetptr is of type
CDATA, not IDREF.

When linking to a DocBook source target outside
the current structure, a relatedlink must also
have a targetdoc attribute similar to olink.

When linking to an external URL, the relatedlink
would instead have an xlink:href attribute.
For the generated link text, an optional linkend
attribute could provide text other than the url.

An olink database can be specified in an
assembly by adding a resource element whose
fileref points to an olink database file.
We discussed the possibility of adding a type
attribute to resource, but it may not be needed
for this purpose.

A structure element designates which resource(s)
to use for olinking.  We did not settle the
markup for that, as it does not seem to be an
<output> or a <module>.  A new element would
be better than an attribute if multiple values
with possible qualifiers must be managed.
With this feature, a type attribute on the
resource element may not be needed for the olink
database resource.

We ran out of time when we were discussing how a
relationship element can express a related link
in a manner similar to the relatedlink element
so that they can be merged at build time.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net