[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-tc] proposal: add relatedlink element to topic
I do like the idea of putting the related-links element in an info. I'd
be concerned about their impact on localization if we allow them to be
scattered with other inline content. I do hear the point of keeping the
links close to the content, though personally feel it's a business
process problem and not an info model problem -- I'd vote to fire the
authors and hire ones who work in accordance with the business rules.
But I don't often have the luxury to actually do that... Nowadays
companies tend to fire the good ones and hire cheaper ones who are even
more clueless and even less likely to work according to the business
rules <sigh/>. So I guess the info model needs to be as idiot-proof as
possible. Or said another way, the info model needs to be as
*user-friendly* as possible, eh?
I also like the idea of an attribute to set how critical failure to
resolve the link is. I don't think @resolve = yes/no captures it for me.
Maybe @resolve-fail = { error | warn | ignore } or something, but I'm
still brainstorming this in my mind... My current thinking is:
Error => report error and abort processing. Rendition is considered a
failure.
Warn => generate a warning message and continue processing. Rendition is
considered a success.
Ignore => don't bother reporting (or processors may optionally generate
an info message) and keep on going. Rendition is considered a success.
Maybe I'd prefer to call the attribute @fail-to-resolve or
@resolve-failure-reporting. Dunno. I'm not hitting the jackpot
tonight... I'm sure someone else will think of a better name for the
attribute.
--
Gershon
-----Original Message-----
From: Scott Hudson [mailto:scott.hudson@flatironssolutions.com]
Sent: Monday, November 23, 2009 9:12 PM
To: Bob Stayton
Cc: Rowland, Larry; Norman Walsh; docbook-tc@lists.oasis-open.org
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.ph
>> p
>>
>>
>>
>
>
> ---------------------------------------------------------------------
> 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]