Golang applications and man files

[Fredrik Wallgren]

Hi!

How are man files typically handled for go applications? I can't seem to find any recommendations anywhere. 

It doesn't seem to be that common to provide a man file for a go app either, is this true?

I've written a small tool https://github.com/walle/wiki where I try to use the common 

layout (that I think is common from code I've seen) with the "library" code in the root and a cmd/ structure for

the application code. Where does the man file fit into this?

For now I have the man file in a directory _doc/ and have added a Makefile and installation instructions in 

the README https://github.com/walle/wiki#installation

Is there a more standard way of solving this?

Should I just skip the man file and elaborate the help output from the application more?

[Staven]

On Sat, Oct 03, 2015 at 07:24:10AM -0700, Fredrik Wallgren wrote:
> Hi!
>
> How are man files typically handled for go applications? I can't seem to
> find any recommendations anywhere.

That's probably because most people don't bother writing man pages and
just rely on godoc for documentation.
Even if you do include man documentation with your project,
obviously it won't be installed by go get.
It's pretty unfortunate.

[Giulio Iotti]

On Saturday, October 3, 2015 at 8:48:54 PM UTC+3, Staven wrote:

That's probably because most people don't bother writing man pages and
just rely on godoc for documentation.
Even if you do include man documentation with your project,
obviously it won't be installed by go get.
It's pretty unfortunate.

Especially because godoc is for programmers, not users (assuming we talk about a CLI command.) 

I tend to write overly long -help output, with the flags at the bottom. After running "command -help" you wil definitely see the flags. For more information, scroll up or "command -help | less".

The advantage is that everything is contained in the executable and no installation (of the manpage) is needed. The disadvantage is that manpages can be formatted better and in different formats (text, PS, html).

-- 

Giulio Iotti

[Fredrik Wallgren]

Yes, that is my thought too (That godoc is for developers, and library documentation) and perhaps the 

best way to go forward is to write everything in the help output instead. Even though it feels good (and polished)

to supply a man file with an application.

On the other hand, using a make file to install (instead of go get) is how every other C application does it.

Too bad that there isn't a convention like, if you put a man file in the cmd structure it gets installed with go get.

Example: cmd/app/main.go and cmd/app/app.1 produces a bin and installs the man page.

But I don't know if there is any support for an idea like this.

[Staven]

On Mon, Oct 05, 2015 at 03:28:33AM -0700, Fredrik Wallgren wrote:
Too bad that there isn't a convention like, if you put a man file in the
> cmd structure it gets installed with go get.
> Example: cmd/app/main.go and cmd/app/app.1 produces a bin and installs the
> man page.

Go is intended to be cross-platform. Installing man files doesn't make sense on, say, Windows.

Note that go get *will* download man files along with everything else if you include them in your source tree.
It's a valid strategy to bundle additional installation scripts in a go-gettable package,
so that users can go get your command and then, if they want, run make to install the documentation.

You could even abandon go get entirely and use a different build system,
if you think that's appropriate.

As for users reading godoc documentation...
If your users are the sort of people who read man pages, they shouldn't have any problems using godoc.

It's pretty unfortunate that I have to know what language a program is written in to look up its manual, though.
Maybe it would be worth it to add troff output to godoc...

[Fredrik Wallgren]

Yes, it doesn't really make sense on Windows. I miss that point sometimes, since I don't use Windows.

That is the strategy I'm currently using. Download everything with go get, and use the make target if you want.

I would say that being go getable is a big plus for any code written in go, not something you should 

throw out the window without thinking on it both once and twice.

As I said before, I see the godoc documentation as library documentation that a user that want to use

your library reads. How would you go about documenting an cli application in godoc?

[Matt Harden]

maybe `go generate -run manpages`?

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Staven]

On Mon, Oct 05, 2015 at 04:48:16AM -0700, Fredrik Wallgren wrote:
> Yes, it doesn't really make sense on Windows. I miss that point sometimes,
> since I don't use Windows.

Heh.

> As I said before, I see the godoc documentation as library documentation
> that a user that want to use
> your library reads. How would you go about documenting an cli application
> in godoc?

The usual way, I guess.
https://godoc.org/golang.org/x/tools/cmd