Being able to generate an Asciidoc backend with the Asciidoctor Reducer

[agoncal]

What is this issue about?

• [ ] Bug report
• [x ] Feature request
• [ ] Question

Description

It is sometimes very useful to generate a single AsciiDoc out of AsciiDoc documents containing include directives. That's the purpose of Asciidoctor Reducer. It would be great to integrate the Reducer in the Maven plugin. As a user, this could be seen just as another backend (<backend>asciidoc</backend>):

<execution>
    <id>generate-asciidoc</id>
    <configuration>
        <backend>asciidoc</backend>
    </configuration>
</execution>

[abelsromero]

I see in the docs it actually runs an Asciidoctor extension, which means "in theory" the gem could be installed with gem-maven-plugin and the extension run as any other.

Would it help if we documented and maintained an example in the asciidoctor-maven-examples repo?

[agoncal]

Oh, I wasn't aware of the gem-maven-plugin plugin. Well, if it's just installing a new Gem with the Maven plugin and setting it up, documenting it would be a great start.

[abelsromero]

Sadly not possible yet 😞 but I could hack it by adding a few lines to the plugin.

We could do this with some caveats:

1. We need to expose new properties in AsciidoctorJ API https://github.com/asciidoctor/asciidoctorj/issues/1143.
2. Since reducer does not use convert but load, we'd need to signal that to the plugin. The idea of using a backend is fine for me.
3. We cannot manage the gem installation, nor I think is a good idea to add extra logic. So users will still need to install the gem with gem-plugin.
4. This will be documented as an experimental feature, fully supported but subject to the evolution of asciidoctor-reducer.

@mojavelinux I wonder if you see any issue with the approach? I can see how presenting it as a backend when it's not, can create confusion to users, but it's a great project and adding it to maven will offer more exposure for it.

[mojavelinux]

I'm fine with the idea of exposing it as a backend target...and it might be interested to see if we can add a mode to Asciidoctor Reducer that makes it function as a true converter. I hadn't really thought of that before.

[agoncal]

Well, and if Asciidoc could be exposed as a new backend, what about Markdown? I had a look at downdoc and used it to export a Asciidoc to Markdown. Works great. If it could be integrated within the Asciidoctor Maven plugin as another backend, that would be great.

[abelsromero]

downdoc and used it to export a Asciidoc to Markdown

Functionally it could make sense, but it won't be as easy, being a CLi in JS. To run in Java it would need GraalVM interpreter and some bindings. I'd advocate having the bindings in another project exposing it as an actual converter and then, we could consider integrating. I like to keep the maven plugin thin and adding bindings for specific projects is extending the scope too much imo.

[mojavelinux]

Functionally it could make sense, but it won't be as easy, being a CLi in JS

downdoc will eventually be available as a Ruby application. I want to finish it first, though, since I don't want to have to make changes in two different languages while developing it.

[abelsromero]

downdoc will eventually be available as a Ruby application.

That would be awesome! I created a story to track it https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/619. Please, refer to it for any comment with downdoc.