OASIS DocBook TC2

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

    Posted 11-23-2009 19:07 
    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


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

    Posted 11-23-2009 19:13 
    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


  • 3.  RE: [docbook-tc] proposal: add relatedlink element to topic

    Posted 11-29-2009 18:23 
    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


Related Content