Optionally invoke external PlantUML instead of embedded copy

[stanwest]

Is there a way to tell pp to invoke an external "plantuml.jar" file for uml and ditaa macros instead of its embedded copy? One use case is to use a version of PlantUML that is patched or more recent than the embedded copy.

[rolandog]

While I don't really know how to invoke an external plantuml.jar from within pp, I've been able to update pp's copy by doing the following steps (this infers that you previously installed pp from the repository):

1. download the wanted version of plantuml.jar (for example, latest stable version is plantuml.1.2019.11.jar).
2. git pull newest version of pp from the repository
3. navigate to pp/.stack-work
4. delete Plantuml.jar
5. move/copy latest plantuml.jar into the folder, and rename as Plantuml.jar
6. in a terminal emulator, navigate to the pp folder
7. run make
8. run make install (if it's applicable in your case)

To test, we would need to parse the following special diagram description with pp's plantuml.jar file:

@startuml
version
@enduml

Oddly enough, I had to wrap the code with @startuml and @enduml, even though the docs state that those lines are added (and indeed they are added in the generated uml file):

!uml(pp-plantuml-version)(Current version of PlantUML used by pp)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@startuml
version
@enduml
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

which results in:

@startuml
@startuml
version
@enduml

@enduml

Nevertheless, this actually runs, instead of raising an exception (as opposed to writing only the 'version' word without wrapping the code in the previous keywords).

But that is something I'll document in order to report as a separate issue.

[CDSoft]

If you just want to update the plantuml version to the last one, you can just recompile it. make will download the last stable version for you (make clean; make). To use an external jar file we should have a standard way to locate it. Is there one?

[CDSoft]

The blank line after version seems to be unexpected. !uml(pp-plantuml-version)(Current version of PlantUML used by pp)(version) works better.

[rolandog]

I didn't know about the last option! Thanks for the feedback!

[CDSoft]

This is not specific to plantuml. The last argument of a macro can be a "regular" argument or a block argument.

!macro
~~~
arg
~~~

and !macro(arg) are equivalent (the only differences are heading and trailing spaces).

[stanwest]

… I've been able to update pp's copy by doing the following steps …

If you just want to update the plantuml version to the last one, you can just recompile it.

Agreed, if I were to set up a build environment on Windows.

To use an external jar file we should have a standard way to locate it. Is there one?

I doubt it, but what about a command-line argument specifying the path to the desired "plantuml.jar" file?

[CDSoft]

I've added the -plantuml option.

[stanwest]

That works nicely. Thank you.

I noticed that the new option is missing from the command line help. Would you consider something like the following to show the new -plantuml and -ditaa options?

--- a/src/Version.hs
+++ b/src/Version.hs
@@ -64,6 +64,8 @@ help = unlines [
         "  -U<name>             Undefine a variable",
         "  -img=<prefix>        Define the prefix to add to output image path",
         "  -M=<target>          Generate make-like dependency list",
+        "  -plantuml=<file>     Use external plantuml.jar file",
+        "  -ditaa=<file>        Use external ditaa.jar file",
         "  -<macro>[=<arg>]     Call a builtin macro with an optional argument",
         "                       ("++name++" -help for the full macro list)",
         "                       Some macros may prevent pp from reading stdin",

[CDSoft]

You're right. I have updated the documentation but not the help message.