[PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output

[PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output

[Joseph Turner]

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

Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output

[Ihor Radchenko]

Joseph Turner <joseph@breatheoutbreathe.in> writes:

> Document the new functionality of ob-plantuml to insert ASCII diagrams
> directly in the buffer.

Thanks!

> -=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]]

I do not think that ob-plantuml.el supports server connections. We may
need to clarify that server part and plantuml-* variables have nothing
to do with ob-plantuml per se.

Otherwise, the patch looks good.

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92

Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output

[Joseph Turner]

You're right! Thank you for catching my mistake. I'll send another patch.

Joseph


Ihor Radchenko <yantar92@gmail.com> writes:

> Joseph Turner <joseph@breatheoutbreathe.in> writes:
>
>> Document the new functionality of ob-plantuml to insert ASCII diagrams
>> directly in the buffer.
>
> Thanks!
>
>> -=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]]
>
> I do not think that ob-plantuml.el supports server connections. We may
> need to clarify that server part and plantuml-* variables have nothing
> to do with ob-plantuml per se.
>
> Otherwise, the patch looks good.

Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output

[Ihor Radchenko]

Joseph Turner <joseph@breatheoutbreathe.in> writes:

> You're right! Thank you for catching my mistake. I'll send another patch.

Did you have a chance to work on the patch?

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92

Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output

[Ihor Radchenko]

Ihor Radchenko <yantar92@gmail.com> writes:

> Joseph Turner <joseph@breatheoutbreathe.in> writes:
>
>> You're right! Thank you for catching my mistake. I'll send another patch.
>
> Did you have a chance to work on the patch?

Oops. Missed that you've sent a patch in another thread. Sorry for the noise.

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92

Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output

[Joseph Turner]

No worries! Thanks for your patient help.

Ihor Radchenko <yantar92@gmail.com> writes:

> Ihor Radchenko <yantar92@gmail.com> writes:
>
>> Joseph Turner <joseph@breatheoutbreathe.in> writes:
>>
>>> You're right! Thank you for catching my mistake. I'll send another patch.
>>
>> Did you have a chance to work on the patch?
>
> Oops. Missed that you've sent a patch in another thread. Sorry for the noise.

Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output

[Joseph Turner]

Actually, I just looked at the org-mode documentation on the site today,
and noticed that the examples of use section
(https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-plantuml.html#org6cd541e)
has the wrong ASCII output. The output should be

      ,---.          ,-----.
      |Bob|          |Alice|
      `-+-'          `--+--'
        | Hello World!  |   
        |-------------->|   
      ,-+-.          ,--+--.
      |Bob|          |Alice|
      `---'          `-----'

but instead it's just

Bob -> Alice : Hello World!

The results appear just find when I execute the org src code block on my
local machine.

Joseph

[BUG] Server-side export problem in Worg? (was: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output)

[Ihor Radchenko]

Joseph Turner <joseph@breatheoutbreathe.in> writes:

> Actually, I just looked at the org-mode documentation on the site today,
> and noticed that the examples of use section
> (https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-plantuml.html#org6cd541e)
> has the wrong ASCII output. The output should be
>
>       ,---.          ,-----.
>       |Bob|          |Alice|
>       `-+-'          `--+--'
>         | Hello World!  |   
>         |-------------->|   
>       ,-+-.          ,--+--.
>       |Bob|          |Alice|
>       `---'          `-----'
>
> but instead it's just
>
> Bob -> Alice : Hello World!

The .org source for the page does contain the correct ASCII art version.
(you can check it at https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-plantuml.org)

Bastien, there seems to be an issue with Worg export on server. Can you
please check?

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92

Re: [BUG] Server-side export problem in Worg? (was: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output)

[Max Nikulin]

On 22/09/2022 19:18, Ihor Radchenko wrote:
> Joseph Turner writes:
> 
>> Actually, I just looked at the org-mode documentation on the site today,
>> and noticed that the examples of use section
>> (https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-plantuml.html#org6cd541e)
>> has the wrong ASCII output. The output should be
>>
>>        ,---.          ,-----.
>>        |Bob|          |Alice|
>>        `-+-'          `--+--'
>>          | Hello World!  |
>>          |-------------->|
>>        ,-+-.          ,--+--.
>>        |Bob|          |Alice|
>>        `---'          `-----'
>>
>> but instead it's just
>>
>> Bob -> Alice : Hello World!
> 
> The .org source for the page does contain the correct ASCII art version.
> (you can check it at https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-plantuml.org)
> 
> Bastien, there seems to be an issue with Worg export on server. Can you
> please check?

There is nothing wrong with Worg export. The code block lacks ":exports 
result", so HTML output contain its source.

Notice that plantuml is not installed by CI (I think intentionally), so 
no code blocks are evaluated during export. You may check logs by 
clicking on a build number at https://builds.sr.ht/~bzg/worg

Re: [BUG] Server-side export problem in Worg?

[Bastien Guerry]

Ihor Radchenko <yantar92@gmail.com> writes:

> Bastien, there seems to be an issue with Worg export on server. Can you
> please check?

This is now fixed, thanks:

https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-plantuml.html#org6cd541e

-- 
 Bastien

Re: [BUG] Server-side export problem in Worg?

[Joseph Turner]

Thank you for the fix!

Joseph
Bastien Guerry <bzg@gnu.org> writes:

> Ihor Radchenko <yantar92@gmail.com> writes:
>
>> Bastien, there seems to be an issue with Worg export on server. Can you
>> please check?
>
> This is now fixed, thanks:
>
> https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-plantuml.html#org6cd541e