This repo contains a "code-as-documentation" example of a proposed cross-reference addressing (and related syntax) scheme for AsciiDoc documents.
This README contains a description of what is being proposed, as well as some research notes.
To try it out:
$ ruby test.rb > results.htmlThe resulting HTML document displays each test environment (including a description of what is being tested) and a table displaying the result of each cross-reference link. Best viewed in a browser.
The document has already been generated and can be viewed here:
The source of the output document is, of course, in this repo. Look for results.html.
-
Correct handling of document name and location ID in xrefs (addressing).
-
Relative "path segments" in document names.
-
Proof-of-concept of xrefs independent of publishing
-
Any kind of AsciiDoc lexing or parsing (the xref links all have labels, for example).
-
Input validation - these tests are all syntactically and semantically correct and the paths are correct.
-
Filesystem handling (but that’s kind of the whole point).
-
Content output generation (HTML links are created as an example because they are ubiquitous and HTML output can be one-to-one, one-to-many and many-to-one in relation to the input source).
(Note that 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 document name 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.
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-NAMEmust refer to the relative path name of another AsciiDoc document within a "document set". -
If the
#is not present, theDOCUMENT-NAMEmust end in the string ".adoc". -
If the
#is present, the ".adoc" ending may left off of theDOCUMENT-NAMEand is implied. -
Either a
DOCUMENT-NAMEorLOCATION-IDis required. -
If both
DOCUMENT-NAMEandLOCATION-IDare 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
LABELis not present, the[]may remain empty in the first form and the,may be left off in the second compact<<>>form.
The regular inline macro form:
xref:foo[Foo] - a link to a location in the same document with ID "foo" xref:bar#[Bar] - a link to a document named "bar" xref:bar.adoc[Bar] - same xref:bar.adoc#[Bar] - same xref:bar#foo[Foobar] - a link to 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 this test application.
The one linking method to rule them all is the World Wide Web’s URI spec, the latest version of which is described in RFC3986:
A Uniform Resource Identifier (URI) provides a simple and extensible means for identifying a resource.
The URI scheme meets goals that are a bit loftier than what is needed for cross-referencing AsciiDoc locations/documents.
However, Section 3.3 Path seems very appropriate for identifying the absolute and relative location of a document in a set of documentation.
Specifically, it seems we could lift these portions wholesale:
A path consists of a sequence of path segments separated by a slash
("/") character. ...
The path segments "." and "..", also known as dot-segments, are
defined for relative reference within the path name hierarchy. They
are intended for use at the beginning of a relative-path reference
(Section 4.2) to indicate relative position within the hierarchical
tree of names. This is similar to their role within some operating
systems' file directory structures to indicate the current directory
and parent directory, respectively. However, unlike in a file
system, these dot-segments are only interpreted within the URI path
hierarchy and are removed as part of the resolution process (Section
5.2).
Sphinx uses reStructuredText (reST):
Sphinx/reST has explicit support for cross-referencing to locations in other files:
To support cross-referencing to arbitrary locations in any document, the standard reST labels are used. For this to work label names must be unique throughout the entire documentation.
Example of normal cross-reference:
.. _my-reference-label: Section to cross-reference -------------------------- This is the text of the section. It refers to the section itself, see :ref:`my-reference-label`.
The documentation explains that this will also work across files automatically!
Sphinx also has explicit support for linking to other reST documents! And note the lack of file extension:
Link to the specified document; the document name can be specified in absolute or relative fashion. For example, if the reference :doc:`parrot` occurs in the document sketches/index, then the link refers to sketches/parrot. If the reference is :doc:`/people` or :doc:`../people`, the link refers to people.
If no explicit link text is given (like usual: :doc:`Monty Python members </people>`), the link caption will be the title of the given document.
There’s also a project that lets you write Sphinx documentation in Markdown and it supports these linking rules as well:
There is no need to put the role. It should just be [Link text](/myMDfile) or the relative path with [Link text](myMDfile).
The GNU Texinfo syntax for writing manuals has the ability to cross-reference other documents:
Ordinarily, you must always name a node in a cross-reference. However, it’s not unusual to want to refer to another manual as a whole, rather than a particular section within it. In this case, giving any section name is an unnecessary distraction.
So, with cross-references to other manuals (see Four and Five Arguments), if the first argument is either ‘Top’ (capitalized just that way) or omitted entirely, and the third argument is omitted, the printed output includes no node or section name. (The Info output includes ‘Top’ if it was given.)
Example, where make is the name of the manual to link to:
@xref{Top,,, make, The GNU Make Manual}.
Not surprisingly, Org-mode has a crazy number of link options:
Amusingly, "internal links" reverse AsciiDoc’s [[]] and <<>> anchor and xref syntax:
<<foo>> This is info about foo. Here is a link to [[foo]].
But most relevant to the AsciiDoc situation is Org-mode’s publishing process, which is impressive:
To create a link from one Org file to another, you would use something like ‘[[file:foo.org][The foo]]’ or simply ‘’ (see External Links). When published, this link becomes a link to ‘foo.html’. You can thus interlink the pages of your “Org web” project and the links will work as expected when you publish them to HTML. If you also publish the Org source file and want to link to it, use an ‘http’ link instead of a ‘file:’ link, because ‘file’ links are converted to link to the corresponding ‘.html’ file.
Eventually, links between published documents can contain some search options (see Search Options), which will be resolved to the appropriate location in the linked file. For example, once published to HTML, the following links all point to a dedicated anchor in ‘foo.html’.
[[file:foo.org::*heading]]
[[file:foo.org::#custom-id]]
[[file:foo.org::target]]
From the original WikiWikiWeb to MediaWiki, linking between documents ("pages") is fundamental to Wikis.
A link in WikiWikiWeb is CamelCaseLikeThis. A link in MediaWiki uses brackets like [[foo]] or [[foo|Foo Description]].
Wiki pages may or may not be stored in files and they are often converted on the fly to HTML for viewing. It is fundamental to wikis that all link conversion is completely automatic and as frictionless as possible.
It looks like inter-document linking can absolutely be done, but it requires additional "packages" such as xr and/or zref. But the "external document" has to be declared in the calling document. I don’t think this is something to be emulated.
Troff is truly for stand-alone documents and manual pages. They have traditional bibiographic-style "references", but virtually no concept of linking other than URL hyperlinks and email address links (which PDF and HTML export types seem to understand) (which PDF and HTML export types seem to understand).
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent