Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: manual pages for Go tools #101

Open
gopherbot opened this issue Nov 12, 2009 · 25 comments

Comments

@gopherbot
Copy link

commented Nov 12, 2009

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

This comment has been minimized.

Copy link
Contributor

commented Nov 12, 2009

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

This comment has been minimized.

Copy link
Contributor

commented Dec 2, 2009

Comment 2:

Labels changed: added documentation.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Dec 9, 2011

Comment 3:

Labels changed: added priority-later.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Dec 12, 2011

Comment 4:

Labels changed: added priority-go1.

@robpike

This comment has been minimized.

Copy link
Contributor

commented Jan 13, 2012

Comment 5:

Owner changed to builder@golang.org.

@gopherbot

This comment has been minimized.

Copy link
Author

commented Feb 22, 2012

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

This comment has been minimized.

Copy link
Member

commented Feb 22, 2012

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

This comment has been minimized.

Copy link
Author

commented Feb 22, 2012

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

This comment has been minimized.

Copy link
Member

commented Feb 22, 2012

Comment 10:

Status changed to Started.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Feb 22, 2012

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

This comment has been minimized.

Copy link
Author

commented Feb 26, 2012

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

This comment has been minimized.

Copy link
Contributor

commented Feb 26, 2012

Comment 13:

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

This comment has been minimized.

Copy link
Author

commented Feb 27, 2012

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

This comment has been minimized.

Copy link
Member

commented Mar 8, 2012

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

This comment has been minimized.

Copy link
Contributor

commented Mar 27, 2012

Comment 16:

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

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

@rsc

This comment has been minimized.

Copy link
Contributor

commented Jul 30, 2013

Comment 17:

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

@gopherbot

This comment has been minimized.

Copy link
Author

commented Nov 14, 2013

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

This comment has been minimized.

Copy link
Contributor

commented Dec 4, 2013

Comment 19:

Labels changed: added repo-main.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Mar 3, 2014

Comment 20:

Adding Release=None to all Priority=Someday bugs.

Labels changed: added release-none.

@rsc rsc added this to the Unplanned milestone Apr 10, 2015

@gopherbot

This comment has been minimized.

Copy link
Author

commented Oct 2, 2015

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

@nathany

This comment has been minimized.

Copy link
Contributor

commented Apr 29, 2016

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

This comment has been minimized.

Copy link
Contributor

commented Dec 13, 2016

Is anyone working on this?

@bradfitz

This comment has been minimized.

Copy link
Member

commented Dec 13, 2016

Nope.

@tianon

This comment has been minimized.

Copy link
Contributor

commented 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

This comment has been minimized.

Copy link
Contributor

commented Apr 1, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
10 participants
You can’t perform that action at this time.