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.
| +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
