[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [asciidoc-lang-dev] Cross-Reference Addressing
|
I’m glad you’ve recognized the necessity of the document set concept, but specifying the format and to some extent meaning of the document id is counterproductive.
In order to support usages such as Antora resource ids, the document id needs to be an uninterpreted token as far as an AsciiDoc processor, and any interpretation needs to be delegated to an extension of some form.
Presumably a default implementation of this extension would refer to the local file system using paths from a configured base, matching Asciidoctor’s current behavior.
I’m currently working on refactoring Asciidoctor into this structure to better understand what operations the extension needs to provide.
Generally speaking, I think the operations include:
- “reading” a source from a document id into something usable such as a string
- computing a relative path between two document ids
- computing an output location from a document id (this may not be needed due to the next one)
- “writing” output associated with a document id.
- copying a resource unchanged between input and output locations (presumably needed in case these happen to the the same)
- adding a resource to the document set at a document id (e.g. for asciidoctor-kroki to add a generated diagram)
With this sort of architecture, two concrete applications are:
- Antora would not need a custom converter or include processor
- jekyll-asciidoc could implement support for ‘permalink’, the jekyll concept separating source file location from output path.
Thanks
David Jencks
> On Feb 28, 2021, at 6:58 AM, Dave Gauer <dave@xxxxxxxxxxxxx> wrote:
>
> 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
> _______________________________________________
> asciidoc-lang-dev mailing list
> asciidoc-lang-dev@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe from this list, visit
> https://dev.eclipse.org/mailman/listinfo/asciidoc-lang-dev
