Create an asciidoc version of the NFFT manual.

[jenskeiner]

The NFFT manual is currently maintained in LaTeX sources. An asciidoc version should be included in the source package to simplify maintenance. The asciidoclanguage is simple yet powerful enough to support what is needed for the manual, including math formulae.

Also, GitHub can render asciidoccontent on-the-fly from the sources, which makes it easier to browse the documentation online.

And additional benefit is that any changes to the library that would entail updating the documentation will become more visible in code review.

[kevinmatthes]

We can create such a documentation very easy with pandoc. We would just need to add the concerning build instructions and experiment with the optimal set of options.

pandoc is a GPL 2 library, written in Haskell, which converts file formats from one into another. It is available for UNIX and Windows, as well, and brings an application in order to access the library's possibilities. This is very useful when dealing with different file types which need to fit a certain target platform's requirements (creating Word documents on Linux for Windows machines -- pandoc cares for the fonts). For instance, Markdown files, such as the README.md and the currently named as such CONVENTIONS.md (see #123), can be converted with pandoc into printable versions by running

pandoc README.md -o readme.pdf

It also supports further formats, such as DOCX, PPTX, TEX and asciidoc. All we need is a source file -- or a set of them -- in order to give it to pandoc. More than one file in the input will cause pandoc to render all of them in order of appearance into the output file, such as sections of a manual. More than one output file requires multiple calls. Since we have them as LaTeX files, we just need to call the application accordingly in order to generate the intended documentations.

Thereby, I would like to suggest furthermore to add according build instructions to all build systems (see #8) such that users can choose if they also want to have printable versions of README.md and CONVENTIONS.md and, if so, in which formats (Word documents, PDF documents, asciidoc, HTML pages etc.).