From 749d5c11829891303df4da79063b9371e2bd4ace Mon Sep 17 00:00:00 2001 From: Chris Lane Date: Tue, 24 Mar 2020 20:19:33 -0400 Subject: [PATCH 1/2] docs(man): implement manpage - Implement `make man` to generate a manpage - Change verb tense in `make` help text --- Makefile | 44 +++++---- cmd/cheat/docopt.txt | 24 ++--- cmd/cheat/str_usage.go | 24 ++--- doc/cheat.1 | 206 +++++++++++++++++++++++++++++++++++++++++ doc/cheat.1.md | 178 +++++++++++++++++++++++++++++++++++ 5 files changed, 434 insertions(+), 42 deletions(-) create mode 100644 doc/cheat.1 create mode 100644 doc/cheat.1.md diff --git a/Makefile b/Makefile index 802677b..fa652a6 100644 --- a/Makefile +++ b/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) | \ diff --git a/cmd/cheat/docopt.txt b/cmd/cheat/docopt.txt index 5877aab..c841549 100644 --- a/cmd/cheat/docopt.txt +++ b/cmd/cheat/docopt.txt @@ -2,18 +2,18 @@ Usage: cheat [options] [] Options: - --init Write a default config file to stdout - -c --colorize Colorize output - -d --directories List cheatsheet directories - -e --edit= Edit - -l --list List cheatsheets - -p --path= Return only sheets found on path - -r --regex Treat search as a regex - -s --search= Search cheatsheets for - -t --tag= Return only sheets matching - -T --tags List all tags in use - -v --version Print the version number - --rm= Remove (delete) + --init Write a default config file to stdout + -c --colorize Colorize output + -d --directories List cheatsheet directories + -e --edit= Edit + -l --list List cheatsheets + -p --path= Return only sheets found on path + -r --regex Treat search as a regex + -s --search= Search cheatsheets for + -t --tag= Return only sheets matching + -T --tags List all tags in use + -v --version Print the version number + --rm= Remove (delete) Examples: diff --git a/cmd/cheat/str_usage.go b/cmd/cheat/str_usage.go index 49d7678..86be7ea 100644 --- a/cmd/cheat/str_usage.go +++ b/cmd/cheat/str_usage.go @@ -11,18 +11,18 @@ func usage() string { cheat [options] [] Options: - --init Write a default config file to stdout - -c --colorize Colorize output - -d --directories List cheatsheet directories - -e --edit= Edit - -l --list List cheatsheets - -p --path= Return only sheets found on path - -r --regex Treat search as a regex - -s --search= Search cheatsheets for - -t --tag= Return only sheets matching - -T --tags List all tags in use - -v --version Print the version number - --rm= Remove (delete) + --init Write a default config file to stdout + -c --colorize Colorize output + -d --directories List cheatsheet directories + -e --edit= Edit + -l --list List cheatsheets + -p --path= Return only sheets found on path + -r --regex Treat search as a regex + -s --search= Search cheatsheets for + -t --tag= Return only sheets matching + -T --tags List all tags in use + -v --version Print the version number + --rm= Remove (delete) Examples: diff --git a/doc/cheat.1 b/doc/cheat.1 new file mode 100644 index 0000000..e4d0c61 --- /dev/null +++ b/doc/cheat.1 @@ -0,0 +1,206 @@ +.\" Automatically generated by Pandoc 1.17.2 +.\" +.TH "CHEAT" "1" "" "Version 3.7.0" "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 + +.IP \[bu] 2 + +.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: +.SH AUTHOR +.PP +Christopher Allen Lane +.SH SEE ALSO +.PP +\f[B]fzf(1)\f[] diff --git a/doc/cheat.1.md b/doc/cheat.1.md new file mode 100644 index 0000000..9df87a7 --- /dev/null +++ b/doc/cheat.1.md @@ -0,0 +1,178 @@ +% CHEAT(1) Version 3.7.0 | 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: + +- +- + +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: + + +AUTHOR +====== + +Christopher Allen Lane + + +SEE ALSO +======== + +**fzf(1)** + From 38b13655fec5091aeac72332c6e133844174becd Mon Sep 17 00:00:00 2001 From: Chris Lane Date: Tue, 24 Mar 2020 20:52:14 -0400 Subject: [PATCH 2/2] chore(version): bump version to 3.8.0 --- cmd/cheat/main.go | 2 +- doc/cheat.1 | 2 +- doc/cheat.1.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/cmd/cheat/main.go b/cmd/cheat/main.go index 77fc06f..e22b915 100755 --- a/cmd/cheat/main.go +++ b/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() { diff --git a/doc/cheat.1 b/doc/cheat.1 index e4d0c61..41bd437 100644 --- a/doc/cheat.1 +++ b/doc/cheat.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.17.2 .\" -.TH "CHEAT" "1" "" "Version 3.7.0" "General Commands Manual" +.TH "CHEAT" "1" "" "" "General Commands Manual" .hy .SH NAME .PP diff --git a/doc/cheat.1.md b/doc/cheat.1.md index 9df87a7..1fa69bc 100644 --- a/doc/cheat.1.md +++ b/doc/cheat.1.md @@ -1,4 +1,4 @@ -% CHEAT(1) Version 3.7.0 | General Commands Manual +% CHEAT(1) | General Commands Manual NAME ====