Re: [docbook-tc] proposal: add relatedlink element to topic

[Scott Hudson <scott.hudson@flatironssolutions.com>]

Bob, et al,

This is what the <relationships> structure was intended for...

Best regards,

--Scott

Scott Hudson
Senior XML Architect
+1 (303) 542-2146  |  Office
+1 (720) 663-SCOT [7268]  |  Gvoice
Scott.Hudson@flatironssolutions.com
http://www.flatironssolutions.com






Bob Stayton wrote:
> 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
> bobs@sagehill.net
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 
>
>