RE: [docbook-tc] Link relationships

["Gershon Joseph (gerjosep)" <gerjosep@cisco.com>]

Hi Norm,

If I'm going to localize my content, I'd hate to have something like
this:
 
  <para>There are chapters<relatedlink linkend="db.chapter"/> and
  appendixes<relatedlink linkend="db.appendix"/> in a book.</para>

It's going to complicate the translation process and add to the cost,
because the <relatedlink> elements are treated as new segments, breaking
up the sentence into incomplete components that can't be translated in
isolation. If I'm going to mark up my related links in the topic, I'd
rather put them at the beginning or end of the <para> element, like so:

  <para>There are chapters and
  appendixes in a book.<relatedlink linkend="db.chapter"/><relatedlink
linkend="db.appendix"/></para>

This lets the sentence be translated (or matched if in the translation
memory) and the relatedlink elements are ignored (presumably the
translator would be told not to localize them).

<aside>Inline index terms should go at the beginning of the paragraph,
since they generate page location markers and usually you want to
reference the beginning of the paragraph in case the paragraph breaks
over two pages. This is not relevant for related links.</aside>

I agree with you that you want to aggregate all related links that apply
to a chunk of output together -- it makes no difference whether they are
marked up at the topic or assembly level, they should be combined in the
rendered deliverable. Note that they are combined per rendered chunk. In
other words, if I have 3 topics that I'm chunking together into a single
HTML page, all related links that pertain to these 3 topics should be
rendered at the bottom of the HTML page. So any sorting, grouping, and
so forth that may be done to the related links needs to happen at the
point in the processing where it makes sense, not at the point they are
marked up in the source XML code.

--
Gershon

-----Original Message-----
From: Norman Walsh [mailto:ndw@nwalsh.com] 
Sent: Sunday, December 13, 2009 9:15 PM
To: docbook-tc@lists.oasis-open.org
Subject: [docbook-tc] Link relationships

I'm still trying to get my head around the relatedlinks in documents and
relationships in assembly files. If these are two different ways of
expressing the same thing, I want to be able to normalize them down to a
single form for processing.

In the assembly file, a relationship is a collection of elements
identified by xml:id attributes.

  <relationship type="component">
    <instance linkend="db.book"/>
    <instance linkend="db.chapter"/>
    ...
  </relationship>

I think this means that after we've assembled the document, the
collection contains all the elements for which the assembled document
has a corresponding xml:id. I think this also means that the
relationship instances can point to either modules or resources (since
the only thing that really matters is the presence of the xml:id).

If that's right, then an inline relatedlink element should just be an ID
as well:

  <para>There are chapters<relatedlink linkend="db.chapter"/> and
  appendixes<relatedlink linkend="db.appendix"/> in a book.</para>

That feels a little weird, though. Authors might feel that they should
be able to identify the resource and the id. OTOH, the link only has
meaning if the corresponding resource is included, so I'm not sure that
makes a lot of sense either. If the author has four resources with
xml:ids that have the value "db.chapter", is this a related link to any
one of them that might be included in any assembled document, or is it a
link to only one of them. Or is it a link to two of them?

Also, in both cases, it's probably a mistake to name the attributes
"linkend" because they can't have the type IDREF. Maybe targetptr would
be a better name, parallel to olink.

Are any of these observations consistent with other's ideas about
related links and relationships?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | The shortness of life can neither
http://www.oasis-open.org/docbook/ | dissuade us from its pleasures,
Chair, DocBook Technical Committee | nor console us for its pains.--
                                   | Vauvenargues