~bzg/worg

worg/org-contrib/babel/languages/ob-doc-plantuml.org -rw-r--r-- 6.0 KiB
b8c2bac2Ihor Radchenko org-maintenance.org: Add CUSTOM-ID anchors 2 days ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
#+OPTIONS:    H:3 num:nil toc:2 \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc broken-links:nil
#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
#+TITLE:      PlantUML Code Blocks in Babel
#+AUTHOR:     Thomas Dye
#+EMAIL:      tsd [at] tsdye [dot] online
#+LANGUAGE:   en
#+HTML_LINK_UP:    index.html
#+HTML_LINK_HOME:  https://orgmode.org/worg/
#+EXCLUDE_TAGS: noexport

#+name: banner
#+begin_export html
  <div id="subtitle" style="float: center; text-align: center;">
  <p>
  Babel support for <a href="https://plantuml.com/">PlantUML</a>
  </p>
  <p>
  <a href="https://www.uml.org/index.htm">
  <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/d/d5/UML_logo.svg/400px-UML_logo.svg.png"/>
  </a>
  </p>
  </div>
#+end_export

* Template Checklist [12/12]                                       :noexport:
  - [X] Revise #+TITLE:
  - [X] Indicate #+AUTHOR:
  - [X] Add #+EMAIL:
  - [X] Revise banner source block [3/3]
    - [X] Add link to a useful language web site
    - [X] Replace "Language" with language name
    - [X] Find a suitable graphic and use it to link to the language
      web site
  - [X] Write an [[Introduction]]
  - [X] Describe [[Requirements and Setup][Requirements and Setup]]
  - [X] Replace "Language" with language name in [[Org Mode Features for Language Source Code Blocks][Babel Features for Language Code Blocks]]
  - [X] Describe [[Header Arguments][Header Arguments]]
  - [X] Describe support for [[Sessions]]
  - [X] Describe [[Result Types][Result Types]]
  - [X] Describe [[Other]] differences from supported languages
  - [X] Provide brief [[Examples of Use][Examples of Use]]
* Introduction
=PlantUML= is a Java component for creating Unified Modeling Language
(UML) diagrams and several non-UML diagrams with a simple language.
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= blocks can be executed in one of two 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

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
for [[https://github.com/skuro/plantuml-mode#integration-with-org-mode][integration with Org]].  While [[https://melpa.org/#/plantuml-mode][plantuml-mode]] does allow use of a
remote server to render the diagram, please note that =ob-plantuml= does
not currently support this functionality.

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 =executable= to use your local =plantuml= executable.

Activate evaluation of =PlantUML= source code blocks by adding
=plantuml= to =org-babel-load-languages=.

#+BEGIN_SRC emacs-lisp
    (org-babel-do-load-languages
     'org-babel-load-languages
     '((plantuml . t))) ; this line activates plantuml
#+END_SRC

#+RESULTS:

* Babel Features for PlantUML Code Blocks
** Header Arguments
=PlantUML= code blocks default to =:results file= and =:exports results=.

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
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
:END:
Here is the obligatory Hello World! example in =PlantUML=.

The =PlantUML= code block in the Org buffer:
#+begin_example
,#+begin_src plantuml :file images/hello-uml.png
Bob -> Alice : Hello World!
,#+end_src
#+end_example

HTML output of the =PlantUML= code block:
#+begin_src plantuml :file images/hello-uml.png :exports both
Bob -> Alice : Hello World!
#+end_src

#+caption: The PNG Hello World! image.
#+RESULTS:
[[file:images/hello-uml.png]]

Here is an example using a theme.

The =PlantUML= code block in the Org buffer:
#+begin_example
,#+begin_src plantuml :file images/theme-uml.png
!theme spacelab
a -> b
b -> c
,#+end_src
#+end_example

PNG output of the =PlantUML= code block:
#+begin_src plantuml :file images/theme-uml.png :exports both
!theme spacelab
a -> b
b -> c
#+end_src

#+caption: The themed PNG image.
#+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|
:      `---'          `-----'