spacemacs/layers/+lang/plantuml/README.org

#+TITLE: plantuml layer

#+TAGS: dsl|layer|markup|programming

[[file:img/logo.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#org-babel-integration][Org-Babel Integration]]
- [[#key-bindings][Key bindings]]

* Description
This layer enables support for [[https://github.com/skuro/plantuml-mode][plantuml-mode]], which provides
a major-mode for [[http://plantuml.com][plantuml]]. PlantUML is a tool to generate [[https://en.wikipedia.org/wiki/Unified_Modeling_Language][UML diagrams]] from plain-text.

For help with how to use plantuml, see the [[http://plantuml.com][plantuml website]] and the [[http://plantuml.com/guide][reference guide]].

The official file extension supported by this layer is =.pum=. and =.puml=. If you want something else,
set it in your =user-config= function of your =~/.spacemacs= file.

For example, the following diagram can be defined as follows:

#+BEGIN_SRC plantuml
  @startuml
  JAremko->robbyoconnor : I think the docs can benefit from some kind of illustration
  JAremko<-robbyoconnor : I'm too lazy -- I have actual work to do. I link to the docs. If you can write me a diagram in plantuml, I'll gladly compile and add it.
  JAremko->robbyoconnor : *gives ths diagram*
  robbyoconnor<-JAremko : *robbyoconnor adds it and JAremko is happy*
  ...
  robbyoconnor->theOtherPerson : And they thinks it's funny? Yup, they definitely finds it funny. Right?
  @enduml
#+END_SRC

[[file:img/dia.png]]

** Features:
- Syntax highlighting
- Diagram preview in various output formats
- Embedding into org documents
- Controlling the =Plantuml= compiler directly from emacs

* Install
To use this contribution add it to your =~/.spacemacs=

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(plantuml))
#+END_SRC

To control the =Plantuml= compiler you also need to download the [[http://plantuml.com/download][Plantuml jar]]
and configure the =plantuml-jar-path= respectively:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '((plantuml :variables plantuml-jar-path "~/plantUml.jar")))
#+END_SRC

To get the full range of =Plantuml= compilations working, you will also need
the native package [[http://graphviz.org/][graphviz]] installed on your system.

If you don't want to compile locally you can set =plantuml-exec-mode= to =server=.
This will make plantuml try to use an online compile server. Be warned these resources
change often and plantuml-mode is not always up-to-date. For a stable user experience
we recommend using the default jar option instead.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '((plantuml :variables plantuml-default-exec-mode 'server)))
#+END_SRC

* Org-Babel Integration
To enable the execution of embedded plantuml code blocks within [[http://orgmode.org/][Org-Mode]]
documents, define a value for =org-plantuml-jar-path= in your =~/.spacemacs=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '((plantuml :variables plantuml-jar-path "~/plantUml.jar" org-plantuml-jar-path "~/plantUml.jar")))
#+END_SRC

* Key bindings

| Key binding              | Description                                           |
|--------------------------+-------------------------------------------------------|
| ~SPC m c c~ or ~C-c C-c~ | Build diagram from the text in the current buffer     |
| ~SPC m c o~              | Set the output type (=unicode text=, =svg=, or =png=) |