[PATCH] man: New sentence, new line
Alejandro Colomar
alx at kernel.org
Sun Sep 24 21:08:51 UTC 2023
Manual pages *must* use either 2 spaces between sentences, or a newline.
Using only 1 space will fool the formatter to think that the '.' is not
a sentence terminator (it could be for example an abbreviation, as in
Jason A. Donenfeld). Let's use a newline, as is recommended by
man-pages(7).
$ MANWIDTH=72 man man-pages \
| sed -n '/Use semantic newlines/,/^$/p';
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, long sentences should be split into lines at
clause breaks (commas, semicolons, colons, and so on), and long
clauses should be split at phrase boundaries. This convention,
sometimes known as "semantic newlines", makes it easier to see
the effect of patches, which often operate at the level of in‐
dividual sentences, clauses, or phrases.
Signed-off-by: Alejandro Colomar <alx at kernel.org>
---
man/pass.1 | 169 +++++++++++++++++++++++++++++++++++------------------
1 file changed, 113 insertions(+), 56 deletions(-)
diff --git a/man/pass.1 b/man/pass.1
index a555dcb..7d5cffa 100644
--- a/man/pass.1
+++ b/man/pass.1
@@ -30,25 +30,31 @@ .SH DESCRIPTION
.B show
or
.BR ls ,
-depending on the type of specifier in ARGS. Alternatively, if \fIPASSWORD_STORE_ENABLE_EXTENSIONS\fP
+depending on the type of specifier in ARGS.
+Alternatively, if \fIPASSWORD_STORE_ENABLE_EXTENSIONS\fP
is set to "true", and the file \fI.extensions/COMMAND.bash\fP exists inside the
password store and is executable, then it is sourced into the environment,
-passing any arguments and environment variables. Extensions existing in a
+passing any arguments and environment variables.
+Extensions existing in a
system-wide directory, only installable by the administrator, are always enabled.
Otherwise COMMAND must be one of the valid commands listed below.
Several of the commands below rely on or provide additional functionality if
-the password store directory is also a git repository. If the password store
+the password store directory is also a git repository.
+If the password store
directory is a git repository, all password store modification commands will
-cause a corresponding git commit. Sub-directories may be separate nested git
+cause a corresponding git commit.
+Sub-directories may be separate nested git
repositories, and pass will use the inner-most directory relative to the
-current password. See the \fIEXTENDED GIT EXAMPLE\fP section for a detailed
+current password.
+See the \fIEXTENDED GIT EXAMPLE\fP section for a detailed
description using \fBinit\fP and
.BR git (1).
The \fBinit\fP command must be run before other commands in order to initialize
-the password store with the correct gpg key id. Passwords are encrypted using
+the password store with the correct gpg key id.
+Passwords are encrypted using
the gpg key set with \fBinit\fP.
There is a corresponding bash completion script for use with tab completing
@@ -61,16 +67,21 @@ .SH COMMANDS
\fBinit\fP [ \fI--path=sub-folder\fP, \fI-p sub-folder\fP ] \fIgpg-id...\fP
Initialize new password storage and use
.I gpg-id
-for encryption. Multiple gpg-ids may be specified, in order to encrypt each
-password with multiple ids. This command must be run first before a password
-store can be used. If the specified \fIgpg-id\fP is different from the key
+for encryption.
+Multiple gpg-ids may be specified, in order to encrypt each
+password with multiple ids.
+This command must be run first before a password
+store can be used.
+If the specified \fIgpg-id\fP is different from the key
used in any existing files, these files will be reencrypted to use the new id.
Note that use of
.BR gpg-agent (1)
is recommended so that the batch decryption does not require as much user
-intervention. If \fI--path\fP or \fI-p\fP is specified, along with an argument,
+intervention.
+If \fI--path\fP or \fI-p\fP is specified, along with an argument,
a specific gpg-id or set of gpg-ids is assigned for that specific sub folder of
-the password store. If only one \fIgpg-id\fP is given, and it is an empty string,
+the password store.
+If only one \fIgpg-id\fP is given, and it is an empty string,
then the current \fI.gpg-id\fP file for the specified \fIsub-folder\fP (or root if
unspecified) is removed.
.TP
@@ -79,56 +90,73 @@ .SH COMMANDS
.I subfolder
by using the
.BR tree (1)
-program. This command is alternatively named \fBlist\fP.
+program.
+This command is alternatively named \fBlist\fP.
.TP
\fBgrep\fP [\fIGREPOPTIONS\fP] \fIsearch-string\fP
Searches inside each decrypted password file for \fIsearch-string\fP, and displays line
-containing matched string along with filename. Uses
+containing matched string along with filename.
+Uses
.BR grep (1)
-for matching. \fIGREPOPTIONS\fP are passed to
+for matching.
+\fIGREPOPTIONS\fP are passed to
.BR grep (1)
-as-is. (Note: the \fIGREP_OPTIONS\fP environment variable functions as well.)
+as-is.
+(Note: the \fIGREP_OPTIONS\fP environment variable functions as well.)
.TP
\fBfind\fP \fIpass-names\fP...
List names of passwords inside the tree that match \fIpass-names\fP by using the
.BR tree (1)
-program. This command is alternatively named \fBsearch\fP.
+program.
+This command is alternatively named \fBsearch\fP.
.TP
\fBshow\fP [ \fI--clip\fP[=\fIline-number\fP], \fI-c\fP[\fIline-number\fP] ] [ \fI--qrcode\fP[=\fIline-number\fP], \fI-q\fP[\fIline-number\fP] ] \fIpass-name\fP
-Decrypt and print a password named \fIpass-name\fP. If \fI--clip\fP or \fI-c\fP
+Decrypt and print a password named \fIpass-name\fP.
+If \fI--clip\fP or \fI-c\fP
is specified, do not print the password but instead copy the first (or otherwise specified)
line to the clipboard using
.BR xclip (1)
or
.BR wl-clipboard(1)
-and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds. If \fI--qrcode\fP
+and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds.
+If \fI--qrcode\fP
or \fI-q\fP is specified, do not print the password but instead display a QR code using
.BR qrencode (1)
either to the terminal or graphically if supported.
.TP
\fBinsert\fP [ \fI--echo\fP, \fI-e\fP | \fI--multiline\fP, \fI-m\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
-Insert a new password into the password store called \fIpass-name\fP. This will
-read the new password from standard in. If \fI--echo\fP or \fI-e\fP is \fInot\fP specified,
+Insert a new password into the password store called \fIpass-name\fP.
+This will
+read the new password from standard in.
+If \fI--echo\fP or \fI-e\fP is \fInot\fP specified,
disable keyboard echo when the password is entered and confirm the password by asking
-for it twice. If \fI--multiline\fP or \fI-m\fP is specified, lines will be read until
-EOF or Ctrl+D is reached. Otherwise, only a single line from standard in is read. Prompt
-before overwriting an existing password, unless \fI--force\fP or \fI-f\fP is specified. This
+for it twice.
+If \fI--multiline\fP or \fI-m\fP is specified, lines will be read until
+EOF or Ctrl+D is reached.
+Otherwise, only a single line from standard in is read.
+Prompt
+before overwriting an existing password, unless \fI--force\fP or \fI-f\fP is specified.
+This
command is alternatively named \fBadd\fP.
.TP
\fBedit\fP \fIpass-name\fP
Insert a new password or edit an existing password using the default text editor specified
by the environment variable \fIEDITOR\fP or using
.BR vi (1)
-as a fallback. This mode makes use of temporary files for editing, but care is taken to
+as a fallback.
+This mode makes use of temporary files for editing, but care is taken to
ensure that temporary files are created in \fI/dev/shm\fP in order to avoid writing to
-difficult-to-erase disk sectors. If \fI/dev/shm\fP is not accessible, fallback to
+difficult-to-erase disk sectors.
+If \fI/dev/shm\fP is not accessible, fallback to
the ordinary \fITMPDIR\fP location, and print a warning.
.TP
\fBgenerate\fP [ \fI--no-symbols\fP, \fI-n\fP ] [ \fI--clip\fP, \fI-c\fP ] [ \fI--in-place\fP, \fI-i\fP | \fI--force\fP, \fI-f\fP ] \fIpass-name [pass-length]\fP
Generate a new password using \fB/dev/urandom\fP of length \fIpass-length\fP
(or \fIPASSWORD_STORE_GENERATED_LENGTH\fP if unspecified) and insert into
-\fIpass-name\fP. If \fI--no-symbols\fP or \fI-n\fP is specified, do not use
-any non-alphanumeric characters in the generated password. The character sets used
+\fIpass-name\fP.
+If \fI--no-symbols\fP or \fI-n\fP is specified, do not use
+any non-alphanumeric characters in the generated password.
+The character sets used
in generating passwords can be changed with the \fIPASSWORD_STORE_CHARACTER_SET\fP and
\fIPASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS\fP environment variables, described below.
If \fI--clip\fP or \fI-c\fP is specified, do not print the password but instead copy
@@ -136,42 +164,59 @@ .SH COMMANDS
.BR xclip (1)
or
.BR wl-clipboard(1)
-and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds. If \fI--qrcode\fP
+and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds.
+If \fI--qrcode\fP
or \fI-q\fP is specified, do not print the password but instead display a QR code using
.BR qrencode (1)
-either to the terminal or graphically if supported. Prompt before overwriting an existing password,
-unless \fI--force\fP or \fI-f\fP is specified. If \fI--in-place\fP or \fI-i\fP is
+either to the terminal or graphically if supported.
+Prompt before overwriting an existing password,
+unless \fI--force\fP or \fI-f\fP is specified.
+If \fI--in-place\fP or \fI-i\fP is
specified, do not interactively prompt, and only replace the first line of the password
file with the new generated password, keeping the remainder of the file intact.
.TP
\fBrm\fP [ \fI--recursive\fP, \fI-r\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
-Remove the password named \fIpass-name\fP from the password store. This command is
-alternatively named \fBremove\fP or \fBdelete\fP. If \fI--recursive\fP or \fI-r\fP
-is specified, delete pass-name recursively if it is a directory. If \fI--force\fP
+Remove the password named \fIpass-name\fP from the password store.
+This command is
+alternatively named \fBremove\fP or \fBdelete\fP.
+If \fI--recursive\fP or \fI-r\fP
+is specified, delete pass-name recursively if it is a directory.
+If \fI--force\fP
or \fI-f\fP is specified, do not interactively prompt before removal.
.TP
\fBmv\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP
-Renames the password or directory named \fIold-path\fP to \fInew-path\fP. This
-command is alternatively named \fBrename\fP. If \fI--force\fP is specified,
-silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a
-trailing \fI/\fP, it is always treated as a directory. Passwords are selectively
+Renames the password or directory named \fIold-path\fP to \fInew-path\fP.
+This
+command is alternatively named \fBrename\fP.
+If \fI--force\fP is specified,
+silently overwrite \fInew-path\fP if it exists.
+If \fInew-path\fP ends in a
+trailing \fI/\fP, it is always treated as a directory.
+Passwords are selectively
reencrypted to the corresponding keys of their new destination.
.TP
\fBcp\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP
-Copies the password or directory named \fIold-path\fP to \fInew-path\fP. This
-command is alternatively named \fBcopy\fP. If \fI--force\fP is specified,
-silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a
-trailing \fI/\fP, it is always treated as a directory. Passwords are selectively
+Copies the password or directory named \fIold-path\fP to \fInew-path\fP.
+This
+command is alternatively named \fBcopy\fP.
+If \fI--force\fP is specified,
+silently overwrite \fInew-path\fP if it exists.
+If \fInew-path\fP ends in a
+trailing \fI/\fP, it is always treated as a directory.
+Passwords are selectively
reencrypted to the corresponding keys of their new destination.
.TP
\fBgit\fP \fIgit-command-args\fP...
If the password store is a git repository, pass \fIgit-command-args\fP as arguments to
.BR git (1)
-using the password store as the git repository. If \fIgit-command-args\fP is \fBinit\fP,
+using the password store as the git repository.
+If \fIgit-command-args\fP is \fBinit\fP,
in addition to initializing the git repository, add the current contents of the password
-store to the repository in an initial commit. If the git config key \fIpass.signcommits\fP
+store to the repository in an initial commit.
+If the git config key \fIpass.signcommits\fP
is set to \fItrue\fP, then all commits will be signed using \fIuser.signingkey\fP or the
-default git signing key. This config key may be turned on using:
+default git signing key.
+This config key may be turned on using:
.B `pass git config --bool --add pass.signcommits true`
.TP
\fBhelp\fP
@@ -246,7 +291,8 @@ .SH SIMPLE EXAMPLES
Copy existing password to clipboard
.B zx2c4 at laptop ~ $ pass -c Email/zx2c4.com
.br
-Copied Email/jason at zx2c4.com to clipboard. Will clear in 45 seconds.
+Copied Email/jason at zx2c4.com to clipboard.
+Will clear in 45 seconds.
.TP
Add password to store
.B zx2c4 at laptop ~ $ pass insert Business/cheese-whiz-factory
@@ -289,7 +335,8 @@ .SH SIMPLE EXAMPLES
Generate new password and copy it to the clipboard
.B zx2c4 at laptop ~ $ pass generate -c Email/jasondonenfeld.com 19
.br
-Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds.
+Copied Email/jasondonenfeld.com to clipboard.
+Will clear in 45 seconds.
.TP
Remove password from store
.B zx2c4 at laptop ~ $ pass remove Business/cheese-whiz-factory
@@ -299,7 +346,8 @@ .SH SIMPLE EXAMPLES
removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]
.SH EXTENDED GIT EXAMPLE
-Here, we initialize new password store, create a git repository, and then manipulate and sync passwords. Make note of the arguments to the first call of \fBpass git push\fP; consult
+Here, we initialize new password store, create a git repository, and then manipulate and sync passwords.
+Make note of the arguments to the first call of \fBpass git push\fP; consult
.BR git-push (1)
for more information.
@@ -399,9 +447,11 @@ .SH FILES
.TP
.B ~/.password-store/.gpg-id
Contains the default gpg key identification used for encryption and decryption.
-Multiple gpg keys may be specified in this file, one per line. If this file
+Multiple gpg keys may be specified in this file, one per line.
+If this file
exists in any sub directories, passwords inside those sub directories are
-encrypted using those keys. This should be set using the \fBinit\fP command.
+encrypted using those keys.
+This should be set using the \fBinit\fP command.
.TP
.B ~/.password-store/.extensions
The directory containing extension files.
@@ -413,7 +463,8 @@ .SH ENVIRONMENT VARIABLES
Overrides the default password storage directory.
.TP
.I PASSWORD_STORE_KEY
-Overrides the default gpg key identification set by \fBinit\fP. Keys must not
+Overrides the default gpg key identification set by \fBinit\fP.
+Keys must not
contain spaces and thus use of the hexadecimal key signature is recommended.
Multiple keys may be specified separated by spaces.
.TP
@@ -421,7 +472,8 @@ .SH ENVIRONMENT VARIABLES
Additional options to be passed to all invocations of GPG.
.TP
.I PASSWORD_STORE_X_SELECTION
-Overrides the selection passed to \fBxclip\fP, by default \fIclipboard\fP. See
+Overrides the selection passed to \fBxclip\fP, by default \fIclipboard\fP.
+See
.BR xclip (1)
for more info.
.TP
@@ -437,15 +489,19 @@ .SH ENVIRONMENT VARIABLES
is unspecified.
.TP
.I PASSWORD_STORE_CHARACTER_SET
-The character set to be used in password generation for \fBgenerate\fP. This value
-is to be interpreted by \fBtr\fP. See
+The character set to be used in password generation for \fBgenerate\fP.
+This value
+is to be interpreted by \fBtr\fP.
+See
.BR tr (1)
for more info.
.TP
.I PASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS
The character set to be used in no-symbol password generation for \fBgenerate\fP,
-when \fI--no-symbols\fP, \fI-n\fP is specified. This value is to be interpreted
-by \fBtr\fP. See
+when \fI--no-symbols\fP, \fI-n\fP is specified.
+This value is to be interpreted
+by \fBtr\fP.
+See
.BR tr (1)
for more info.
.TP
@@ -459,7 +515,8 @@ .SH ENVIRONMENT VARIABLES
.I PASSWORD_STORE_SIGNING_KEY
If this environment variable is set, then all \fB.gpg-id\fP files and non-system extension files
must be signed using a detached signature using the GPG key specified by the full 40 character
-upper-case fingerprint in this variable. If multiple fingerprints are specified, each
+upper-case fingerprint in this variable.
+If multiple fingerprints are specified, each
separated by a whitespace character, then signatures must match at least one.
The \fBinit\fP command will keep signatures of \fB.gpg-id\fP files up to date.
.TP
--
2.40.1
More information about the Password-Store
mailing list