Man page renderer

[casey]

trafficstars

It would be absolutely lovely if there was a man page renderer for mdbook. It would be huge for me to be able to read the rust documentation in a terminal window.

Also, it would be awesome if rust binary crate authors could write command documentation in markdown and be able to turn it it into well formatted man pages.

Here's an example of a tool called ronn that does this: http://rtomayko.github.io/ronn

It's written in ruby, but it has some good ideas for how to transform markdown into man pages.

[casey]

Also wanted to reference #149.

It might take some thought and careful design to make sure that the rendering interface is sufficiently general in order to support the constraints of the format: limited formatting options, no images, limited colors, and so on.

[matthiasbeyer]

I would love this as well.

[Michael-F-Bryan]

Hmm, this is an interesting idea, although mdbook's primarily goal is to be a tool for generating documentation in book form. The Book is over 500 pages long, so I'm not sure a man page renderer makes sense.

That said, alternate backends have been merged into master (#507) so it's actually really easy to create your own backend and plug it into mdbook! You can use the mdbook-epub backend as an example of how this is done. There's also a page explaining it in the user guide.

[brianbruggeman]

I arrived at this open ticket because I had been pondering the use-case of adding a man page from all of the markdown I'm building to a clap-based cli. The markdown has a bunch of great detail, examples, use-cases, etc. which would be fantastic in a man page. That way, users of the cli do not actually need to go back to any particular website (or actually pull the repo and build locally) to figure out how to use the cli. It can all be "built-in" similar to cargo help doc.