headers
Thomas Schraitle | 17 May 2012 19:32
Picon

Best Practise of Referencing Between Modules in Assemblies?

Hi,

as I'm currently playing with DocBook assemblies, I'm wondering about the 
"best practise" of referencing from one module into another.

The "classical" (or usual) way is to get the ID of your target resource and 
put it into a linkend attribute of <xref/>. This establish a strong bond of a 
single one-way ID/IDREF which can be checked during validation.

Of course, this method can still be used with assemblies. However, it seems to 
me, as this method creates hard dependencies it makes maintaining all the 
topics/modules a bit too hard.

For example, if you have several modules in your assembly file, referencing 
back and forth, you can't be sure if the target resource is really "used". 
Therefor you can't be sure to have a valid single result DocBook document 
after the assemble process.

Thinking about assemblies and referencing, some issues are still unresolved to 
me and leads me to the following questions:

 (1) How do I reference to a chapter when I do not know if this
     chapter will be included or not? 

 (2) Is there a "preferred" method which is still readable and
     easy to maintain?

 (3) How do I reference to a set of links where I do not know the
     exact IDs?
     For example, if I have a book with several topics and I want
(Continue reading)

Permalink | Reply |
headers
Jirka Kosek | 18 May 2012 12:38
Picon
Favicon
Gravatar

Re: 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.

				Jirka

--

-- 
------------------------------------------------------------------
  Jirka Kosek      e-mail: jirka <at> kosek.cz      http://xmlguru.cz
------------------------------------------------------------------
       Professional XML consulting and training services
  DocBook customization, custom XSLT/XSL-FO document processing
------------------------------------------------------------------
 OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
------------------------------------------------------------------
(Continue reading)

Permalink | Reply |
headers
Bob Stayton | 18 May 2012 18:33

Re: 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.

Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net

----- Original Message ----- 
From: "Jirka Kosek" <jirka <at> kosek.cz>
To: "Thomas Schraitle" <tom_schr <at> web.de>
Cc: <docbook <at> 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
(Continue reading)

Permalink | Reply |
headers
Bob Stayton | 18 May 2012 18:52

Re: Best Practise of Referencing Between Modules in Assemblies?

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.

Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net

----- Original Message ----- 
From: "Bob Stayton" <bobs <at> sagehill.net>
To: "Jirka Kosek" <jirka <at> kosek.cz>; "Thomas Schraitle" <tom_schr <at> web.de>
Cc: <docbook <at> 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
(Continue reading)

Permalink | Reply |
headers
davep | 19 May 2012 08:45
Picon

Re: Best Practise of Referencing Between Modules in Assemblies?

On 18/05/12 17:33, Bob Stayton wrote:
> 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.
>
> Bob Stayton
> Sagehill Enterprises
> bobs <at> sagehill.net

Since the idea of assemblies is this isolation (with potential for 
re-use?) I'm surprised that olink ideas weren't embedded.

Their indirection has lots of benefits, though I like Bobs later idea
of the processor warning/erroring on missing link targets.

regards

--

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk
Permalink | Reply |
headers
Thomas Schraitle | 19 May 2012 17:11
Picon

Re: Best Practise of Referencing Between Modules in Assemblies?

Hi,

Am Freitag, 18. Mai 2012, 09:33:51 schrieb Bob Stayton:
> [...]
> 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.

Thanks Jirka and Bob for your ideas. Yes, I haven't thought of olinks. Good 
idea!

--

-- 
Gruß/Regards
  Thomas Schraitle
Permalink | Reply |
headers
Jirka Kosek | 21 May 2012 10:05
Picon
Favicon
Gravatar

Re: Best Practise of Referencing Between Modules in Assemblies?

On 18.5.2012 18:33, Bob Stayton wrote:

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

Do you mean using OLinks without targetdoc attributes to avoid ID/IDREFs
warning when editing standalone modules or do you have any idea how
OLink database should relate to assembly structure and what should be
separate OLink target document from assembly point of view?

Although there are many benefits of OLinks I think that assembly should
also provide linking similar to one known from DITA which allows direct
linking to source XML file of module.

				Jirka

--

-- 
------------------------------------------------------------------
  Jirka Kosek      e-mail: jirka <at> kosek.cz      http://xmlguru.cz
------------------------------------------------------------------
       Professional XML consulting and training services
  DocBook customization, custom XSLT/XSL-FO document processing
------------------------------------------------------------------
 OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
------------------------------------------------------------------
Permalink | Reply |
headers
Bob Stayton | 24 May 2012 22:53

Re: Best Practise of Referencing Between Modules in Assemblies?

I suggesting using Olinks without targetdoc attributes to avoid ID/IDREFs warning.

I have not given much thought to how an olink database might relate to an assembly 
structure.  Now I will, though.  8^)

Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net

----- Original Message ----- 
From: "Jirka Kosek" <jirka <at> kosek.cz>
To: "Bob Stayton" <bobs <at> sagehill.net>
Cc: "Thomas Schraitle" <tom_schr <at> web.de>; <docbook <at> lists.oasis-open.org>
Sent: Monday, May 21, 2012 1:05 AM
Subject: Re: [docbook] Best Practise of Referencing Between Modules in Assemblies?

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

Do you mean using OLinks without targetdoc attributes to avoid ID/IDREFs
warning when editing standalone modules or do you have any idea how
OLink database should relate to assembly structure and what should be
separate OLink target document from assembly point of view?

Although there are many benefits of OLinks I think that assembly should
also provide linking similar to one known from DITA which allows direct
linking to source XML file of module.
(Continue reading)

Permalink | Reply |

Gmane