[asciidoc-lang-dev] Cross-Reference Addressing

[Dave Gauer <dave@xxxxxxxxxxxxx>]

Hello AsciiDoc ML!

I believe it would be valuable to have consistent and well-defined
linking between AsciiDoc source documents.

(I previously proposed adding a DocBook link type in "Proposing olinks".
I have since learned that it is well established that cross-reference
"xref" macros are used for this purpose.)

I would like to propose that the AsciiDoc spec be made more explicit
regarding cross-reference links to other AsciiDoc source documents.

To take it a step further, I would like to propose that the spec make
the syntax for cross-references both unambiguous *and* platform independent.

I believe this can be done in a way that is mostly just a description of
the xref macro behavior *as it exists now* and should cause very little
(if any) trouble for existing documentation.


== Proposing AsciiDoc Cross-Reference Addressing

(Again, this mostly describes behavior that already exists. The new
concept is that AsciiDoc would define this behavior for a "document set"
regardless of platform, filesystem, or type of output.)

AsciiDoc documents may make cross-reference links to:

* A location in the same document (by location ID)
* A location in another document (by document name and location ID)
* Another document (by document name)

Cross-reference links to other documents must be within a "document
set". That is, a group of AsciiDoc source documents.

The document name may include multiple segments separated by "/" which
resemble a file path.  Cross-reference links may reference other
documents with names that are relative to the current document in a
manner similar to URIs.

Example: If made in a document named `foo/bar.adoc`, the following links
would resolve like so:


    Xref link      |  Resolves to document named
-------------------+------------------------------
  baz.adoc         |  foo/baz
  beep/boop.adoc   |  foo/beep/boop
  ../home.adoc     |  home
  ../qux/biff.adoc |  qux/biff


These _look_ like file paths (and they might very well correspond with
actual files!), but the names (including the "/"-separated segments) are
independent of any platform or implementation.

This "path-like" naming scheme allows documents to be organized into a
hierarchical tree. It's use is entirely optional on the part of document
authors.

The ".adoc" suffix at the end of each example xref link _looks_ like a
file extension, but no such file needs to exist. The ".adoc" suffix is
simply part of the cross-reference syntax that identifies these as
document names instead of location IDs. (More on that in a moment.)

A beginning `/` (as in `/foo/bar.adoc`) will not be used. Doing so will
result in "undefined behavior". This is to allow AsciiDoc
implementations to continue to handle this situation as they do now for
backward compatibility. A `/` at the beginning of the link would seem to
imply the "root" or "base" directory of the document set. This might be
a handy thing to have, but is a new concept would doubtlessly clash with
existing behavior.


== Cross-reference ("xref") syntax

AsciiDoc cross-references have the following syntax:

    xref:DOCUMENT-NAME#LOCATION-ID[LABEL]

Or the alternate compact form:

    <<DOCUMENT-NAME#LOCATION-ID,LABEL>>

With the following rules:

* DOCUMENT-NAME must refer to the relative path name of another
  AsciiDoc document within a "document set".

* If the `#` is _not_ present, the DOCUMENT-NAME _must_ end in the
  string ".adoc" or it will be understood to be a LOCATION-ID!

* If the `#` is present, the ".adoc" ending may left off of the
  DOCUMENT-NAME and is implied.

* Either a DOCUMENT-NAME _or_ LOCATION-ID is required.

* If both DOCUMENT-NAME _and_ LOCATION-ID are present, they must
  be separated with `#`.

* LABEL is optional _unless_ the DOCUMENT-NAME is provided (current
  tooling cannot infer the title, else we could lift this restriction).

* If the LABEL is not present, the `[]` may remain empty in the first
  form and the `,` may be left off in the second compact `<<>>` form.


=== Examples of "xref" syntax

The regular inline macro form:

    xref:foo[Foo]    - a location in the same document with ID "foo"
    xref:bar#[Bar]       - a document named "bar"
    xref:bar.adoc[Bar]   - same
    xref:bar.adoc#[Bar]  - same
    xref:bar#foo[Foobar] - a location ID "foo" in document "bar"
    xref:bar.adoc#foo[Foobar] - same

The same cross-reference links in the alternative syntax:

    <<foo,Foo>>
    <<bar#,Bar>>
    <<bar.adoc,Bar>> *
    <<bar.adoc#,Bar>>
    <<bar#foo,Foobar>>
    <<bar.adoc#foo,Foobar>>

Note that the form marked with a `*` doesn't currently work in
_existing_ AsciiDoc implementations! It _does_ work in the test
application included in the repo (see below).


== Test and notes repository

In an effort to be sure what I'm proposing is complete and workable,
I've created a Ruby test application, hosted here:

https://github.com/ratfactor/xref.adoc

It produces HTML output demonstrating the content addressing, which you
can view here (and also in the above repo):

http://ratfactor.com/asciidoc/results.html

The output is compact (though hopefully not too cryptic), and aims to
show how the relative addressing between "document names" would work
given various combinations of syntax and environments (type of output to
be generated, name of the document containing the xref links, etc.).

The test application was largely inspired by GNU Texinfo, which produces
many types of output, including HTML in a single large file or split
into many files while retaining links between locations.

The above proposal text was lifted directly from this repository and
reformatted for email.


== Summary

The goal of this proposal is to support and strengthen the existing
document cross-referencing abilities in AsciiDoc with emphasis on:

* Clarity about the types of cross-references supported
* Explicit support for relative document links
* Platform and implementation independence

This likely raises many more questions than it answers, but I hope it at
least makes sense. With any luck, the test application and its results
may help to fill in any gaps in my prose.

I'll start the questions with my own:

Given the need for relative addressing between documents in a "document
set", what exactly constitutes a "document set"? Or would this be better
left intentionally ambiguous?

Thank you for your time and consideration!

-Dave Gauer