OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: proposal: add relatedlink element to topic

In support of the new modular DocBook schema, I propose that we add a 
relatedlink element to DocBook.  I suggest that this be an inline element 
like link, but that it be processed like an indexterm.  That is, the content 
of relatedlink does not appear inline in the output, but rather all 
relatedlink elements are gathered up by the stylesheet and presented as a 
list at the end of each topic.

Use case:

Cross references in modular content can sometimes be left unresolved. This 
typically happens when one module is included in a structure and another 
module containing the target of a cross reference is not.  When unresolved 
inline cross references are encountered by the processing engine, they are 
reported as an error and some indication of error may be included in the 
output. A sentence containing such a link may be rendered meaningless and 
confusing to the reader.

A relatedlink element provides a solution to this problem.  Instead of an 
explicit cross reference, an author can insert a relatedlink element at any 
point in a topic element like an indexterm. At processing time, only those 
relatedlink elements that resolve are included in the output. And instead of 
appearing inline, they are gathered up and presented as a list, typically at 
the end of each topic. This avoids the problem of awkward unresolved inline 
references, and useless error messages about missing links.

Allowing relatedlink elements to appear inline permits them to be kept close 
to the text they are related to. Then if the text is deleted, so is the 
relatedlink. If the text is modified, then the relatedlink can be evaluated 
by the author to see if it is still relevant.

The stylesheet could optionally emit a warning for unresolved relatedlinks. 
Reviewing such messages would provide an author with an indication that an 
unresolved link is acceptable rather than just a typo.

Bob Stayton
Sagehill Enterprises

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]