Re: [docbook] Linking to an Unknown Amount of Targets (1:n relationships)?

["Dew, Simon" <Simon.Dew@sbdinc.com>]

Hi Thomas

On 22/07/2013 14:25, Thomas Schraitle wrote:

>> I would use locator elements in the info of each topic to associate
>> label(s) with each topic.
>>
>> <info xmlns:xl="http://www.w3.org/1999/xlink";>
>>     <extendedlink xl:role="#see_also_labels">
>>       <locator xl:label="topic_1"/>
>>     </extendedlink>
>> </info>
>
> Ok, this looks good, but where do I put my category description?
>
> For example, if I want to say, "this topic belong to the group X and Y"
> then the labels(?) "X" and "Y" doesn't have to be the description.
>
> There is a xlink:title attribute for a <locator/>, which seems to be
> made for this purpose. However, adding this to *each* locator elements
> for every topic in this group wouldn't be very useful. You have a lot of
> duplicate code (which raises the risk of inserting a typo).

I that case I would put the xl:title attribute on the extendedlink. It 
looks like you can have multiple extendedlink elements in each info 
section. So you could group locators with similar xl:titles in separate 
extendedlink elements.

(It's not quite clear from The Complete Guide, but looking at 
docbook.rng, you can see that the extendedlink element supports the 
xl:title attribute.)

> I have a typical "cookbook style" in my book. To have more control, my
> structure looks like this with added extendedlink elements:
>
>    topic
>      title
>      info
>        extendedlink           <-- (1)
>      section role="problem"
>      section role="solution"
>      section role="discussion"
>      section role="seealso"
>        title
>        itemizedlist
>          info
>            extendedlink       <-- (2)
>
> (1) Contains the definition which additional, related categories (or
>      groups) can be viewed.
> (2) Is the actual markup which is replaced by a "real" itemized list
>
> Based on your example above, would that fit into your idea, too?

Your scheme seems fine to me! Personally I would omit the section 
role="seealso". I would include an extendedlink element with the xl:role 
"seealso" (or whatever) in the topic's info section. I would write a 
transformation to generate the seealso section at the end of the topic 
automatically. I'm afraid that's the way my mind works. This would 
create a bit of a gap between the semantics of the markup and the way 
that you want it presented; you would probably need to explain it to 
other authors maintaining your documents.

>> You'd need to find or create full URIs to identify the xl:roles and /
>> or xl:arcroles, if you choose to use these attributes.
>
> Hmn... it seems, using XLinks to markup a 1:n relationship is a
> daunting task. ;)

I guess that's why it's been slow to catch on :-)

As I understand it, the xl:role URIs don't have to point to a real 
resource on the net. They just have to be agreed within your system... 
e.g. "http://my.org/xlinkroles/seealso"; or whatever. There might be 
existing URI schemes which you could use; I haven't got time to look. 
Dublin Core might be a good place to start.

Sorry for mixing up top-quoting and bottom-quoting.

Simon Dew

Technical Author | Stanley Security Solutions
1 Park Gate Close, Bredbury, Stockport SK6 2SZ, U.K.

Simon.Dew@SBDInc.com | +44 (0) 161 406 3405
www.stanleysecuritysolutions.co.uk

Registered Office: Stanley House, Bramble Road, Swindon
Registered in England and Wales No. 181585 VAT No. 232 2446 95