#7484 Create man pages for all tools

[gavinb]

This patch updates the existing manpage and creates new pages for all of the rust command line tools. Closes #7484.

[graydon]

These are great. I'm curious where you got the rustpkg docs from, though; the man page in this PR describes how rustpkg worked in 0.6 but it has been substantially changed for 0.7, so those docs aren't really accurate. The current markdown docs are mostly up-to-date: https://github.com/mozilla/rust/blob/master/doc/rustpkg.md

[gavinb]

I must have somehow used the older version; I will update the rustpkg page based on the Markdown and update the PR.

[gavinb]

@graydon Here's the proper rustpkg manpage. Hope it's all good to go now.

[kud1ing]

Very nice. I wonder though whether we could hold the tool documentation in one format, say markdown, and generate HTML and man pages e.g. using pandoc.

[gavinb]

@kud1ing This is certainly possible, though not without compromises. A manpage has particular formatting conventions, such as section headings, ordering, option layout and so on. So unless the original Markdown followed this general layout, the result would be a document viewable with man, without being an actual manpage.

I just tried using pandoc to do just this; produce a man document from Markdown. It seems to work ok (once I added a title for the .TH).

However, the original Markdown documents would need some major editing for the result to resemble a proper manpage. But then we should also ensure the format produces decent HTML (and possibly PDF) output as well. So it's hard to serve all purposes well.

I'm happy to do this if that's what people want. Perhaps the pages in this patch could serve in the interim? Should this become another issue?