You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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?
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
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.
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?
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.
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.
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?
Reacted by Mark Delk, Harold Dost, Axel Latvala and Ron Wolf
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.
Activity
rsc commentedon Nov 12, 2009
Comment 1:
Status changed to LongTerm.
rsc commentedon Dec 2, 2009
Comment 2:
Labels changed: added documentation.
rsc commentedon Dec 9, 2011
Comment 3:
Labels changed: added priority-later.
rsc commentedon Dec 12, 2011
Comment 4:
Labels changed: added priority-go1.
robpike commentedon Jan 13, 2012
Comment 5:
Owner changed to builder@golang.org.
gopherbot commentedon Feb 22, 2012
Comment 7 by rcostu:
bradfitz commentedon Feb 22, 2012
Comment 8:
gopherbot commentedon Feb 22, 2012
Comment 9 by rcostu:
bradfitz commentedon Feb 22, 2012
Comment 10:
Status changed to Started.
rsc commentedon Feb 22, 2012
Comment 11:
gopherbot commentedon Feb 26, 2012
Comment 12 by rcostu:
ianlancetaylor commentedon Feb 26, 2012
Comment 13:
gopherbot commentedon Feb 27, 2012
Comment 14 by rcostu:
jimmyfrasche commentedon Mar 8, 2012
Comment 15:
rsc commentedon Mar 27, 2012
Comment 16:
Labels changed: added priority-later, removed priority-go1.
16 remaining items
bradfitz commentedon Dec 13, 2016
Nope.
tianon commentedon Dec 13, 2016
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 commentedon Apr 1, 2018
Clearly the man format has slowed the process to a crawl. How about a proper format like a GNU Texinfo manual?
anoxic commentedon Feb 2, 2020
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 commentedon Jul 18, 2020
Is anyone working on it ?
@rsc @ianlancetaylor
mpstewart commentedon Nov 8, 2020
Any progress on this? Or workarounds?
anoxic commentedon Nov 8, 2020
I think it's safe to say the maintainers don't care about this one.
gopherbot commentedon Dec 16, 2020
Change https://golang.org/cl/278574 mentions this issue:
doc: add man page generatorrsc commentedon Jan 8, 2021
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 commentedon Jan 8, 2021
An eleven year saga has come to a close :) I believe this was the oldest open issue on this repository.