| Thanks for the updates!
I’ve been trained to think that the existing asciidoc.org site is out of date and not really to be trusted. My understanding is that in the near future that domain name will point to the AsciiDoc spec project and the existing content will be moved elsewhere. Again, as far as I’m concerned, what AsciiDoc is is the existing behavior of Asciidoctor.
As this is an effort to come up with a spec, full backward compatibility is not a realistic goal. Maximizing backward compatibility while also maximizing usability, clarity, implementability, etc, surely is :-)
Now jumping inline to some more specific points….
On 2/17/21 12:50 PM, David Jencks wrote: I don’t think I understand what problem you are trying to solve, and
I would like to.
The fault is entirely mine! I don't think I provided enough context at the outset. I know pretty much nothing about DocBook
To quote Wikipedia on the relationship: "AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text mark-up conventions." https://en.wikipedia.org/wiki/AsciiDocThe AsciiDoc FAQ is likewise littered with references to DocBook: https://asciidoc.org/faq.html - I don’t know if maintaining/increasing DocBook/AsciiDoc
compatibility is a goal of anyone in the spec effort
I have no idea if it is either. It was an original AsciiDoc goal, but the importance of DocBook may have waned over the years. It's not something I'm personally vested in. I'd be curious what other opinions are on this list. - I regard the current behavior of Asciidoctor as the de-facto
specification for what AsciiDoc is.
I want to agree with this, but the fact is that some tools out there still use the old original Python `asciidoc` implementation. Full backward compatibility should take those into account. (Mind you, AsciiDoctor does a phenomenal job of this.) 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.
To be clear: in the case of my wiki, there is _no_ output format! I am navigating between AsciiDoc (.adoc) files via links. They are never converted to another form. (It's neat!)
I don’t believe you when you say there is no output format :-) If there were no output format, you wouldn’t need a parser, and you’d be happy typing “mykindofref:abracadabra-link-to-magic-page{foo!!!}” and having it do nothing. I suspect that your output format is conceptually something like a table mapping source locations in one page to source locations in other pages, and you have some way of responding to actions on a “source location” and “taking” you to the “target location”.
I’d like to understand your "output format” in this sense and how you use it.
Don't get me wrong, I'm keenly interested in HTML output. But the
concept of a relative link isn't limited to any particular output format.
I agree, for another common use case, pdfs also have links.
I posit that, at the moment, AsciiDoc has no formal way of expressing
this concept.
That depends on what you mean by “formal”. Since there’s no grammar, nothing in AsciiDoc is “formal”. Since xrefs between documents work today just fine in Asciidoctor as long as you are happy with the restriction that you have to rely on file system organization, and Asciidoctor behavior is the de-facto spec, then there is a formal way of expressing this concept.
It’s quite possible that introducing ‘olinks’ would be a good idea, but it’s pretty certain to be either redundant or very disruptive, so I think we need to be very careful and thorough about understanding what we want it to do and the consequences.
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).
While it is *possible* to make AsciiDoctor generate HTML links and make, say, a web site, it currently requires using "this one weird trick" with the <<url#,text>> xref syntax. (Or other processing, etc.)
I would argue that it is NOT possible to express a SEMANTIC relative
link to another document.
The key reason is that "xrefs" were NOT designed to link between
documents, but between LOCATIONS in a document.
If AsciiDoc is going to change the meaning of "xrefs" to be links to
locations AND to whole documents, this should be made more explicit than
it currently is (and I'd like to see more examples!).
This should appear (possibly with slight modifications) soon as the initial contribution to the spec project. 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.
You would like: "An implementation-independent concept of a link to a document." Am I summarizing that correctly? If so, I want that too! But what I'm asking for initially is: "A link to a document."
To me, that doesn’t make sense without a model of a set of documents and navigation. Currently this is hardcoded to be “the file system” which is really inadequate. However, a file system model might be completely adequate for your use case.
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.
Thank you very much for the chance to explain further! If anyone is interested in going down the rabbit-hole from whence this proposal came, here's the tragic back-story: https://github.com/ratfactor/vviki/pull/4Thank you! -Dave Gauer
Thanks! David Jencks _______________________________________________ asciidoc-lang-dev mailing list asciidoc-lang-dev@xxxxxxxxxxxTo change your delivery options, retrieve your password, or unsubscribe from this list, visit https://dev.eclipse.org/mailman/listinfo/asciidoc-lang-dev
|
