Storage and presentation format for specification

[mo-marqh]

Decide on a storage format and presentation formats for the #5 specification

requirements:

1. storage format is plain text
   • to support source control
2. identified releases of source and publish content are provided
3. html presentation format required
   • may this be in the public domain?
4. pdf presentation format required

Options Analysis

• markdown
• asciidoc
• sphinx
• latex
• m$Word
  • discounted - not plain text or source controllable

[mo-marqh]

on AsciiDoc (https://asciidoctor.org/)

• +ve
  • meets core requirements
  • widely used by standards bodies (e.g. CF-netCDF, OGC)
  • flexible and well featured
  • simple markup syntax
• -ve
  • asciidoctor not installed on linux desktop
  • not widely used within Met Office

[mo-marqh]

on MarkDown

• +ve
  • flexible and usefully featured
  • simple markup syntax
• -ve
  • processors not installed on linux desktop (e.g. pandoc)
  • lacking rich features

[mo-marqh]

on sphinx

• +ve
  • meets core requirements
  • flexible and well featured
  • simple markup syntax
• -ve
  • lots of tools targeting code documentation, rather than specification

[mo-marqh]

on LaTeX

• +ve
  • widely used in UM documentation
  • flexible and well featured
  • widely used within Met Office
• -ve
  • not so good at producing html content
  • less than simple markup syntax

[mo-marqh]

there's a TeX example in PR #11 and an asciidoc example in PR #12

[mo-marqh]

after in-person discussions, the consensus appears to be to run with asciidoc for now

there's a good set of reasons to consider sphinx and we may come back to this in the future
(indeed, converting from asciidoc markup to sphinx should not be too onerous, if needed)

But the simple setup, the clear markup, and the PDF and HTML document style output of asciidoctor have gained significant support.
Also recognising that communities including the CF-netCDF community use this for their own publishing.

So, we'll close this Issue, merge #12 and close #11