[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [asciidoc-lang-dev] Proposing olinks
|
Hi Dave,
I don’t think I understand what problem you are trying to solve, and I would like to.
My point of view includes:
- I know pretty much nothing about DocBook
- I don’t know if maintaining/increasing DocBook/AsciiDoc compatibility is a goal of anyone in the spec effort
- I regard the current behavior of Asciidoctor as the de-facto specification for what AsciiDoc is.
If we abstract what you are trying to do away from any syntax, my impression is that your have a set of documents in some sort of relationship to one another (such as being in a folder in a file system) with names (such as file system paths from a base folder) and you would like a way to process these documents so that some syntax in one document is output as instructions on how to go to a place in another document.
Assuming this is reasonably close to what you have in mind, in some circumstances Asciidoctor supports that with xrefs today. The restrictions are that the documents have to be in a file system and the source document paths have to match the desired output document paths.
I don’t see you indicate what your output format is other than “not html”. If the assumptions above apply, you could write a converter backend for Asciidoctor to render your documents into that output format and translating xrefs into whatever navigation information you need.
If you want to propose a new syntax for something that is already supported by Asciidoctor I think you need a strong argument about how it will benefit users rather than cause confusion (if there are now two ways to do the same thing) and disruption (if the existing way no longer works).
I do not regard the current situation as acceptable, but not because of xrefs between documents. To me, the big problem is that AsciiDoc/Asciidoctor is fundamentally about converting one document, but it makes highly questionable assumptions about how to interpret the symbols encoding the “other document” in xrefs, namely that they refer to file system paths. I think that AsciiDoc processors should interpret location information as uninterpreted tokens and delegate the interpretation to an extension. Presumably the default extension would provide the current file-system-based behavior.
What I write tends to be hard to understand :-( but I hope that you will be able to explain what you want in more detail and in relationship with what I’ve written, and also explain how it will generally be an improvement to AsciiDoc in comparison to the current Asciidoctor behavior.
Thanks!
David Jencks
> On Feb 17, 2021, at 8:20 AM, Dave Gauer <dave@xxxxxxxxxxxxx> wrote:
>
> Intentional duplication: I'm re-sending this message with proper text
> wrapping as a reply. Apologies to anyone who had a hard time reading the
> original. If only email messages were written in AsciiDoc format, right?
> (And yes, the mail client will be punished.)
>
>
>
>
> == What We Have Now
>
> There are currently two types of links in AsciiDoc. (I'll use the
> DocBook documentation to describe these and you'll see why in a moment.)
>
> 1. link:http://foo[Foo]
>
> DocBook describes this type of link as:
>
>> "The link is a general-purpose hypertext element. Usually, link
> surrounds the text that should be made "hot" (unlike xref which must
> generate the text)..."
>
> and
>
> 2. xref:foo[] (or with optional link label xref:foo[Foo])
>
>> "The xref element forms a cross-reference from the location of the
> xref to the element to which it points. Unlike link and the other
> cross-referencing elements, xref is empty. The processing system has to
> generate appropriate cross-reference text for the reader."
>
> Also note that there exists <<foo>> syntax for xrefs as well, and I have
> found a fair amount of confusion surrounding the two syntax styles.
>
>
> == The Problem
>
> As an avid fan of the AsciiDoc format, I use it not just for
> "traditional" documents, but also for pretty much everything I write:
> personal wiki, website, notes. These are all inter-linked bodies of
> documentation residing in separate files. I have tooling which
> understands these relationships.
>
> Unfortunately, AsciiDoc currently has no One True Way to make relative
> links between documents.
>
> * link:http://foo[Foo] is intended for absolute URLs
>
> * xref:foo[] is intended for cross-references WITHIN a document
>
> (Yes, xref links _can_ also be used to make relative links to references
> in other documents and it _can_ be "tricked" into linking to another
> document directly in at least one AsciiDoc implementation.)
>
> In practice, I've found that you can coerce EITHER of these link types
> to produce HTML output with relative links between documents (I'm
> personally using "links", others are using "xrefs"). No one method is
> cross-implementation compatible!
>
>
> == The Proposal
>
> I propose we take a third type of link from DocBook: the olink.
>
>> "Unlike link, the semantics of olink are application specific. The
> olink element provides a mechanism for establishing links across
> documents, where ID/IDREF linking is not possible and URI-based linking
> may be inappropriate.
>> In general terms, the strategy employed by olink is to point to the
> target document by URI, and point into that document in some
> application-specific way."
>
> https://tdg.docbook.org/tdg/5.2/olink.html
>
> To put it plainly, this is a link type made expressly for relative
> linking between documents!
>
> I would love for this link type to:
>
> 1. Exist
> 2. Mimic the macro syntax of the existing link types
>
> Therefore, I propose AsciiDoc have these three link types:
>
> link:http://foo[Foo] <-- absolute URL
> xref:foo[] <-- reference ("anchor") link
> olink:foo[Foo] <-- relative link to document
>
> To make the examples even more concrete and using HTML as an example, I
> might expect this output for the above links:
>
> <a href="http://foo";>Foo</a>
> <a href="#foo">Foo</a>
> <a href="foo.html">Foo</a>
>
> Note the ".html" extension appended to the olink href above, which would
> be application-specific (and user-configurable!).
>
> Lest anyone think all of this is Web-centric, my main purpose in
> proposing this is to have a correct type of link to use for my wiki
> system (a Vim plugin) which navigates local .adoc files natively. Most
> of these are never converted to HTML.
>
>
> I'm really excited about the standardization of AsciiDoc and appreciate
> this effort!
>
> AsciiDocaly Yours,
>
> 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
