174 lines
7.8 KiB
Markdown
174 lines
7.8 KiB
Markdown
[![MELPA](http://melpa.org/packages/plantuml-mode-badge.svg)](http://melpa.org/#/plantuml-mode) [![MELPA Stable](http://stable.melpa.org/packages/plantuml-mode-badge.svg)](http://stable.melpa.org/#/plantuml-mode) [![CircleCI](https://circleci.com/gh/skuro/plantuml-mode.svg?style=svg)](https://circleci.com/gh/skuro/plantuml-mode) [![Coverage Status](https://coveralls.io/repos/github/skuro/plantuml-mode/badge.svg?branch=HEAD)](https://coveralls.io/github/skuro/plantuml-mode?branch=HEAD)
|
|
|
|
|
|
# PlantUML mode for Emacs
|
|
|
|
<img src="https://raw.githubusercontent.com/skuro/plantuml-mode/master/banner.png"
|
|
alt="plantuml-mode in action" title="Behold the beauty of text-based UML diagrams!" />
|
|
|
|
> “Pummel me all you want," I say. "Pummel me to death, in fact. My answers will not change."
|
|
> The Invierno step back, frowning. "You must love her very much," he says, not unkindly.”
|
|
>
|
|
> from [The Bitter Kingdom - Fire and Thorns #3](https://www.goodreads.com/book/show/11431896-the-bitter-kingdom)
|
|
|
|
|
|
A [PlantUML](http://plantuml.sourceforge.net/) major mode for Emacs.
|
|
|
|
# Installation
|
|
|
|
Make sure you have [MELPA](http://melpa.org/) enabled in your ``emacs.d``. Then, you can just
|
|
|
|
M-x package-install<RET>
|
|
plantuml-mode<RET>
|
|
|
|
Also, to enable preview you need to tell `plantuml-mode` where to locate the PlantUML JAR file. By default it will look for it in `~/plantuml.jar`, but you can specify any location with:
|
|
|
|
M-x customize-variable<RET>
|
|
plantuml-jar-path<RET>
|
|
|
|
You can also download the latest version of PlantUML straight into `plantuml-jar-path`:
|
|
|
|
M-x plantuml-download-jar<RET>
|
|
|
|
# Features
|
|
|
|
- Syntax highlight
|
|
- Autocompletion
|
|
- Preview of buffer or region
|
|
- [EXPERIMENTAL] Use either local JAR or remote server for preview
|
|
|
|
# Enable the major mode
|
|
|
|
You can automatically enable `plantuml-mode` for files with extension `.plantuml` by adding the following to your `.emacsrc`:
|
|
|
|
;; Enable plantuml-mode for PlantUML files
|
|
(add-to-list 'auto-mode-alist '("\\.plantuml\\'" . plantuml-mode))
|
|
|
|
Of course, you can always enable manually the major mode by typing `M-x plantuml-mode` once in the desired PlantUML file buffer.
|
|
|
|
# Usage
|
|
|
|
You can tell `plantuml-mode` to autocomplete the word before the cursor by typing `M-x plantuml-complete-symbol`. This will open a popup with all the available completions as found in the list of keywords given by running PlantUML with the `-language` flag.
|
|
|
|
To render the PlantUML diagram within Emacs, you can hit `M-x plantuml-preview`. This will run PlantUML and display the result in the `*PLANTUML-Preview*` buffer. The format used to render the diagram is automagically chosen from what's supported by your Emacs. It will be one of the following, in order of preference:
|
|
|
|
- SVG
|
|
- PNG
|
|
- Unicode ASCII art
|
|
|
|
The diagram will be either created from the selected region if one is available in the current buffer, or using the whole buffer otherwise.
|
|
|
|
If you want to force a specific output format, you can customize the variable `plantuml-output-type` to the value you prefer.
|
|
|
|
## Default key bindings
|
|
|
|
The following shortcuts are enabled by default:
|
|
|
|
C-c C-c plantuml-preview: renders a PlantUML diagram from the current buffer in the best supported format
|
|
|
|
C-u C-c C-c plantuml-preview in other window
|
|
|
|
C-u C-u C-c C-c plantuml-preview in other frame
|
|
|
|
## Integration with `org-mode`
|
|
|
|
You can use `plantuml-mode` to edit PlantUML source snippets within an [`org-mode`](http://orgmode.org/) document. To do so, you need to first register it with the `plantuml` language:
|
|
|
|
```
|
|
(add-to-list
|
|
'org-src-lang-modes '("plantuml" . plantuml))
|
|
```
|
|
|
|
Then you can edit a `plantuml` code block with `plantuml-mode` by hitting `C-'` while inside of the code block itself:
|
|
|
|
```elisp
|
|
#+BEGIN_SRC plantuml
|
|
<hit C-c ' here to open a plantuml-mode buffer>
|
|
#+END_SRC
|
|
```
|
|
|
|
When in the `plantuml-mode` buffer you can then hit again `C-'` to return to the original `org-mode` document.
|
|
|
|
# Execution modes
|
|
|
|
**EXPERIMENTAL**
|
|
|
|
As of `v1.3.0` support is added for switching execution mode. The following two modes are available:
|
|
|
|
- `jar` (default) to run PlantUML as a local JAR file. This is the traditional system used by `plantuml-mode`
|
|
- `server` (experimental) to let an instance of [`plantuml-server`](https://github.com/plantuml/plantuml-server) render the preview
|
|
- `executable` to run PlantUML as a local executable file. This is useful if your package manager provides a executable for PlantUML.
|
|
|
|
You can customize `plantuml-default-exec-mode` or run `plantuml-set-exec-mode` from a `plantuml-mode` buffer to switch modes.
|
|
|
|
## Configure server rendering
|
|
|
|
When selecting `server` execution modes, you can customize the following variable to set the server to use for rendering:
|
|
|
|
```
|
|
plantuml-server-url
|
|
```
|
|
|
|
It defaults to `"https://www.plantuml.com/plantuml"`.
|
|
|
|
# Migration from `puml-mode`
|
|
|
|
If you were previously using `puml-mode`, you should change any reference to a `puml-..` variable or function to its `plantuml-..` counterpart. Most notably, `puml-plantuml-jar-path` is now just `plantuml-jar-path`.
|
|
|
|
## Deprecation warning
|
|
|
|
If `puml-mode` is still being loaded by your Emacs, a Warning will be shown any time you open a PlantUML file. This is to remind you that you are running deprecated software. If you want to suppress the (intentionally) annoying warning, you can customize the variable `plantuml-suppress-deprecation-warning`.
|
|
|
|
# Troubleshooting
|
|
|
|
## Debug messages
|
|
|
|
As of `v0.6.2` the following commands have been added to help resolving problems:
|
|
|
|
```
|
|
plantuml-enable-debug
|
|
plantuml-disable-debug
|
|
```
|
|
|
|
With debug enabled, the actual command used to invoke PlantUML is printed into a buffer called `*PLANTUML Messages*`. You can inspect that buffer to make sure that PlantUML is properly set up, or use it to supply extra information when opening [issues](https://github.com/skuro/plantuml-mode/issues).
|
|
|
|
## Blank previews
|
|
|
|
If you are using SVG rendering and `plantuml-preview` shows you an empty buffer, chances are something is wrong with the PlantUML output. While inside the preview buffer, hit `C-c C-c` to switch to
|
|
the textual mode and see if the output is valid SVG.
|
|
|
|
## Development
|
|
|
|
Development happens mostly on the `develop` branch, which is released on MELPA at every commit. The `master` branch is used to generate tags which are then released to [MELPA
|
|
stable](https://stable.melpa.org).
|
|
|
|
In order to contribute to `plantuml-mode` make sure to:
|
|
|
|
- agree with the [GPLv3+ licencing terms](#License) as they are mandated by Emacs
|
|
- install [`cask`](https://github.com/cask/cask)
|
|
- always test your code and run the full test suite with `cask exec ert-runner` (or just by `make`)
|
|
- ensure you always target `develop` in your pull requests
|
|
|
|
For collaborators who have merge access to the repo:
|
|
- make sure [`set-version.sh`](./blob/develop/bin/set-version.sh) is run as part of your [`pre-commit` git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
|
|
- always merge PRs on the command line
|
|
- when releasing a new stable version, add the proper entry in the changelog within `plantuml-mode.el` to ensure the right version is set for `plantuml-mode-version`
|
|
|
|
# Credits
|
|
|
|
This project stemmed from the great work of [Zhang Weize](http://zhangweize.wordpress.com/2010/09/20/update-plantuml-mode/),
|
|
and the current code still borrows a lot from it.
|
|
|
|
Thanks to [Pavel G. Koukoushkin](https://github.com/svargellin) for implementing the preview functionality.
|
|
Thanks to [Raymond Huang](https://github.com/rymndhng) for implementing the first drop of the indentation support.
|
|
|
|
Thanks to [all the awesome contributors](https://github.com/skuro/plantuml-mode/graphs/contributors), you rock!
|
|
|
|
# See also
|
|
|
|
- [PlantUML](http://plantuml.com/)
|
|
- [`flycheck-plantuml`](https://github.com/alexmurray/flycheck-plantuml)
|
|
|
|
# License
|
|
|
|
Released under the terms of [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) or (at your option) any later version. See [LICENSE.txt](https://github.com/skuro/plantuml-mode/blob/master/LICENSE.txt).
|