Hi,
Following this conversation, I might have some interesting things to
add. To summarize: the situation is IMHO much better than the tone of
discourse suggests. Let me explain.
Since I'm relatively unknown here, I'd just say I've been using Asciidoc
Python for about 4 years: asciidoc -> docbook -> LaTeX -> PDF, with a
custom LaTeX style and a number of variables that are automatically
extracted from a companion XML file that sits near each document (using
a combination of a Makefile and a bash script). I love the ability to
always produce perfectly typeset documents from a simple, no hidden
state, source code.
I also was surprised, nearly shocked, or at least a little afraid at
first, to read that "Currently there isn't a specification".
So, below I want to build upon this part of Dan's answer:
[The OP is] confusing a defacto standard with something that's not
well defined. A defacto standard is one where the standard is born out
of the implementation. This is not necessarily a bad thing. It's one
approach to making a platform. (A good example of this is Spring).
This approach has carried AsciiDoc along for many years and has worked
well so far. But now that AsciiDoc is becoming more pervasive and
there's a need for multiple implementations, we can see that a
specification of the core language would be very useful. So we've
reached a transition moment. Let's just acknowledge it as that.
I have worked in the digital video industry and learned one thing:
typical video codec specifications (I'm thinking about MPEG here, where
by the way the specification only tell how to decode, not how to encode)
are text written in English by human to be read by humans. But
interestingly, as video compression becomes more and more sophisticated
throughout the years, the text looks more and more like formal code.
There are parts that explain how to interpret other parts, etc. More so
than in the RFCs that define "MUST", "SHOULD", etc.
Why do I mention this? Because the pattern that emerges is that text
written in English by humans for humans keeps some part of ambiguity,
and its evolution to clarity converges to something that looks like
code. Because that's the way it can be complete and unambiguous.
What can we anticipate? Perhaps the ultimate specification is some kind
of code.
Right now, Asciidoctor is the leading implementation and it's test
suite maintains the definition of the modern language. If there's a
reference for the specification, that would be it.
That's where we should be careful and we'll soon see why I think the
situation is already pretty good at the moment.
Incomplete specification is dangerous. We've had an example of
incomplete specification with VP8 video codec (ref.
https://en.wikipedia.org/wiki/VP8): "since the source constitutes the
actual specification, any bugs will also be defined as something that
has to be implemented to be in compliance".
So why did I start with "the situation is IMHO much better than the tone
of discourse suggests"?
Because Dan and Lex wrote that Asciidoc has an "extensive test suite".
A test suite is something that can both:
* be read by a human/developer
* be read by a computer to automatically check an implementation for
compliance.
Of course, a test suite is generally a collection of examples inputs and
expected outputs (it can be richer since it's actually a program), so
what follows is a little schematic, yet might be insightful.
** What if we "realized" that a comprehensive test suite qualifies
simultaneously as (1) a human-readable specification, (2) a
machine-readable specification, (3) an automatic judge that can bless
any new implementation (even in a different language)?
Then, AsciiDoc is actually in a pretty good shape!
Jaime can download a test suite adapt it perhaps a little to test their
new implementation, and voilà, they have an automatic teacher that can
tirelessly tell what cases are missing in the new implementation and
what it should produce. I call that a pretty strong case to expect
AsciiDoc to thrive with compatible implementations, for the delight of
people writing documents in that common format.
Kudos to all the people working with Asciidoc!
Please share your thoughts.
--
Stéphane Gourichon
--
You received this message because you are subscribed to the Google Groups
"asciidoc" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/asciidoc.
For more options, visit https://groups.google.com/d/optout.
