[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-tc] Link relationships
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:firstname.lastname@example.org] Sent: Monday, December 14, 2009 9:15 PM To: email@example.com Subject: Re: [docbook-tc] Link relationships "Gershon Joseph (gerjosep)" <firstname.lastname@example.org> 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 <email@example.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.