On Sat, 8 Dec 2018 at 22:54, Jaime Tarrasa <[email protected]> wrote: > > I'm trying to program (just for fun) a parser of asciidoc , but I'm a little > confused. Where is the specification? It looks like there are not such > asciidoc syntax but only asciidoc toolchains with a similar base syntax > described clearly nowhere .
Currently there isn't a specification, its on the todo list of a number of people, but nobody has had the time available to do it. Having multiple implementations is good for the ecosystem (eg Asciidoc Python can't be used by github, but Asciidoctor being Ruby can be), but the intention is to try to avoid the markdown scenario where everybody has their own variant. Hopefully the specification effort will begin in the new year. > > Reading users guide, examples, blogs and FAQs I can gather scattered > information so I can "reverse engineering" for a parser, but with are lot of > doubts. > One of the supposed advantages of asciidoc over markdown is that there are > not a lot of incompatible flavors. But it looks that the standarization of > asciidoc comes from having only two "de facto" parsers: asciidoc.org and > asciidoctor.org, (and now asciidoc3.org?) Effectively the current standard is asciidoctor, its the one actively maintained and enhanced. Asciidoc Python versions are essentially (not much) maintained for those who have made a large investment in surrounding infrastructure and their own add ons or who can't use Asciidoctor (in Ruby or one of its other variants). Asciidoc Python will end-of-life soon, as Python 2 EOLs, asciidoc-py3 is a port to Python 3 to extend its life but it has not much activity. The intention is that when asciidoc python 2 EOLs it will be renamed in github (working title asciidoc-py2) and be left available if anyone needs it and then the specification effort replace it at asciidoc.org. > > I guess asciidoc syntax is very simple, but thanks to its macros and brackets > for paragraphs can be easily expanded to a very powerful system. So you > depend upon a toolchain that defines a minimal usable types of paragraphs, > but they are not standard, so another toolchain may define it other way. > The syntax is fairly simple, but ... its hugely context dependent, to the extent that the "subs=..." construct effectively allows user control of what is parsed. This has little effect on the Python pure conversion implementations as it controls "substitution" (hence subs=), and the same on Asciidoctor which is still only a part parser, part converter IIUC, but it has huge impact on full parsers and formal specifications. The Asciidoc python implementation (the original) has a fairly large regression test suite, and Asciidoctor was originally designed to produce output that passed those tests as its developers understood that documents have a long lifetime and compatibility is important. Asciidoctor still has a compatibility mode, although I wouldn't be surprised if the next major version left that out. So to date compatibility is good between versions. Other than a few mis-features (like underline titles) that are only available in compatibility mode, Asciidoctor has mainly made extensions. One thing Asciidoctor is working towards is toolchainless conversion, it is available for all but PDF I believe. There is a PDF effort, but it is however proving more difficult IIUC and there are plans to re-implement it in a different way. > So, when I write an asciidoc document should I add "to be parsed with xxxxx"? Well, if you don't have a huge investment in Asciidoc Python, then the advice is to use the Asciidoctor implementation, as I said its the one thats maintained and enhanced, so not needed at the moment. Cheers Lex > > > > -- > 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. -- 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.
