How to programmatically generate asciidoc syntax?

[andi-huber]

Given following JUnit Test ...

import java.util.HashMap;

import org.asciidoctor.Asciidoctor;
import org.asciidoctor.ast.Document;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;

class AsciiDocWriterTest {

    private Document doc;

    @BeforeEach
    void setUp() throws Exception {
        Asciidoctor asciidoctor = Asciidoctor.Factory.create();
        doc = asciidoctor.load("", new HashMap<String, Object>()); // generate a blank/empty document object
    }

    @Test
    void test() {

        doc.setTitle("Hello World"); // manipulate the abstract syntax tree (set a doc title)

        String actualAdoc = toString(doc); 
        String expectedAdoc = "= Hello World";

        assertEquals(expectedAdoc, actualAdoc);
    }

    /**
     * the inverse of {@link Asciidoctor#load(String, java.util.Map)}}
     */
    private static String toString(Document doc) {
        // TODO implement
        return null;
    }

}

How would I implement the helper method toString(...) at the bottom?

Context: I do want to generate adoc syntax programmatically using Java. Thought the asciidoctorj abstract syntax tree would be an excellent model to get me started.

[andi-huber]

I guess my question is whether there is already some Writer available that would do this for me. (don't want to reinvent the wheel if possible)

[robertpanzer]

I am not aware of such a converter.

[andi-huber]

Ok, need to write some code then. Anyway thanks for the quick response!

[mojavelinux]

The document object itself does not have a toAsciiDoc() feature, though it's certainly a reasonable suggestion.

Currently, all conversion is handled by the converter API. So one approach is to make an AsciiDoc converter. The convenience of the converter is that it walks the tree for you, so you only need to handle each node as it comes.

You may also be interested in the AsciiDoc writer I implemented for kramdoc. See https://github.com/asciidoctor/kramdown-asciidoc/blob/master/lib/kramdown-asciidoc/writer.rb. Poke around for how it is used.

[andi-huber]

Thanks for the directions!

I've started a Java project under the Apache Isis Tooling umbrella here: https://github.com/apache/isis/tree/master/tooling/asciidoc-model

Nowhere near complete, but we are yet able to model and write basic ascii-doc tables and will just extend as required.

Also if anybody is interested to contribute, we are happy to accept PRs. (Maven snapshots are published on a daily basis.)

[mojavelinux]

If you haven't already, I strongly encourage you to join the specification effort for AsciiDoc under the AsciiDoc Working Group. See https://projects.eclipse.org/proposals/asciidoc-language and https://accounts.eclipse.org/mailing-list/asciidoc-wg. We'd certainly value your participation and input.

Due note that the AsciiDoc name is now trademarked by Eclipse Foundation. As such, I believe I'm accurate in saying that the project would need to be named model-for-asciidoc (or model4asciidoc) rather than asciidoc-model. (According to the guidelines, a project called something like "Foo for AsciiDoc" would be fine, but "Asciidoc Foo" would not. The former form suggests a separation, but the latter suggests a tight coupling). The project must also mention that AsciiDoc is a registered trademark of the Eclipse Foundation. We'll be putting out guidelines in the near future to help projects with naming. For now, see https://www.eclipse.org/lists/incubation/msg00723.html. The idea is to avoid confusion about what the AsciiDoc name means for the benefit of us all.

[andi-huber]

Thanks for the directions once more! I'll see that I update things to respect your policies.

[mojavelinux]

Thanks Andi!

[andi-huber]

Project now moved to (in accordance with the suggested change of naming) ... https://github.com/apache/isis/tree/master/tooling/model4adoc

I also placed notices at multiple places (source code, artifact description, README) pointing to the info provided above. And also informing developers, that we are happy to help transferring source code, should there be any project, under the umbrella of the AsciiDoc Working Group, that is willing to take over.

[mojavelinux]

That's awesome. I look forward to working with you! Great things ahead, especially in the development of APIs.

[oliviercailloux]

The document object itself does not have a toAsciiDoc() feature, though it's certainly a reasonable suggestion.

I was surprised to find out in this issue, after having written code using AsciidoctorJ to parse an existing document and change it slightly, that it is currently impossible to get the thus modified AsciiDoc form back. I was expecting to be able to generate it back as a string.

(Just wanted to mention that such a feature would be useful to at least one person.)

[dgautier]

I'm also interested to find a way to load an existing adoc, modify it and save it back as an adoc file.

I didn't find anything useful at the moment, if anybody as any tips, examples, libraries that can do the trick ?

Thanks

[andi-huber]

Meanwhile for reference: The ASF project Isis was renamed to Apache Causeway. We also relocated the former AsciiDoc factory packages to

<dependency>
    <groupId>org.apache.causeway.valuetypes</groupId>
    <artifactId>causeway-valuetypes-asciidoc-builder</artifactId>
</dependency>

which is now part of our official releases. If all goes well, we'll have final releases 2.0.0 and 3.0.0 in spring (2024).

With these tools you can create AsciiDoc documents programmatically (from scratch). However, only a subset of features is supported.

See also https://github.com/apache/causeway/tree/master/valuetypes/asciidoc/builder

[dgautier]

Hi @andi-huber ,

It doesn't seems that it answers to the first part of the requirement which is to load an existing adoc and modify it.

I have found this https://github.com/Swagger2Markup/markup-document-builder which seems to do quite the same thing as this one : https://github.com/apache/causeway/tree/master/valuetypes/asciidoc/builder

Any other ideas ?