emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Joseph Turner <joseph@breatheoutbreathe.in>
To: emacs-orgmode@gnu.org
Cc: yantar92@gmail.com, Joseph Turner <joseph@breatheoutbreathe.in>
Subject: [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output
Date: Fri,  5 Aug 2022 14:42:14 -0700	[thread overview]
Message-ID: <20220805214214.25723-1-joseph@breatheoutbreathe.in> (raw)

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



             reply	other threads:[~2022-08-05 21:43 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-08-05 21:42 Joseph Turner [this message]
2022-08-06  8:37 ` [PATCH] org-contrib/babel/languages/ob-doc-plantuml.org: ASCII output 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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220805214214.25723-1-joseph@breatheoutbreathe.in \
    --to=joseph@breatheoutbreathe.in \
    --cc=emacs-orgmode@gnu.org \
    --cc=yantar92@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).