Improvement request: Consistent naming in the man page

[Heikki Lehvaslaiho]

I was reading the pass man page that I have not looked at for along time
and found it really confusing. I can figure things out, but new users sure
get bad impression. The terminology is mix of pass-name, password,
(old-|new-)path, names of passwords -- all without clearly defining terms.
The convention that the password is stored in the first line of the
password file, but the file can contain additional lines of information
should be presented more prominently. A rewrite is clearly needed.

Especially confusing lines:

- init [ --path=sub-folder, -p sub-folder ] gpg-id...
  command line programs like pass deal with directories, not folders
- find pass-names
  pass-names is a space separated list of substrings that match pass-names.
- cp|mv old-path new-path
  Documentation for these talk about directories without making it clear
that it is talking about pass directories that are inside
PASSWORD_STORE_DIR, not file system directories.
- SIMPLE EXAMPLES/List existing passwords in store
  Lists directories and pass-names, not passwords
- SIMPLE EXAMPLES/Find existing passwords in store that match .com
  Finds pass-names, not passwords
- SIMPLE EXAMPLES/Add multiline password to store
  Adds multiple lines, but only one line can be copied to the clipboard at
the time, so calling it a multiline password.

I am sure there are more.


In my opinion the man page needs a paragraph explaining the terms and
conventions to be more inline with the information in pass home page. These
then need to be followed consistently. Below is text that includes the most
important points and can be used as a starting point for additional text in
the man page. (The first item is in already the man page.)

- *password file* is an gpg2(1) encrypted file inside a directory tree at
PASSWORD_STORE_DIR that defaults to ' ~/.password-store'.
- The name of the password file is the *password name* (alias *pass-name*)
with extension '.gpg'. The extension nor the PASSWORD_STORE_DIR is never
included in the pass arguments. E.g. 'doorcode'.
- If the password file is placed in a subdirectory, the name has to include
the whole  *path*  to identify the password file. Some commands also work
on directories. E.g. 'myhome/doorcode'.
- The *password* is stored in the first line of the password file by
convention. The password string consists of (printable|any characters,
except which ones?) characters excluding the new line character. Use option
'--clip|-c' to copy the password to the clipboard without displaying it.
- Subsequent lines of the password file can be used to store free and
semistructured text that can be copied to the clipboard one line at the
time by giving a numerical argument to the '--clip|-c' option.

Best,

     -Heikki

Heikki Lehväslaiho - skype:heikki_lehvaslaiho cell: +358 40 850 6640
http://about.me/heikki
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.zx2c4.com/pipermail/password-store/attachments/20170429/f4ee5945/attachment.html>