Since crystal-lang/shards#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.
Since crystal-lang/shards#262 the manpages
shards.1andshard.yml.5are 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.
pandoccan'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.
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.