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.

[rsc]

Comment 17:

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

[gopherbot]

Comment 18 by baryluk@google.com:

mango-doc is awesome. It would be cool to integrate it into standard distribution, and
generate manpages for all packages and tools.

[rsc]

Comment 19:

Labels changed: added repo-main.

[rsc]

Comment 20:

Adding Release=None to all Priority=Someday bugs.

Labels changed: added release-none.

[gopherbot]

CL https://golang.org/cl/15254 mentions this issue.

[nathany]

The mentioned CL was abandoned and discussed further on the mailing list. To update the status of this issue:

"Let's make our existing doc tools have a JSON output mode, outputting a data structure, and then you can implement your own standalone program that filters that JSON into whatever (troff, pdf, etc)." - https://groups.google.com/d/msg/golang-dev/Rouzs-OnujQ/GJ8Ytx2_BgAJ

[jessfraz]

Is anyone working on this?

[bradfitz]

Nope.

[tianon]

Debian includes https://anonscm.debian.org/cgit/pkg-golang/golang-defaults.git/tree/man?id=f7372ceb7313dce943617cb53bdef425dd955b58 (moved there from https://anonscm.debian.org/cgit/pkg-golang/golang.git/tree/debian/man?h=debian/2%251.6.1-2, to include a little bit more historical context for those files) -- might be a decent starting point or source of inspiration (even if only to create the templates the scraped doc data is placed into). 👍

(cc @stapelberg)

[as]

Clearly the man format has slowed the process to a crawl. How about a proper format like a GNU Texinfo manual?

[anoxic]

It seems odd that even though multiple people appear to have implemented workable solutions (to the degree you can get converting the go docs to man format), none of them have been actually been integrated. Am I missing something?

[nasirhm]

Is anyone working on it ?

@rsc @ianlancetaylor

[mpstewart]

Any progress on this? Or workarounds?

[anoxic]

I think it's safe to say the maintainers don't care about this one.

[gopherbot]

Change https://golang.org/cl/278574 mentions this issue: doc: add man page generator

[rsc]

It's 2021 and there are many other valid forms of documentation.
Not everything has to fit into the man page format, the affection I have for it notwithstanding.
It's safe to say we're not going to take the time to adopt and maintain a solution ourselves here.
Closing this issue.

[velovix]

An eleven year saga has come to a close :) I believe this was the oldest open issue on this repository.