Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/josteink/wsd-mode

A major-mode for Emacs and websequencediagrams.com
https://github.com/josteink/wsd-mode

Last synced: 21 days ago
JSON representation

A major-mode for Emacs and websequencediagrams.com

Awesome Lists containing this project

README 

        
* 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  wsd-mode ~.



** 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  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?