Document the new functionality of ob-plantuml to insert ASCII diagrams directly in the buffer. --- This patch documents the changes made here: https://lists.gnu.org/archive/html/emacs-orgmode/2022-08/msg00110.html
.../babel/languages/ob-doc-plantuml.org | 55 +++++++++++++++---- 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/org-contrib/babel/languages/ob-doc-plantuml.org b/org-contrib/babel/languages/ob-doc-plantuml.org index ec347de4..2bd46861 100644 --- a/org-contrib/babel/languages/ob-doc-plantuml.org +++ b/org-contrib/babel/languages/ob-doc-plantuml.org @@ -49,9 +49,13 @@ Diagram images can be generated in PNG, SVG, and LaTeX formats. =PlantUML= is integrated with [[https://plantuml.com/running][a wide variety of software applications]]. Babel is a [[https://plantuml.com/emacs][standard way to use PlantUML in Emacs]]. * Requirements and Setup -=PlantUML= requires a working [[https://www.java.com/en/download/][Java]] installation and access to the -=plantuml.jar= component. A working [[https://graphviz.org/][GraphViz]] installation is required -for many diagrams. +=PlantUML= blocks can be executed in one of three ways, requiring either + +- a working [[https://www.java.com/en/download/][Java]] installation and access to the =plantuml.jar= component or +- the =plantuml= executable available from your distribution's package manager or +- a connection to a remote [[https://github.com/plantuml/plantuml-server][PlantUML server]] + +A working [[https://graphviz.org/][GraphViz]] installation is required for many diagrams. Emacs has [[https://github.com/skuro/plantuml-mode][plantuml-mode]], a major mode for editing PlantUML sources. There are detailed [[https://github.com/skuro/plantuml-mode#installation][installation instructions]], as well as instructions @@ -59,8 +63,9 @@ for [[https://github.com/skuro/plantuml-mode#integration-with-org-mode][integrat You will likely want to set the variables =plantuml-jar-path= and =org-plantuml-jar-path= with the path to your local installation of -=PlantUML=. Alternatively, set the variable -=plantuml-default-exec-mode= to access =PlantUML= non-locally. +=PlantUML=. Alternatively, set the variable =plantuml-default-exec-mode= +to =executable= to use your local =plantuml= executable or to =server= to +access =PlantUML= non-locally. Activate evaluation of =PlantUML= source code blocks by adding =plantuml= to =org-babel-load-languages=. @@ -77,15 +82,22 @@ Activate evaluation of =PlantUML= source code blocks by adding ** Header Arguments =PlantUML= code blocks default to =:results file= and =:exports results=. -=PlantUML= has these language-specific header arguments and one requirement: - - file :: =PlantUML= code blocks require that an output file be specified +If you wish to export the =PlantUML= code block to a file, you must +specify a =:file= header argument. Alternatively, if you set =:results= +to a value other than =file=, such as =:results verbatim=, then the ASCII +=PlantUML= output will be inserted into the buffer below the code block. + +=PlantUML= has these language-specific header arguments: - cmdline :: specify [[https://plantuml.com/command-line][command line arguments]] for =PlantUML= - java :: arguments for the =java= runtimes (JRE) ** Sessions =PlantUML= does not support sessions. ** Result Types -A =PlantUML= code block returns a link to the file it generates. - +When the =:file= header argument has been specified, =PlantUML= code +blocks return a link to the generated file. Alternatively, if +=:results= is set to a value other than =file=, then the generated ASCII +diagram will be inserted into the buffer. + * Examples of Use :PROPERTIES: :header-args:plantuml: :eval no-export @@ -119,7 +131,7 @@ b -> c ,#+end_src #+end_example -HTML output of the =PlantUML= code block: +PNG output of the =PlantUML= code block: #+begin_src plantuml :file images/theme-uml.png :exports both !theme spacelab a -> b @@ -130,3 +142,26 @@ b -> c #+RESULTS: [[file:images/theme-uml.png]] +Here is an example of ASCII output inserted directly into the buffer. + +The =PlantUML= code block in the Org buffer: +#+begin_example +,#+begin_src plantuml :results verbatim +Bob -> Alice : Hello World! +,#+end_src +#+end_example + +ASCII output of the =PlantUML= code block: +#+begin_src plantuml :results verbatim +Bob -> Alice : Hello World! +#+end_src + +#+RESULTS: +: ,---. ,-----. +: |Bob| |Alice| +: `-+-' `--+--' +: | Hello World! | +: |-------------->| +: ,-+-. ,--+--. +: |Bob| |Alice| +: `---' `-----' -- 2.37.0
