Rewrite manpages in asciidoc

[ysbaddaden]

It would be nice to rewrite the manpages in asciidoc and to build them using the asciidoctor gem. It's nicer to write in, and that would allow to have different output formats (man, html, md, ...). Git does that and I really like it.

[straight-shoota]

I've just manually transformed the man page to Markdown 😄 (crystal-lang/crystal-book#316). Having a single source format would definitely help to keep these instances in sync.

[ZaWertun]

Calling asciidoctor with empty SOURCE_DATE_EPOCH env variable gives this error:

SOURCE_DATE_EPOCH= asciidoctor -a shards_version=0.14.0 docs/shards.adoc -b manpage -o man/shards.1
asciidoctor: FAILED: /home/zawertun/tmp/shards/docs/shards.adoc: Failed to load AsciiDoc document - invalid value for Integer(): ""
Use --trace for backtrace

(I'm building shards from the tar.gz archive, not from the git repo)

[straight-shoota]

That makefile call is completely broken. Sorry, this was a really crappy copy and paste 😢

Fix is in #479.

[szabgab]

There are two man pages committed in the man/ that are removed when you run make clean. Should those be removed from the repository or are they still needed? If they are still needed then probably make clean should not remove them.

[straight-shoota]

For the time being, they're checked in as a convenience so you don't have to install asciidoctor to read the manpages.

So yeah, probably they shouldn't be cleaned. Feel free to make a PR. It's low priority, though.