Import manual pages from shards

[straight-shoota]

Since https://github.com/crystal-lang/shards/pull/262 the manpages shards.1 and shard.yml.5 are generated from asciidoc source. As a benefit it allows to transform the content to other formats. We can import it into this repo to replace the The shards command page - which is effectively just an HTML version of the manpage. Mkdocs doesn't support asciidoc directly, but it can be convert to markdown via HTML or docbook. pandoc can't read asciidoc, so adoc->md is a two-step process.

The result of importing the markdown transformation isn't that great. It's okay and gets the job done. The important benefit is it avoids maintaing the same content twice.

But unfortunately it doesn't integrate nicely on terms of UX. It's essentially just a manpage and formatted like a man page. Some formatting can be automatically fixed, but others is hard to do.

• The asciidoc source includes language tags for syntax highlighting. But it seems they don't propagate to the markdown transformation.
• Highlights for code and bold text are also a bit wanky, but I suppose that's mostly due to strange manpage conventions. This can be improved in the asciidoc source.
• Currently there are sub-headers for every command. But they don't exist in the manpage-targeted asciidoc source. So in-document navigation is reduced.

I have some hope in Pandoc's filter system. It's quite powerful and allows custom modifications to the transformation process. It's still a bit of a task to find out how exactly to do things. But it looks like it could help improve many of the smaller problems.

[straight-shoota]

I forgot to include a link to the code: https://github.com/straight-shoota/crystal-book/tree/feature/import-manuals

[straight-shoota]

Rendered previews:

• https://straight-shoota.github.io/crystal-book/feature/import-manuals/shards/shards.html
• https://straight-shoota.github.io/crystal-book/feature/import-manuals/shards/shard.yml.html

[straight-shoota]

I proposed some changes to the man page format in https://github.com/crystal-lang/shards/pull/488 These changes help improve the content for decent HTML rendering.

The major issue left now is that definition list formats are lost in the translation process. The term and definition blocks are converted to inline text separated by a <br/>. That's not great, especially with nested definition lists (such as the arguments list of the install command). I think this would be important to have.

In the mean time I was also made aware of https://github.com/postmodern/kramdown-man by @postmodern which offers a similar transformation process from markdown to roff. This could be a better alternative than the current asciidoc setup because we wouldn't need to cross-transform from asciidoc to markdown for mkdocs. While trying kramdown-man I immediately discovered some strange behaviours and filed some bug reports. I'm not sure if it could improve on the content transformation problems with definition lists.

[beta-ziliani]

Somewhat relevant, @crimson-knight asked for a more prominent place to explain shards.override.yml

[ysbaddaden]

@straight-shoota I found downdoc to convert from asciidoc to markdown in one step. It may have sufficient support for most features?