Asciidoc - inter-document xrefs

[pmuir]

Anyone got a good tip for how to handle this? I guess we need to plug some xref transformer that has domain specific knowledge into asciidoc?

[jaredmorgs]

I know in ECS, we've had a standards discussion about deep-linking between user guides. To cut a long story short, we agreed not to deep-link. You run the risk of links becoming dead when a book's structure changes. And it also becomes a real maintenance overhead. Unless someone can come up with a tool, as you suggest.

Consider using one of the following text formats consistently to suggest a reader looks at another user guide:

1) For more information about AsciiDoc, refer to the documentation at http://docs.redhat.com/docs/http://www.methods.co.nz/asciidoc/userguide.html.

2) For more information about AsciiDoc, refer to the AsciiDoc _User Guide_

3) For more information about AsciiDoc, refer to the AsciiDoc 8.6.7 _User Guide_

4) For more information about Document Structure, refer to _Chapter 8: "Document Structure"_ of the AsciiDoc _User Guide_.

If your document URLs for your project are going to remain static for your project (such as hosted on Nexus in a consistent build location) then you *may* want to consider adding in a link to the book root, and (optionally) putting in an alias so the link is shorter.

For example:

For more information about AsciiDoc, refer to the AsciiDoc _User Guide_ at http://www.methods.co.nz/asciidoc/userguide.html.

For more information about AsciiDoc, refer to the AsciiDoc 8.6.7 _User Guide_ at http://www.methods.co.nz/asciidoc/userguide.html.

For more information about Inline URLs, refer to _21.1.1 URLs_ of the http://www.methods.co.nz/asciidoc/userguide.html[AsciiDoc User Guide].

Any manual deep-linking deeper than that is just asking for trouble.

Hope it helps

Jared

[pmuir]

Actually, I'm really within the same guide, but splitting up each chapter up into separate files.

As we don't use asciidoc to collect the chapters into a book (but instead use our guides plugin for awestruct - e.g. http://www.jboss.org/jdf/examples/ticket-monster/tutorial/WhatIsTicketMonster/) we hit the problem of resolving xrefs.

[jaredmorgs]

I think this needs more air time. I've tweeted the link to this forum post to see if we can get some traction on it for you, Pete.

[pmuir]

In the end, I've just decided to make the links normal xrefs, and define a convention of <SourceFileNameWithoutExtension>-<LocationInDoc> as the id. I've then added a link rebuilder to our html reparse phase on the website, to recognise links in this format from AsciiDoc, and rebuild the link correctly.