From 094f65dc9966ffddc9798ed506de6c4e159d82af Mon Sep 17 00:00:00 2001 From: Teddy Wing Date: Sat, 3 Mar 2018 15:50:23 +0100 Subject: Add man page Provide a man page for in situ documentation. Use AsciiDoc to generate the man page. Yay, my first man page! Resources: - https://github.com/BurntSushi/ripgrep/blob/fe9be65/build.rs - https://github.com/BurntSushi/ripgrep/blob/f5411b9/doc/rg.1.txt.tpl - http://www.methods.co.nz/asciidoc/asciidoc.1.txt - https://github.com/git/git/blob/23f8239/Documentation/git-clean.txt - https://github.com/git/git/blob/8a8f121049fdd881981799755a041b3f81449805/Documentation/asciidoctor-extensions.rb - http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ - https://github.com/git/git/commit/5945717009cbd07fc303939452df6475ac342fe7 --- Makefile | 2 + doc/passextract.1 | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/passextract.1.txt | 68 ++++++++++++++++++++++++++++ 3 files changed, 191 insertions(+) create mode 100644 Makefile create mode 100644 doc/passextract.1 create mode 100644 doc/passextract.1.txt diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..6ea628a --- /dev/null +++ b/Makefile @@ -0,0 +1,2 @@ +doc/passextract.1: doc/passextract.1.txt + a2x --no-xmllint --format manpage $< diff --git a/doc/passextract.1 b/doc/passextract.1 new file mode 100644 index 0000000..cddc96f --- /dev/null +++ b/doc/passextract.1 @@ -0,0 +1,121 @@ +'\" t +.\" Title: passextract +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.78.1 +.\" Date: 03/03/2018 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "PASSEXTRACT" "1" "03/03/2018" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +passextract \- Copy login details from pass(1) +.SH "SYNOPSIS" +.sp +\fBpassextract\fR [\fIOPTIONS\fR] [\fIPASS_FILE\fR] +.SH "DESCRIPTION" +.sp +An extension to the pass(1) password manager\&. Passextract provides a UI similar to urlview(2) that enables these additional fields to be copied to the system clipboard\&. Three fields are recognised: emails, usernames, and passwords\&. They are defined as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +This text is ignored +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +e: email@example\&.com +u: username +p: secret\-password +.fi +.if n \{\ +.RE +.\} +.sp +In order to be recognised by Passextract, those fields must be prefixed by \(lqe: \(rq, \(lqu: \(rq, or \(lqp: \(rq as illustrated above\&. +.sp +The passextract(1) command will parse those fields from \fIPASS_FILE\fR\&. If \fIPASS_FILE\fR is not provided or if it\(cqs \fI\-\fR then the standard input is used\&. +.SH "OPTIONS" +.PP +\-i +.RS 4 +Make password strings invisible by replacing them with stars ("*")\&. +.RE +.SH "INTERACTIVE CONTROL" +.sp +In the interactive UI, the following commands are available: +.PP +q / C\-c +.RS 4 +Quit and clear the clipboard +.RE +.PP +j +.RS 4 +Move the selection down +.RE +.PP +k +.RS 4 +Move the selection up +.RE +.PP +g +.RS 4 +Move the selection to the top +.RE +.PP +G +.RS 4 +Move the selection to the bottom +.RE +.PP +ENTER +.RS 4 +Copy the currently selected line +.RE +.SH "EXAMPLES" +.sp +Passextract can be invoked on its own or with the piped output of pass show\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ pass show github\&.com | passextract +$ passextract github\&.com +.fi +.if n \{\ +.RE +.\} +.sp +The included Bash completion file provides the same tab completion options as pass show\&. +.SH "SHELL COMPLETION" +.sp +Shell completion is provided to complete pass(1) files\&. To enable Bash completion, source the included passextract\&.bash\-completion file\&. diff --git a/doc/passextract.1.txt b/doc/passextract.1.txt new file mode 100644 index 0000000..7b4596d --- /dev/null +++ b/doc/passextract.1.txt @@ -0,0 +1,68 @@ +passextract(1) +============== + +NAME +---- +passextract - Copy login details from pass(1) + +SYNOPSIS +-------- +*passextract* ['OPTIONS'] ['PASS_FILE'] + +DESCRIPTION +----------- +An extension to the pass(1) password manager. Passextract provides a UI +similar to urlview(2) that enables these additional fields to be copied +to the system clipboard. Three fields are recognised: emails, usernames, +and passwords. They are defined as follows: + + This text is ignored + + e: email@example.com + u: username + p: secret-password + +In order to be recognised by Passextract, those fields must be prefixed +by “e: ”, “u: ”, or “p: ” as illustrated above. + +The passextract(1) command will parse those fields from 'PASS_FILE'. If +'PASS_FILE' is not provided or if it's '-' then the standard input is +used. + +OPTIONS +------- +-i:: + Make password strings invisible by replacing them with stars ("*"). + +INTERACTIVE CONTROL +------------------- +In the interactive UI, the following commands are available: + +q / C-c:: + Quit and clear the clipboard +j:: + Move the selection down +k:: + Move the selection up +g:: + Move the selection to the top +G:: + Move the selection to the bottom +ENTER:: + Copy the currently selected line + +EXAMPLES +-------- +Passextract can be invoked on its own or with the piped output of `pass +show`. + + $ pass show github.com | passextract + $ passextract github.com + +The included Bash completion file provides the same tab completion +options as `pass show`. + +SHELL COMPLETION +---------------- +Shell completion is provided to complete pass(1) files. To enable Bash +completion, source the included `passextract.bash-completion` file. -- cgit v1.2.3 From af1720c73402fbac95ce05a03acf153fdbf404b3 Mon Sep 17 00:00:00 2001 From: Teddy Wing Date: Sat, 3 Mar 2018 18:22:02 +0100 Subject: passextract.1: Make literals bold To more clearly identify literals in "`literal`" blocks in the man page, make them bold by doing a simple text replacement on them. Note that this Makefile makes a `passextract.1` file at the root of the project. Need to fix that. --- Makefile | 7 ++++++- doc/passextract.1 | 6 +++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 6ea628a..ec9e50a 100644 --- a/Makefile +++ b/Makefile @@ -1,2 +1,7 @@ +MAN_PAGE := doc/passextract.1.txt +TRANSFORMED_MAN_PAGE := $(patsubst %,%.tmp,$(MAN_PAGE)) + doc/passextract.1: doc/passextract.1.txt - a2x --no-xmllint --format manpage $< + sed 's/`/*/g' $< > $(TRANSFORMED_MAN_PAGE) && \ + a2x --no-xmllint --format manpage $(TRANSFORMED_MAN_PAGE) && \ + rm $(TRANSFORMED_MAN_PAGE) diff --git a/doc/passextract.1 b/doc/passextract.1 index cddc96f..8aa4f0b 100644 --- a/doc/passextract.1 +++ b/doc/passextract.1 @@ -102,7 +102,7 @@ Copy the currently selected line .RE .SH "EXAMPLES" .sp -Passextract can be invoked on its own or with the piped output of pass show\&. +Passextract can be invoked on its own or with the piped output of \fBpass show\fR\&. .sp .if n \{\ .RS 4 @@ -115,7 +115,7 @@ $ passextract github\&.com .RE .\} .sp -The included Bash completion file provides the same tab completion options as pass show\&. +The included Bash completion file provides the same tab completion options as \fBpass show\fR\&. .SH "SHELL COMPLETION" .sp -Shell completion is provided to complete pass(1) files\&. To enable Bash completion, source the included passextract\&.bash\-completion file\&. +Shell completion is provided to complete pass(1) files\&. To enable Bash completion, source the included \fBpassextract\&.bash\-completion\fR file\&. -- cgit v1.2.3 From 517f9c6ec992212576aaef7b510486650dd99f50 Mon Sep 17 00:00:00 2001 From: Teddy Wing Date: Sat, 3 Mar 2018 18:26:00 +0100 Subject: Makefile: Clean up man page bold literal transformation Instead of the messy variables we were using, which caused `passextract.1.txt.tmp` and `passextract.1` files to be generated at the root of the project, create a few new targets to do the "`"` to "*" transformation and build the man page from a temporary file. --- Makefile | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index ec9e50a..1248d57 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,14 @@ -MAN_PAGE := doc/passextract.1.txt -TRANSFORMED_MAN_PAGE := $(patsubst %,%.tmp,$(MAN_PAGE)) +TRANSFORMED_MAN_PAGE := doc/passextract.1.transformed -doc/passextract.1: doc/passextract.1.txt - sed 's/`/*/g' $< > $(TRANSFORMED_MAN_PAGE) && \ - a2x --no-xmllint --format manpage $(TRANSFORMED_MAN_PAGE) && \ +$(TRANSFORMED_MAN_PAGE): doc/passextract.1.txt + sed 's/`/*/g' $< > $@ + +clean_transformed: rm $(TRANSFORMED_MAN_PAGE) + +doc/passextract.1: $(TRANSFORMED_MAN_PAGE) + a2x --no-xmllint --format manpage $< + +doc: doc/passextract.1 clean_transformed + +.PHONY: clean_transformed doc -- cgit v1.2.3