documentation was added

Author: verhas

jamal-json/README.adoc

@@ -401,5 +401,3 @@ will result
 ----
 @json:keys a/ = "a,b,c,d"
 ----
-
-

jamal-maven-load/README.adoc

@@ -2,18 +2,18 @@
 
 The Jamal Maven Load module contains a macro to download Java JAR files from Maven repositories during run-time and load the macro classes into the running application.
 
-The library's security was designed carefully to balance the ease of use and the security of the application.
-Without any security measures, a Jamal file could execute any Java code published online, which is not a good idea.
-To prevent this the Jamal installation has to be configured properly to use this module.
+I designed the library's security, balancing the ease of use and the application's security.
+Without security measures, a Jamal file could execute any Java code published online, which is not a good idea.
+The Jamal installation has to be adequately configured to use this module.
 The requirements of a proper configuration are described in the section about security.
 
 == Macro
 
-Currently, there is only one maco defined in this module.
+Currently, there is only one macro defined in this module.
 
 === `maven:load`
 
-It loads the macros from a Maven artifact along with its dependencies, unless the `noDependencies` option is used.
+It loads the macros from a Maven artifact and its dependencies unless the `noDependencies` option is used.
 
 This macro reads its input and interprets it as a maven coordinate set.
 The format has to be
@@ -25,9 +25,9 @@ The macro works in two steps:
 
 1. First, it downloads the artifact JAR and all the dependencies.
 
-2. It loads the macros from the JAR files (the specified one and the dependencies) using a class loader.
+2. Using a class loader, it loads the macros from the JAR files (the specified one and the dependencies).
 
-It is possible to load only the file without the dependencies using the `noDependencies` option.
+Loading only the file without the dependencies is possible using the `noDependencies` option.
 
 [WARNING]
 ====
@@ -37,6 +37,7 @@ For more information, see the section about security.
 ====
 
 The behavior of the macro can be controlled using options.
+The options should follow the macro's name between `(` and `)` characters.
 The options are:
 
 * `repositories` (aliases are `repository`, `repo`, `repos`) define the Maven repositories used comma separated.
@@ -50,9 +51,10 @@ The symbolic names can be
 - `google-maven-central-asia`
 +
 The default value is `central`.
-When a URL is specified it is checked against the configuration.
-The symbolic names are permitted by default, they can be used without configuration.
-For more information see the section about security.
+When a URL is specified, it is checked against the configuration.
+The symbolic names are permitted by default; they can be used without configuration.
+URLs must be configured in the `maven.load.repo` configuration property.
+For more information, see the section about security.
 
 * `noDependencies` (alias is `noDeps`) says that the dependencies of the JAR should not be loaded.
 The default value is `false`.
@@ -62,8 +64,8 @@ already loaded.
 
 * `local` can specify the location of the local Maven repository.
 The default value is `~/.m2/repository`.
-If this option is used it is checked against the configuration.
-For more information see the section about security.
+If this option is used, it is checked against the configuration.
+For more information, see the section about security.
 
 * `exclude` can specify a comma-separated list of maven coordinates that should not be loaded.
 This parameter will not stop loading the "root" artifact specified in the macro input.
@@ -79,14 +81,14 @@ The macro `maven:load` reads the configuration of Jamal via an API that works on
 
 === Secure configuration
 
-This macro works only if your configuration files' access control is properly set.
-Without that someone accessing the computer in a different account could modify the configuration and load malicious code.
+This macro works only if your configuration files' access control is set correctly.
+Without that, someone accessing the computer in a different account could modify the configuration, potentially loading malicious code.
 
-The configuration must be secure meaning:
+The configuration must be secure, meaning:
 
 * There is no configuration.
 In that case, nothing can be opened, so there is no security risk.
-However, in this case, the macro will not be able to load any JAR file.
+However, in this case, the macro cannot load any JAR file.
 OR
 
 The configuration directory and the files are _SAFE_
@@ -125,31 +127,42 @@ When reading the configuration, if any of the
 
 * `maven.load.repo`
 
-properties point to files, these files should also be _SAFE_.
+properties point to files; these files should also be _SAFE_.
 ====
 
 NOTE: Securing the configuration is not a must for Jamal's other parts and functionalities, although it is a good practice.
 The security is only checked before reading the configuration for the `maven:load` macro.
 
 Also, the `maven:load` macro uses a unique API to read the configuration.
 Every time the macro runs, the API rereads the files, checks the security of the configuration, and ignores the in-memory cached configuration.
-Also, note that while most of the macros and functionalities of Jamal read configuration via an API that consults the system properties first, environment variables second, and lastly only
+Also, note that while most of the macros and functionalities of Jamal read configuration via an API that consults the system properties first, environment variables second, and lastly, only
 the configuration files,
 
 ====
 the API used by the `maven:load` macro reads only the configuration files in the directory `~/.jamal/`.
-These are `~/.jamal/settings.properties` or `~/.jamal/settings.xml` and the files references by the above-mentioned properties.
+These are `~/.jamal/settings.properties` or `~/.jamal/settings.xml`.
+====
+
+[NOTE]
+====
+When Jamal is executed in an interactive environment the security for a specific `maven:load` macro is checked only once.
+The security is checked only when the macro tries to load the classes.
+When the classes were loaded by the same JVM in a previous run, the security is not checked again.
+
+It also means that changing the configuration to prevent the load of a macro library that was already loaded is futile.
+On the other hand, changing the configuration to allow the load of a macro library that failed to load due to security settings is effective.
+There is no need to restart the application executing Jamal.
 ====
 
 === Configuration
 
 The `maven:load` macro has to be configured for security reasons.
 It can only load JAR files which are explicitly allowed by the configuration.
-Also, the remote repositories and the local repository have to be configured unless the hardwired well-known repositories are used with the default local location.
+Also, the remote and local repositories must be configured unless the well-known hardwired repositories are used with the default local location.
 
 The values for the property keys are
 
-* comma separated list of maven coordinates + path,
+* comma-separated list of maven coordinates + path,
 
 * absolute paths,
 
@@ -159,13 +172,13 @@ The values for the property keys are
 
 When a key points to a file, the file also has to be _SAFE_ as defined in the previous section.
 It has to be in the same directory as the configuration file and has to be specified by the bare name and extension but without any path.
-The file contains the configuration information one per line.
+The file contains the configuration information, one per line.
 
 [NOTE]
 ====
 You can use the comma-separated list in the `.properties` file.
-When you have too many configuration items, however, it is better to use a file.
-To have a readable format the file contains the list of the configuration items one per line.
+However, it is better to use a file when you have many configuration items.
+The file contains the list of configuration items, one per line.
 ====
 
 ==== `maven.load.include`
@@ -178,6 +191,7 @@ Every maven coordinate has to be in the format
           groupId:artifactId:version
 
 or
+
           groupId:artifactId:version:path
 
 The `groupId` cannot be a wildcard.
@@ -186,19 +200,20 @@ The path part is optional.
 If the `artifactId` is a wildcard, then the `version` has to be a wildcard too.
 
 The path represents the path to the Jamal source.
-It can either be the absolute path to the Jamal text or a directory.
-When the value ends with a `/` it is considered a directory.
+It can be the absolute path to the Jamal input file or the directory containing one or more Jamal input files.
+If the path is a directory, `maven:load` is also permitted for all subdirectories.
+When the value ends with a `/`, it is considered a directory.
 
-When the path is specified it is compared against the path of the Jamal source.
+When the path is specified, it is compared against the path of the Jamal source.
 The Jamal source file has to be the same or has to be in the specified directory.
 
-The macro `maven:load` is used sometimes from a file included or imported by the top Jamal source directly or through other includes or imports.
-In this case, just as when the normal, the path of the top level Jamal file is used only.
+The macro `maven:load` is sometimes used from a file included or imported by the top Jamal source directly or through other includes or imports.
+In this case, the path of the top-level Jamal file is used only.
 
 ==== `maven.load.exclude`
 
-The key `maven.load.exclude` can be used to exclude some maven coordinates from the list of allowed coordinates.
-If a coordinate is excluded, it cannot be used even if it is included in the `maven.load.include` list.
+The key `maven.load.exclude` can exclude some maven coordinates from the list of allowed coordinates.
+If a coordinate is excluded, it cannot be used even if included in the `maven.load.include` list.
 
 A coordinate will also be skipped if one is present as a dependency.
 In this case, however, the download will not stop.
@@ -207,16 +222,18 @@ The class loading, however, may still fail if classes are missing because of the
 ==== `maven.load.local`
 
 The key `maven.load.local` can be used to specify the location of the local Maven repository.
-It has to be configured when the option `local` used.
-The values have to specify the absolute paths of the allowed directories that can be used as local repos.
+It has to be configured when the option `local` is used.
+The values have to specify the absolute paths of the allowed directories that can be used as local repositories.
 
 WARNING: This is a security configuration.
 Specifying a location here will not change the default location.
+It merely lists the allowed locations.
 
 ==== `maven.load.repo`
 
 The key `maven.load.repo` can be used to specify the list of allowed remote repositories in addition to the predefined ones.
-The values have to be the URLs as they appear in the `repositories` option of the `maven:load` macro.
+The values must be the URLs appearing in the `repositories` option of the `maven:load` macro.
 
 WARNING: This is a security configuration.
 Specifying a URL here will not change the default repository.
+It merely lists the allowed repositories.