OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


This idea of using extendedlink for a section's See Also list came up on the docbook mailing list, and I wanted to see if there was any interest in this idea among members of the DocBook TC. The nice thing about this use case is that it does not require a runtime mechanism for a dynamic popup list of link targets, because the list is rendered statically at build time.

The idea here is to mark sections as belonging to one or more categories, and then an author could create a See Also list by referring to category names.

I would be interested in hearing if anyone has already done this, and what extended link syntax you used, or would use if you had this requirement.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

--------------------------------------------------
From: "Thomas Schraitle" <tom_schr@web.de>
Sent: Monday, July 22, 2013 6:25 AM
To: <docbook@lists.oasis-open.org>
Subject: Re: [docbook] Linking to an Unknown Amount of Targets (1:n relationships)?

Hi Simon,

thanks for sharing your idea!

On Mon, 22 Jul 2013 05:33:31 -0400
"Dew, Simon" <Simon.Dew@sbdinc.com> wrote:

If you're using Docbook 5, and as long as we're only talking about
markup, I think this use case is crying out for extended links.

That was also my impression, because XLink promised to solve
exactly this problem.


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

Any other idea?


Then, wherever you want a "see also" list to be generated, I would
use arc elements (again, in the info of the topic) to point to the
label(s) that you want to include.

<info xmlns:xl="http://www.w3.org/1999/xlink";>
   <extendedlink xl:role="#see_also_list">
     <arc xl:to="topic_1"/>
     <arc xl:to="topic_2"/>
   </extendedlink>
</info>

Where would you insert this info? I'm a bit concerned about the
discrepancy between the definition and where it really appears in the
document.

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?


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 others have similar issues and it would be really, really
helpful to have an official "blessed" method how XLinks are supposed to
work in DocBook.

Maybe something for the next DocBook Technical Committee Meeting to
define an "official method"? Documented in the TDG? Supported by the
stylesheets?

Thanks for all the ideas! :-)


--
Gruß/Regards,
   Thomas Schraitle

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]