Rewrite manpages in Asciidoc

[straight-shoota]

This translates the manpages to Asciidoc as suggested in #253

It's a simple translation and tries to keep close to the original. Further enhancements are probably coming.

[bcardiff]

I guess there should be an update in the readme for the new development dependency. And I guess the crystal man page will be the next to fall.

I'm not eager in seeing a new dependency in the build process, but at least is only on the build rather than the actual development.

[jkthorne]

I agree with @bcardiff concern about adding the dependency. This seems like a big dependency to add for preference in man page file format.

[straight-shoota]

I've done a huge update on the documentation.

• Documentation is now written in asciidoc and resides in docs/. All documentation formats are generated from a single source.
• Man pages are automatically generated from asciidoc.
• SPEC.md has been merged with man/shard.yml.5 into docs/shard.yml.adoc.
• relevant parts have been synced with shards on crystal-book
• Added documentation for new commands not yet documented
• Added documentation for env vars

Integration with CI to build manpages automatically for shards releases is still missing. I'd like to ask for feedback first before fiddeling with that.

Next steps:

• doc files should also be made available as HTML on http://crystal-lang.org/reference

[straight-shoota]

Bump can we please merge this before documentation gets out of sync again?

[straight-shoota]

@bcardiff Could you take a look at this, please?

[bcardiff]

Is really needed to move the SPEC.md to asciidocs? Maybe is because I haven't used asciidocs in the past that I am not eager to see that change.

I would suggest also to commit the generated man files. Otherwise distribution-scripts and other package mantainers will need to deal with asciidocs+python dependency. I usually prefer to avoid committing generated files, but in this case I think it make sense.

Eventually the generated man files could go away, but to avoid blocking shards releases I would go that way.

[bcardiff]

is this information right or should it get from the SHARDS_VERSION set in the Makefile?

[straight-shoota]

Oh yeah, this can be automated. IIRC I didn't implement that right away because I wasn't sure it's a good idea because it could propagate incorrect information if the documentation is not accurate for the newest version. But that's probably hard to coordinate anyways, so it might be better to assume we keep the docs always up to date and it always displays the most recent version.

[straight-shoota]

Is really needed to move the SPEC.md to asciidocs?

SPEC.md is entirely merged into the manpage for shard.yml. They describe the same thing: The format of shard.yml. I don't think it makes sense to keep two separate documents with duplicate content.

I would suggest also to commit the generated man files. Otherwise distribution-scripts and other package mantainers will need to deal with asciidocs+python dependency. I usually prefer to avoid committing generated files, but in this case I think it make sense.

Eventually the generated man files could go away, but to avoid blocking shards releases I would go that way.

Sounds good 👍 I was also hesitant about this too. But yeah maybe it's better to commit them (at least for now).

[straight-shoota]

Building man pages in CI is not an issue. We could use that for validation to ensure the rendered pages are up to date. But I'd leave that for a follow-up. Priority is to get this merged to avoid falling out of sync again.

[bcardiff]

I guess we should add a shards release checklist procedure to the "Crystal Release Checklist" doc in order to avoid forgetting to update the manpage upon release.