No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Latest commit 4e443f0 Oct 31, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
testdata
.gitignore
LICENSE.blackfriday.txt
LICENSE.dwarf.go.txt
LICENSE.mdcat.txt
LICENSE.txt
LICENSE.which.txt
README.md Add link to Go Time episode #51 Jul 25, 2017
_config.yml
dwarf.go
dwarf_test.go
go.mod Fix issue #6 Oct 31, 2018
go.sum
goman.gif
goman.go
goman.png
goman_test.go

README.md

goman - the missing man page for Go binaries

goman logo

Almost all Go binaries come without any man page, even when properly installed through means like Homebrew.

goman substitutes the missing man page by the README file from the Go binary's sources.

goman first grabs the source path from the binary. Then it tries to locate the README file locally via the GOPATH. If this fails, it tries to fetch the README file from the binary's public repository.

For that last option, goman makes a couple of assumptions about the location, but at least with github and gitlab, those assumptions should be valid.


Featured on episode #51 of the Go Time podcast! (In the "Free Software Friday" section, at 1:02:35)


Demo

goman demo

Usage

goman <go binary file>

goman <go binary file> | less -R

(-R tells less to render ANSI color codes.)

Installation

go get -u github.com/christophberger/goman

Shell Integration

goman can blend in with the standard man command. Bash example (to be placed in ~/.bashrc):

man() { 
    if ! /usr/bin/man $1; then 
        goman $1 | less -R; 
    fi; 
}

On macOS, ensure to source ~/.bashrc at the end of ~/.bash_profile, as the Terminal app starts all shells as login shells that do not read .bashrc. (Background information on this is available here or here or via search engines.)
(Adding this script directly to ~/.bash_profile is perhaps not a good idea as some interactive shells may start as non-login shells and therefore do not source ~/.bash_profile.)

Credits and Licenses

All code written by myself is governed by a 3-clause BSD license, see LICENSE.txt.

The which package is part of the which command that is licensed under the MIT license; see LICENSE.which.txt.

The code that extracts the source code path from a go binary is a part of the gorebuild tool that is published under the MIT license; See LICENSE.dwarf.go.txt.

The Markdown renderer is a fork of blackfriday with extra code for rendering Markdown to plain text with ANSI color codes. See LICENSE.blackfriday.txt and the copyright notice in ec1oud/blackfriday/ansi.go.

Limitations

In its current state, goman is little more than a proof of concept. Bugs certainly do exist, as well as functional shortcomings due to oversimplified design, such as:

  • goman assumes that the README file contains either Markdown text or plain text. I know of at least one README.md that contains HTML. goman does not treat such cases in any special way.

  • If a binary originates from a command subdirectory of a project, chances are that this subdirectory contains no extra README file. goman then tries to find the README file in the parent directories.

  • Some binaries contain an absolute path to their source code, and goman assumes that the GOPATH used at compile time is the part from the root to the first directory named /src/. If the GOPATH itself contains a /src/ directory (e.g., "export GOPATH=/home/user/src/go"), goman fails extracting the relative source code path.

  • goman's output may wrap character-wise instead of word-wise.

  • Path redirection to canonical paths (like, e.g. from "https://npf.io/gorram" to https://github.com/natefinch/gorram) are not handled right now.

See also

mdcat - a cat tool for Markdown

mandown - write real man pages in Markdown

mango - generate man pages from your source code

gorebuild - rebuild Go binaries from source

binstale - check if your go binaries are outdated

bin and gobin - update all your Go binaries

Changelog

v0.2.1 (2017-07-04)

Fix stripping prefix from absolute path on Windows (PR #5)

v0.2.0 (2017-07-03)

Add support for the PE file format (Windows). (Implements issue #3)

v0.1.3 (2017-06-28)

Change search strategy for README file to cover all possible cases. (Fixes issue #2)

v0.1.2 (2017-06-27)

Fix slice panic if URL path is shorter than "github.com" (issue #1)