A major-mode for Emacs and websequencediagrams.com
Clone or download

README.org

wsd-mode

wsd-mode is a Emacs major-mode for www.websequencediagrams.com.

Travis-CI build-page. Build-status: https://api.travis-ci.org/josteink/wsd-mode.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 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

KeyAction
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:

(add-hook 'wsd-mode-hook 'company-mode)

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?