Change Modelica language spec documentation format

Abstract

We want a version of the specification that:

  • Can be easily modified.
  • Supports collaboration.
  • Can be converted to different formats easily.

Revisions

Version Date Comments
v1 2015-06-08 Initial version

Proposed Changes in Specification

The specification will need to be updated. The initial conversion can be done by pandoc with manual changes of the specification to make sure all formatting has been preserved, indexes updated, source code using source code blocks, etc.

Required changes in List of Keywords

Conversion to restructured text.

Required changes in Grammar

Conversion to restructured text. Actually write the grammar in EBNF (the old one does not follow the grammar).

Required changes in Specification Text

All sections.

Motivation

Benefits of using restructured text (Sphinx)

It is a text-based representation

  • Equations are converted to nice vector graphics:

{\partial x \over \partial t} = 0.0

  • Easy to get diff’s for equations as they are also written in textual markup (latex).
  • Easier to merge changes using a textual format than a binary one. This makes collaboration much simpler, in particular when working on making sure MCP’s are up-to-date.
  • Easy to track individual changes (each commit is textual and easy to see).
  • We could work on the specification directly during the design or web meetings.

Restructured text specifics

Easier to reference particular subsections or items (a static, named, link instead of an ever-changing section number). That is, how to reference the specification from for example an e-mail or forum discussion.

Automatic syntax highlighting for Modelica code snippets (no more trying to remember which words to boldface):

Listing 1 Bouncing ball example with emphasis on lines 4 and 14
model BouncingBall
  parameter Real e=0.7 "coefficient of restitution";
  parameter Real g=9.81 "gravity acceleration";
  Real h(start=1) "height of ball";
  Real v "velocity of ball";
  Boolean flying(start=true) "true, if ball is flying";
  Boolean impact;
  Real v_new;
  Integer foo;
equation
  impact = h <= 0.0;
  foo = if impact then 1 else 2;
  der(v) = if flying then -g else 0;
  der(h) = v;

  when {h <= 0.0 and v <= 0.0,impact} then
    v_new = if edge(impact) then -e*pre(v) else 0;
    flying = v_new > 0;
    reinit(v, v_new);
  end when;
end BouncingBall;

Good search functionality (the JavaScript is able to search the html even when the HTML is generated locally - no server required).

Google indexes the generated HTML easily.

It is also possible to host different versions of the documentation on https://readthedocs.org.

http://sphinx-doc.org/ has good documentation on how to use restructured text.

There are many useful features available:

  • Abbreviations like using :abbr: MSL or as a short-hand name |MLS| MLS
  • Citations like :cite:`something` (working with bibtex) is available as plugins.
  • Easy generation of an index, like if and when.
  • Easy to theme the generated HTML.

Generation of the text into multiple formats:

  • HTML (the primary format, web searchable and linkable)
  • PDF (via LaTeX)
  • epub (e-book readers)
  • qthelp (minor benefit; tools can use the built-in help and load the spec in it)

Benefits of using git

Easier to propose changes, for example by writing an MCP in restructured text or creating a github pull request for fixing typo’s.

Possible to work on the specification during meetings even when the Wi-Fi is failing.

Rationale

Design process

Binary documentation formats are horrible. ModelicaBook uses Sphinx, and OpenModelica documentation will as well since the system mostly works.

Alternative Designs

Investigated pandoc, docbook, ASCIIDoc.

State of the Art

It is used to document libraries, for example on http://phpmyadmin.readthedocs.org/en/latest/. It supports other languages as well, but the sphinx things allows you to choose version and which version (HTML/PDF/etc) to download.

Backwards Compatibility

Corruption of existing models

No actual changes will be made.

Means of mitigation

No actual changes will be made.

Implementation Effort

No changes will be made that directly affect Modelica tools.

Mandatory Parts

No changes will be made that directly affect Modelica tools.

Optional Parts

No changes will be made that directly affect Modelica tools.

Way of Implementation

No changes will be made that directly affect Modelica tools.

Required Patents

No changes will be made that affect patents.

References