Specification Technical Editing

This page provides some details and background on the process for editing the technical specification and the “style” used within it. Direct contributors are asked to review it before submitting pull requests.

• The GEISA specification is maintained in our github specification repository.

• Instructions for building the specification are in the ReadMe.

• The specification is written in Restructured Text and uses Sphinx to build the PDF and HTML outputs.

• Graphics should be provided as SVGs and placed in the images directory. The build script will automatically generate the interim PDF files required to include them in the Latex PDF output.

• The project has integrated Mermaid to support text based creation of diagrams. To include a mermaid diagram, include a .mermaid file with the mermaid diagram instructions in the same folder as the .rst file. These diagrams will be automatically converted to .svg for the html output and for inclusion in the PDF. To include the mermaid diagram in the text create an appropriate .. figure:: reference in the text.

• Images which will be widely used should be given a substitution macro in conf.py.

• Substitution macros should begin with geisa- followed by some short description of the element.

• Contributors are likely to be using a variety of different text editors to work on the specification. With this in mind contributors are asked to configure their editors to support:

  • No tab characters – Tabs should generate two spaces

  • Unix file format – Newlines only, no Carriage Returns or Carriage Return/Line Feeds

  • Hard wrap at 80 columns – Soft wraps can make editing challenging on some editors and makes file comparisons harder

• Where appropriate, editors are encouraged to provide cross references using Restructured Text’s :doc:`section-name` syntax.

• Subsections which focus on a specific aspect of interoperability should begin with the appropriate header image substitution macro. Current header images include:

  • |geisa-adm-hdr|

  • |geisa-api-hdr|

  • |geisa-lee-hdr|

  • |geisa-vee-hdr|

• A GEISA pyramid should be placed at the end of a subsection using |geisa-pyramid|. This indicates that a given subsection or interoperability discussion is complete.

• Terms and abbreviations should have entries in glossary.rst.

• Standards or specifications that the GEISA specification refers to should be listed with the full URL in references.rst