mirror of
https://github.com/cheat/cheat.git
synced 2024-12-21 20:25:06 +01:00
docs(man): implement manpage
- Implement `make man` to generate a manpage - Change verb tense in `make` help text
This commit is contained in:
Chris Lane
parent
521f83377c
commit
749d5c1182
44
Makefile
44
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) | \
|
||||
|
||||
@ -2,18 +2,18 @@ Usage:
|
||||
cheat [options] [<cheatsheet>]
|
||||
|
||||
Options:
|
||||
--init Write a default config file to stdout
|
||||
-c --colorize Colorize output
|
||||
-d --directories List cheatsheet directories
|
||||
-e --edit=<sheet> Edit <sheet>
|
||||
-l --list List cheatsheets
|
||||
-p --path=<name> Return only sheets found on path <name>
|
||||
-r --regex Treat search <phrase> as a regex
|
||||
-s --search=<phrase> Search cheatsheets for <phrase>
|
||||
-t --tag=<tag> Return only sheets matching <tag>
|
||||
-T --tags List all tags in use
|
||||
-v --version Print the version number
|
||||
--rm=<sheet> Remove (delete) <sheet>
|
||||
--init Write a default config file to stdout
|
||||
-c --colorize Colorize output
|
||||
-d --directories List cheatsheet directories
|
||||
-e --edit=<cheatsheet> Edit <cheatsheet>
|
||||
-l --list List cheatsheets
|
||||
-p --path=<name> Return only sheets found on path <name>
|
||||
-r --regex Treat search <phrase> as a regex
|
||||
-s --search=<phrase> Search cheatsheets for <phrase>
|
||||
-t --tag=<tag> Return only sheets matching <tag>
|
||||
-T --tags List all tags in use
|
||||
-v --version Print the version number
|
||||
--rm=<cheatsheet> Remove (delete) <cheatsheet>
|
||||
|
||||
Examples:
|
||||
|
||||
|
||||
@ -11,18 +11,18 @@ func usage() string {
|
||||
cheat [options] [<cheatsheet>]
|
||||
|
||||
Options:
|
||||
--init Write a default config file to stdout
|
||||
-c --colorize Colorize output
|
||||
-d --directories List cheatsheet directories
|
||||
-e --edit=<sheet> Edit <sheet>
|
||||
-l --list List cheatsheets
|
||||
-p --path=<name> Return only sheets found on path <name>
|
||||
-r --regex Treat search <phrase> as a regex
|
||||
-s --search=<phrase> Search cheatsheets for <phrase>
|
||||
-t --tag=<tag> Return only sheets matching <tag>
|
||||
-T --tags List all tags in use
|
||||
-v --version Print the version number
|
||||
--rm=<sheet> Remove (delete) <sheet>
|
||||
--init Write a default config file to stdout
|
||||
-c --colorize Colorize output
|
||||
-d --directories List cheatsheet directories
|
||||
-e --edit=<cheatsheet> Edit <cheatsheet>
|
||||
-l --list List cheatsheets
|
||||
-p --path=<name> Return only sheets found on path <name>
|
||||
-r --regex Treat search <phrase> as a regex
|
||||
-s --search=<phrase> Search cheatsheets for <phrase>
|
||||
-t --tag=<tag> Return only sheets matching <tag>
|
||||
-T --tags List all tags in use
|
||||
-v --version Print the version number
|
||||
--rm=<cheatsheet> Remove (delete) <cheatsheet>
|
||||
|
||||
Examples:
|
||||
|
||||
|
||||
206
doc/cheat.1
Normal file
206
doc/cheat.1
Normal file
@ -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
|
||||
<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[]
|
||||
178
doc/cheat.1.md
Normal file
178
doc/cheat.1.md
Normal file
@ -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:
|
||||
|
||||
- <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)**
|
||||
|
||||
Loading…
Reference in New Issue
Block a user