Jamal is a tool for automating documentation maintenance. You can avoid copying information from your documented system into the documentation and repeatedly copying it when the system is updated. It reduces the risk of outdated documentation by automating its maintenance.
Jamal can be used with Asciidoc, Markdown, XML, JSON, YAML, JavaDoc, and any other markup languages. The application integrates seamlessly into the document processing tools' pipeline in the least intrusive, non-invasive way.
Technically, Jamal is a meta-markup language enhancing the features of the original markup language. The conversion is done as a preprocessing step prior to the markup processing. It can be inserted into any toolchain without risk, as it can also be removed at any time.
TOC
|
|
|
|
Note
|
This is the latest development documentation.
To see the documentation of a release, you have to follow the link in the documentation RELEASES.adoc.
If you want to read the latest release, please visit Jamal2.5.0
|
Jamal is implemented as a Java library and is embedded in different applications. It can be used as a command-line tool, as a Maven plugin, as a Maven extension, as a JavaDoc doclet, as a JShell script, as a JBang script, as a Java library, and as a JSR223 script engine. The installation may be as simple as starting it from the command line (JBang) when the embedding application is already installed.
In the following sections, we will discuss how to install and use Jamal in the different applications it is embedded in.
You can start Jamal from Maven as a plugin. The plugin is available in the Maven Central repository.
To do that, you must have Maven installed. Having that, you can issue the command:
mvn com.javax0.jamal:jamal-maven-plugin:2.5.1-SNAPSHOT:jamalif you have a pom.xml file in your directory.
If you do not have one, then read the documentation of the Jamal Maven plugin at Jamal Maven Plugin README. It is short and straightforward.
You can use Jamal macros to maintain your Maven POM files.
Move the content of the POM XML into the file pom.jam and extend it freely with Jamal macros.
Create a .mvn directory with an extensions.xml file in your project root.
<?xml version="1.0" encoding="UTF-8"?>
<extensions>
<extension>
<groupId>com.javax0.jamal</groupId>
<artifactId>jamal-maven-extension</artifactId>
<version>2.5.1-SNAPSHOT</version>
</extension>
</extensions>Next time you start Maven, it will include Jamal in the processing chain.
It will also generate the pom.xml files from the pom.jam files, so your IDE and other tools that depend on the XML format keep working.
For more information about the Maven extension, read the documentation.
The repository contains the jamal.sh shell script that can be used to start Jamal from the command line.
It assumes that the libraries are already installed in the local Maven repository.
After that, you can type:
./jamal.sh
that will show you a short usage message:
Usage: jamal [options] input output
-help help
-shcnf show the configuration values from ~/.jamal/settings.(properties|xml)
-version display version
-verbose print out the conversions
-open=<macroOpen> the macro opening string
-close=<macroClose> the macro closing string
-depth=<depth> directory traversal depth, default is infinite
-debug=<debug> type:port, usually http:8080
-include=<include> file name regex pattern to include into the processing
-exclude=<exclude> file name regex pattern to exclude from the processing
-source=<sourceDirectory> source directory to start the processing
-target=<targetDirectory> target directory to create the output
-from=<regex> pattern for the file name transformation.
-to=<replacement> replacement for the file name transformation.
-dry-dry-run run dry, do not execute Jamal
-dry-run run dry, do not write result to output file
-docx treat the input as a docx, Microsoft Word file
-jamalize create the .asciidoctor/lib directory and download the Jamal Asciidoctor extensionFor more information about the command line version, read the documentation.
JBang (https://www.jbang.dev) is a popular command-line tool that eases the startup of Java applications. Jamal can be started using JBang. This is the recommended way to run Java from the command line if you have limited experience with Java. When running Jamal using JBang, JBang will install everything that is needed to execute Jamal in a clean and non-intrusive way.
JBang installation is described on the documentation page of JBang.
To start Jamal when you have J
Bang installed on your machine, type:
jbang jamal@verhas ... options ...This command will invoke the command line version automatically.
The syntax and meaning of the options are the same as in the case of the command line version.
This startup also loads all the safe Jamal extensions, including snippet, and debug and some others.
If you want to see the exact list of the modules this startup loads, have a look at the starter file.
|
Note
|
If you have used Jamal with JBang before, then JBang will store its catalog file in the local cache.
When you start Jamal using After that, you can start JBang again.
It will download the new catalog, always pointing to the latest release.
You will find the command that deletes this file in the root of the project in the shell script |
Using Jamal in IntelliJ together with the Asciidoctor plugin is fairly easy. All you have to do is download a ZIP file from the Maven repository and explode it into a directory. The details are described in the documentation.
When the installation is done, all you need to do is start IntelliJ and open the project. You can edit your AsciiDoc files, and the plugin will automatically invoke Jamal to process the macros.
If you want to use AsciidocFX, the same package should be used. The installation is similar, downloading the ZIP file and extracting it to a directory. The detailed documentation is in the documentation.
You can start using Jamal in five minutes as described in the tutorial, "Starting with Jamal in 5 minutes".
Jamal has many configuration parameters, but each of these has reasonable default values. It means that you do not need to configure Jamal before using it. Configuration is needed only when you want to change some of the default values or use a macro package that, without configuration, could pose a security risk.
Configuration values can be set in the following ways:
-
Using system properties
-
Using environment variables
-
Using a configuration file in the user’s home directory (
~/.jamal)
The configuration values are searched for in this order. Different macros use different configuration keys. They are documented along with the macro documentation.
The environment variables and their meanings are documented in their documentation.
Jamal is a meta markup language that extends existing markup languages in a transparent way. The language is designed so that it will not interfere with any existing or future markup.
The original markup, for example, AsciiDoc or Markdown, is responsible for formatting and semantic definition of the text. Jamal will do the extra task, which is not or in some cases only partially supported by the document markup. Without Jamal or some other similar tools, these tasks are performed manually.
Jamal can
-
collect information from source code and other non-document files,
-
transform the collected information to fit
-
the document markup,
-
the document format, and
-
the document semantics.
-
Jamal can include other files, parts of files, number the included lines, filter lines, replace parts of the lines, reorder lines, and many other things as needed.
When information exists in the documented system or in the documentation, it must not be manually copied. The copy and the transformation of the information must be automated.
Jamal is implemented in Java. You can write user-defined macros in Jamal itself and built-in macros in Java, Kotlin, or other JVM languages.
You can execute Jamal from Maven, Javadoc, CLI, AsciiDocFX, IntelliJ, and other applications. Jamal is extensible with multiple different SPIs. One such SPI is the debugging interface. The library includes a debugger that you can use via a React.js web client to debug the macro evaluations step-by-step.
The library comes with more than 200 macros for different purposes. The macros are grouped into modules. The largest module is the document maintenance module (snippet macros), but there are modules to handle
-
JSON,
-
YAML,
-
XML, and other data formats.
The use of Jamal makes it possible to include automatically generated images, for example, from PlantUML, Graphviz, or other tools into any markup-formatted document. You can also include programmatic formatting and content calculation using Groovy, Ruby, and other languages.
Jamal is an open-source project, and the developers welcome any contribution. We treat all suggestions, requests, comments, or any other contribution with respect.
First and foremost, you can contribute by using Jamal and giving feedback. Start using it and tell us what you like and what you do not like. A program without users is not a program. If you use Jamal, you are a contributor, and if you wish, we will include you as a reference in the documentation.
You can contribute to Jamal by reading the documentation. If you find a typo, a mistake, or something that is not clear, please tell us. The best way is to fork the project, fix the documentation, and send us a pull request. Even a single character correction is welcome as a full-blown pull request.
You can also write documentation. Writing documentation is a huge task, and we are happy to accept any help. We are gravely missing, for example, "How to" tutorials. Why? Because as developers, we develop Jamal first and our use is limited to the use cases we have. We are not using Jamal in the same way as you do.
Every use is different, write about it.
Jamal supports the JSR223 standard.
That way, Jamal can be used in any JSR223 compliant application that may need scripting.
The macro opening and closing strings are { and } in this case unless the script attributes open and close are set.
Script bindings are put into Jamal macros and are loaded from Jamal macros after execution.
We would love a tutorial describing this feature.
If you find Jamal fascinating, you can write an article about it. We have experience writing and publishing articles, and we can help you. We also write articles, but we cannot write your article.
Help us spread the word.
Talk about Jamal at conferences. Give a talk or just mention it in your presentation. Or just mention it at the coffee break or other social events.
If something does not work as you expect, please
tell us. It may be a code bug, or it may be a documentation bug.
It is NEVER a user error. If it works as we expect and not as you expect, then it is a bug in the documentation.
Use the GitHub issue tracker to report bugs. If you can locate the bug in the code and have a suggestion to fix it, then you can also send us a pull request.
If you miss a feature, please tell us. We will consider it, and if it is a good idea, we will implement it. If you can implement it, then send us a pull request.
Since Jamal is a complex program, the documentation is split into several parts. The modules, each has its documentation in the form of a README file in the module directory. Jamal is eating its own dog food, so the documentation is written in Jamal and AsciiDoc.
Here we will link the different documentation parts.
The core built-in macros are part of the core package. They contain those essential macros that are vital for the working and use of Jamal. These macros are documented in their separate documentation each.
They are
There are two special user-defined macros, output:writable and output:charset.
These can control the output file creation.
Note that this is not a core feature of Jamal, but most current embeddings (AsciiDoc, Maven plugin, and command line) support these macros.
By default, the generated file is not writable. This is to prevent accidental editing of the generated files. Many times the generated files are stored along with the Jamal files, and it is an easy mistake to edit the generated file. To prevent this, the generated file is read-only by default.
There are cases when the output has to be writable.
An example is the live template XML file that cannot be handled properly by IntelliJ if it is read-only.
If the value of the macro output:writable is true, then the generated file will be writable.
The macro output:charset can be used to set the character set of the generated file.
The default value is UTF-8.
Note that even if you set the character set to UTF-16LE, the generated file will not contain the BOM.
-
Jamal AsciiDoc Documentation, How to configure and use Jamal to edit AsciiDoc files using the IntelliJ editor in a WYSIWYG way, or the AsciiDocFX editor.
-
Jamal Doclet Documentation, How to use Jamal in Javadoc.
-
Jamal Maven Plugin README, How to use Jamal as a Maven plugin.
-
Jamal Maven Extension README, How to use Jamal as a Maven extension.
-
Jamal API Documentation, How to use Jamal as a Java library.
The debugger is a web-based, interactive tool using React.js. There is no separate documentation describing where to click and how to use it. The existing documentation describes the debugging architecture and how to start Jamal in debug mode.
Anyway, here is a screenshot of the debugger in action:
-
Ruby Module README, How to use Ruby code in your Jamal source
-
Groovy Module README, How to use Groovy code in your Jamal source
-
ScriptBasic Module README, How to use ScriptBasic code in your Jamal source
-
Prog Module README, How to use Prog code in your Jamal source is a simple BASIC-like language tightly integrated with Jamal.
-
Io Module README, How to read and write external files from Jamal macros
-
Jamal Jamal Module README, How to use Jamal inside Jamal as an embedded language
-
Jamal Markdown Module README, Convert markdown to HTML, mainly usable together with the Jamal Doclet to have Markdown in Javadoc
-
Jamal Mock Module README, Mock built-in macros to test macros that are to run in a specific environment
-
Jamal Snippet Module README, Use snippets to compile your documentation
-
Jamal Yaml Module README, Use data from Yaml files in your macros and use macros in your Yaml files
-
Jamal JSON Module README, Use data from JSON files in your macros and use macros in your JSON files
-
Jamal Assertions Module README, contains macros to make assertions to ensure the consistency of your documentation
-
DOCX Word Processing README, describes the Jamal Microsoft Word Processing module and the macros that are specific to DOCX processing
-
Jamal Test Module README, Use this module to test your own Java or Kotlin implemented macros.
Jamal uses GitHub. The changelog is maintained online on the GitHub releases page. There is also a local copy of the release notes.
The roadmap is maintained in the document: ROADMAP. It is more like a collection of ideas and plans than a strict roadmap.
See the separate document: FAQ.