atom feed8 messages in org.oasis-open.lists.docbookRe: [docbook] Best Practise of Refere...
FromSent OnAttachments
Thomas SchraitleMay 17, 2012 10:31 am 
Jirka KosekMay 18, 2012 3:37 am 
Bob StaytonMay 18, 2012 9:33 am 
Bob StaytonMay 18, 2012 9:52 am 
davepMay 18, 2012 11:45 pm 
Thomas SchraitleMay 19, 2012 8:10 am 
Jirka KosekMay 21, 2012 1:04 am 
Bob StaytonMay 24, 2012 1:53 pm 
Subject:Re: [docbook] Best Practise of Referencing Between Modules in Assemblies?
From:Bob Stayton (bo@sagehill.net)
Date:May 18, 2012 9:52:28 am
List:org.oasis-open.lists.docbook

I meant to also add that the issue of what to do with links that don't resolve
once a document is assembled is a general one. The stylesheets could be customized to
simply ignore unresolved links, on the assumption that the link failure is due to
excluded content rather than a typo in the link. I don't know if there is a way for a stylesheet to distinguish between the two cases. It would be good for the
processor to at least emit an error message during processing so that such unresolved
links could be confirmed.

The other half of the problem making sure the written context of such a
disappearing link still makes sense. Putting links in the middle of a sentence risks
creating a garbled sentence if the link text disappears. I've written customizations where
the practice was to place such "soft" links as the sole content in a standalone
para, and if the link does not resolve, the entire para disappears. The link style in
that case included generating the surrounding text ("See ... for more information"). You
could also create an itemizedlist with role="relatedlinks" to contain them. Then the stylesheet could also omit the listitem container of an unresolved link, and the entire list and list title if none of the links resolve in the list.

----- Original Message ----- From: "Bob Stayton" <bo@sagehill.net> To: "Jirka Kosek" <jir@kosek.cz>; "Thomas Schraitle" <tom_@web.de> Cc: <docb@lists.oasis-open.org> Sent: Friday, May 18, 2012 9:33 AM Subject: Re: [docbook] Best Practise of Referencing Between Modules in
Assemblies?

The stylesheets do not currently support such XLink syntax. The current
assembly stylesheet would first need to preserve the xml filenames in xml:base attributes when assembling resources into a single DocBook document for processing. That should be done anyway to preserve relative paths to images and such.

You can use olinks right now. One of the most frequent uses of olinks is for linking between modular content. Olinks let you avoid hard coding filenames in
your links, which can be troublesome to maintain if you rename or move files.

----- Original Message ----- From: "Jirka Kosek" <jir@kosek.cz> To: "Thomas Schraitle" <tom_@web.de> Cc: <docb@lists.oasis-open.org> Sent: Friday, May 18, 2012 3:38 AM Subject: Re: [docbook] Best Practise of Referencing Between Modules in
Assemblies?

On 17.5.2012 19:32, Thomas Schraitle wrote:

as I'm currently playing with DocBook assemblies, I'm wondering about the "best practise" of referencing from one module into another. ... What do you think? Do you have used assemblies already and how do you deal with referencing? Do I miss anything?

First, it's good that someone is using assemblies -- it would be very hard to develop them without feedback from users. Regarding links, I think that proper way of linking is to use XLink pointing to source XML file of module and optionally to ID withing this fragment. E.g.:

<xref xlink:href="installation.xml#system.requirements"/>

However I'm not sure that stylesheets are already supporting this mechanism.