Format-agnostic links between documents

[juli...@googlemail.com]

Hello,

the documentation for a project of mine is all asciidoc - there's a
user manual and a bunch of man pages. The user manual links to the man
pages as described in "18.1.3. Linking to Local Documents" in the
asciidoc user manual. This works fine for HTML documents.

I'd now like to generate Info documentation as well (via docbook2X)
and I'd like to resolve the links so they translate to a Texinfo @xref
{} link.

I'm happy to hack the docbook2X XSLT stylesheets - I've already had to
patch it heavily anyway - and of course I could do something like
check for the ulink's target and redirect some links. But I was
wondering if there is a more elegant way, maybe generating an olink
using macros? Any suggestions?

Thanks,

Julian

[Stuart Rackham]

I'm not familar with Info documentation, but if you have an example of a
hypothetical AsciiDoc macro call and the generated DocBook I'll try to
come up with an example macro.

Cheers, Stuart


>
> Thanks,
>
> Julian
>
> >
>

[Julian Scheid]

Hi Stuart,

On Wed, May 6, 2009 at 11:14 PM, Stuart Rackham <srac...@gmail.com> wrote:
> I'm not familar with Info documentation, but if you have an example of a
> hypothetical AsciiDoc macro call and the generated DocBook I'll try to
> come up with an example macro.

thank you for your offer.

First off, I had to read up on olink myself. In case you are not
familiar with it, may I recommend Sagehill's excellent overview of the
topic:

http://www.sagehill.net/docbookxsl/Olinking.html

I've attached a simple example that works with Docbook XSL (1.74.0).
It consists of two example Docbook XML files, user_manual and
reference, with user_manual olink'ing to reference. The corresponding
.db files were generated as described on the page mentioned above, and
the olinkdb.xml I've created as per these instructions as well.

You should be able to generate HTML files with a proper <a href> link
from these using Docbooc XSL as usual.

As for Asciidoc syntax, how about this:

olink:<targetdoc>#<targetptr>[<caption>]

e.g.

olink:reference#the_quick_brown_fox[foobar]

If possible with the option to omit the link text, as in

olink:reference#the_quick_brown_fox

This is just a suggestion, if olink is too Docbook-specific for your
taste, or if you dislike it for any other reason, feel free to choose
a different syntax... I don't care too much about this detail.

In the long run it would be great if we could find a way to make this
work for asciidoc's XHTML backend as well.

Thanks again,

Julian

[Stuart Rackham]

Hi Julian

Julian Scheid wrote:
> Hi Stuart,
>
> On Wed, May 6, 2009 at 11:14 PM, Stuart Rackham <srac...@gmail.com> wrote:
>> I'm not familar with Info documentation, but if you have an example of a
>> hypothetical AsciiDoc macro call and the generated DocBook I'll try to
>> come up with an example macro.
>
> thank you for your offer.
>
> First off, I had to read up on olink myself. In case you are not
> familiar with it, may I recommend Sagehill's excellent overview of the
> topic:
>
> http://www.sagehill.net/docbookxsl/Olinking.html
>
> I've attached a simple example that works with Docbook XSL (1.74.0).
> It consists of two example Docbook XML files, user_manual and
> reference, with user_manual olink'ing to reference. The corresponding
> .db files were generated as described on the page mentioned above, and
> the olinkdb.xml I've created as per these instructions as well.
>
> You should be able to generate HTML files with a proper <a href> link
> from these using Docbooc XSL as usual.
>
> As for Asciidoc syntax, how about this:
>
> olink:<targetdoc>#<targetptr>[<caption>]
>
> e.g.
>
> olink:reference#the_quick_brown_fox[foobar]

I like this syntax but AsciiDoc doesn't have a mechanism to split the
target (the standard inline macro syntax is <name>:<target>[<attrlist>])

So this will have to do:

olink:reference[the_quick_brown_fox,foobar]

Or with implicit caption:

olink:reference[the_quick_brown_fox]

The macro in the attached olink.conf should do the trick but
unfortunately here is a deficiency in the default macro regular
expression which causes it to match olink to link. I've fixed this in
the trunk (http://hg.sharesource.org/asciidoc/rev/f7197f5c410e) so that now:

olink:reference[the_quick_brown_fox,foobar] generates:

<olink targetdoc="reference"
targetptr="the_quick_brown_fox">foobar</olink>

And olink:reference[the_quick_brown_fox] generates:

<olink targetdoc="reference" targetptr="the_quick_brown_fox"></olink>

If it works then I could put it in the distribution docbook.conf


Cheers, Stuart

[Julian Scheid]

2009/5/10 Stuart Rackham <srac...@gmail.com>:

> I like this syntax but AsciiDoc doesn't have a mechanism to split the
> target (the standard inline macro syntax is <name>:<target>[<attrlist>])
>
> So this will have to do:
>
>   olink:reference[the_quick_brown_fox,foobar]
>
> Or with implicit caption:
>
>   olink:reference[the_quick_brown_fox]
>
> The macro in the attached olink.conf should do the trick but
> unfortunately here is a deficiency in the default macro regular
> expression which causes it to match olink to link. I've fixed this in
> the trunk (http://hg.sharesource.org/asciidoc/rev/f7197f5c410e) so that now:
>
> olink:reference[the_quick_brown_fox,foobar] generates:
>
>   <olink targetdoc="reference"
> targetptr="the_quick_brown_fox">foobar</olink>
>
> And olink:reference[the_quick_brown_fox] generates:
>
>   <olink targetdoc="reference" targetptr="the_quick_brown_fox"></olink>
>
> If it works then I could put it in the distribution docbook.conf

I just realized I never got back to you on this one, my apologies.

Many thanks for your advice and for putting the fix in trunk.
Unfortunately I've got sidetracked on the whole "olink" issue and
didn't get around yet to giving it a go.

I'll be on vacation for two weeks but I'll pick it up when I get back.

Thanks again,

Julian