Markup languages for the newsletter

• Table of contents
• Automatic section numbering
• Output in HTML, plain text, PDF
• Including images to HTML and PDF version
• Easy generating of plain text version w/o markup and unresolved image links etc.
• 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.

You can format your file in Pandoc-enhanced Markdown. Markdown is a very easy-to-read and easy-to-write plain text format. The pandoc tool can convert your plain text source file into html, LaTeX, and other output formats (it can, in fact, convert between various formats, as described on its webpage).

Once your newsletter source file is written, create an html version like so:

  pandoc -s --toc -N --css=style.css -o newsletter_n.html newsletter_n.txt

To create a pdf version:

  pandoc -s --toc -N -o newsletter_n.tex newsletter_n.txt
  pdflatex newsletter_n.tex
  pdflatex newsletter_n.tex

where you run that pdflatex command twice in order to correctly generate the table of contents.

On Debian-based GNU/Linux systems, you can install Pandoc in the usual way: aptitude install pandoc. Otherwise, see the install instructions.

For generating the pdf, you'll also need a LaTeX distribution installed, such as texlive. On Debian-based systems: aptitude install texlive