diff --git a/jamal-assertions/README.adoc b/jamal-assertions/README.adoc index f641ac8a..253e1a60 100644 --- a/jamal-assertions/README.adoc +++ b/jamal-assertions/README.adoc @@ -565,4 +565,7 @@ results 7. ERROR: 8. ERROR: 3.14 is not a not numeric 9. ERROR: three is an int, not a not int, and thus a numeric ----- \ No newline at end of file +---- + + + diff --git a/jamal-snippet/README.adoc b/jamal-snippet/README.adoc index bfb3c669..08a37a02 100644 --- a/jamal-snippet/README.adoc +++ b/jamal-snippet/README.adoc @@ -168,7 +168,7 @@ Since 1.7.4 option `onceAs` This macro collects text snippets from files. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. The syntax of the macro is @@ -318,7 +318,7 @@ The output of the `collect` macro is an empty string. The macro behaviour can be altered using options. -These options are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These options are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. * `include` @@ -780,8 +780,8 @@ will result in [source] ---- -/Users/verhasp/github/jamal/jamal-snippet/documentation/macros/snippy.txt -/Users/verhasp/github/jamal/jamal-snippet/documentation/macros/snip_define.adoc.jam +../jamal-snippet/documentation/macros/snippy.txt +../jamal-snippet/documentation/macros/snip_define.adoc.jam ---- @@ -1108,7 +1108,7 @@ You cannot use `warning` and `error` together. This macro lists the defined snippets. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. The list is represented as comma-delimited, which contains the names of the snippets. @@ -1152,7 +1152,7 @@ This is not an error in Jamal, only if you try to use any of these snippets. This macro saves all the collected snippets to a file. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. The file name must be specified by the parameter `output`. The general syntax of the macro is @@ -1244,7 +1244,7 @@ It is saved as a `CDATA` section(s). This macro can load the snippets from a file, which was saved by <>. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. The file's name has to be specified by the parameter `input`. The general syntax of the macro is @@ -1294,7 +1294,7 @@ If you want to change something in the XML file and edit some snippet code tempo This macro can cut off the unneeded spaces from the start and end of the lines. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. When you include a code fragment in the documentation as a snippet, the lines may have extra spaces at the start. @@ -1700,7 +1700,7 @@ will result [source] ---- -/Users/verhasp/github/jamal/jamal-snippet/README.adoc.jam:967:30 +../jamal-snippet/README.adoc.jam:968:30 ---- @@ -1914,7 +1914,7 @@ If you write `semver` (case insensitive) instead of the fully qualified domain n This macro can put numbers in front of the lines, sequentially numbering them. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. The syntax of the macro is @@ -1983,7 +1983,7 @@ Any illegal formatting will result in an error. This macro deletes, or keeps the selected lines from its input. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. The format of the macro is @@ -2072,7 +2072,7 @@ In this case only the comment lines remained that start with `//` at the start o You can use this macro to skip lines from the snippet. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. It is similar to <> but this macro deletes ranges of lines instead of individual lines. @@ -2183,7 +2183,7 @@ In that case you can switch it off using the option `(detectNoChange=false)` in This macro replaces strings in the input. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. It works similarly to the macro <>. @@ -2618,7 +2618,7 @@ This macro will define the macro with the literal text `UNDEFINED` if the macro This macro reflows the content. The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. The default behavior is to remove all single new-line characters replacing them with spaces. @@ -2882,7 +2882,7 @@ It can kill/keep lines, skip, replace, trim, lines, select line ranges; it can r The first line following the macro identifier until the end of the line may contain parameters. -These parameters are parsed using the Standard Parameter Parsing as defined in link:../documentation/PAROPS.adoc[PAROPS]. +These parameters are parsed using the Standard Parameter Parsing as defined in link:../../../documentation/PAROPS.adoc[PAROPS]. The macro implementation itself is calling the underlying other macros, so the functionality what and how it does the above actions are identical. @@ -3600,7 +3600,7 @@ will result in the output [source] ---- -2023-11-18 18:20:49 +2023-11-18 22:08:12 ---- @@ -3949,7 +3949,7 @@ will result in [source] ---- -/Users/verhasp/github/jamal/jamal-snippet/README.adoc +/Users/verhasp/github/jamal/jamal-snippet/../jamal-snippet/README.adoc ---- diff --git a/jamal-test/DEMO.md b/jamal-test/DEMO.md new file mode 100644 index 00000000..06ad56c3 --- /dev/null +++ b/jamal-test/DEMO.md @@ -0,0 +1,129 @@ +# Jamal Markdown Demo + + +> This document is not meant to be read formatted. +The formatted version is `DEMO.md`. +What you need to read is the `DEMO.md.jam` file in IntelliJ and see the source code and the formatted version side-by-side. + +This is a simple markdown demo file, that you can edit using IntelliJ IDEA with the Asciidoctor plugin and Jamal installed as a preprocessor. +The current Jamal version is`2.5.0-SNAPSHOT`. +This version information is read from the `pom.xml` file. +It means that there is no need to edit this document if the version changes only to change the version number. + +## Dependency on External Files + +This document depends on many files. +(No, not really.) +One file is `README.adoc.jam` (no, not really). +In this text this file is referenced using the `file` macro. +With this macro, we can be sure that the file exists. + +If the file `README.adoc.jam` was renamed, or removed and the Jamal processing of this file is part of the CI/CD process, the build will fail. +This is a god thing, because it means that the documentation is always up-to-date. + + + + +We can check not only the existence of the file, but also its content. +Currently, the hashCode of the file `README.adoc.jam` is `5030f7f5.fd1c50e4.629944fd.44409cb9.9b55f346.bd66859c.73cd98cd.da5418d5`. +We can use the `snip:check` macro to check that the file has not been changed. +If the file has changed, the build will fail. +This is a god thing, because it means that the documentation is always up-to-date. + +Oh, by the way: you do not need the whole hash code! +Do not freak out! +It is enough if you copy 8 characters from the hash code. + +## Internal Consistency of the Document + +Did I say that already? +Oh yes, I did. +What happens if I realize that there is a typo in this text and I want to correct it? +It is not a _god_ thing, even though Jamal is superb, but still it is a _good_ thing. + +Without Jamal, the probable scenario would be that I change the occurrence where I see that there is a missing 'o'. +The other occurrence would remain unchanged. +However, using the `variation` macro Jamal will warn me that there are multiple occurrences of the same text. +Until I change all of them to be identical, the build will fail. +This is a god thing, because it means that the documentation is always up-to-date. +(Sorry, I still have to write it so again, because I want this typo for demonstration.) + +However, you can use the `variation` macro even if the texts differ a bit. +You can separate the "constant" and the "variable" part of the text. +Like here: + +This is a good thing, because it means that the documentation is always up-to-date. + +How did this happen? +I enclosed the variable part of the text in `pass:[<<]` and `pass:[>>]`. +So I wrote `This is a gopass:[<<]o>>d thing,...` +As simple as that. + +## Avoid copy-paste totally + +If you do not want to use the `variation` macro and maintain copies of the same text you can define macros. +In this document, we have already used a macro definition. +If you look at the `DEMO.md.jam` file you will see a definition on the line 24. +We define the macro `HASH` there because we want to use the same value in the `snip:check` macro and in the text. +Usually you do not display such hash codes in the text, you use it only in the `snip:check` macro. + +Macros are not only constant texts named. +Macros can have arguments, defined inside other macros, enclosed in scopes and many other things. +There are more than 200 different macros defined in several macro libraries. +Use only that you are comfortable with and what you need. + +## Diagrams + + +You can use, for example, the KROKI diagram creating macro. +Like here: + +![](KROKI_MD.svg) + +![](STR.svg) + +With this, you can embed diagrams into your documentation. +The `kroki` macro supports all the 27 diagram types that Kroki itself support. +You can embed any or all of the diagram texts into your documentation. +Jamal's processing will create the diagrams and embed them into the documentation. + +You do not need any Markdown (or whatever format you use) extensions. +The markdown file Jamal generates will only contain the image links. +Uploading the document to GitLab, GitHub or to another platform that handles only plain Markdown will work. +You will have there the `DEMO.md`, `KROKI_MD.svg` and `STR.svg` files. +(To avoid unnecessary processing the `.svg.hash` files are also created and Kroki runs only when the digram code changes.) + +BTW: the diagram code inside your document may also contain Jamal code, and it will be processed if you need it. + +## Fecth data from external sources + +You can fetch data from external sources. +You have already seen the software version. +You do not need to copy any text from the documented system. +You can define snippets in your code, collect them in your document and reference them. + + +For example, here is the default implementation of the `getId()` method of the Jamal interface `Macro`. + +```java + default String getId() { + return this.getClass().getSimpleName().toLowerCase(); + } + +``` + +If the code changes, the documentation will change too, automatically. +This is a good thing, because it means that the documentation is always up-to-date. + +It is not only code samples, you can fetch any text from any file, and you can also transform them before using them in your document. +If you think that a small piece of the documentation is easier to maintain as little comment in the code, you can do that. +Keep that small piece there, and fetch it into your documentation. +When your code changes, you are less likely to forget to update the documentation when the documenting text is right there with your code. + +## What else? + +What I described here is only the tip of the iceberg. +You can include files, information from JAR files, web pages, and so on. +You can use hierarchical counters, make transformations on the included lines, repeat the same text multiple times, and so on. + +For all the possibilities and the details, please read the [Jamal documentation](../README.adoc). \ No newline at end of file diff --git a/jamal-test/DEMO.md.jam b/jamal-test/DEMO.md.jam new file mode 100644 index 00000000..81ce9c1d --- /dev/null +++ b/jamal-test/DEMO.md.jam @@ -0,0 +1,162 @@ +# Jamal Markdown Demo +{%@snip:xml pom=pom.xml%}{%#define VERSION={%pom /project/version/text()%}%} + +> This document is not meant to be read formatted. +The formatted version is `DEMO.md`. +What you need to read is the `DEMO.md.jam` file in IntelliJ and see the source code and the formatted version side-by-side. + +This is a simple markdown demo file, that you can edit using IntelliJ IDEA with the Asciidoctor plugin and Jamal installed as a preprocessor. +The current Jamal version is`{%VERSION%}`. +This version information is read from the `pom.xml` file. +It means that there is no need to edit this document if the version changes only to change the version number. + +## Dependency on External Files + +This document depends on many files. +(No, not really.) +One file is `{%@file README.adoc.jam%}` (no, not really). +In this text this file is referenced using the `file` macro. +With this macro, we can be sure that the file exists. + +If the file `{%@file README.adoc.jam%}` was renamed, or removed and the Jamal processing of this file is part of the CI/CD process, the build will fail. +{%@variation This is a god thing, because it means that the documentation is always up-to-date.%} + +{%@define HASH=5030f7f5.fd1c50e4.629944fd.44409cb9.9b55f346.bd66859c.73cd98cd.da5418d5%} +{%#define LINE={%@pos.line%}%} +{%#snip:check file=README.adoc.jam hashCode={%HASH%}%} +We can check not only the existence of the file, but also its content. +Currently, the hashCode of the file `{%@file README.adoc.jam%}` is `{%HASH%}`. +We can use the `snip:check` macro to check that the file has not been changed. +If the file has changed, the build will fail. +{%@variation This is a god thing, because it means that the documentation is always up-to-date.%} + +Oh, by the way: you do not need the whole hash code! +Do not freak out! +It is enough if you copy 8 characters from the hash code. + +## Internal Consistency of the Document + +Did I say that already? +Oh yes, I did. +What happens if I realize that there is a typo in this text and I want to correct it? +It is not a _god_ thing, even though Jamal is superb, but still it is a _good_ thing. + +Without Jamal, the probable scenario would be that I change the occurrence where I see that there is a missing 'o'. +The other occurrence would remain unchanged. +However, using the `variation` macro Jamal will warn me that there are multiple occurrences of the same text. +Until I change all of them to be identical, the build will fail. +{%@variation This is a god thing, because it means that the documentation is always up-to-date.%} +(Sorry, I still have to write it so again, because I want this typo for demonstration.) + +However, you can use the `variation` macro even if the texts differ a bit. +You can separate the "constant" and the "variable" part of the text. +Like here: + +{%@variation This is a go<>d thing, because it means that the documentation is always up-to-date.%} + +How did this happen? +I enclosed the variable part of the text in `pass:[<<]` and `pass:[>>]`. +So I wrote `This is a gopass:[<<]o>>d thing,...` +As simple as that. + +## Avoid copy-paste totally + +If you do not want to use the `variation` macro and maintain copies of the same text you can define macros. +In this document, we have already used a macro definition. +If you look at the `DEMO.md.jam` file you will see a definition on the line {%LINE%}. +We define the macro `HASH` there because we want to use the same value in the `snip:check` macro and in the text. +Usually you do not display such hash codes in the text, you use it only in the `snip:check` macro. + +Macros are not only constant texts named. +Macros can have arguments, defined inside other macros, enclosed in scopes and many other things. +There are more than 200 different macros defined in several macro libraries. +Use only that you are comfortable with and what you need. + +## Diagrams + +{%@import res:kroki.jim%} +You can use, for example, the KROKI diagram creating macro. +Like here: + +{%kroki /KROKI_MD/plantuml/svg/ +Alice -> Bob: Authentication Request +Bob --> Alice: Authentication Response + +Alice -> Bob: Another authentication Request +Alice <-- Bob: Another authentication Response +%} + +{%kroki /STR/structurizr/svg/ +workspace { +model { +user = person "Algien" +softwareSystem = softwareSystem "Software System" { +webapp = container "Web Application" { +user -> this "Uses!!!" +} +database = container "Database" { +webapp -> this "Reads from and writes to" +} +} +} +views { +systemContext softwareSystem { +include * +autolayout lr +} +container softwareSystem { +include * +autolayout lr +} +theme default +} +} +%} + +With this, you can embed diagrams into your documentation. +The `kroki` macro supports all the 27 diagram types that Kroki itself support. +You can embed any or all of the diagram texts into your documentation. +Jamal's processing will create the diagrams and embed them into the documentation. + +You do not need any Markdown (or whatever format you use) extensions. +The markdown file Jamal generates will only contain the image links. +Uploading the document to GitLab, GitHub or to another platform that handles only plain Markdown will work. +You will have there the `DEMO.md`, `KROKI_MD.svg` and `STR.svg` files. +(To avoid unnecessary processing the `.svg.hash` files are also created and Kroki runs only when the digram code changes.) + +BTW: the diagram code inside your document may also contain Jamal code, and it will be processed if you need it. + +## Fecth data from external sources + +You can fetch data from external sources. +You have already seen the software version. +You do not need to copy any text from the documented system. +You can define snippets in your code, collect them in your document and reference them. +{%@snip:collect from=../jamal-api/src%} + +For example, here is the default implementation of the `getId()` method of the Jamal interface `Macro`. + +```java +{%@snip getId%} +``` + +If the code changes, the documentation will change too, automatically. +{%@variation This is a go<>d thing, because it means that the documentation is always up-to-date.%} + +It is not only code samples, you can fetch any text from any file, and you can also transform them before using them in your document. +If you think that a small piece of the documentation is easier to maintain as little comment in the code, you can do that. +Keep that small piece there, and fetch it into your documentation. +When your code changes, you are less likely to forget to update the documentation when the documenting text is right there with your code. + +## What else? + +What I described here is only the tip of the iceberg. +You can include files, information from JAR files, web pages, and so on. +You can use hierarchical counters, make transformations on the included lines, repeat the same text multiple times, and so on. + +For all the possibilities and the details, please read the [Jamal documentation](../README.adoc). + + + + + diff --git a/jamal-test/KROKI_MD.svg b/jamal-test/KROKI_MD.svg new file mode 100644 index 00000000..dad65ba2 --- /dev/null +++ b/jamal-test/KROKI_MD.svg @@ -0,0 +1 @@ +AliceAliceBobBobAuthentication RequestAuthentication ResponseAnother authentication RequestAnother authentication Response \ No newline at end of file diff --git a/jamal-test/KROKI_MD.svg.hash b/jamal-test/KROKI_MD.svg.hash new file mode 100644 index 00000000..aa48d990 --- /dev/null +++ b/jamal-test/KROKI_MD.svg.hash @@ -0,0 +1 @@ +b5a5bcc5fa63cd707cb51302e1036fb1773b33818760a6a0da96e1913e40d88b \ No newline at end of file diff --git a/jamal-test/STR.svg b/jamal-test/STR.svg new file mode 100644 index 00000000..cf5de03e --- /dev/null +++ b/jamal-test/STR.svg @@ -0,0 +1 @@ +Software System - ContainersSoftware System[Software System]Web Application[Container]Database[Container]Algien[Person]Uses!!!Reads from andwrites to \ No newline at end of file diff --git a/jamal-test/STR.svg.hash b/jamal-test/STR.svg.hash new file mode 100644 index 00000000..c0153b41 --- /dev/null +++ b/jamal-test/STR.svg.hash @@ -0,0 +1 @@ +7308555bc6d712513cbec875321940bc46b6b29793c526611a32ffcc66d4f77a \ No newline at end of file diff --git a/jamal-word/src/test/resources/demoConverted.docx b/jamal-word/src/test/resources/demoConverted.docx index 83bb0507..7eaf9119 100644 Binary files a/jamal-word/src/test/resources/demoConverted.docx and b/jamal-word/src/test/resources/demoConverted.docx differ diff --git a/jamal-word/src/test/resources/includetestConverted.docx b/jamal-word/src/test/resources/includetestConverted.docx index eb515007..df3d080c 100644 Binary files a/jamal-word/src/test/resources/includetestConverted.docx and b/jamal-word/src/test/resources/includetestConverted.docx differ diff --git a/jamal-word/src/test/resources/pictureConverted.docx b/jamal-word/src/test/resources/pictureConverted.docx index ee67e556..bce702f4 100644 Binary files a/jamal-word/src/test/resources/pictureConverted.docx and b/jamal-word/src/test/resources/pictureConverted.docx differ diff --git a/jamal-word/src/test/resources/sampleConverted.docx b/jamal-word/src/test/resources/sampleConverted.docx index a8046790..79608f47 100644 Binary files a/jamal-word/src/test/resources/sampleConverted.docx and b/jamal-word/src/test/resources/sampleConverted.docx differ