Create a specification of the fpm command line interface (asciidoctor)

[awvwgk]

Create fpm(1) and the currently available six subcommand manual pages.

To check the resulting manual pages on the command line translate them with asciidoctor:

asciidoctor -b manpage fpm.adoc
man -l fpm.1

I guess asciidoc is not that well known by everybody, checkout its homepage and the asciidoctor project for a short overview. It is comparable to reStructuredText as an extendable and standardized markup language for technical writing. There are several large projects using it extensively but it is not as well known as Markdown.

Please review this PR while comparing to #261 and consider the following points

• setup/usage of the toolchain
• the markup language to express the command line documentation
• the output (both HTML and roff/man page)
• the preview on GH

Closes #227
Closes #261

[awvwgk]

I have looked for alternatives to write man pages and CLI documentation, but asciidoc seems to be the best solution I could fine so far, therefore I will just open this PR for discussion.

[milancurcic]

Have you tried converting Markdown to man page format using Pandoc? There's an example here.

I ask because 1) Markdown is simpler than Asciidoc and we're already writing Markdown for READMEs, and 2) pandoc is a more mature tool than asciidoctor (I think).

[awvwgk]

Thanks for the suggestion, I will give it a try and open another PR with markdown files if it works out nicely. Than we can compare and make a choice between the two.

[awvwgk]

Closing this for now. I might pickup the project again at some point. Feel free to use 2024a64 in case anyone wants to continue on this project.