[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-tc] proposal: add relatedlink element to topic
My primary concern about adding the <relatedlink> element as a new inline is the effect of localization. Elements like index terms create a new segment, complicating the translation process and adding to the cost of the translation job as well as increasing the chances of the translator missing the inline element. Another reason against this idea is that when assembling documents out of independently written modules, the person doing the assembly (i.e., the person creating the map) understands how they want to put the various topics together and maintain the related links at the map level -- the way it's done with <relationships> today. The DITA spec deliberately puts the relationship table in the map for this reason. However, that being said, there are use cases for related links that are related to the content within the topic. DITA has a <related-links> element at the end of topics, though it's not often used. The theory is it's best practice to manage all related links at the assembly (map) level rather than at the topic level. Since this proposal includes the fact that broken links are suppressed, I'm OK going ahead with it. I just wanted to share some of the rationale and DITA best practices with the wider group. Personally, I don't see much point in authoring related links in the topic, because it adds to the maintenance overhead and may cause problems when the topic is reused. For example, you may want a number of different related links, depending on the assembly. With this proposal, you could put them all in the topic and expect the ones that are not relevant to be suppressed. I would rather author the relevant one in each of the maps. Re an element to indicate the anchor of the rendered related links: I prefer not to have an element to indicate the location of the related links. If a number of topics are being rendered as a single chunk, then I'd expect the stylesheets to treat that chunk as a single topic and assemble all the related links at the bottom of the chunk. Otherwise, we let the authors decide where the related links should be rendered, and in some multi-user situations one is likely to get inconsistent rendering due to different author preferences. I say let the stylesheets do their job to ensure correct and consistent rendering of the related links. -- Gershon -----Original Message----- From: Bob Stayton [mailto:bobs@sagehill.net] Sent: Monday, November 16, 2009 8:58 PM 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]