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

Closed
gopherbot opened this issue Nov 12, 2009 · 32 comments
Closed

doc: manual pages for Go tools #101

gopherbot opened this issue Nov 12, 2009 · 32 comments

Comments

@gopherbot
Copy link

@gopherbot gopherbot 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
Copy link
Contributor

@rsc rsc 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
Copy link
Contributor

@rsc rsc commented Dec 2, 2009

Comment 2:

Labels changed: added documentation.

@rsc
Copy link
Contributor

@rsc rsc commented Dec 9, 2011

Comment 3:

Labels changed: added priority-later.

@rsc
Copy link
Contributor

@rsc rsc commented Dec 12, 2011

Comment 4:

Labels changed: added priority-go1.

@robpike
Copy link
Contributor

@robpike robpike commented Jan 13, 2012

Comment 5:

Owner changed to builder@golang.org.

@gopherbot
Copy link
Author

@gopherbot gopherbot 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
Copy link
Contributor

@bradfitz bradfitz 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
Copy link
Author

@gopherbot gopherbot 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
Copy link
Contributor

@bradfitz bradfitz commented Feb 22, 2012

Comment 10:

Status changed to Started.

@rsc
Copy link
Contributor

@rsc rsc 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
Copy link
Author

@gopherbot gopherbot 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
Copy link
Contributor

@ianlancetaylor ianlancetaylor commented Feb 26, 2012

Comment 13:

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

@gopherbot
Copy link
Author

@gopherbot gopherbot 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
Copy link
Member

@jimmyfrasche jimmyfrasche 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
Copy link
Contributor

@rsc rsc 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
Copy link
Contributor

@rsc rsc commented Jul 30, 2013

Comment 17:

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

@gopherbot
Copy link
Author

@gopherbot gopherbot 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
Copy link
Contributor

@rsc rsc commented Dec 4, 2013

Comment 19:

Labels changed: added repo-main.

@rsc
Copy link
Contributor

@rsc rsc commented Mar 3, 2014

Comment 20:

Adding Release=None to all Priority=Someday bugs.

Labels changed: added release-none.

@gopherbot
Copy link
Author

@gopherbot gopherbot commented Oct 2, 2015

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

@nathany
Copy link
Contributor

@nathany nathany 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
Copy link
Contributor

@jessfraz jessfraz commented Dec 13, 2016

Is anyone working on this?

@bradfitz
Copy link
Contributor

@bradfitz bradfitz commented Dec 13, 2016

Nope.

@tianon
Copy link
Contributor

@tianon tianon 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
Copy link
Contributor

@as as 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?

@anoxic
Copy link

@anoxic anoxic commented 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
Copy link

@nasirhm nasirhm commented Jul 18, 2020

Is anyone working on it ?

@rsc @ianlancetaylor

@mpstewart
Copy link

@mpstewart mpstewart commented Nov 8, 2020

Any progress on this? Or workarounds?

@anoxic
Copy link

@anoxic anoxic commented Nov 8, 2020

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

@gopherbot
Copy link
Author

@gopherbot gopherbot commented Dec 16, 2020

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

@rsc
Copy link
Contributor

@rsc rsc commented 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.

@rsc rsc closed this Jan 8, 2021
@velovix
Copy link

@velovix velovix commented Jan 8, 2021

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet