* wsd-mode

wsd-mode is a Emacs major-mode for
[[http://www.websequencediagrams.com][www.websequencediagrams.com]].

Build status: [[https://github.com/josteink/wsd-mode/workflows/CI/badge.svg]]

** wsd-mode explained in two screenshots

Model processes through simple sequence-scripts like this:

[[https://github.com/josteink/wsd-mode/raw/devel/artwork/wsd-mode-1.png]]

And get pretty diagrams like this generated for you:

[[https://github.com/josteink/wsd-mode/raw/devel/artwork/wsd-mode-2.png]]

If that sounds interesting and you want to know how that works,
feel free to read along.

** Features

The major-mode provides the following features:

- proper syntax highlighting for all standard WSD syntax. Almost
  feature complete syntax for pro-only features (see [[https://github.com/josteink/wsd-mode/issues][issues]])
- indentation based on nested constructs and alternative paths.
- supports running Emacs in GUI and the terminal.
- auto-generating diagrams based on source.
- inline rendering in Emacs frames when possible, with fallback to OS or
  browser for viewing when critical features are unavailable.
- ~org-babel~ support (use ~wsd~ as language).
- ~company-mode~ support.
- limited ~flycheck~ support.


** Installation

wsd-mode can be installed as a package, from Marmalade, MELPA and MELPA stable.

Installation from MELPA will be a development snapshot and always be latest version.
Versions available from Marmalade and MELPA stable should match, and be more stable versions
released at less frequent intervals.

To install the package, simply start Emacs and issue the following command:

~M-x package-install <RET> wsd-mode <RET>~.

** Usage

Using wsd-mode is very easy. Either create a new buffer and activate using
~M-x wsd-mode~, or open a new file with a ~.wsd~ extension. For files with
a ~.wsd~ extension wsd-mode is activated automatically.

Once the mode is active, type along as you would otherwise do on
[[websequencediagrams.com]].

*** Key-bindings

| Key     | Action                                                      |
|---------+-------------------------------------------------------------|
| C-c C-c | "Build" diagram and display inline in Emacs (when possible) |
| C-c C-e | "Export" diagram and show online on [[websequencediagrams.com]] |


*** Customization

All customizable options are available in the normal Emacs customize
framework.

~M-x customize-group <RET> wsd-mode~

Briefly, here are the defaults for the variables which can be customized:

- wsd-base-url (default "http://www.websequencediagrams.com/". The URL of your in-house WSD installation)
- wsd-api-key (default blank. required for premium-features.)
- wsd-format (default png. svg requires premium, thus api-key.)
- wsd-style (default modern-blue)
- wsd-indent-offset (default 4)
- wsd-font-lock-keywords

~wsd-mode~ supports three different fontification levels:

- ~wsd-font-lock-keywords-1~: keywords 
- ~wsd-font-lock-keywords-2~: keywords and operators
- ~wsd-font-lock-keywords-3~: keywords, operators and variables (default)

*** Org-babel

For usage with org-babel create a ~#+BEGIN_SRC~ block with ~wsd~ as language. Use ~C-c C-c~ to evaluate
the code and write the diagram to disk, putting it in a ~#+RESULTS:~ block below.

You can optionally use a ~:file~ parameter as argument to use a hard-coded filename instead of having one
generated for you automatically, on the fly.

When exporting org-document as HTML or similar (~C-e C-c h o~), the ~wsd-mode~ code will not be included
in the document, but instead the rendered diagram.

See the [[demo.org]]-file for a concrete example. It is recommended to
inspect this file in Emacs, not on Github.

*** Flycheck

~wsd-mode~ has limited support for ~flycheck~. While flycheck in general does
all the checking as you type, providing you with real-time feedback,
~wsd-mode~ only updates the error-list upon script-compilation.

This means that using flycheck should incur no extra processing cost, and
therefore, if flycheck is installed, it will also be activated automatically whenever
~wsd-mode~ is.

This is due to implementation and may be subject to change in the future.

*** company-mode

~wsd-mode~ supports company-mode completion. Enable it the way you
usually enable it in your init.el:

#+BEGIN_SRC emacs-lisp
  (add-hook 'wsd-mode-hook 'company-mode)
#+END_SRC

Currently completion on keywords and participants is supported.

** Planned features

The following features has been considered. They may eventually be
implemented:

- auto-insert-mode integration?
- websequencediagram.com account-integration?