Merge pull request #546 from chrisallenlane/issue-272

docs(man): implement manpage

Makefile

@@ -11,7 +11,9 @@ GO     := go
 GREP   := grep
 GZIP   := gzip --best
 LINT   := revive
+MAN    := man
 MKDIR  := mkdir -p
+PANDOC := pandoc
 RM     := rm
 SCC    := scc
 SED    := sed
@@ -32,16 +34,16 @@ releases :=                        \
 	$(dist_dir)/cheat-linux-arm7   \
 	$(dist_dir)/cheat-windows-amd64.exe
 
-## build: builds an executable for your architecture
+## build: build an executable for your architecture
 .PHONY: build
-build: $(dist_dir) clean vendor generate
+build: $(dist_dir) clean vendor generate man
 	$(GO) build $(BUILD_FLAGS) -o $(dist_dir)/cheat $(cmd_dir)
 
-## build-release: builds release executables
+## build-release: build release executables
 .PHONY: build-release
 build-release: $(releases)
 
-## ci: builds a "release" executable for the current architecture (used in ci)
+## ci: build a "release" executable for the current architecture (used in ci)
 .PHONY: ci
 ci: | setup prepare build
 
@@ -83,75 +85,81 @@ $(dist_dir):
 generate:
 	$(GO) generate $(cmd_dir)
 
-## install: builds and installs cheat on your PATH
+## install: build and install cheat on your PATH
 .PHONY: install
 install: build
 	$(GO) install $(BUILD_FLAGS) $(GOBIN) $(cmd_dir) 
 
-## clean: removes compiled executables
+## clean: remove compiled executables
 .PHONY: clean
 clean: $(dist_dir)
 	$(RM) -f $(dist_dir)/*
 
-## distclean: removes the tags file
+## distclean: remove the tags file
 .PHONY: distclean
 distclean:
 	$(RM) -f tags
 
-## setup: installs revive (linter) and scc (sloc tool)
+## setup: install revive (linter) and scc (sloc tool)
 .PHONY: setup
 setup:
 	GO111MODULE=off $(GO) get -u github.com/boyter/scc github.com/mgechev/revive
 
-## sloc: counts "semantic lines of code"
+## sloc: count "semantic lines of code"
 .PHONY: sloc
 sloc:
 	$(SCC) --exclude-dir=vendor
 
-## tags: builds a tags file
+## tags: build a tags file
 .PHONY: tags
 tags:
 	$(CTAGS) -R --exclude=vendor --languages=go
 
-## vendor: downloads, tidies, and verifies dependencies
+## man: build a man page
+# NB: pandoc may not be installed, so we're ignoring this error on failure
+.PHONY: man
+man:
+	-$(PANDOC) -s -t man doc/cheat.1.md -o doc/cheat.1
+
+## vendor: download, tidy, and verify dependencies
 .PHONY: vendor
 vendor:
 	$(GO) mod vendor && $(GO) mod tidy && $(GO) mod verify
 
-## fmt: runs go fmt
+## fmt: run go fmt
 .PHONY: fmt
 fmt:
 	$(GO) fmt ./...
 
-## lint: lints go source files
+## lint: lint go source files
 .PHONY: lint
 lint: vendor
 	$(LINT) -exclude vendor/... ./...
 
-## vet: vets go source files
+## vet: vet go source files
 .PHONY: vet
 vet:
 	$(GO) vet ./...
 
-## test: runs unit-tests
+## test: run unit-tests
 .PHONY: test
 test: 
 	$(GO) test ./...
 
-## coverage: generates a test coverage report
+## coverage: generate a test coverage report
 .PHONY: coverage
 coverage:
 	$(GO) test ./... -coverprofile=$(TMPDIR)/cheat-coverage.out && \
 	$(GO) tool cover -html=$(TMPDIR)/cheat-coverage.out
 
-## check: formats, lints, vets, vendors, and run unit-tests
+## check: format, lint, vet, vendor, and run unit-tests
 .PHONY: check
 check: | vendor fmt lint vet test
 
 .PHONY: prepare
 prepare: | $(dist_dir) clean generate vendor fmt lint vet test
 
-## help: displays this help text
+## help: display this help text
 .PHONY: help
 help:
 	@$(CAT) $(makefile) | \

cmd/cheat/docopt.txt

@@ -2,18 +2,18 @@ Usage:
   cheat [options] [<cheatsheet>]
 
 Options:
-  --init                Write a default config file to stdout
+  --init                  Write a default config file to stdout
-  -c --colorize         Colorize output
+  -c --colorize           Colorize output
-  -d --directories      List cheatsheet directories
+  -d --directories        List cheatsheet directories
-  -e --edit=<sheet>     Edit <sheet>
+  -e --edit=<cheatsheet>  Edit <cheatsheet>
-  -l --list             List cheatsheets
+  -l --list               List cheatsheets
-  -p --path=<name>      Return only sheets found on path <name>
+  -p --path=<name>        Return only sheets found on path <name>
-  -r --regex            Treat search <phrase> as a regex
+  -r --regex              Treat search <phrase> as a regex
-  -s --search=<phrase>  Search cheatsheets for <phrase>
+  -s --search=<phrase>    Search cheatsheets for <phrase>
-  -t --tag=<tag>        Return only sheets matching <tag>
+  -t --tag=<tag>          Return only sheets matching <tag>
-  -T --tags             List all tags in use
+  -T --tags               List all tags in use
-  -v --version          Print the version number
+  -v --version            Print the version number
-  --rm=<sheet>          Remove (delete) <sheet>
+  --rm=<cheatsheet>       Remove (delete) <cheatsheet>
 
 Examples:
 

cmd/cheat/main.go

@@ -17,7 +17,7 @@ import (
 	"github.com/cheat/cheat/internal/installer"
 )
 
-const version = "3.7.1"
+const version = "3.8.0"
 
 func main() {
 

cmd/cheat/str_usage.go

@@ -11,18 +11,18 @@ func usage() string {
   cheat [options] [<cheatsheet>]
 
 Options:
-  --init                Write a default config file to stdout
+  --init                  Write a default config file to stdout
-  -c --colorize         Colorize output
+  -c --colorize           Colorize output
-  -d --directories      List cheatsheet directories
+  -d --directories        List cheatsheet directories
-  -e --edit=<sheet>     Edit <sheet>
+  -e --edit=<cheatsheet>  Edit <cheatsheet>
-  -l --list             List cheatsheets
+  -l --list               List cheatsheets
-  -p --path=<name>      Return only sheets found on path <name>
+  -p --path=<name>        Return only sheets found on path <name>
-  -r --regex            Treat search <phrase> as a regex
+  -r --regex              Treat search <phrase> as a regex
-  -s --search=<phrase>  Search cheatsheets for <phrase>
+  -s --search=<phrase>    Search cheatsheets for <phrase>
-  -t --tag=<tag>        Return only sheets matching <tag>
+  -t --tag=<tag>          Return only sheets matching <tag>
-  -T --tags             List all tags in use
+  -T --tags               List all tags in use
-  -v --version          Print the version number
+  -v --version            Print the version number
-  --rm=<sheet>          Remove (delete) <sheet>
+  --rm=<cheatsheet>       Remove (delete) <cheatsheet>
 
 Examples:
 

doc/cheat.1

@@ -0,0 +1,206 @@
+.\" Automatically generated by Pandoc 1.17.2
+.\"
+.TH "CHEAT" "1" "" "" "General Commands Manual"
+.hy
+.SH NAME
+.PP
+\f[B]cheat\f[] \[em] create and view command\-line cheatsheets
+.SH SYNOPSIS
+.PP
+\f[B]cheat\f[] [options] [\f[I]CHEATSHEET\f[]]
+.SH DESCRIPTION
+.PP
+\f[B]cheat\f[] allows you to create and view interactive cheatsheets on
+the command\-line.
+It was designed to help remind *nix system administrators of options for
+commands that they use frequently, but not frequently enough to
+remember.
+.SH OPTIONS
+.TP
+.B \-\-init
+Print a config file to stdout.
+.RS
+.RE
+.TP
+.B \-c, \-\-colorize
+Colorize output.
+.RS
+.RE
+.TP
+.B \-d, \-\-directories
+List cheatsheet directories.
+.RS
+.RE
+.TP
+.B \-e, \-\-edit=\f[I]CHEATSHEET\f[]
+Open \f[I]CHEATSHEET\f[] for editing.
+.RS
+.RE
+.TP
+.B \-l, \-\-list
+List available cheatsheets.
+.RS
+.RE
+.TP
+.B \-p, \-\-path=\f[I]PATH\f[]
+Filter only to sheets found on path \f[I]PATH\f[].
+.RS
+.RE
+.TP
+.B \-r, \-\-regex
+Treat search \f[I]PHRASE\f[] as a regular expression.
+.RS
+.RE
+.TP
+.B \-s, \-\-search=\f[I]PHRASE\f[]
+Search cheatsheets for \f[I]PHRASE\f[].
+.RS
+.RE
+.TP
+.B \-t, \-\-tag=\f[I]TAG\f[]
+Filter only to sheets tagged with \f[I]TAG\f[].
+.RS
+.RE
+.TP
+.B \-T, \-\-tags
+List all tags in use.
+.RS
+.RE
+.TP
+.B \-v, \-\-version
+Print the version number.
+.RS
+.RE
+.TP
+.B \-\-rm=\f[I]CHEATSHEET\f[]
+Remove (deletes) \f[I]CHEATSHEET\f[].
+.RS
+.RE
+.SH EXAMPLES
+.TP
+.B To view the foo cheatsheet:
+cheat \f[I]foo\f[]
+.RS
+.RE
+.TP
+.B To edit (or create) the foo cheatsheet:
+cheat \-e \f[I]foo\f[]
+.RS
+.RE
+.TP
+.B To edit (or create) the foo/bar cheatsheet on the \[aq]work\[aq] cheatpath:
+cheat \-p \f[I]work\f[] \-e \f[I]foo/bar\f[]
+.RS
+.RE
+.TP
+.B To view all cheatsheet directories:
+cheat \-d
+.RS
+.RE
+.TP
+.B To list all available cheatsheets:
+cheat \-l
+.RS
+.RE
+.TP
+.B To list all cheatsheets whose titles match \[aq]apt\[aq]:
+cheat \-l \f[I]apt\f[]
+.RS
+.RE
+.TP
+.B To list all tags in use:
+cheat \-T
+.RS
+.RE
+.TP
+.B To list available cheatsheets that are tagged as \[aq]personal\[aq]:
+cheat \-l \-t \f[I]personal\f[]
+.RS
+.RE
+.TP
+.B To search for \[aq]ssh\[aq] among all cheatsheets, and colorize matches:
+cheat \-c \-s \f[I]ssh\f[]
+.RS
+.RE
+.TP
+.B To search (by regex) for cheatsheets that contain an IP address:
+cheat \-c \-r \-s \f[I]\[aq](?:[0\-9]{1,3}.){3}[0\-9]{1,3}\[aq]\f[]
+.RS
+.RE
+.TP
+.B To remove (delete) the foo/bar cheatsheet:
+cheat \-\-rm \f[I]foo/bar\f[]
+.RS
+.RE
+.SH FILES
+.SS Configuration
+.PP
+\f[B]cheat\f[] is configured via a YAML file that is conventionally
+named \f[I]conf.yaml\f[].
+\f[B]cheat\f[] will search for \f[I]conf.yaml\f[] in varying locations,
+depending upon your platform:
+.SS Linux, OSX, and other Unixes
+.IP "1." 3
+\f[B]CHEAT_CONFIG_PATH\f[]
+.IP "2." 3
+\f[B]XDG_CONFIG_HOME\f[]/cheat/conf.yaml
+.IP "3." 3
+\f[B]$HOME\f[]/.config/cheat/conf.yml
+.IP "4." 3
+\f[B]$HOME\f[]/.cheat/conf.yml
+.SS Windows
+.IP "1." 3
+\f[B]CHEAT_CONFIG_PATH\f[]
+.IP "2." 3
+\f[B]APPDATA\f[]/cheat/conf.yml
+.IP "3." 3
+\f[B]PROGRAMDATA\f[]/cheat/conf.yml
+.PP
+\f[B]cheat\f[] will search in the order specified above.
+The first \f[I]conf.yaml\f[] encountered will be respected.
+.PP
+If \f[B]cheat\f[] cannot locate a config file, it will ask if you\[aq]d
+like to generate one automatically.
+Alternatively, you may also generate a config file manually by running
+\f[B]cheat \-\-init\f[] and saving its output to the appropriate
+location for your platform.
+.SS Cheatpaths
+.PP
+\f[B]cheat\f[] reads its cheatsheets from "cheatpaths", which are the
+directories in which cheatsheets are stored.
+Cheatpaths may be configured in \f[I]conf.yaml\f[], and viewed via
+\f[B]cheat \-d\f[].
+.PP
+For detailed instructions on how to configure cheatpaths, please refer
+to the comments in conf.yml.
+.SS Autocompletion
+.PP
+Autocompletion scripts for \f[B]bash\f[]/\f[B]zsh\f[] and \f[B]fish\f[]
+are available for download:
+.IP \[bu] 2
+<https://github.com/cheat/cheat/blob/master/scripts/cheat.bash>
+.IP \[bu] 2
+<https://github.com/cheat/cheat/blob/master/scripts/cheat.fish>
+.PP
+The \f[B]bash\f[]/\f[B]zsh\f[] scripts provide optional integration with
+\f[B]fzf\f[], if the latter is available on your \f[B]PATH\f[].
+.PP
+The installation process will vary per system and shell configuration,
+and thus will not be discussed here.
+.SH ENVIRONMENT
+.TP
+.B \f[B]CHEAT_CONFIG_PATH\f[]
+The path at which the config file is available.
+If \f[B]CHEAT_CONFIG_PATH\f[] is set, all other config paths will be
+ignored.
+.RS
+.RE
+.SH BUGS
+.PP
+See GitHub issues: <https://github.com/cheat/cheat/issues>
+.SH AUTHOR
+.PP
+Christopher Allen Lane <chris@chris-allen-lane.com>
+.SH SEE ALSO
+.PP
+\f[B]fzf(1)\f[]

doc/cheat.1.md

@@ -0,0 +1,178 @@
+% CHEAT(1) | General Commands Manual
+
+NAME
+====
+
+**cheat** — create and view command-line cheatsheets
+
+SYNOPSIS
+========
+
+| **cheat** \[options] \[_CHEATSHEET_]
+
+DESCRIPTION
+===========
+**cheat** allows you to create and view interactive cheatsheets on the
+command-line. It was designed to help remind \*nix system administrators of
+options for commands that they use frequently, but not frequently enough to
+remember.
+
+OPTIONS
+=======
+
+--init
+: Print a config file to stdout.
+
+-c, --colorize
+: Colorize output.
+
+-d, --directories
+: List cheatsheet directories.
+
+-e, --edit=_CHEATSHEET_
+: Open _CHEATSHEET_ for editing.
+
+-l, --list
+: List available cheatsheets.
+
+-p, --path=_PATH_
+: Filter only to sheets found on path _PATH_.
+
+-r, --regex
+: Treat search _PHRASE_ as a regular expression.
+
+-s, --search=_PHRASE_
+: Search cheatsheets for _PHRASE_.
+
+-t, --tag=_TAG_
+: Filter only to sheets tagged with _TAG_.
+
+-T, --tags
+: List all tags in use.
+
+-v, --version
+: Print the version number.
+
+--rm=_CHEATSHEET_
+: Remove (deletes) _CHEATSHEET_.
+
+
+EXAMPLES
+========
+
+To view the foo cheatsheet:
+: cheat _foo_
+
+To edit (or create) the foo cheatsheet:
+: cheat -e _foo_
+
+To edit (or create) the foo/bar cheatsheet on the 'work' cheatpath:
+: cheat -p _work_ -e _foo/bar_
+
+To view all cheatsheet directories:
+: cheat -d
+
+To list all available cheatsheets:
+: cheat -l
+
+To list all cheatsheets whose titles match 'apt':
+: cheat -l _apt_
+
+To list all tags in use:
+: cheat -T
+
+To list available cheatsheets that are tagged as 'personal':
+: cheat -l -t _personal_
+
+To search for 'ssh' among all cheatsheets, and colorize matches:
+: cheat -c -s _ssh_
+
+To search (by regex) for cheatsheets that contain an IP address:
+: cheat -c -r -s _'(?:[0-9]{1,3}\.){3}[0-9]{1,3}'_
+
+To remove (delete) the foo/bar cheatsheet:
+: cheat --rm _foo/bar_
+
+
+FILES
+=====
+
+Configuration
+-------------
+**cheat** is configured via a YAML file that is conventionally named
+_conf.yaml_.  **cheat** will search for _conf.yaml_ in varying locations,
+depending upon your platform:
+
+### Linux, OSX, and other Unixes ###
+
+1. **CHEAT_CONFIG_PATH**
+2. **XDG_CONFIG_HOME**/cheat/conf.yaml
+3. **$HOME**/.config/cheat/conf.yml
+4. **$HOME**/.cheat/conf.yml
+
+### Windows ###
+
+1. **CHEAT_CONFIG_PATH**
+2. **APPDATA**/cheat/conf.yml
+3. **PROGRAMDATA**/cheat/conf.yml
+
+**cheat** will search in the order specified above. The first _conf.yaml_
+encountered will be respected.
+
+If **cheat** cannot locate a config file, it will ask if you'd like to generate
+one automatically. Alternatively, you may also generate a config file manually
+by running **cheat --init** and saving its output to the appropriate location
+for your platform.
+
+
+Cheatpaths
+----------
+**cheat** reads its cheatsheets from "cheatpaths", which are the directories in
+which cheatsheets are stored. Cheatpaths may be configured in _conf.yaml_, and
+viewed via **cheat -d**.
+
+For detailed instructions on how to configure cheatpaths, please refer to the
+comments in conf.yml.
+
+
+Autocompletion
+--------------
+Autocompletion scripts for **bash**/**zsh** and **fish** are available for
+download:
+
+- <https://github.com/cheat/cheat/blob/master/scripts/cheat.bash>
+- <https://github.com/cheat/cheat/blob/master/scripts/cheat.fish>
+
+The **bash**/**zsh** scripts provide optional integration with **fzf**, if the
+latter is available on your **PATH**.
+
+The installation process will vary per system and shell configuration, and thus
+will not be discussed here.
+
+
+ENVIRONMENT
+===========
+
+**CHEAT_CONFIG_PATH**
+
+: The path at which the config file is available. If **CHEAT_CONFIG_PATH** is
+set, all other config paths will be ignored.
+
+
+BUGS
+====
+
+See GitHub issues: <https://github.com/cheat/cheat/issues>
+
+
+AUTHOR
+======
+
+Christopher Allen Lane <chris@chris-allen-lane.com>
+
+
+SEE ALSO
+========
+
+**fzf(1)**
+