Markup languages for the newsletter

• Table of contents
• Automatic section numbering
• Output in HTML, plain text, PDF
• Including images to HTML and PDF version
• Lists and simple tables
• Customizable styles/templates for PDF and HTML
• Free Software (Free as in freedom – GPL, BSD, PD etc.)
• Available on Debian, Ubuntu, Fedora, SuSE, *BSD (and at least a little chance for Windowsuser to contribute something)

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.

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.

As mentioned in the mailing list Pandoc is quite suitable for the newsletter and it supports Markdown which is quite nice.