[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-tc] proposal: add relatedlink element to topic
Do we also need an element to indicate where the links that are resolved at processing time are to be displayed? I think "at the end of the topic" is a little ambiguous. If I combine a couple of short modules to make a larger chunk, I might want to have the links for all of them presented at the end of the section combining the topics rather than breaking up the flow at the end of each piece. Having an element that behaves like a toc element, indicating where to put the list would be helpful. Regards, Larry -----Original Message----- From: Bob Stayton [mailto:bobs@sagehill.net] Sent: Monday, November 16, 2009 11:58 AM To: Scott Hudson Cc: docbook-tc@lists.oasis-open.org Subject: Re: [docbook-tc] proposal: add relatedlink element to topic 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 > > --------------------------------------------------------------------- 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]