This is an old revision of the document!
Table of Contents
Markup languages for the newsletter
Featureset
- Table of contents
- Automatic section numbering
- Output in HTML, plain text, PDF
Languages / Toolkits
LaTeX
ReST
Sphinx
AsciiDoc
Asciidoc provides table of contents, automatic section numbering and output in all three formats. As shown in the example at: https://github.com/elextr/geany_stuff/commit/d094fb77d37bd00c4172041ea95be08ba294460c the html can be css formatted to be the same as Newsletter 2, so that is done. The lightweight markup language is similar to most such languages, eg ReST, Markdown etc and like them you could almost use the source as the text version. Pros are this is what Asciidoc is designed for, writing human documents, it isn't a code docstring extractor that is being forced into another role. It also provides a Python script to assist in running the backend toolchains and it supports more than one toolchain in case one proves to be a problem and xhtml11 or xhtml5 are produced directly without any toolchain. Cons it isn't used in Geany so its an extra tool, but it can be just installed in a user directory, it doesn't need to be a system install.
Doxygen
Not sure about automatic section numbering, but Doxygen does all the other stuff and is already being used in Geany (see the Plugin Howto). It can be used like this to generate documents, even though it's normally used with source code API docs (I guess it's the same case as Sphinx and GTK-DOC?). Pros are it's easy, matches existing Geany documents, and supports lots of output formats. Cons are that it's not the primary use for the tool and it might not do plain text output, and the markup seems not to be great for plain-text use.
