Re: [docbook-tc] Link relationships

[Norman Walsh <ndw@nwalsh.com>]

"Gershon Joseph (gerjosep)" <gerjosep@cisco.com> writes:
> 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).

Right. I'd prefer them out-of-line entirely, given their purpose, but
others argued for putting them inline so that they're more likely to be
updated.

For the purpose of figuring out what the semantics are, I don't really
care where they occur in the actual source documents.

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

That's often true, but I don't think it's always true. If a particular
concept occurs halfway through a paragraph, I think the indexterm
should be attached to a particular word in that concept. That way, the
reader will be directed to the actual page where the reference occurs,
even if the paragraph is split across the page.

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

Yep.

And do I take it you agree with the rest of my comments. That the relatedlink
elements just contain ID references and are combined with relationships from
the assembly?

(Hmm, maybe they also need a type attribute so that they can be combined with
the correct relationships.)

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | So, are you working on finding
http://www.oasis-open.org/docbook/ | that bug now, or are you leaving
Chair, DocBook Technical Committee | it until later? Yes.

PGP signature