|
Note
|
This is out-of-date! Please see my Ruby proof-of-concept for xref addressing (github repo) with lots of notes instead. However, this does have illustrations, so feel free to take a look. |
Current Linking Methods
The current recommended method for linking from one AsciiDoc document to another is using cross-references using the xref macro:
xref:foo.adoc[Foo]
Cross-references are also the method for creating links to content sections by ID:
xref:section2[Section Two]
Note that because foo.adoc in the first example contains the text .adoc, AsciiDoc processing tools understand that it is a link to another document.
Because the second example does not contain .adoc, it is understood to be a link to a section ID.
You can also combine a document name and section ID using the # separator like so:
xref:foo.adoc#section2[Section Two]
This will link to the location section2 the document foo.adoc.
The Proposal
What I’m proposing is formalization of the existing Document+ID addressing.
It would require absolutely no changes to the current functionality of popular tools such as AsciiDoctor, nor would it require any changes to existing AsciiDoc content which may or may not be using this addressing scheme.
What’s the point, exactly? The point is to solidify the idea that there is the concept of a "document" and the concept of a "location" and that these two concepts are independent of any specific implementation, filesystem, database, etc.
-
A "document" may or may not be stored in a file, but it should have a name ending in
.adoc. -
A "location" is a section of a document which has been given an ID.
Given the following:
-
Section ID in the current document:
bar -
Other document name:
foo.adoc -
Section ID in other document foo.adoc:
baz
Then each type of link would take the following:
xref:bar[] xref:foo.adoc[] xref:foo.adoc#baz[]
The alternative angle bracket cross-reference syntax should work identically (there are currently some differences and not all of the examples below will work):
<<bar>> <<foo.adoc>> <<foo.adoc#baz>>
The above links would be correct no matter where the source of the document named foo.adoc is stored. It could be in a file named foo.adoc, a blob of text in a database field, or a temporary area of computer memory.
The above links would also be correct if the output document is a series of separate HTML files (one per AsciiDoc source document), or a single PDF file, or even if the output was a series of tiny screen interactions (multiple per source document, perhaps split by section). The document names and section IDs would still point to the same content.
To illustrate this idea, the following graphical examples attempt to show how the link addresses are independent of storage or output medium.
Exporting to multiple HTML files (one per input .adoc source)
This is a very common scenario: multiple source .adoc document results in multiple output .html file. Notice how both bar.adoc and qux.adoc have section IDs b1 and b2. This probably isn’t a good idea, but it illustrates how sections need only be unique to the documents that contain them. Programmers refer to this as
namespacing.
Exporting to a single PDF document
This also seems like a likely scenario: multiple source .adoc documents result in a single combined .pdf file. Now it is even clearer that the addressing is independent of the output format.
Exporting to and from future technology
This fictitious example attempts to illustrate that document addressing is independent of the concept of files entirely. AsciiDoc must be ready for the future!
