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

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

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