AsciiDoc Rust Implementation

asciidoc.md

Pledging for Rust support of the Asciidoc format

On 2021-01-17, @bitshiftmask requested an open source implementation of the AsciiDoc format.

Please see the original twitter thread for details.

The project is currently being developed here on GitHub.

NOTE: The repo/library name is likely to change in the near future to avoid Trademark Confusion. The link above will be changed once that has happened.

If you would like to add your pledge, please DM James on twitter, or reply to the thread. We are still looking for more contributions, to help prioritize or accelerate the work!

Deliverables

All of the following deliverables have the following requirements:

1. The deliverables must be developed under a permissive open source license
   • Ideally this would be dual MIT+Apache 2.0
   • If you'd like to use another license, please check with James first.
2. Both components must be completely written in Rust, and must not wrap a non-Rust library or CLI program.
3. All work must be public, at least at the time of release/acceptance

Your work will be reviewed prior to acceptance of payment. You must be listed on this page under "Implementors" to be elligible for the payment.

We are currently tracking the following deliverables

Deliverable 1 - Syntax Parser

A syntax parser for the AsciiDoc format, implemented in pure Rust.

The parser should have tests verifying its compliance with at least one common flavor of the AsciiDoc format.

Concrete acceptance criteria is under development.

Supporters for this deliverable:

• @bitshiftmask - 250 EUR
• @HeavyPackets - 250 EUR
• @Argorak - 250 EUR
• @bobmcwhirter - 250 EUR

The total support for this deliverable is currently 1000 EUR.

Deliverable 2 - mdBook Support

Support for this AsciiDoc syntax parser for the mdbook tool.

The mdbook support does not need to be merged upstream, but does need to be submitted.

Concrete acceptance criteria is under development.

Supporters for this deliverable:

• @bitshiftmask - 250 EUR
• @HeavyPackets - 250 EUR
• @Argorak - 250 EUR

The total support for this deliverable is currently 750 EUR.

Deliverable 3 - Format-Preserving re-serialization

The parser (deliverable #1) should be equipped for format-preserving re-serialization.

Concrete acceptance criteria is under development.

Supporters for this deliverable:

• @Argorak - 250 EUR

The total support for this deliverable is currently 250 EUR.

Funding

This amount is being paid by individuals that are pledging their amounts. This money will be paid out by each individual independently. James cannot control the individuals pledging, but will make a best effort to follow up with them once payment is due.

Please see above for the current pledge amounts.

If you would like to add your pledge, please DM James on twitter, or reply to the thread. We are still looking for more contributions, to help prioritize or accelerate the work!

Implementors

Currently, Lukas Wirth (GitHub, Twitter) has been assigned as the primary implementor. At the moment, he plans to take this commission on as a solo developer.

The project is currently being developed here on GitHub.

Potential Alternates

In the case that Lukas is unable to continue or finish development of the deliverables above, or is looking for potential collaborators, we are looking for interested alternates! If you are interested, please DM James for more details.

The following people have contacted James as potentially interested in helping:

• @stunibert
• @Plecra
• @barginbinhuman

I'd add another 250EUR if the parser is equipped for format-preserving re-serialization.

@skade I added this to the gist!

I'm the lead developer of the Asciidoctor project. I support the initiative to bring support for the AsciiDoc format to other languages. That's a key reason why I (along with the Asciidoctor community) have embarked on the journey to create a specification for the language. In doing so, we hope to encourage new, compliant implementations. We invite those interested in creating a Rust implementation to join us on that journey. See the following resources for more information:

• https://www.eclipse.org/org/workinggroups/asciidoc-charter.php
• http://www.eclipse.org/lists/asciidoc-wg
• https://asciidoctor.org/news/2019/01/07/asciidoc-spec-proposal/

Please note that there's no such thing as the Asciidoctor format. Asciidoctor is a processor implementation of the AsciiDoc format. Also note that AsciiDoc is a registered trademark of the Eclipse Foundation, stewarded by the AsciiDoc Working Group. It will be necessary to self-certify using the forthcoming TCK for an implementation to claim to be compliant (and, in turn, to use the AsciiDoc name in the description). If you participate now, you can have influence in how that TCK is defined.

As it stands now, you cannot use AsciiDoc as the name of the project or in the project name, so I respectfully request that you rename the repository to something else. That request is in the best interest of the community so we don't create confusion about what AsciiDoc is.

If you have any questions or concerns, don't hesitate to reach out to me or to the AsciiDoc WG list. I'll close by saying that I very much want this effort to succeed. An implementation of the AsciiDoc language in Rust would be great for the AsciiDoc community. And I hope that it will play an active roll in that community.

Hi @mojavelinux, thanks for reaching out!

I wasn't clear on the Asciidoctor/AsciiDoc relationship (and proper naming), but I've gone ahead and updated the gist as of this revision to try and better describe the goals with correct nomenclature. Feel free to let me know if you have any other suggestions to make!

Regarding the project name, I don't think that will be a problem. @Veykril is managing the development, and I'll reach out to him to change the name of the repository (and library). I expect this to happen in the near future (before major development begins, and certainly before any releases).

Regarding participation in the working group, I'll leave that up to @Veykril whether he is interested in that or not. We will very likely not tie any of our funding acceptance criteria to that. Thank you for sharing the resources!

Feel free to let me or @Veykril know if you have any other comments or concerns.

Thanks @jamesmunns! I really appreciate it. And I really am encouraged by this effort. We absolutely want AsciiDoc to be accessible to everyone who wants to write in it, and that means bringing it to new language runtimes.

As for the relationship between Asciidoctor/AsciiDoc, perhaps this section will help: https://docs.asciidoctor.org/asciidoctor/latest/#relationship-to-asciidoc If not, feel free to let me know what isn't clear and I'll happily revise it.

That said, one of the primary goals of the spec is to allow the AsciiDoc format to stand alone, independent of Asciidoctor or any other implementation. We want it to be both consistent and ubiquitous. While there isn't a website to point to yet, there will be soon (as stipulated in our 2021 program plan).

I wholeheartedly welcome those involved in this endeavor to participate in the working group or the language project. But please understand this is merely an invitation, not a requirement or mandate. This is a community effort and just like with all community efforts, it is at will. So tying your funding acceptance criteria to it is not at all necessary (and would likely just complicate things). If you prefer, this project can choose to self-certify using the resources we provide (when the time comes) and leave it at that. It's up to you. Though we really would value your participation in whatever form that may be. After all, the goal is to make AsciiDoc the best it can be.

I can't think of any other concerns at the moment, but we'll be in touch. My door is always open.

p.s. One very minor thing. The "D" in AsciiDoc is always uppercase*.

* The exception is if the "a" is lowercase, then the "d" follows it, such as in a variable name.

Wow, I'm glad that I found this conversation. Trademark issues are a very important thing these times. And to force Projects to rename their projects is a good Indicator what is coming up. Good Luck with that... I'm glad that at least the spelling is specified and enforced...

Indeed, we've put in a lot of work over the last few years to ensure the trademark is protected and that the meaning of AsciiDoc remains consistent. And a key part of why we're doing that is so that AsciiDoc can be made available on more language platforms, like Rust. We really want AsciiDoc to be a success in every sense of the word.

Really interested in a pure Rust implementation of the parser, but seems the discussion stopped last year. Is the TCK ready?

Parsing an AsciiDoc document into an AST with source positions would be a great first step. Lots of more features can be added gradually from there.

Just wondering if it's possible to keep it moving, even a tiny step periodically? I'm interested in looking into the current implementation and experimenting how hard it is to write a Rust parser. I may try it in a private test repo first.

In terms of funding, perhaps Open Collective and Github Sponsors are good options to keep things rolling?
The more supporters are there, the quicker the project would be developed.

Hello. I came here after seeing a comment on @Veykril's project saying "see the linked gist if you are interested in taking over the project instead".

I am interested in this project. In the past week or so, I have written a process to convert an AsciiDoc document to Markdown for rust-analyzer's release notes (but I am not sure yet if this PR will be accepted). This process was implemented based on the documentation on AsciiDoctor's site, and it handles the limited source documentation in a nice way. However, it contains some ad hoc parts and I wanted to create a more decent parser. I found @Veykril's project while researching existing projects and ended up here.

I am a solo open source developer with a company job that deals primarily with binary data, and also have a translation book manuscript, so I can't devote full time to this project. However, I am very interested in participating as an implementer, as I would like to use AsciiDoc more in the Rust community and would be happy to use AsciiDoc in mdBook as well. Note that I have used the AsciiDoc format in my manuscripts, so I have some understanding of it, but I am still refining the details by reading AsciiDoctor's documentation.

I'm not sure if the pledgers are still willing, as it's been almost 2 years. I'm interested in the effort for personal reasons, and intend to fork raphlinus/pulldown-cmark in order to get a bit of a head start. However, between a demanding day job and a busy family, I doubt I'll have a lot of time to spend on this (besides the fact that I'll likely end up going down more than a couple of rabbit holes cleaning it up, read making it more idiomatic).

Just wanted to throw this tip into the wild, to see if anybody else can get a working implementation up faster than I.