Interested in contributing an asciidoctor syntax

Development
#1

Hi folks,

After chatting with @vmassol , I’m actually interested in contributing an Asciidoctor syntax to XWiki. Would be great to see this hosted at xwiki-contribs.

As you might know I’m also a member of the Gradle team so it might be an opportunity to see what we can do in this area (with a dual build in the beginning). Independently of this, we’re currently evaluating several tools and one thing we’d really like to see is a tool letting us use the asciidoctor syntax.

My GH username is melix, so I guess such a project should be bootstrapped as syntax-asciidoctor?

Thanks!

#2

Excellent! :slight_smile:

Done (and invitation sent on GH):

I’ve called it syntax-asciidoc since I think that’s the name of the syntax. Let me know if that’s not correct.

:+1:

I can help too. Don’t hesitate to ask questions on the chat or on the forum and we’ll be happy to help. I’m also available to talk, to get you up and running fast.

#3

Thanks, I have pushed an initial project skeleton, including a very broken implementation of a parser (just to integrate with asciidoctorj)

1 Like
#4

Cool! I see you’ve named the syntax asciidoctor. Isn’t it asciidoc (see AsciiDoc Syntax Quick Reference :: Asciidoctor Docs)?

Thx

#5

Yes, I used asciidoctor because the asciidoctor syntax is a superset of the asciidoc one. Asciidoc itself is, AFAIK, barely used.

#6

ok I didn’t know there were 2 syntaxes. When googling I can only find AsciiDoc Syntax Quick Reference :: Asciidoctor Docs (AsciiDoc syntax).

Would you have a link to the AsciiDoctor syntax so that I can see what it adds to AsciiDoc?

Thanks

#7

Seems that there’s work to have an official syntax at Eclipse:

So I’m not sure what AsciiDoc Syntax Quick Reference :: Asciidoctor Docs is. It’s called " AsciiDoc Syntax Quick Reference" too, suggesting it’s also AsciiDoc. I don’t know how it differs from AsciiDoc User Guide. Does it mean there are 2 syntaxes called “AsciiDoc” ATM?

EDIT: Also asked on twitter: https://twitter.com/vmassol/status/1380130192065183744

#8

The asciidoc syntax is documented at AsciiDoc cheatsheet

But we wouldn’t get a parser for this one in any case I think.

#9

That URL doesn’t seem very official to me. I don’t know what they refer to and they don’t link to any spec.

#10

This linked from the asciidoc page itself: https://asciidoc.org/

But as I said, I don’t think it’s worth focusing on this one and I’d make it clear we focus on asciidoctor support.

#11

ok so it’s the same as AsciiDoc User Guide that I mentioned above.

I hope Dan Allen will reply to my tweet, I still don’t know how https://asciidoc.org/ and AsciiDoc Syntax Quick Reference :: Asciidoctor Docs differ and why there are 2 different syntaxes both called “AsciiDoc” (you sure about that @melix, right?).

#12

Yes, it’s on the home page of Asciidoctor:

image

#13

ok, starting to make sense :slight_smile: So the “AsciiDoctor” syntax (which they still call “AsciiDoc”) is a superset of the official “AsciiDoc” syntax (from Eclipse), adding some new elements (and they don’t say explicitly which ones they add, they just mention two here but since they say “such as”, it hints that there could be more…).

I think the 2 they mention correspond to:

It’s a pity they don’t specify in AsciiDoc Language Documentation :: Asciidoctor Docs when it’s the official syntax and when it’s addition to the syntax.

Actually I wonder if there isn’t a single syntax which is “AsciiDoc” and that syntax is extensible with macros and AsciiDoctor just adds some more macros. If this is the case then there’s no “AsciiDoctor” syntax. In XWiki we have the same thing, and specific macros are not part of the syntax (it’s only the macro syntax that is part of the syntax).

#14

You are both partly right :wink:

Let’s try an analogy with Groovy.

Groovy.py is a Python implementation that supports Groovy 1.x (the language) and Groovydoctor is a Ruby implementation that supports the latest version of Groovy (still the language).

It’s the same with AsciiDoc (the language) with AsciiDoc.py (legacy Python implementation) and Asciidoctor (current/reference implementation) that supports the latest definition of the langage to date.

The AsciiDoc.py project will (soon) move out from https://asciidoc.org/. This website will become the homepage of AsciiDoc the language.

@melix If you are interested in working on a Java implementation of the AsciiDoc language, you should reach out to the AsciiDoc WG.
A first step would be to send an email on the mailing list: Mailing list: asciidoc-wg (121 subscribers) | Eclipse - The Eclipse Foundation open source community website. to tell that you are interested in contributing on the Java implementation.
You can join as an individual contributor or as a Gradle employee (if Gradle wants to join the AsciiDoc Working Group: Explore Our Members - Eclipse AsciiDoc | The Eclipse Foundation).

I know that some people working at VMware/Pivotal have also express interest in working on the Java implementation.

For reference, we will be working on a Java implementation as part of the Eclipse specification process (i.e., as an Eclipse project).
Other new or existing implementations (Rust, Go, JavaScript…) are willing to become compliant implementations and will work with the AsciiDoc WG. Please note that it’s not required to become an Eclipse project in order to be a compliant implementation. In other words, you could work on your own on another Java implementation and still be a compliant AsciiDoc implementation (if you pass the TCK).

I hope this clarify things!

#15

Not for long: update introduction content and URLs in README by graphitefriction · Pull Request #3999 · asciidoctor/asciidoctor · GitHub :sweat_smile:

As mentioned in the updated README:

AsciiDoc is the language.
Asciidoctor is the processor.

#16

@ggrossetie thanks for the explanations and details.

Sorry for the false hope here :wink: but we are just looking to integrate AsciiDoc into XWiki by using the AsciiDoc parser provided by AsciiDoctor and we were wondering how to call the AsciiDoc syntax it supports, i.e. wether it should be asciidoctor or asciidoc. Basically whether there are 2 syntaxes or not. In other words, imagine another parser written by another project, would it give the same AST? I think from what I understand from https://twitter.com/mojavelinux/status/1380597585505742850, it should. Right?

Thx