RE: [docbook-tc] Link relationships

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

Yes, I do agree with your other statements. A @type may be useful to
group the relationships (e.g. a list of concepts, a list of tasks, a
list of references).

I also agree with your index term comment. From a localization
perspective we prefer to not have those, but when there really is a term
you need to index in-situ, you need the index term tag at the
appropriate point. This is really more useful for online that print
outputs, since for print you anyway just get the page number and have to
go and figure out where on the page you're supposed to find it. 


--
Gershon

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

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