From 171730e4ca3235f7717ec957602b23bcba8a2355 Mon Sep 17 00:00:00 2001 From: Peter Verhas Date: Sun, 28 Feb 2021 17:45:52 +0100 Subject: [PATCH] release 1.7.2 --- BUILTIN.adoc | 6 ++-- README.adoc | 6 ++-- jamal-api/pom.xml | 4 +-- jamal-cmd/pom.xml | 4 +-- jamal-core/pom.xml | 4 +-- jamal-engine/pom.xml | 4 +-- jamal-extensions/pom.xml | 4 +-- jamal-groovy/README.adoc | 67 ++++++++++++++++++----------------- jamal-groovy/pom.xml | 8 ++--- jamal-maven-plugin/pom.xml | 4 +-- jamal-plantuml/README.adoc | 2 +- jamal-plantuml/pom.xml | 6 ++-- jamal-ruby/README.adoc | 67 ++++++++++++++++++----------------- jamal-ruby/pom.xml | 8 ++--- jamal-scriptbasic/README.adoc | 2 +- jamal-scriptbasic/pom.xml | 10 +++--- jamal-snippet/README.adoc | 20 +++++------ jamal-snippet/README.adoc.jam | 10 +++--- jamal-snippet/pom.xml | 4 +-- jamal-test/pom.xml | 4 +-- jamal-testsupport/pom.xml | 4 +-- jamal-tools/pom.xml | 4 +-- pom.xml | 20 +++++------ scriptingReadme.adoc.jim | 65 ++++++++++++++++----------------- version.jim | 2 +- 25 files changed, 171 insertions(+), 168 deletions(-) diff --git a/BUILTIN.adoc b/BUILTIN.adoc index 30f246798..ec0bac1cd 100644 --- a/BUILTIN.adoc +++ b/BUILTIN.adoc @@ -38,7 +38,7 @@ You need the following dependency in your project: com.javax0.jamal jamal-api - 1.7.2-SNAPSHOT + 1.7.2 ---- @@ -50,7 +50,7 @@ In later versions, when we will do a bit more in our macros we will also need th com.javax0.jamal jamal-tools - 1.7.2-SNAPSHOT + 1.7.2 ---- @@ -105,7 +105,7 @@ To do that you have to add the dependency to your `pom.xml` file: com.javax0.jamal jamal-testsupport - 1.7.2-SNAPSHOT + 1.7.2 test ---- diff --git a/README.adoc b/README.adoc index 3600e00d7..6b89d7bb3 100644 --- a/README.adoc +++ b/README.adoc @@ -2613,7 +2613,7 @@ will result [source] ---- -The current version 1.7.2-SNAPSHOT is older than the required version. It has to be newer. +The current version 1.7.2 is older than the required version. It has to be newer. ---- @@ -2727,7 +2727,7 @@ For example to add the pomlib library JAR to the classpath you can use the follo com.javax0.jamal jamal-maven-plugin - 1.7.2-SNAPSHOT + 1.7.2 execution @@ -2820,7 +2820,7 @@ If you use Maven, you can simply have com.javax0.jamal jamal-engine - 1.7.2-SNAPSHOT + 1.7.2 ---- diff --git a/jamal-api/pom.xml b/jamal-api/pom.xml index 03d685cf9..774e6489c 100644 --- a/jamal-api/pom.xml +++ b/jamal-api/pom.xml @@ -4,11 +4,11 @@ jamal api jar jamal-api - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library API interfaces diff --git a/jamal-cmd/pom.xml b/jamal-cmd/pom.xml index 41fa9287e..f44fac9ab 100644 --- a/jamal-cmd/pom.xml +++ b/jamal-cmd/pom.xml @@ -4,11 +4,11 @@ jamal command line jar jamal-cmd - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library command line interface diff --git a/jamal-core/pom.xml b/jamal-core/pom.xml index e54513d8d..2f4fcad96 100644 --- a/jamal-core/pom.xml +++ b/jamal-core/pom.xml @@ -4,11 +4,11 @@ jamal core jar jamal-core - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library built-in macros diff --git a/jamal-engine/pom.xml b/jamal-engine/pom.xml index 23687fcef..9db740e18 100644 --- a/jamal-engine/pom.xml +++ b/jamal-engine/pom.xml @@ -4,11 +4,11 @@ jamal engine jar jamal-engine - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library execution engine diff --git a/jamal-extensions/pom.xml b/jamal-extensions/pom.xml index 1fe0b72c1..cab0ae68a 100644 --- a/jamal-extensions/pom.xml +++ b/jamal-extensions/pom.xml @@ -5,11 +5,11 @@ jar com.javax0.jamal jamal-extensions - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library extra macros diff --git a/jamal-groovy/README.adoc b/jamal-groovy/README.adoc index 7fdc5f617..982c4fbfd 100644 --- a/jamal-groovy/README.adoc +++ b/jamal-groovy/README.adoc @@ -9,7 +9,7 @@ To use this module you have to add the dependency to you Maven project, as: com.javax0.jamal jamal-groovy - 1.7.2-SNAPSHOT + 1.7.2 ---- @@ -358,39 +358,40 @@ The second evaluation is performed in a different shell, but the definition of t === Sample Application, Converting this `README.adoc` -In this chapter I will tell the story, and the technology used to maintain this documentation file. -There are several macros used during the maintenance of the documentation to ensure that the documentation is correct and up-to-date. -The processing of this special document uses Groovy scripts, which are used instead of some built-in macros for demonstration purposes. +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 Groovy scripts, which are used instead of some built-in macros for demonstration purposes. The documentation of Jamal is a series of Asccidoc files. The Asciidoc format was invented to be a documentation source format that is easy to read and edit. -The same time it can also be converted to many different output formats. -Asciidoc, however, is provides only limited possibility to eliminate redundancy, and to ensure consistency. +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. -The documentation of Jamal 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, rather intermediate files along the conversion path. +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:README.adoc[documentation] in root folder of the project. -The documentation of the Snippet macros are documented in the link:jamal-snippet/README.adoc[Snippet README.adoc] file. -It is not necessary to know and understand how the snippet macros work in order to read this chapter, but in general, it is a recommended read. +If you need to refresh the memory, then read the link:README.adoc[documentation] in the project's root folder. +Snippet macros are documented in the link: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. ==== -The technical documentations using Jamal and the snippet macros usually generate the documentation in multiple steps. +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 file. +* 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 from the generated sample output files the samples. +* 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 certain part of the code. -The output of the documentation purposed tests are captured into output files. +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 `jamal-groovy/src/test/java/javax0/jamal/groovy/TestGroovyMacros.java` contains [source,java] @@ -417,14 +418,14 @@ To get this content into the document what we have to write is the following: The output generated (none in this case) can also be included using the `snip` macro. -This is absolutely logical to run the tests, and generate the test output in a prior test in case of Java. -When we test and document Jamal processing, however, it is a logical idea to use the Jamal environment, which is converting the documentation. -The external approach with a proir step is also possible, but it is not needed. +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 code sample. -Using Jamal macros it can also be converted to the corresponding output, which can also be included into the resulting document without saving it into an intermediate file. +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 +To do that, the Jamal Snippet package unit test file `jamal-snippet/src/test/java/javax0/jamal/documentation/TestConvertReadme.java` uses a built-in macro, implemented in the file: @@ -434,11 +435,11 @@ This Java implemented macro is available on the classpath when the unit test run [NOTE] ==== -Executing the Jamal processing of the documentation of a Java software package via the unit tests has other advantages. +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 then they throw an exception if the class or method does not exits. +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: @@ -456,17 +457,17 @@ public class Output implements Macro { ---- It creates a single Jamal processor instance and uses it to evaluate the input passed to it. -This way this macro runs a Jamal processor separate from the Jamal processor that is converting the document. -The two Jamal processors, however, run in the same JVM and one is invoking the other through this built-in macro. +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 `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 the content of it in Asciidoc code sample format adding `[source]\n----` before and `----` after the sample code. -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 buil-in `output` from the `Output.java` displays the calculated result as a code block. +To simplify the use, there is a `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. -This is very similar when we are using Groovy, but in this case we do not need the built-in macro `output`. -When this very document is converted the readmemacros.jim` inside the `jamal-groovy` directory contains some Groovy scripts instead of the built-in macros. +It is very similar when we are using Groovy, but in this case, we do not need the built-in macro `output`. +When Jamal converts this document, the readmemacros.jim` inside the `jamal-groovy` directory contains some Groovy scripts instead of the built-in macros. The unit test code that invokes the Jamal processor to convert this document is the following: diff --git a/jamal-groovy/pom.xml b/jamal-groovy/pom.xml index dceacad77..c9015d054 100644 --- a/jamal-groovy/pom.xml +++ b/jamal-groovy/pom.xml @@ -3,11 +3,11 @@ 4.0.0 jamal groovy jamal-groovy - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Groovy module for Jamal @@ -46,13 +46,13 @@ com.javax0.jamal jamal-testsupport - 1.7.2-SNAPSHOT + 1.7.2 test com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 test diff --git a/jamal-maven-plugin/pom.xml b/jamal-maven-plugin/pom.xml index f4a9313f3..a69f9d09c 100644 --- a/jamal-maven-plugin/pom.xml +++ b/jamal-maven-plugin/pom.xml @@ -4,11 +4,11 @@ jamal maven plugin maven-plugin jamal-maven-plugin - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library maven plugin diff --git a/jamal-plantuml/README.adoc b/jamal-plantuml/README.adoc index ce0937ef9..0969fc27c 100644 --- a/jamal-plantuml/README.adoc +++ b/jamal-plantuml/README.adoc @@ -148,7 +148,7 @@ The maven coordinates for the Jamal module are: com.javax0.jamal jamal-plantuml - 1.7.2-SNAPSHOT + 1.7.2 ---- diff --git a/jamal-plantuml/pom.xml b/jamal-plantuml/pom.xml index df11b4c1a..882884ecc 100644 --- a/jamal-plantuml/pom.xml +++ b/jamal-plantuml/pom.xml @@ -4,11 +4,11 @@ jamal plantuml jar jamal-plantuml - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library snippet macros @@ -57,7 +57,7 @@ com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 test diff --git a/jamal-ruby/README.adoc b/jamal-ruby/README.adoc index a34523a43..21f5ba2c0 100644 --- a/jamal-ruby/README.adoc +++ b/jamal-ruby/README.adoc @@ -10,7 +10,7 @@ To use this module you have to add the dependency to you Maven project, as: com.javax0.jamal jamal-ruby - 1.7.2-SNAPSHOT + 1.7.2 ---- @@ -422,39 +422,40 @@ The second evaluation is performed in a different shell, but the definition of t -In this chapter I will tell the story, and the technology used to maintain this documentation file. -There are several macros used during the maintenance of the documentation to ensure that the documentation is correct and up-to-date. -The processing of this special document uses Ruby scripts, which are used instead of some built-in macros for demonstration purposes. +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 Ruby scripts, which are used instead of some built-in macros for demonstration purposes. The documentation of Jamal is a series of Asccidoc files. The Asciidoc format was invented to be a documentation source format that is easy to read and edit. -The same time it can also be converted to many different output formats. -Asciidoc, however, is provides only limited possibility to eliminate redundancy, and to ensure consistency. +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. -The documentation of Jamal 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, rather intermediate files along the conversion path. +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:README.adoc[documentation] in root folder of the project. -The documentation of the Snippet macros are documented in the link:jamal-snippet/README.adoc[Snippet README.adoc] file. -It is not necessary to know and understand how the snippet macros work in order to read this chapter, but in general, it is a recommended read. +If you need to refresh the memory, then read the link:README.adoc[documentation] in the project's root folder. +Snippet macros are documented in the link: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. ==== -The technical documentations using Jamal and the snippet macros usually generate the documentation in multiple steps. +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 file. +* 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 from the generated sample output files the samples. +* 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 certain part of the code. -The output of the documentation purposed tests are captured into output files. +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 `jamal-ruby/src/test/java/javax0/jamal/ruby/TestRubyMacros.java` contains [source,java] @@ -486,14 +487,14 @@ To get this content into the document what we have to write is the following: The output generated (none in this case) can also be included using the `snip` macro. -This is absolutely logical to run the tests, and generate the test output in a prior test in case of Java. -When we test and document Jamal processing, however, it is a logical idea to use the Jamal environment, which is converting the documentation. -The external approach with a proir step is also possible, but it is not needed. +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 code sample. -Using Jamal macros it can also be converted to the corresponding output, which can also be included into the resulting document without saving it into an intermediate file. +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 +To do that, the Jamal Snippet package unit test file `jamal-snippet/src/test/java/javax0/jamal/documentation/TestConvertReadme.java` uses a built-in macro, implemented in the file: @@ -503,11 +504,11 @@ This Java implemented macro is available on the classpath when the unit test run [NOTE] ==== -Executing the Jamal processing of the documentation of a Java software package via the unit tests has other advantages. +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 then they throw an exception if the class or method does not exits. +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: @@ -525,17 +526,17 @@ public class Output implements Macro { ---- It creates a single Jamal processor instance and uses it to evaluate the input passed to it. -This way this macro runs a Jamal processor separate from the Jamal processor that is converting the document. -The two Jamal processors, however, run in the same JVM and one is invoking the other through this built-in macro. +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 `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 the content of it in Asciidoc code sample format adding `[source]\n----` before and `----` after the sample code. -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 buil-in `output` from the `Output.java` displays the calculated result as a code block. +To simplify the use, there is a `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. -This is very similar when we are using Ruby, but in this case we do not need the built-in macro `output`. -When this very document is converted the readmemacros.jim` inside the `jamal-ruby` directory contains some Ruby scripts instead of the built-in macros. +It is very similar when we are using Ruby, but in this case, we do not need the built-in macro `output`. +When Jamal converts this document, the readmemacros.jim` inside the `jamal-ruby` directory contains some Ruby scripts instead of the built-in macros. The unit test code that invokes the Jamal processor to convert this document is the following: diff --git a/jamal-ruby/pom.xml b/jamal-ruby/pom.xml index bde003c1b..b5059fe86 100644 --- a/jamal-ruby/pom.xml +++ b/jamal-ruby/pom.xml @@ -3,11 +3,11 @@ 4.0.0 jamal ruby jamal-ruby - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Ruby module for Jamal @@ -46,13 +46,13 @@ com.javax0.jamal jamal-testsupport - 1.7.2-SNAPSHOT + 1.7.2 test com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 test diff --git a/jamal-scriptbasic/README.adoc b/jamal-scriptbasic/README.adoc index e8c2ce1ba..ab5c4c6cf 100644 --- a/jamal-scriptbasic/README.adoc +++ b/jamal-scriptbasic/README.adoc @@ -10,7 +10,7 @@ To use this module you have to add the dependency to you Maven project, as: com.javax0.jamal jamal-scriptbasic - 1.7.2-SNAPSHOT + 1.7.2 ---- diff --git a/jamal-scriptbasic/pom.xml b/jamal-scriptbasic/pom.xml index c84010827..0b06e4496 100644 --- a/jamal-scriptbasic/pom.xml +++ b/jamal-scriptbasic/pom.xml @@ -3,11 +3,11 @@ 4.0.0 jamal scriptbasic jamal-scriptbasic - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 ScriptBasic support for Jamal @@ -34,18 +34,18 @@ com.javax0.jamal jamal-testsupport - 1.7.2-SNAPSHOT + 1.7.2 test com.javax0.jamal jamal-api - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-engine - 1.7.2-SNAPSHOT + 1.7.2 test diff --git a/jamal-snippet/README.adoc b/jamal-snippet/README.adoc index 26621aeca..eb38695a1 100644 --- a/jamal-snippet/README.adoc +++ b/jamal-snippet/README.adoc @@ -20,7 +20,7 @@ For example, if you want to use the latest version of Jamal Snippet macro as a d com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 ---- @@ -89,7 +89,7 @@ If you are using Jamal programmatically or from Maven then the dependency you ha com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 ---- @@ -300,7 +300,7 @@ The result is: [source] ---- ... -1.7.2-SNAPSHOT +1.7.2 ... ---- @@ -1075,7 +1075,7 @@ For example, 4.0.0jamal snippetjar -com.javax0.jamaljamal-snippet1.7.2-SNAPSHOT +com.javax0.jamaljamal-snippet1.7.2 } ---- @@ -1091,7 +1091,7 @@ will result jar com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 ---- @@ -1107,7 +1107,7 @@ For example, {@define tabsize=0} 4.0.0jamal snippetjar -com.javax0.jamaljamal-snippet1.7.2-SNAPSHOT +com.javax0.jamaljamal-snippet1.7.2 } ---- @@ -1123,7 +1123,7 @@ will result jar com.javax0.jamal jamal-snippet -1.7.2-SNAPSHOT +1.7.2 ---- @@ -1145,7 +1145,7 @@ The rpevious example that we used before can be formulated also this way. 4.0.0jamal snippetjar -com.javax0.jamaljamal-snippet1.7.2-SNAPSHOT +com.javax0.jamaljamal-snippet1.7.2 ---- @@ -1162,7 +1162,7 @@ It will result the same output as before: jar com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 ---- @@ -1184,7 +1184,7 @@ wll result the output [source] ---- -2021-02-27 20:56:30 +2021-02-28 17:44:26 ---- diff --git a/jamal-snippet/README.adoc.jam b/jamal-snippet/README.adoc.jam index dfc99d442..cb28da58e 100644 --- a/jamal-snippet/README.adoc.jam +++ b/jamal-snippet/README.adoc.jam @@ -283,7 +283,7 @@ The result is: [source] ---- ... -1.7.2-SNAPSHOT +1.7.2 ... ---- @@ -1091,7 +1091,7 @@ will result jar com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 ---- @@ -1125,7 +1125,7 @@ will result jar com.javax0.jamal jamal-snippet -1.7.2-SNAPSHOT +1.7.2 ---- @@ -1166,7 +1166,7 @@ It will result the same output as before: jar com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 ---- %} @@ -1189,7 +1189,7 @@ wll result the output {%@snip dateOutput [source] ---- -2021-02-27 20:56:30 +2021-02-28 17:44:26 ---- %} diff --git a/jamal-snippet/pom.xml b/jamal-snippet/pom.xml index f46583aa4..32edbda8c 100644 --- a/jamal-snippet/pom.xml +++ b/jamal-snippet/pom.xml @@ -4,11 +4,11 @@ jamal snippet jar jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library snippet macros diff --git a/jamal-test/pom.xml b/jamal-test/pom.xml index 8959fcb27..070c201ea 100644 --- a/jamal-test/pom.xml +++ b/jamal-test/pom.xml @@ -4,11 +4,11 @@ jamal test jar jamal-test - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library integration tests diff --git a/jamal-testsupport/pom.xml b/jamal-testsupport/pom.xml index 5a5d6ccf9..a8f1f0a0d 100644 --- a/jamal-testsupport/pom.xml +++ b/jamal-testsupport/pom.xml @@ -4,11 +4,11 @@ jamal testsupport jar jamal-testsupport - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library macro test supporting classes diff --git a/jamal-tools/pom.xml b/jamal-tools/pom.xml index f4ce1690c..957ae7aed 100644 --- a/jamal-tools/pom.xml +++ b/jamal-tools/pom.xml @@ -4,11 +4,11 @@ jamal tools jar jamal-tools - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 -in Jamal macro library support tools diff --git a/pom.xml b/pom.xml index 39543ad0e..830ebf647 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ pom com.javax0.jamal jamal-parent - 1.7.2-SNAPSHOT + 1.7.2 Jamal macro library to process text files jamal-engine @@ -148,47 +148,47 @@ com.javax0.jamal jamal-testsupport - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-api - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-core - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-tools - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-engine - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-extensions - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-scriptbasic - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-snippet - 1.7.2-SNAPSHOT + 1.7.2 com.javax0.jamal jamal-plantuml - 1.7.2-SNAPSHOT + 1.7.2 org.junit.jupiter diff --git a/scriptingReadme.adoc.jim b/scriptingReadme.adoc.jim index 7f48068dc..a61f88203 100644 --- a/scriptingReadme.adoc.jim +++ b/scriptingReadme.adoc.jim @@ -1,36 +1,37 @@ -In this chapter I will tell the story, and the technology used to maintain this documentation file. -There are several macros used during the maintenance of the documentation to ensure that the documentation is correct and up-to-date. -The processing of this special document uses {%$Lang%} scripts, which are used instead of some built-in macros for demonstration purposes. +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 Asccidoc files. The Asciidoc format was invented to be a documentation source format that is easy to read and edit. -The same time it can also be converted to many different output formats. -Asciidoc, however, is provides only limited possibility to eliminate redundancy, and to ensure consistency. +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. -The documentation of Jamal 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, rather intermediate files along the conversion path. +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 root folder of the project. -The documentation of the Snippet macros are documented in the link:{%@file jamal-snippet/README.adoc%}[Snippet README.adoc] file. -It is not necessary to know and understand how the snippet macros work in order to read this chapter, but in general, it is a recommended read. +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. ==== -The technical documentations using Jamal and the snippet macros usually generate the documentation in multiple steps. +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 file. +* 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 from the generated sample output files the samples. +* 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 certain part of the code. -The output of the documentation purposed tests are captured into output files. +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] @@ -54,14 +55,14 @@ To get this content into the document what we have to write is the following: The output generated (none in this case) can also be included using the `snip` macro. -This is absolutely logical to run the tests, and generate the test output in a prior test in case of Java. -When we test and document Jamal processing, however, it is a logical idea to use the Jamal environment, which is converting the documentation. -The external approach with a proir step is also possible, but it is not needed. +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 code sample. -Using Jamal macros it can also be converted to the corresponding output, which can also be included into the resulting document without saving it into an intermediate file. +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 +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: @@ -71,11 +72,11 @@ This Java implemented macro is available on the classpath when the unit test run [NOTE] ==== -Executing the Jamal processing of the documentation of a Java software package via the unit tests has other advantages. +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 then they throw an exception if the class or method does not exits. +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: @@ -95,17 +96,17 @@ public class Output implements Macro { ---- It creates a single Jamal processor instance and uses it to evaluate the input passed to it. -This way this macro runs a Jamal processor separate from the Jamal processor that is converting the document. -The two Jamal processors, however, run in the same JVM and one is invoking the other through this built-in macro. +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 the content of it in Asciidoc code sample format adding `[source]\n----` before and `----` after the sample code. -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 buil-in `output` from the `Output.java` displays the calculated result as a code block. +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. -This is very similar when we are using {%$Lang%}, but in this case we do not need the built-in macro `output`. -When this very document is converted the {%@file readmemacros.jim%}` inside the `jamal-{%$lang%}` directory contains some {%$Lang%} scripts instead of the built-in macros. +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: diff --git a/version.jim b/version.jim index 0aa43ba61..6d9324b11 100644 --- a/version.jim +++ b/version.jim @@ -2,7 +2,7 @@ -{@define VERSION=1.7.2-SNAPSHOT} +{@define VERSION=1.7.2} {@define LAST_RELEASE=1.7.1}