[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-tc] proposal: add relatedlink element to topic
Perhaps an atttribute like resolve="yes" for the must-have case where an error occurs if not found, with resolve="no" the default? --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: > Hi Larry, > I thought about that a bit before I replied. Since para does allow info in > DB5, you can associate a relatedlink with a para (or other block) using > info. That implies that this relatedlink is associated with a specific bit > of information rather than the whole topic. Whole-topic related links could > still be managed in the topic or section info element. > > That flexibility also gives you options for how you present related links in > output. I can think of two styles: > > 1. All relatedlink elements in the topic are collected and presented as a > single list at the end. > > 2. Only whole-topic relatedlinks appear at the end, while block-level > related links are presented with their block. How you present such links > that may be an interesting challenge, but it could be very useful to the > reader. If the relatedlink target exists, it could generate an entire > sentence, such as "For additional information, see ...". The whole > sentence is omitted if the link does not resolve. That lets the author be > specific, yet fails gracefully (unlike xref, link, and olink in existing > sentences) in modular builds. > > As a statement of authoring style, I think lists of related links should be > kept short, otherwise the reader won't read them. That differs from > indexterms, where more is generally better. > > I'd like to also consider indicating the relative importance of a > relatedlink element. This one is a "must-have" and I want the build to fail > if its target is not present, and this other one is "would-be-nice" that > fails silently if the target is not present. Most would fall into the > latter category, I would think. > > Bob Stayton > Sagehill Enterprises > bobs@sagehill.net > > > ----- Original Message ----- > From: "Rowland, Larry" <larry.rowland@hp.com> > To: "Bob Stayton" <bobs@sagehill.net>; "Scott Hudson" > <scott.hudson@flatironssolutions.com>; "Norman Walsh" <ndw@nwalsh.com> > Cc: <docbook-tc@lists.oasis-open.org> > Sent: Monday, November 23, 2009 10:23 AM > Subject: RE: [docbook-tc] proposal: add relatedlink element to topic > > > I am somewhat concerned about moving these from inline to an info > element. I have found that having keywords in the info element > frequently leads to them being out of date as information is > modified and the keywords associated with them are not updated. > If a paragraph moves from one topic to another, the keywords > frequently get left behind in the info element. If it is deleted, > they do not always get deleted with it. I realize this is a > problem with the authoring process, but it is exacerbated by > separating the tag representing the cross reference from the > content it describes. Unless an info element is attached to > each paragraph, it becomes harder to assure that the cross > references represented by the relatedlink follows content as it > is altered, moved, or removed. > > I guess it is a usability issue. I find that indexterms are > much more robust than keywords in our content because they are > embedded in the content they represent rather than remotely > located from it. Adjacency is a strong principal in interface > design and general human factors. > > Regards, > Larry Rowland > > -----Original Message----- > From: Bob Stayton [mailto:bobs@sagehill.net] > Sent: Monday, November 23, 2009 11:05 AM > To: Scott Hudson; Norman Walsh > Cc: docbook-tc@lists.oasis-open.org > Subject: Re: [docbook-tc] proposal: add relatedlink element to topic > > Putting relatedlink elements in info is fine with me. Should we create a > relatedlinks wrapper for them, or allow a random scattering of relatedlink > elements in info? > > Bob Stayton > Sagehill Enterprises > bobs@sagehill.net > > > ----- Original Message ----- > From: "Scott Hudson" <scott.hudson@flatironssolutions.com> > To: "Norman Walsh" <ndw@nwalsh.com> > Cc: <docbook-tc@lists.oasis-open.org> > Sent: Monday, November 23, 2009 8:03 AM > Subject: Re: [docbook-tc] proposal: add relatedlink element to topic > > > >> I like Norm's suggestion. Related links "feels" more like metadata than >> inline content, and as the documentation states: "Many of the elements in >> this wrapper may be used in presentation..." >> >> 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 >> >> >> >> >> >> >> Norman Walsh wrote: >> >>> "Bob Stayton" <bobs@sagehill.net> writes: >>> >>> >>>> 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. >>>> >>>> >>> Index terms have to be located inline because their location >>> identifies a target for a cross-reference. In the case of relatedlink, >>> it sounds like the relationship is from (some parent of) the >>> relatedlink element to some other place. >>> >>> If a relatedlink element appears in a para in a section in a chapter >>> in a part in a book in a set, what determines the granularity of the >>> link source? >>> >>> It sounds to me like perhaps relatedlink should be allowed inside an >>> info wrapper and not in inline content. >>> >>> >>> >>>> 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. >>>> >>>> >>> Can you give a concrete example of a relatedlink element? >>> >>> Be seeing you, >>> norm >>> >>> >>> >> --------------------------------------------------------------------- >> 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]