Skip to content

Commit

Permalink
Ruby documentation finished and the common part of the documentation …
Browse files Browse the repository at this point in the history 
…was moved to an imported file

also a bug was fixed in the core macro `include` that reported an internal error if there was an error in the included file
  • Loading branch information
@verhas
verhas committed Feb 28, 2021
1 parent 5e0dda1 commit da25b13
Show file tree
Hide file tree
Showing 9 changed files with 448 additions and 160 deletions.
12 changes: 3 additions & 9 deletions jamal-core/src/main/java/javax0/jamal/builtins/Include.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,22 +37,16 @@ public String evaluate(Input input, Processor processor) throws BadSyntax {
final var position = input.getPosition();
skipWhiteSpaces(input);
var reference = input.getReference();
if (reference == null) {

}
var fileName = absolute(reference, input.toString().trim());
if (depth-- == 0) {
depth = getDepth(); // try macro may recover
throw new BadSyntax("Include depth is too deep");
}
var marker = new Marker("{@include " + fileName + "}", position);
final String result;
try {
processor.getRegister().push(marker);
result = processor.process(getInput(fileName));
} finally {
processor.getRegister().pop(marker);
}
processor.getRegister().push(marker);
result = processor.process(getInput(fileName));
processor.getRegister().pop(marker);
depth++;
return result;
}
Expand Down
50 changes: 28 additions & 22 deletions jamal-groovy/README.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -357,6 +357,12 @@ The second evaluation is performed in a different shell, but the definition of t
[[Sample]]
=== 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.


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.
Expand All @@ -371,9 +377,9 @@ The Jamal snippet library macros are used to keep the sample codes included in t
[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 neccessary 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 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.
====

The technical documentations using Jamal and the snippet macros usually generate the documentation in multiple steps.
Expand All @@ -385,28 +391,27 @@ The technical documentations using Jamal and the snippet macros usually generate
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.
The test file `src/test/java/javax0/jamal/groovy/TestGroovyMacros.java` contains
The test file `jamal-groovy/src/test/java/javax0/jamal/groovy/TestGroovyMacros.java` contains

[source,java]
----
// snippet sample_snippet
@Test
@DisplayName("Test a simple groovy eval")
void testSimpleEval() throws Exception {
TestThat.theInput("{@groovy:eval 6+3}").results("9");
}
// end snippet
----
// snippet sample_snippet
@Test
@DisplayName("Test a simple groovy eval")
void testSimpleEval() throws Exception {
TestThat.theInput("{@groovy:eval 6+3}").results("9");
}
// end snippet
----
To get this content into the document what we have to write is the following:


[source,java]
----
// snippet sample_snippet
{%@snip sample_snippet
%}\
// end snippet
// snippet sample_snippet
{%@snip sample_snippet %}\
// end snippet
----


Expand All @@ -420,10 +425,10 @@ 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.

To do that the Jamal Snippet package unit test file
`../jamal-snippet/src/test/java/javax0/jamal/documentation/TestConvertReadme.java`
`jamal-snippet/src/test/java/javax0/jamal/documentation/TestConvertReadme.java`
uses a built-in macro, implemented in the file:

* `../jamal-snippet/src/test/java/javax0/jamal/documentation/Output.java`
* `jamal-snippet/src/test/java/javax0/jamal/documentation/Output.java`

This Java implemented macro is available on the classpath when the unit test runs.

Expand Down Expand Up @@ -454,17 +459,18 @@ It creates a single Jamal processor instance and uses it to evaluate the input p
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.

To simplify the use there is a `../readmemacros.jim` macro import file that defines the user defined macro `sample` and `output`.
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----` brefore and `----` after the sample code.
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 `ouput` uses the `lastCode` and using the buil-in `output` from the `Output.java` displays the calculated result as a code block.
The macro `output` uses the `lastCode` and using the buil-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.

The unit test code that invokes the Jamal processor to convert this document is the following:


[source]
----
final var processor = new Processor("{%", "%}");
Expand Down Expand Up @@ -520,7 +526,7 @@ The result value of the macro is the output of the processor.
In this chapter we discussed how documentations should be "programs" to avoid redundacy in the source and to support consistency.
After that we made a short detour discussing the Jamal snippets, which have a full documentation in the file link:../jamal-snippet/README.adoc[Snippet README].
We also discussed how the documentation conversion works with snippets and Jamal samples in the Snippet module.
Finally we had a look at how simpler it is using the Groovy integration.
Finally, we had a look at how simpler it is using the Groovy integration.

NOTE: None of the sample codes in the source `README.adoc.jam` was manually copied.

Expand Down
117 changes: 4 additions & 113 deletions jamal-groovy/README.adoc.jam
View file
Original file line number Diff line number Diff line change
Expand Up @@ -333,118 +333,9 @@ The second evaluation is performed in a different shell, but the definition of t

[[Sample]]
=== Sample Application, Converting this `README.adoc`

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.
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 `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 neccessary to know and understand how the snippet macros work in order to read this chapter, but in general, it is a recommended read.
====

The technical documentations using Jamal and the snippet macros usually generate the documentation in multiple steps.

* Run the tests including the sample code and capture the sample output in one or more output file.

* Process the Jamal source of the documentation and include from the source code and from 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.
The test file `{%@file src/test/java/javax0/jamal/groovy/TestGroovyMacros.java%}` contains

[source,java]
----
// snippet sample_snippet
{%@snip sample_snippet
@Test
@DisplayName("Test a simple groovy eval")
void testSimpleEval() throws Exception {
TestThat.theInput("{@groovy:eval 6+3}").results("9");
}
%}\
// end snippet
----

To get this content into the document what we have to write is the following:

{%@escape `ESCAPE`
[source,java]
----
// snippet sample_snippet
{%@snip sample_snippet `ESCAPE`%}{%@comment avoid update for this one%}{%@escape `ESCAPE`
%}\
// end snippet
----
`ESCAPE`%}

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.

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.

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:

* `{%@file ../jamal-snippet/src/test/java/javax0/jamal/documentation/Output.java%}`

This Java implemented macro is available on the classpath when the unit test runs.

[NOTE]
====
Executing the Jamal processing of the documentation of a Java software package 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.
====

This class is very simple:

[source,java]
----
{%@snip Output_java
public class Output implements Macro {
final Processor localProc = new javax0.jamal.engine.Processor("{", "}");

@Override
public String evaluate(Input in, Processor processor) throws BadSyntax {
return localProc.process(new javax0.jamal.tools.Input(in.toString(), in.getPosition()));
}
}
%}\
----

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.

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----` brefore and `----` after the sample code.
The same time it also saves the sample code in a user defined variable called `lastCode`.
The macro `ouput` uses the `lastCode` and using the buil-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 {%@file 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:
{%@define $lang=groovy%}
{%@define $Lang=Groovy%}
{%@include ../scriptingReadme.adoc.jim%}

[source]
----
Expand Down Expand Up @@ -492,7 +383,7 @@ The result value of the macro is the output of the processor.
In this chapter we discussed how documentations should be "programs" to avoid redundacy in the source and to support consistency.
After that we made a short detour discussing the Jamal snippets, which have a full documentation in the file link:{%@file ../jamal-snippet/README.adoc%}[Snippet README].
We also discussed how the documentation conversion works with snippets and Jamal samples in the Snippet module.
Finally we had a look at how simpler it is using the Groovy integration.
Finally, we had a look at how simpler it is using the Groovy integration.

NOTE: None of the sample codes in the source `README.adoc.jam` was manually copied.

Expand Down
Loading

0 comments on commit da25b13

Please sign in to comment.