4 Replies Latest reply on Jul 18, 2012 1:08 PM by pmuir

    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?

        • 1. Re: Asciidoc - inter-document xrefs
          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

          • 2. Re: Asciidoc - inter-document xrefs
            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.

            • 3. Re: Asciidoc - inter-document 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.

              • 4. Re: Asciidoc - inter-document xrefs
                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.