doc: manual pages for Go tools

[gopherbot]

by hugo.vincent:

Go compilers/toolchain have no man pages.

Which revision are you sync'ed to?  (hg log -l 1)
changeset:   3975:b51fd2d6c160

[rsc]

Comment 1:

It's true that there are no man pages, but there is documentation.  See 
http://golang.org/cmd/ or run "godoc 6g" and "godoc gc" (for example) after installing 
Go.
We certainly need proper man pages eventually, but since this is still quite 
experimental, the godoc output should suffice.

Status changed to LongTerm.

[rsc]

Comment 2:

Labels changed: added documentation.

[rsc]

Comment 3:

Labels changed: added priority-later.

[rsc]

Comment 4:

Labels changed: added priority-go1.

[robpike]

Comment 5:

Owner changed to builder@golang.org.

[gopherbot]

Comment 7 by rcostu:

Is anyone working on this?
I have a little patch to automatically generate man pages with the documentation from
the commands, but is not yet finished.
Would this be likely to be part of godoc or execute a program during all.bash
installation so as man pages get installed on the right place?

[bradfitz]

Comment 8:

Auto-generating man pages from the existing documentation seems like the right direction
and a nice patch would almost certainly be welcome.
That said, this is ultimately a distro packaging problem (e.g. Debian/Ubuntu requiring
man pages), moreso than a Go problem (we have documentation already, but not in the
desired format(s)).
So this won't hold up the Go 1 release, but if you have something working, by all means
send it in.  Follow the process at http://golang.org/doc/contribute.html

[gopherbot]

Comment 9 by rcostu:

Thanks, will go on working on it to have the best possible solution starting with what
I've already done.
Hope to have it by the weekend. You could mark this issue as started if you want.

[bradfitz]

Comment 10:

Status changed to Started.

[rsc]

Comment 11:

I don't believe that generating man pages from godoc will make very
good man pages, but I'm interested to see what you come up with.

[gopherbot]

Comment 12 by rcostu:

Almost done, though still to debug some little things that seem not to be writing
correctly in the man file, but looks like the man pages autogenerated should be good
enough and will be able to rebuild every time a doc.go file is changed.
I have a question while I patch it and before submitting. Would it be likely to have
this as a package if anyone would want to generate a manpage? The design I've come into
would let that having a lot of flexibility if the guides on how to comment go commands.
I've also run into a couple of typos in the docs, should I report them or do I fix them
and submit a CL too?

[ianlancetaylor]

Comment 13:

If you signed the CLA, then sending a CL for doc typos would be helpful.  Thanks.

[gopherbot]

Comment 14 by rcostu:

Done. The CL for this issue is at http://golang.org/cl/5700081/
It may not be optimized but seems to work well. I generated a "goman" command to
generate and install the man pages, but don't now what to modify in order to install
them during ./all.bash execution.
By default it installs on /usr/local/share/man/man1, though can be changed with -path
parameter.

[jimmyfrasche]

Comment 15:

I made this program for generating man pages from go a long time ago.
https://code.google.com/p/mango-doc/ I haven't updated it in a bit but recently enough
that it should work with the latest weekly. Hope it's useful.

[rsc]

Comment 16:

Too late; will have to wait until after Go 1.

Labels changed: added priority-later, removed priority-go1.