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

["Bob Stayton" <bobs@sagehill.net>]

Hi Scott,
The relationships element operates at the structure level and is maintained 
outside of the topics.  The relatedlink element is a mechanism for allowing 
users to insert related links within topics as they are being authored.  I 
think the two mechanism are complementary.  Some links are best managed 
outside the topics and some inside the topics.  I would expect that links 
from both sources would be merged at processing time.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "Scott Hudson" <scott.hudson@flatironssolutions.com>
To: "Bob Stayton" <bobs@sagehill.net>
Cc: <docbook-tc@lists.oasis-open.org>
Sent: Monday, November 16, 2009 10:49 AM
Subject: Re: [docbook-tc] proposal: add relatedlink element to topic


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