scriptingReadme.adoc.jim

In this chapter, I will tell the story and the technology used to maintain this documentation file.
Several macros are used during the maintenance of the documentation to ensure that the documentation is correct and up-to-date.
This particular document's processing uses {%$Lang%} scripts, which are used instead of some built-in macros for demonstration purposes.


The documentation of Jamal is a series of Asciidoc files.
The Asciidoc format was invented to be a documentation source format that is easy to read and edit.
At the same time, Jamal can also convert it to many different output formats.
Asciidoc, however, provides only limited possibility to eliminate redundancy and to ensure consistency.
This is where Jamal comes into play.

Jamal's documentation is maintained in `xxx.adoc.jam` files, and they are converted to `xxx.adoc` files.
With this workflow, the Asciidoc files are not source files.
They are intermediate files along the conversion path.
Jamal `define` macros are used to eliminate text repetition, redundancy whenever it is possible.
The Jamal snippet library macros are used to keep the sample codes included in the document up-to-date.

[NOTE]
====
When reading this part of the documentation, you are probably familiar with the basic functionalities of Jamal.
If you need to refresh the memory, then read the link:{%@file README.adoc%}[documentation] in the project's root folder.
Snippet macros are documented in the link:{%@file jamal-snippet/README.adoc%}[Snippet README.adoc] file.
It is unnecessary to know and understand how the snippet macros work to read this chapter, but it is a recommended read in general.
====

Technical documentation using Jamal and the snippet macros usually generates the documentation in multiple steps.

* Run the tests, including the sample code, and capture the sample output in one or more output files.

* Process the Jamal source of the documentation and include from the source code and the generated sample output files the samples.

For example, a Java application can support the documentation with unit test samples.
Some of the unit tests serve the purpose of testing only, while others are there to document specific code parts.
The output of the documentation purposed tests is captured into output files.
The test file `{%#file jamal-{%$lang%}/src/test/java/javax0/jamal/{%$lang%}/Test{%$Lang%}Macros.java%}` contains

[source,java]
----
{%#trimLines
    // snippet sample_snippet
{%@snip sample_snippet%}\
    // end snippet
%}
----
To get this content into the document what we have to write is the following:

{%@escape `ESCAPE`
        [source,java]
        ----
        // snippet sample_snippet
        {%@snip sample_snippet %}\
        // end snippet
        ----
`ESCAPE`%}

The output generated (none in this case) can also be included using the `snip` macro.

It is logical to run the tests and generate the test output in an initial step in the case of Java.
However, when we test and document Jamal processing, it is a logical idea to use the Jamal environment, which is converting the documentation.
The external approach with an initial step is also possible, but it is not needed.

The sample Jamal code can be included in the documentation as a code sample.
Using Jamal macros, Jamal can also convert it to the corresponding output, which can also be included in the resulting document without saving it into an intermediate file.

To do that, the Jamal Snippet package unit test file
`{%@file jamal-snippet/src/test/java/javax0/jamal/documentation/TestConvertReadme.java%}`
uses a built-in macro, implemented in the file:

* `{%@file jamal-snippet/src/test/java/javax0/jamal/documentation/Output.java%}`

This Java implemented macro is available on the classpath when the unit test runs.

[NOTE]
====
Executing the Jamal processing of a Java software package documentation via the unit tests has other advantages.
The macros `java:class` and `java:method` can check that the class and method names referenced in the document are valid.
Class and method names may change during refactoring.
The documentation many times does not follow this change and becomes stale.
When the classes and methods are referenced using these macros, they throw an exception if the class or method does not exist.
====

This class is very simple:

[source,java]
----
{%@snip Output_java
public class Output implements Macro {
    final Processor localProc = new javax0.jamal.engine.Processor("{", "}");

    @Override
    public String evaluate(Input in, Processor processor) throws BadSyntax {
        return localProc.process(new javax0.jamal.tools.Input(in.toString(), in.getPosition()));
    }
}
%}\
----

It creates a single Jamal processor instance and uses it to evaluate the input passed to it.
This macro runs a Jamal processor separate from the Jamal processor that is converting the document.
However, the two Jamal processors run in the same JVM, and one is invoking the other through this built-in macro.

To simplify the use, there is a `{%@file readmemacros.jim%}` macro import file that defines the user-defined macro `sample` and `output`.
(A built-in macro can have the same name as a user-defined.)
The macro `sample` results in its content in Asciidoc code sample format, adding `[source]\n----` before and `----` after the sample code.
At the same time, it also saves the sample code in a user-defined variable called `lastCode`.
The macro `output` uses the `lastCode` and using the built-in `output` from the `Output.java` displays the calculated result as a code block.

It is very similar when we are using {%$Lang%}, but in this case, we do not need the built-in macro `output`.
When Jamal converts this document, the {%@file readmemacros.jim%}` inside the `jamal-{%$lang%}` directory contains some {%$Lang%} scripts instead of the built-in macros.

The unit test code that invokes the Jamal processor to convert this document is the following: