command line version packaged got documented

T7 command line option was added jpackage was removed from the build process
verhas · Oct 7, 2024 · bf43659 · bf43659
1 parent 3b59257
commit bf43659
Show file tree

Hide file tree

Showing 19 changed files with 162 additions and 120 deletions.
diff --git a/.github/workflows/jamal-build.yml b/.github/workflows/jamal-build.yml
@@ -13,16 +13,6 @@ jobs:
       uses: actions/setup-java@v4
       with: {java-version: '21', distribution: temurin}
     - {name: Build with Maven, run: mvn -B package}
-    - {name: Package application, run: sh ./jamal-cmd/package.sh}
-    - name: Upload Package Artifact
-      uses: actions/upload-artifact@v3
-      with:
-        name: ur-package-ubuntu
-        path: |
-          output/*.pkg
-          output/*.deb
-          output/*.exe
-          output/*.msi
   windows-latest:
     runs-on: windows-latest
     steps:
@@ -31,31 +21,11 @@ jobs:
       uses: actions/setup-java@v4
       with: {java-version: '21', distribution: temurin}
     - {name: Build with Maven, run: mvn -B package}
-    - {name: Package application, run: sh ./jamal-cmd/package.sh}
-    - name: Upload Package Artifact
-      uses: actions/upload-artifact@v3
-      with:
-        name: ur-package-ubuntu
-        path: |
-          output/*.pkg
-          output/*.deb
-          output/*.exe
-          output/*.msi
   macos-latest:
     runs-on: macos-latest
     steps:
     - {uses: actions/checkout@v4}
     - name: Set up JDK 21
       uses: actions/setup-java@v4
       with: {java-version: '21', distribution: temurin}
-    - {name: Build with Maven, run: mvn -B package}
-    - {name: Package application, run: sh ./jamal-cmd/package.sh}
-    - name: Upload Package Artifact
-      uses: actions/upload-artifact@v3
-      with:
-        name: ur-package-ubuntu
-        path: |
-          output/*.pkg
-          output/*.deb
-          output/*.exe
-          output/*.msi
+    - {name: Build with Maven, run: mvn -B package}
diff --git a/.github/workflows/jamal-build.yml.jam b/.github/workflows/jamal-build.yml.jam
@@ -7,17 +7,6 @@
     distribution: 'temurin'
 - name: Build with Maven
   run: mvn -B package
-- name: Package application
-  run: sh ./jamal-cmd/package.sh
-- name: "Upload Package Artifact"
-  uses: actions/upload-artifact@v3
-  with:
-    name: ur-package-ubuntu
-    path: |
-      output/*.pkg
-      output/*.deb
-      output/*.exe
-      output/*.msi
 %}
 
 {%@define job($env,...$name)={%@if/$name/$name/$env%}:

diff --git a/README.adoc b/README.adoc
@@ -70,57 +70,51 @@ The installation may be as simple as starting it from the command line (JBang) w
 
 In the following sections, we will discuss how to install and use Jamal in the different applications it is embedded in.
 
+. <<Starting Command Line Version, Starting Command Line Version>>
 . <<MavenPlugin, Maven Plugin>>
 . <<MavenExtension, Maven Extension>>
-. <<Starting Command Line Version, Starting Command Line Version>>
 . <<Starting with JBang, Starting with JBang>>
 . <<ASCIIDOC, IntelliJ, AsciidocFx>>
 
-[[MavenPlugin]]
-==== Maven Plugin
+==== Starting Command Line Version
 
-You can start Jamal from Maven as a plugin.
-The plugin is available in the Maven Central repository.
+To install Jamal and use it on Linux, macOS, or Windows, you can use the installer kit.
+The installer kit is attached to the release starting with version 2.8.1.
+The installer kit contains the Jamal code as well as a minimal Java environment to run it.
+That was all you need to do is download the installer kit, and execute it.
+The installation is straightforward and does not require any special knowledge.
 
-To do that, you must have Maven installed.
-Having that, you can issue the command:
+Currently, the installation kits are available for
 
-[source]
-----
-mvn com.javax0.jamal:jamal-maven-plugin:2.8.2-SNAPSHOT:jamal
-----
-
-if you have a `pom.xml` file in your directory.
+* Linux Intel 64-bit architecture,
+* macOS Intel 64-bit and `Mx` architecture, and
+* Windows Intel 64-bit architecture.
 
-If you do not have one, then read the documentation of the Jamal Maven plugin at
-link:jamal-maven-plugin/README.adoc[Jamal Maven Plugin README].
-It is short and straightforward.
+Installation kits come along with a tailored version of the Java 21 JDK temurin distribution.
+The Java source is compatible with Java 17, and the compiled JAR files are compatible with Java 11.
 
-[[MavenExtension]]
-==== Maven Extension
-
-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.
+.Supported platform for installation kits
+[NOTE]
+====
+The above kits are created on GitHub using the GitHub actions.
+The project for creating the kits is separate from the Jamal development repository `https://github.com/verhas/jamal_packaging`.
+Upon request, I can provide Linux arm 64-bit installation kit, but that is not automatically built.
+I also plan to support that platform as soon as GitHub will support arm64 linux and windows workflows.
+====
 
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<extensions>
-    <extension>
-        <groupId>com.javax0.jamal</groupId>
-        <artifactId>jamal-maven-extension</artifactId>
-        <version>2.8.2-SNAPSHOT</version>
-    </extension>
-</extensions>
-----
+.Windows PATH setting
+[NOTE]
+====
+The Windows installation kit does not modify the path of the operating system.
+It means that you need to
 
-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.
+* start Jamal from the command line using the full path to the `jamal` executable, or
 
-For more information about the Maven extension, read the link:jamal-maven-extension/README.adoc[documentation].
+* modify the user or system level PATH to include the directory where the `jamal` executable is located.
 
-==== Starting Command Line Version
+The typical installation location for Jamal on Windows is `C:\Program Files\jamal`.
+====
+If you have Java installed on your system and do not want to install another Java environment, you can download the ZIP file from the Maven repository.
 
 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.
@@ -139,6 +133,7 @@ Usage: jamal [options] input output
   -verbose                   print out the conversions
   -open=<macroOpen>          the macro opening string
   -close=<macroClose>        the macro closing string
+  -T7                        use {% and %} as macro opening and closing
   -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
@@ -151,12 +146,58 @@ Usage: jamal [options] input output
   -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 extension
+                             Use together with -version=M.m.p to specify which version to use if different from current
 
 
 ----
 
 For more information about the command line version, read the link:jamal-cmd/README.adoc[documentation].
 
+
+[[MavenPlugin]]
+==== Maven Plugin
+
+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:
+
+[source]
+----
+mvn com.javax0.jamal:jamal-maven-plugin:2.8.2-SNAPSHOT:jamal
+----
+
+if 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
+link:jamal-maven-plugin/README.adoc[Jamal Maven Plugin README].
+It is short and straightforward.
+
+[[MavenExtension]]
+==== Maven Extension
+
+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.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<extensions>
+    <extension>
+        <groupId>com.javax0.jamal</groupId>
+        <artifactId>jamal-maven-extension</artifactId>
+        <version>2.8.2-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 link:jamal-maven-extension/README.adoc[documentation].
+
 ==== Starting with JBang
 
 JBang (https://www.jbang.dev) is a popular command-line tool that eases the startup of Java applications.

diff --git a/README.adoc.jam b/README.adoc.jam
@@ -70,12 +70,68 @@ The installation may be as simple as starting it from the command line (JBang) w
 
 In the following sections, we will discuss how to install and use Jamal in the different applications it is embedded in.
 
+. <<Starting Command Line Version, Starting Command Line Version>>
 . <<MavenPlugin, Maven Plugin>>
 . <<MavenExtension, Maven Extension>>
-. <<Starting Command Line Version, Starting Command Line Version>>
 . <<Starting with JBang, Starting with JBang>>
 . <<ASCIIDOC, IntelliJ, AsciidocFx>>
 
+==== Starting Command Line Version
+
+To install Jamal and use it on Linux, macOS, or Windows, you can use the installer kit.
+The installer kit is attached to the release starting with version 2.8.1.
+The installer kit contains the Jamal code as well as a minimal Java environment to run it.
+That was all you need to do is download the installer kit, and execute it.
+The installation is straightforward and does not require any special knowledge.
+
+Currently, the installation kits are available for
+
+* Linux Intel 64-bit architecture,
+* macOS Intel 64-bit and `Mx` architecture, and
+* Windows Intel 64-bit architecture.
+
+Installation kits come along with a tailored version of the Java 21 JDK temurin distribution.
+The Java source is compatible with Java 17, and the compiled JAR files are compatible with Java 11.
+
+.Supported platform for installation kits
+[NOTE]
+====
+The above kits are created on GitHub using the GitHub actions.
+The project for creating the kits is separate from the Jamal development repository `https://github.com/verhas/jamal_packaging`.
+Upon request, I can provide Linux arm 64-bit installation kit, but that is not automatically built.
+I also plan to support that platform as soon as GitHub will support arm64 linux and windows workflows.
+====
+
+.Windows PATH setting
+[NOTE]
+====
+The Windows installation kit does not modify the path of the operating system.
+It means that you need to
+
+* start Jamal from the command line using the full path to the `jamal` executable, or
+
+* modify the user or system level PATH to include the directory where the `jamal` executable is located.
+
+The typical installation location for Jamal on Windows is `C:\Program Files\jamal`.
+====
+If you have Java installed on your system and do not want to install another Java environment, you can download the ZIP file from the Maven repository.
+
+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:
+
+[source,text]
+----
+{%#snip:define usage_snippet={%@include [verbatim] usage.txt%}%}{%@snip usage_snippet%}
+----
+
+For more information about the command line version, read the link:jamal-cmd/README.adoc[documentation].
+
+
 [[MavenPlugin]]
 ==== Maven Plugin
 
@@ -120,23 +176,6 @@ It will also generate the `pom.xml` files from the `pom.jam` files, so your IDE
 
 For more information about the Maven extension, read the link:jamal-maven-extension/README.adoc[documentation].
 
-==== Starting Command Line Version
-
-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:
-
-[source,text]
-----
-{%#snip:define usage_snippet={%@include [verbatim] usage.txt%}%}{%@snip usage_snippet%}
-----
-
-For more information about the command line version, read the link:jamal-cmd/README.adoc[documentation].
-
 ==== Starting with JBang
 
 JBang (https://www.jbang.dev) is a popular command-line tool that eases the startup of Java applications.

diff --git a/README.jrf b/README.jrf
@@ -1,5 +1,5 @@
 # This is a Jamal reference file containing serialized base64 encoded macros
-# Created: 2024-09-30 14:30:33 +0200
+# Created: 2024-10-07 21:54:28 +0200
 # id|openStr|closeStr|verbatim|tailParameter|pure|content|parameters
 # TOC
 VE9D|eyU=|JX0=|0|0|0|Ci4gPDxJbnN0YWxsYXRpb24+PgouIDw8R1M+PgouIDw8Q29uZmlndXJhdGlvbj4+Ci4gPDxGZWF0dXJlcz4+Ci4gPDxDb250cmlidXRpbmc+PgouIDw8RG9jdW1lbnRhdGlvbj4+Ci4gPDxMaWNlbnNlPj4KLiA8PENoYW5nZWxvZz4+Ci4gPDxSb2FkbWFwPj4KLiA8PFN1cHBvcnQ+PgouIDw8RkFRPj4KLiA8PE1haW50ZW5hbmNlPj4=|
diff --git a/SECURITY.md b/SECURITY.md
@@ -20,9 +20,9 @@ Such a design allows for stringent control and limitation of these functionaliti
 Jamal is committed to maintaining the highest level of security and functionality in its text-processing library.
 To achieve this, **the latest release of Jamal is always actively supported**.
 
-Currently, the latest version is `+2.8.0+`.
+Currently, the latest version is `+2.8.1+`.
 
-The development version is `+2.8.1-SNAPSHOT+`
+The development version is `+2.8.2-SNAPSHOT+`
 
 Users are strongly encouraged to upgrade to the newest version to benefit from the latest features, improvements, and security patches.
 
@@ -31,7 +31,7 @@ Users are strongly encouraged to upgrade to the newest version to benefit from t
 While the primary focus is on the current release, we understand that upgrading to the latest version may not always be immediately feasible for all users.
 In cases where a serious security issue is reported in an older version, **support and patches will be considered under specific conditions**:
 
-- **Severity and Impact**: The security issue must be significant and pose considerable risk to users.
+- **Severity and Impact**: The security issue must be significant and pose a considerable risk to users.
 - **Demand for the Patch**: There must be a reasonable and strong demand for a patch among users who are unable to upgrade to the latest version.
 This is often evaluated based on the user base's feedback and the critical nature of the environments where the older version is deployed.
 - **Feasibility**: The feasibility of backporting a patch to an older version will be considered.

diff --git a/SECURITY.md.jam b/SECURITY.md.jam
@@ -32,7 +32,7 @@ Users are strongly encouraged to upgrade to the newest version to benefit from t
 While the primary focus is on the current release, we understand that upgrading to the latest version may not always be immediately feasible for all users.
 In cases where a serious security issue is reported in an older version, **support and patches will be considered under specific conditions**:
 
-- **Severity and Impact**: The security issue must be significant and pose considerable risk to users.
+- **Severity and Impact**: The security issue must be significant and pose a considerable risk to users.
 - **Demand for the Patch**: There must be a reasonable and strong demand for a patch among users who are unable to upgrade to the latest version.
 This is often evaluated based on the user base's feedback and the critical nature of the environments where the older version is deployed.
 - **Feasibility**: The feasibility of backporting a patch to an older version will be considered.

diff --git a/documentation/macros/env.adoc b/documentation/macros/env.adoc
@@ -20,7 +20,7 @@ is
 .output
 [source]
 ----
-/Users/verhasp/.sdkman/candidates/java/21.0.2-open
+/Users/verhasp/.sdkman/candidates/java/21.0.1-oracle
 ----