emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output
@ 2022-08-05 21:42 Joseph Turner
  2022-08-06  8:37 ` Ihor Radchenko
  0 siblings, 1 reply; 11+ messages in thread
From: Joseph Turner @ 2022-08-05 21:42 UTC (permalink / raw)
  To: emacs-orgmode; +Cc: yantar92, 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



^ permalink raw reply related	[flat|nested] 11+ messages in thread

* Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output
  2022-08-05 21:42 [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output Joseph Turner
@ 2022-08-06  8:37 ` Ihor Radchenko
  2022-08-14  5:30   ` Joseph Turner
  0 siblings, 1 reply; 11+ messages in thread
From: Ihor Radchenko @ 2022-08-06  8:37 UTC (permalink / raw)
  To: Joseph Turner; +Cc: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output
  2022-08-06  8:37 ` Ihor Radchenko
@ 2022-08-14  5:30   ` Joseph Turner
  2022-09-15  9:32     ` Ihor Radchenko
  0 siblings, 1 reply; 11+ messages in thread
From: Joseph Turner @ 2022-08-14  5:30 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

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.



^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output
  2022-08-14  5:30   ` Joseph Turner
@ 2022-09-15  9:32     ` Ihor Radchenko
  2022-09-15  9:33       ` Ihor Radchenko
  0 siblings, 1 reply; 11+ messages in thread
From: Ihor Radchenko @ 2022-09-15  9:32 UTC (permalink / raw)
  To: Joseph Turner; +Cc: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output
  2022-09-15  9:32     ` Ihor Radchenko
@ 2022-09-15  9:33       ` Ihor Radchenko
  2022-09-15 16:23         ` Joseph Turner
  0 siblings, 1 reply; 11+ messages in thread
From: Ihor Radchenko @ 2022-09-15  9:33 UTC (permalink / raw)
  To: Joseph Turner; +Cc: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output
  2022-09-15  9:33       ` Ihor Radchenko
@ 2022-09-15 16:23         ` Joseph Turner
  2022-09-21  9:19           ` Joseph Turner
  0 siblings, 1 reply; 11+ messages in thread
From: Joseph Turner @ 2022-09-15 16:23 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

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.



^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output
  2022-09-15 16:23         ` Joseph Turner
@ 2022-09-21  9:19           ` Joseph Turner
  2022-09-22 12:18             ` [BUG] Server-side export problem in Worg? (was: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output) Ihor Radchenko
  0 siblings, 1 reply; 11+ messages in thread
From: Joseph Turner @ 2022-09-21  9:19 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

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



^ permalink raw reply	[flat|nested] 11+ messages in thread

* [BUG] Server-side export problem in Worg? (was: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output)
  2022-09-21  9:19           ` Joseph Turner
@ 2022-09-22 12:18             ` Ihor Radchenko
  2022-09-22 14:03               ` Max Nikulin
  2022-09-22 15:36               ` [BUG] Server-side export problem in Worg? Bastien Guerry
  0 siblings, 2 replies; 11+ messages in thread
From: Ihor Radchenko @ 2022-09-22 12:18 UTC (permalink / raw)
  To: Joseph Turner, Bastien; +Cc: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [BUG] Server-side export problem in Worg? (was: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output)
  2022-09-22 12:18             ` [BUG] Server-side export problem in Worg? (was: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output) Ihor Radchenko
@ 2022-09-22 14:03               ` Max Nikulin
  2022-09-22 15:36               ` [BUG] Server-side export problem in Worg? Bastien Guerry
  1 sibling, 0 replies; 11+ messages in thread
From: Max Nikulin @ 2022-09-22 14:03 UTC (permalink / raw)
  To: Ihor Radchenko, Joseph Turner, Bastien; +Cc: emacs-orgmode

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



^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [BUG] Server-side export problem in Worg?
  2022-09-22 12:18             ` [BUG] Server-side export problem in Worg? (was: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output) Ihor Radchenko
  2022-09-22 14:03               ` Max Nikulin
@ 2022-09-22 15:36               ` Bastien Guerry
  2022-09-22 23:53                 ` Joseph Turner
  1 sibling, 1 reply; 11+ messages in thread
From: Bastien Guerry @ 2022-09-22 15:36 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: Joseph Turner, emacs-orgmode

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


^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: [BUG] Server-side export problem in Worg?
  2022-09-22 15:36               ` [BUG] Server-side export problem in Worg? Bastien Guerry
@ 2022-09-22 23:53                 ` Joseph Turner
  0 siblings, 0 replies; 11+ messages in thread
From: Joseph Turner @ 2022-09-22 23:53 UTC (permalink / raw)
  To: Bastien Guerry; +Cc: Ihor Radchenko, emacs-orgmode

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



^ permalink raw reply	[flat|nested] 11+ messages in thread

end of thread, other threads:[~2022-09-22 23:54 UTC | newest]

Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-08-05 21:42 [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output Joseph Turner
2022-08-06  8:37 ` Ihor Radchenko
2022-08-14  5:30   ` Joseph Turner
2022-09-15  9:32     ` Ihor Radchenko
2022-09-15  9:33       ` Ihor Radchenko
2022-09-15 16:23         ` Joseph Turner
2022-09-21  9:19           ` Joseph Turner
2022-09-22 12:18             ` [BUG] Server-side export problem in Worg? (was: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output) Ihor Radchenko
2022-09-22 14:03               ` Max Nikulin
2022-09-22 15:36               ` [BUG] Server-side export problem in Worg? Bastien Guerry
2022-09-22 23:53                 ` Joseph Turner

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).