Asciidoc Support

[sashokbg]

🤔 What's the problem you're trying to solve?

Feature: Add asciidoc support for feature formatting
Asciidoc is a feature rich alternative to markdown that covers almost everything that markdown does but
also adds much more

As a product owner
I want to use asciidoc formatting for my user stories
In order to better express my needs with well-formatted and pretty documents

As a quality engineer
I want to write examples (scenarios) using asciidoc
So that I can better express the features and underline important information using formatting and images

As a developer
I want to receive well-structured user stories to develop
So that I know exactly what I need to develop

As an end user
I want a pretty and well-formatted living documentation
So that I can quickly understand how the software works

As a tech lead
I want to generate a website using a tool like antora
In order to organize my documentation in a single well-structured documentation site

✨ What's your proposed solution?

There is currently a working markdown format so I think we can base ourselves on this module.
I haven't yet looked at the code though ..

⛏ Have you considered any alternatives or workarounds?

There is a project called cukedocktor that I have tried using for a while.
Unfortunately this project uses the old version of the cucumber framework pre-ndmessages and lacks some of the newer features
of the language like the rules.

It also seems like a redundant solution to the existing react html formatter.

📚 Any additional context?

Thanks for all of the hard work !

---

This text was originally generated from a template, then edited by hand. You can modify the template here.

[sashokbg]

Hello can anyone please give me some guidelines on where I can start from - I wish to try to implement the ASCIIDOC support :).
If I understand correctly I need to implement a Token Matcher just like GherkinInMarkdownTokenMatcher ?

https://github.com/cucumber/common/blob/main/gherkin/javascript/src/GherkinInMarkdownTokenMatcher.ts ?

[mattwynne]

Hey @sashokbg, thanks for pushing on this. It looks to me like you've found the right place in the code to get started. We'll want to see a test-driven solution, so also have a look at https://github.com/cucumber/common/tree/main/gherkin/testdata/ for acceptance tests. We'll also want to add something akin to https://github.com/cucumber/compatibility-kit/tree/main/devkit/samples/markdown so we can test support in the Cucumber implementations themselves.

If you want to chat 🍵 about this, you're welcome to join us in our community Slack in the #committers channel 😄

I'm also available for live pairing ⚡ you can book a slot with me here.

[aslakhellesoy]

Asciidoc is great, but it has lost to Markdown. Very few people use it.

For this reason I'm against adding Asciidoc support. I would rather we focus on improving Markdown support, which is already implemented in the JavaScript implementation of the Gherkin parser, but not yet ported to other languages.

If we haven't (yet) managed to make Markdown supported in all implementations, and also managed to make the community adopt it, why should we start another similar effort for a more obscure markup language?

[mpkorstanje]

Reading this I'm a little confused.

Is the purpose of this request to:

• Write features in Ascii Doc?
• Render features to Ascii Doc?
• Render test results to Ascii Doc?

[mpkorstanje]

Also, because I'm doing a clean up of old issues, I'm closing this because I doubt this will happen.

Never the less, please feel free to reopen this discussion.

[sashokbg]

Hello everyone, @mpkorstanje, @aslakhellesoy, @mattwynne

To answer your comments:

• Yes the feature is about writing features in asciidoc and is essentially the same as the markdown support
• @aslakhellesoy I don't think it is productive to discuss if one technology has "lost it" to another. There are clear benefits of using asciidoc over markdown and I do not wish to delve into the details - there is plenty of materials online for this.

I think however that I have a solution that might be good for everyone:

Instead of implementing asciidoc support in the gherkin / common repository we can just add some sort of "CustomFlavorRegistry" that allows us to register any arbitrary type that implements ITokenMatcher.

What we gain:

• Keep the code base clean and not over-complexified
• Open the code for extension (SPI style)
• Keep the code close for modification (SOLID)
• Allow nerds like myself to implement a third party plugin that supports asciidoc features by just implementing a new token matcher and calling a "CustomFlavorRegistry.registerNew()" or something like that.

I wrote some bits of code and can open a draft PR so that we can discuss more details if you wish.

P.S. Please let's keep the conversation productive and not talk about "why that effort" for "that technology that I don't use"

[sashokbg]

I thought i'd give a code example real quick to show how trivial adding "asciidoc" support will become with this new feature:

1. I modified the original token matcher to accept the prefixes so that we can override them
2. Implement or extend existing TokenMatcher

export default class GherkinInAsciidocTokenMatcher extends GherkinInMarkdownTokenMatcher {

    constructor(defaultDialectName: string = 'en') {
        const asciidocPrefixes = {
            BULLET: '^(\\s*[*\\.-]\\s*)',
            HEADER: '^(={1,6}\\s)',
        }
        super(defaultDialectName, asciidocPrefixes);
    }
}

3. Then register it

        CustomFlavorRegistry.getInstance().registerFlavor('asciidoc', '.adoc', new GherkinInAsciidocTokenMatcher());

[sashokbg]

PRs opened:

#95
cucumber/messages#139

[mpkorstanje]

I've reopened this issue. It may be a while before we get around to this one though. We're rather short handed at the moment

[sashokbg]

Thank you @mpkorstanje , please don't hesitate to ask me if you need help.
I am actually already using the code in the PRs in a forked repo for a project in our company.

I am very passionate about the topic of creating living documentation with asciidoc, antora and cucumber.
We can connect on slack / discord if you want to discuss or do pair program.