bin/48395: NetPGP manpage improvements

[anthony%cathet.us@localhost]

>Number:         48395
>Category:       bin
>Synopsis:       NetPGP manpage improvements
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Nov 22 06:25:00 +0000 2013
>Originator:     Anthony J. Bentley
>Release:        NetBSD-current
>Organization:
>Environment:
>Description:
Here is a patch to improve the NetPGP man pages a bit.

- Use mdoc(7) bibliographies for RFC references
- Consistently say "the foo() function" or "foo()" instead of "the foo()"
- Don't break author name sentences in the middle of the line
- Various typos/macros/formatting fixes
>How-To-Repeat:

>Fix:
Index: src/hkpclient/hkpc.1
===================================================================
RCS file: /cvsroot/src/crypto/external/bsd/netpgp/dist/src/hkpclient/hkpc.1,v
retrieving revision 1.2
diff -u -p -u -p -r1.2 hkpc.1
--- src/hkpclient/hkpc.1        20 Jul 2013 21:39:55 -0000      1.2
+++ src/hkpclient/hkpc.1        3 Nov 2013 08:47:33 -0000
@@ -86,8 +86,7 @@ whilst the hostname defaults to
 .Pp
 The
 .Dv netpgp
-suite of libraries and commands provides a copnvenient client
-in
+suite of libraries and commands provides a convenient client in
 .Xr hkpd 1 .
 .Pp
 The information is sent to the server in the form of
@@ -111,9 +110,16 @@ Output will be printed on stdout.
 .Xr libmj 3 ,
 .Xr libnetpgp 3
 .Sh STANDARDS
-The
-.Nm
-utility is designed to conform to IETF RFC 4880.
+.Rs
+.%A J. Callas
+.%A L. Donnerhacke
+.%A H. Finney
+.%A D. Shaw
+.%A R. Thayer
+.%D November 2007
+.%R RFC 4880
+.%T OpenPGP Message Format
+.Re
 .Sh HISTORY
 The
 .Nm
Index: src/lib/libnetpgp.3
===================================================================
RCS file: /cvsroot/src/crypto/external/bsd/netpgp/dist/src/lib/libnetpgp.3,v
retrieving revision 1.15
diff -u -p -u -p -r1.15 libnetpgp.3
--- src/lib/libnetpgp.3 20 Jul 2013 21:39:55 -0000      1.15
+++ src/lib/libnetpgp.3 3 Nov 2013 08:47:33 -0000
@@ -184,14 +184,14 @@ If no public key ring file is set, initi
 in the
 .Pa .gnupg/pubring.gpg
 file in the user's home directory.
-Similarily, if no secret key ring file is set,
+Similarly, if no secret key ring file is set,
 initial values will be taken from those
 in the
 .Pa .gnupg/secring.gpg
 file in the user's home directory.
 The
 .Fn netpgp_init
-returns 1 on sucess, 0 on failure.
+function returns 1 on success, 0 on failure.
 .Pp
 To list all the keys in a keyring, the
 .Fn netpgp_list_keys
@@ -218,18 +218,18 @@ the keyrings.
 .Pp
 To export a key, the
 .Fn netpgp_export_key
-is used.
+function is used.
 Output is sent to the standard output.
 .Pp
 To import a key onto the public keyring, the
 .Fn netpgp_import_key
-is used.
+function is used.
 The name of the file containing the key to be imported is provided
 as the filename argument.
 .Pp
 To generate a key, the
 .Fn netpgp_generate_key
-is used.
+function is used.
 It takes an argument of the number of bits to use in the key.
 At the time that this manual page was created (April 2009),
 the recommendations are that the bare minimum key size
@@ -244,12 +244,13 @@ files are the lifeblood of the
 library.
 To encrypt a file, the
 .Fn netpgp_encrypt_file
+function is used,
 and the
 .Fn netpgp_decrypt_file
-is used to decrypt the results of the encryption.
+function is used to decrypt the results of the encryption.
 To sign a file, the
 .Fn netpgp_sign_file
-is used, and the resulting signed file can be verified
+function is used, and the resulting signed file can be verified
 using the
 .Fn netpgp_verify_file
 function.
@@ -310,7 +311,7 @@ file basis).
 .Pp
 The
 .Fn netpgp_get_info
-returns the version or maintainer information depending upon the
+function returns the version or maintainer information depending upon the
 .Ar type
 argument.
 At the present time, two types are defined:
@@ -333,6 +334,7 @@ The
 library first appeared in
 .Nx 6.0 .
 .Sh AUTHORS
+.An -nosplit
 .An Ben Laurie ,
 .An Rachel Willmer .
 .An Alistair Crooks Aq Mt agc%NetBSD.org@localhost
Index: src/libbn/libnetpgpbn.3
===================================================================
RCS file: /cvsroot/src/crypto/external/bsd/netpgp/dist/src/libbn/libnetpgpbn.3,v
retrieving revision 1.3
diff -u -p -u -p -r1.3 libnetpgpbn.3
--- src/libbn/libnetpgpbn.3     20 Jul 2013 21:39:56 -0000      1.3
+++ src/libbn/libnetpgpbn.3     3 Nov 2013 08:47:33 -0000
@@ -246,21 +246,21 @@
 emulates the API of the openssl
 .Xr bn 3
 library.
-It is implemented using Tom St Denis
+It is implemented using Tom St Denis'
 .Dq libtommath
 library.
 .Sh EXAMPLES
-The follow code fragment will make a JSON object
+The following code fragment will make a JSON object
 out of the string
 .Dq Hello <USERNAME>\en
 in the
 buffer called
-.Dq buf
+.Va buf
 where
-.Dq USERNAME
+.Ev USER
 is the name of the user taken from the runtime environment.
 The encoded text will be in an allocated buffer called
-.Dq s
+.Va s .
 .Bd -literal -offset indent
 mj_t atom;
 char buf[BUFSIZ];
@@ -273,9 +273,10 @@ mj_create(\*[Am]atom, "string", buf, cc)
 cc = mj_asprint(\*[Am]s, \*[Am]atom, MJ_JSON_ENCODE);
 .Ed
 .Pp
-and the following example will take the (binary) text which has been encoded 
into
+Next,
+the following example will take the (binary) text which has been encoded into
 JSON and is in the buffer
-.Dq buf ,
+.Va buf ,
 such as in the previous example, and re-create the original text:
 .Bd -literal -offset indent
 int from, to, tok, cc;
@@ -290,7 +291,7 @@ printf("%.*s", cc, s);
 .Ed
 .Pp
 The
-.Dv s
+.Va s
 pointer points to allocated storage with the original NUL-terminated string
 in it.
 .Sh SEE ALSO
@@ -301,4 +302,4 @@ The
 library first appeared in
 .Nx 7.0 .
 .Sh AUTHORS
-.An Alistair Crooks Aq Mt agc%NetBSD.org@localhost
+.An Alistair Crooks Aq Mt agc%NetBSD.org@localhost .
Index: src/libdigest/tiger.3
===================================================================
RCS file: /cvsroot/src/crypto/external/bsd/netpgp/dist/src/libdigest/tiger.3,v
retrieving revision 1.3
diff -u -p -u -p -r1.3 tiger.3
--- src/libdigest/tiger.3       20 Jul 2013 21:39:56 -0000      1.3
+++ src/libdigest/tiger.3       3 Nov 2013 08:47:33 -0000
@@ -116,10 +116,9 @@ and
 .Pp
 The
 .Fn TIGER_End
-function is a front end for
+function is a frontend for
 .Fn TIGER_Final
-which converts the digest into an
-.Tn ASCII
+which converts the digest into an ASCII
 representation of the 160 bit digest in hexadecimal.
 .Pp
 The
@@ -155,8 +154,8 @@ and should be freed using
 .Xr free 3
 when it is no longer needed.
 .Sh EXAMPLES
-The follow code fragment will calculate the digest for the string
-"The quick brown fox jumps over the lazy dog"
+The following code fragment will calculate the digest for the string
+.Dq The quick brown fox jumps over the lazy dog ,
 which is
 .Dq 6d12a41e72e644f017b6f0e2f7b44c6285f06dd5d2c5b075 .
 .Bd -literal -offset indent
@@ -189,11 +188,10 @@ printf("0x%s", TIGER_Data(buf, strlen(bu
 .Sh SEE ALSO
 .Xr md5 3 ,
 .Xr sha1 3
-.Pp
 .Rs
 .%A Ross Anderson
 .%A Eli Biham
-.%T "Tiger - A Fast New Hash Function"
+.%T "Tiger \- A Fast New Hash Function"
 .%B Proceedings of Fast Software Encryption 3, Cambridge
 .%D 1996
 .Re
@@ -213,7 +211,7 @@ and
 .Fn TIGER_Data
 helper functions are derived from code written by Poul-Henning Kamp.
 .Sh BUGS
-All attempts have bene made to optimise for the underlying hardware,
+All attempts have been made to optimise for the underlying hardware,
 as well as to format the digest properly in an endian-neutral manner.
 The author has no VAX hardware on which to test, and so it is not known
 whether that platform is supported.
Index: src/libmj/libmj.3
===================================================================
RCS file: /cvsroot/src/crypto/external/bsd/netpgp/dist/src/libmj/libmj.3,v
retrieving revision 1.6
diff -u -p -u -p -r1.6 libmj.3
--- src/libmj/libmj.3   20 Jul 2013 21:39:55 -0000      1.6
+++ src/libmj/libmj.3   3 Nov 2013 08:47:33 -0000
@@ -98,7 +98,7 @@ JSON object output functions:
 .Nm
 is a small library interface to allow JSON text to be created and parsed.
 JSON is the Java Script Object Notation,
-a lightweight data-interchange format, standardised in the ECMA standard.
+a lightweight data-interchange format, standardised by the ECMA.
 The library name
 .Nm
 is derived from a further acronym of
@@ -115,7 +115,7 @@ rebuilt to produce the original structur
 .Pp
 JSON contains basic units called atoms, the two
 basic atoms being strings and numbers.
-Three other useful atomic values are provided,
+Three other useful atomic values are provided:
 .Dq null ,
 .Dq false ,
 and
@@ -127,6 +127,7 @@ and as individual, ordered atoms, in an
 .Pp
 To create a new object, the
 .Fn mj_create
+function
 is used.
 It can be deleted using the
 .Fn mj_delete
@@ -154,7 +155,7 @@ and the JSON serialised text is copied i
 This memory can later be de-allocated using
 .Xr free 3 .
 For formatted output to a
-.Dv FILE *
+.Vt FILE *
 stream, the
 .Fn mj_pretty
 function is used.
@@ -220,17 +221,17 @@ A value of
 .Dv \-1
 may be used if the string length is not known.
 .Sh EXAMPLES
-The follow code fragment will make a JSON object
+The following code fragment will make a JSON object
 out of the string
 .Dq Hello <USERNAME>\en
 in the
 buffer called
-.Dq buf
+.Va buf
 where
-.Dq USERNAME
+.Ev USER
 is the name of the user taken from the runtime environment.
 The encoded text will be in an allocated buffer called
-.Dq s
+.Va s .
 .Bd -literal -offset indent
 mj_t atom;
 char buf[BUFSIZ];
@@ -243,9 +244,10 @@ mj_create(\*[Am]atom, "string", buf, cc)
 cc = mj_asprint(\*[Am]s, \*[Am]atom, MJ_JSON_ENCODE);
 .Ed
 .Pp
-and the following example will take the (binary) text which has been encoded 
into
+Next,
+the following example will take the (binary) text which has been encoded into
 JSON and is in the buffer
-.Dq buf ,
+.Va buf ,
 such as in the previous example, and re-create the original text:
 .Bd -literal -offset indent
 int from, to, tok, cc;
@@ -260,7 +262,7 @@ printf("%.*s", cc, s);
 .Ed
 .Pp
 The
-.Dv s
+.Va s
 pointer points to allocated storage with the original NUL-terminated string
 in it.
 .Sh SEE ALSO
Index: src/libverify/libnetpgpverify.3
===================================================================
RCS file: 
/cvsroot/src/crypto/external/bsd/netpgp/dist/src/libverify/libnetpgpverify.3,v
retrieving revision 1.4
diff -u -p -u -p -r1.4 libnetpgpverify.3
--- src/libverify/libnetpgpverify.3     20 Jul 2013 21:39:56 -0000      1.4
+++ src/libverify/libnetpgpverify.3     3 Nov 2013 08:47:33 -0000
@@ -121,15 +121,22 @@ It frees and de-allocates all resources 
 The program used for signing may encode into base64 encoding, and it may also
 use embedded compression to make the output smaller than it would otherwise be.
 This is handled automatically by
-.Nm
+.Nm .
 .Sh SEE ALSO
 .Xr bn 3 ,
 .\" .Xr bzlib2 3 ,
 .Xr zlib 3
 .Sh STANDARDS
-The
-.Nm
-utility is designed to conform to IETF RFC 4880.
+.Rs
+.%A J. Callas
+.%A L. Donnerhacke
+.%A H. Finney
+.%A D. Shaw
+.%A R. Thayer
+.%D November 2007
+.%R RFC 4880
+.%T OpenPGP Message Format
+.Re
 .Sh HISTORY
 The
 .Nm
Index: src/netpgp/netpgp.1
===================================================================
RCS file: /cvsroot/src/crypto/external/bsd/netpgp/dist/src/netpgp/netpgp.1,v
retrieving revision 1.18
diff -u -p -u -p -r1.18 netpgp.1
--- src/netpgp/netpgp.1 20 Jul 2013 21:39:55 -0000      1.18
+++ src/netpgp/netpgp.1 3 Nov 2013 08:47:33 -0000
@@ -180,7 +180,7 @@ The following commands can be used to en
 .Bl -tag -width Ar
 .It Fl Fl decrypt
 Decrypt the file using the user's private key.
-The pass phrase will be optained by prompting the user
+The pass phrase will be obtained by prompting the user
 to type it in, using
 .Xr getpass 3 .
 .It Fl Fl encrypt
@@ -271,7 +271,7 @@ utility has no way of verifying that an 
 that a key belongs to a certain individual.
 The trust for a signed key is given by the other signers of that key.
 The 16 hexadecimal digit user identity should be used when specifying
-user identities - email addresses and names are provided as aliases.
+user identities\(ememail addresses and names are provided as aliases.
 .It Fl Fl pass\-fd Ns = Ns Ar fd
 This option is intended for the use of external programs which may
 like to use the
@@ -317,10 +317,11 @@ the process of the
 .Nm
 requests.
 .It Fl Fl coredumps
-in normal processing,
-if an error occurs, the contents of memory are saved to disk, and can
+In most programs,
+if an error occurs during normal processing,
+the contents of memory are saved to disk, and can
 be read using tools to analyse behaviour.
-Unfortuinately this can disclose information to people viewing
+Unfortunately this can disclose information to people viewing
 the core dump, such as secret keys, and passphrases protecting
 those keys.
 In normal operation,
@@ -511,9 +512,16 @@ or 2 if any other error occurs.
 .Xr ssl 3 ,
 .Xr zlib 3
 .Sh STANDARDS
-The
-.Nm
-utility is designed to conform to IETF RFC 4880.
+.Rs
+.%A J. Callas
+.%A L. Donnerhacke
+.%A H. Finney
+.%A D. Shaw
+.%A R. Thayer
+.%D November 2007
+.%R RFC 4880
+.%T OpenPGP Message Format
+.Re
 .Sh HISTORY
 The
 .Nm
Index: src/netpgpkeys/netpgpkeys.1
===================================================================
RCS file: 
/cvsroot/src/crypto/external/bsd/netpgp/dist/src/netpgpkeys/netpgpkeys.1,v
retrieving revision 1.19
diff -u -p -u -p -r1.19 netpgpkeys.1
--- src/netpgpkeys/netpgpkeys.1 20 Jul 2013 21:39:56 -0000      1.19
+++ src/netpgpkeys/netpgpkeys.1 3 Nov 2013 08:47:33 -0000
@@ -37,27 +37,27 @@
 .Nm
 .Fl Fl export\-key
 .Op options
-.Ar file ...
+.Ar
 .Nm
 .Fl Fl find\-key
 .Op options
-.Ar file ...
+.Ar
 .Nm
 .Fl Fl generate\-key
 .Op options
-.Ar file ...
+.Ar
 .Nm
 .Fl Fl import\-key
 .Op options
-.Ar file ...
+.Ar
 .Nm
 .Fl Fl list\-keys
 .Op options
-.Ar file ...
+.Ar
 .Nm
 .Fl Fl list\-sigs
 .Op options
-.Ar file ...
+.Ar
 .Nm
 .Fl Fl trusted\-keys
 .Op options
@@ -67,7 +67,7 @@
 .Nm
 .Op Fl Vgls
 .Op Fl olong-option Ns = Ns value
-.Ar file ...
+.Ar
 .Pp
 where the long options for all commands are:
 .Pp
@@ -108,7 +108,7 @@ keys from other identities.
 .Pp
 The
 .Xr netpgp 1
-utility should be used for file management and transformation - encryption,
+utility should be used for file management and transformation\(emencryption,
 decryption,
 signing and verification of files.
 .Pp
@@ -211,7 +211,8 @@ or options may be given.
 .Bl -tag -width Ar
 .It Fl Fl cipher Ar cipher\-algorithm
 Specify the cipher to be used for symmetric encryption.
-The default cipher is "CAST5".
+The default cipher is
+.Dq CAST5 .
 .It Fl Fl hash Ar hash\-algorithm
 Specify the hash algorithm which is used during fingerprint calculation.
 For reference, at the present time,
@@ -247,7 +248,7 @@ utility has no way of verifying that an 
 that a key belongs to a certain individual.
 The trust for a signed key is given by the other signers of that key.
 The 16 hexadecimal digit user identity should be used when specifying
-user identities - email addresses and names are provided as aliases.
+user identities\(ememail addresses and names are provided as aliases.
 .It Fl Fl pass\-fd Ns = Ns Ar fd
 This option is intended for the use of external programs which may
 like to use the
@@ -377,9 +378,16 @@ uid              RSA 2048-bit key \*[Lt]
 .Xr ssl 3 ,
 .Xr zlib 3
 .Sh STANDARDS
-The
-.Nm
-utility is designed to conform to IETF RFC 4880.
+.Rs
+.%A J. Callas
+.%A L. Donnerhacke
+.%A H. Finney
+.%A D. Shaw
+.%A R. Thayer
+.%D November 2007
+.%R RFC 4880
+.%T OpenPGP Message Format
+.Re
 .Sh HISTORY
 The
 .Nm
Index: src/netpgpverify/netpgpverify.1
===================================================================
RCS file: 
/cvsroot/src/crypto/external/bsd/netpgp/dist/src/netpgpverify/netpgpverify.1,v
retrieving revision 1.6
diff -u -p -u -p -r1.6 netpgpverify.1
--- src/netpgpverify/netpgpverify.1     20 Jul 2013 21:39:56 -0000      1.6
+++ src/netpgpverify/netpgpverify.1     3 Nov 2013 08:47:33 -0000
@@ -160,9 +160,16 @@ or 2 if any other error occurs.
 .Xr ssl 3 ,
 .Xr zlib 3
 .Sh STANDARDS
-The
-.Nm
-utility is designed to conform to IETF RFC 4880.
+.Rs
+.%A J. Callas
+.%A L. Donnerhacke
+.%A H. Finney
+.%A D. Shaw
+.%A R. Thayer
+.%D November 2007
+.%R RFC 4880
+.%T OpenPGP Message Format
+.Re
 .Sh HISTORY
 The
 .Nm
Index: src/pgp2ssh/pgp2ssh.1
===================================================================
RCS file: /cvsroot/src/crypto/external/bsd/netpgp/dist/src/pgp2ssh/pgp2ssh.1,v
retrieving revision 1.3
diff -u -p -u -p -r1.3 pgp2ssh.1
--- src/pgp2ssh/pgp2ssh.1       20 Jul 2013 21:39:56 -0000      1.3
+++ src/pgp2ssh/pgp2ssh.1       3 Nov 2013 08:47:33 -0000
@@ -87,9 +87,16 @@ It can be redirected to a file for use b
 .\" .Xr libbz2 3 ,
 .Xr libnetpgp 3
 .Sh STANDARDS
-The
-.Nm
-utility is designed to conform to IETF RFC 4880.
+.Rs
+.%A J. Callas
+.%A L. Donnerhacke
+.%A H. Finney
+.%A D. Shaw
+.%A R. Thayer
+.%D November 2007
+.%R RFC 4880
+.%T OpenPGP Message Format
+.Re
 .Sh HISTORY
 The
 .Nm