Manual pages #131
Manual pages #131
Conversation
cmd/age-keygen/age-keygen.1
Outdated
| .Pp | ||
| If the | ||
| .Fl o | ||
| flag is not specified the key is output to standard output with the public key |
There was a problem hiding this comment.
Grammar nit: a comma after “specified” is required here due to the prefixed “if” clause as far as I know.
cmd/age-keygen/age-keygen.1
Outdated
| If the | ||
| .Fl o | ||
| flag is not specified the key is output to standard output with the public key | ||
| as a comment. |
There was a problem hiding this comment.
This leaves out what the happens with -o: What is stored where?
Experienced users will know that -o normally means “output file”, sure, but perhaps it'd be useful to specify what it does for all those who aren't familiar with this convention.
Maybe I'm being too pedantic here though.
cmd/age-keygen/age-keygen.1
Outdated
| .Dt AGE-KEYGEN 1 | ||
| .Sh NAME |
There was a problem hiding this comment.
This may be invalid mdoc.
According to mdoc(7), .Os is the mandatory third macro for any mdoc file. groff_mdoc(7) is less clear about this; the “TITLE MACROS” section only seems to imply it as convention, rather than necessity.
Also affects age.1.
cmd/age/age.1
Outdated
| .Op Fl o Ar output | ||
| .Op Ar input | ||
| .Sh DESCRIPTION | ||
| In the first synopsis form, |
There was a problem hiding this comment.
Nit: Wouldn't “If --decrypt is not given” be easier to read and understand? That would avoid people having to refer back to the synopsis section.
Similarly for line 24.
| .Bl -tag -width Ds -compact | ||
| .It Fl o , Fl -output Ar output | ||
| Write the result to the file at path | ||
| .Ar output . |
There was a problem hiding this comment.
Something that people might want to know: Does this overwrite output or error out if the file already exists?
Just food for thought.
cmd/age/age.1
Outdated
| is a path to a file with | ||
| .Nm | ||
| secret keys, one per line | ||
| (ignoring "#" prefixed comments and empty lines), or to an SSH key file. |
There was a problem hiding this comment.
Did you mean to use .Qq here or .Sq since it's a single characters instead of ""?
cmd/age/age.1
Outdated
| .Fl -recipient . | ||
| Every recipient will be able to decrypt the file. | ||
| .Ss Passphrases | ||
| Files can be encrypted by using |
There was a problem hiding this comment.
“encrypted with a passphrase”? Without the heading, this sentence seems to imply that any other options don't encrypt files.
cmd/age/age.1
Outdated
| .Fl -passphrase . | ||
| By default | ||
| .Nm | ||
| will automatically generate a secure passphrase. Passphrase protected files are |
| public key tag in the encrypted file, making it possible to track files that | ||
| are encrypted to a specific public key. | ||
| .Sh EXAMPLES | ||
| Generate a secret key, encrypt data, and decrypt: |
There was a problem hiding this comment.
I'm not sure if this was secret brilliance on your part or just a coincidence of copying over the README, but this conveniently also encourages people just following the examples blindly to frequently generate new keys, which seems like a net win to me.
There was a problem hiding this comment.
I shall attribute the brilliance here to Filippo. :-)
cmd/age/age.1
Outdated
| Encrypt | ||
| .Pa example.jpg | ||
| to multiple recipients and output to | ||
| .Pa example.jpg.age: |
There was a problem hiding this comment.
Did you mean to add a space in front of the colon?
Add section 1 manual pages for each of the command-line utilities. The `age` manual page is based on the README.
|
Thanks @xorhash, great feedback! I've updated based on your suggestions. Let me know how it looks now. |
|
Looks shippable to me now. Thanks for sorting this out! (Compare and contrast with #16 if you're bored.) |
|
This is awesome, thanks James |
|
FYI, while preparing a Debian package for age, I created man pages from the |
|
@johanfleury isn't AUTHOR information normally added at the end of man pages? |
|
is there anything left that needs to be done for this? |
|
How does this works on platforms other than *nix? |
Mandoc has options to output HTML files. One would use that for non-Unix distributions. |
|
Thanks everyone! I finally expanded the man page and merged it! |
Inspired by https://twitter.com/FiloSottile/status/1277084905428656129 I thought I'd quickly throw together a couple of man pages, based on the README. :-)