Interested in contributing an asciidoctor syntax

[melix]

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!

[vmassol]

Excellent!

Done (and invitation sent on GH):

• GitHub - xwiki-contrib/syntax-asciidoc: AsciiDoc Syntax Parser for XWiki
• AsciiDoc Syntax - XWiki.org JIRA

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

@melix

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).

@melix

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.

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.

[melix]

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

[vmassol]

@melix

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

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

Thx

[melix]

@vmassol

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

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

[vmassol]

@melix

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

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

[vmassol]

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

• AsciiDoc User Guide
• Eclipse Projects / AsciiDoc Language / AsciiDoc Language · GitLab

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: x.com

[melix]

The asciidoc syntax is documented at AsciiDoc cheatsheet

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

[vmassol]

@melix

The asciidoc syntax is documented at AsciiDoc cheatsheet

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.

[melix]

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.

[vmassol]

@melix

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

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?).

[melix]

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

[vmassol]

ok, starting to make sense 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:

• Font Icons Mode | Asciidoctor Docs
• Button and Menu UI Macros | Asciidoctor Docs (btw they say button: but it seems it’s a bug and it’s btn: in practice.

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).

[ggrossetie]

You are both partly right

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 (144 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!

[ggrossetie]

@melix

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

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

As mentioned in the updated README:

AsciiDoc is the language.
Asciidoctor is the processor.

[vmassol]

@ggrossetie thanks for the explanations and details.

@ggrossetie

If you are interested in working on a Java implementation of the AsciiDoc language, you should reach out to the AsciiDoc WG.

Sorry for the false hope here 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 x.com, it should. Right?

Thx