The announcement of the AsciiDoc specification effort stated a goal as:
> Goal 2::
> The first version of the AsciiDoc specification will be as compatible
> as possible with documents that are currently being processed by
> Asciidoctor.
But what does "as possible" mean?
Does it mean identical? In which case it becomes a question of what the "AsciiDoc ecosystem" is that the specification is supporting, is it just the Asciidoctor implementation, or does it support alternative implementations? And as I raised in another thread, what of the language of APIs?
There is a valid argument to be made that a community around a single excellent implementation is the most efficient method of using limited resources. But such an implementation will lose use-cases where it can't run (an example I am aware of is Linux kernel development, the devs build their own systems, they don't use anything backed by a distribution, so they would need to build the entire Ruby or Java infrastructure to use Asciidoctor, an extra cost that at least one has expressed to me they won't accept, similarly embedded uses).
I suggest these questions need to be addressed by the working group and clarified before too much else happens.
My understanding of it is that behaviour that is not specified in the document that was tendered as the initial specification (see
https://docs.asciidoctor.org/asciidoc/latest/) is "implementation specific" as there was an exercise to remove such before it was released to Eclipse.
My proposal is that "as possible" does not mean "identical", but that it means the specified language can have a different interpretation of documents that depend on unspecified or unintended behaviour.
An example is overlapping inline markup (quotes) where the behaviour is unspecified (actually nesting is not addressed either AFAICT) and is dependent on the Asciidoctor implementation. I have addressed this in another thread (Eclipse does not appear to have web browsing of their mailing lists, so I can't reference it AFAIK, I do hope Eclipse is maintaining a copy of the lists, not relying on individuals inboxes as the record of conversations).
In the case of unintended/unwanted/problematic behaviour that may be significantly disruptive to a lot of existing documents, then it should be specified as deprecated and the new behaviour documented, so new implementations can directly target the future behaviour rather than incurring the cost of implementing Asciidoctor implementation specific behavior and then the new behaviour. (Asciidoctor existing behaviour is sunk cost, so that project only incurs the cost of implementing the new behaviour the same as new implementations).
As an additional but related note, I suggest there needs to be a search of the Asciidoctor github issues and other communications to identify those items that were closed as "to be addressed by the specification" so that they will in fact be addressed to keep faith with those who made the suggestions.
Cheers
Lex
