From: jmc <jmc@openbsd.org>
Date: Thu, 21 Jul 2016 18:33:27 +0000 (+0000)
Subject: rename NOTES to COMMON SYNTAX (explains itself better); rework the
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=b7786361af6719a199a351b35fb09bd61243f785;p=openbsd

rename NOTES to COMMON SYNTAX (explains itself better); rework the
passphrase section a little; move the DER|PEM stuff in there to help
avoid text repetition, and prefer the lowercase (less keys to press);
adjust ENVIRONMENT to format a little more nicely;
---

diff --git a/usr.bin/openssl/openssl.1 b/usr.bin/openssl/openssl.1
index 52949f6bd2b..d93a19b91d1 100644
--- a/usr.bin/openssl/openssl.1
+++ b/usr.bin/openssl/openssl.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: openssl.1,v 1.37 2016/07/21 16:34:08 jmc Exp $
+.\" $OpenBSD: openssl.1,v 1.38 2016/07/21 18:33:27 jmc Exp $
 .\" ====================================================================
 .\" Copyright (c) 1998-2002 The OpenSSL Project.  All rights reserved.
 .\"
@@ -263,14 +263,6 @@ of the structures.
 The input file; the default is standard input.
 .It Fl inform Cm der | pem | txt
 The input format.
-.Cm der
-.Pq Distinguished Encoding Rules
-is binary format and
-.Cm pem
-.Pq Privacy Enhanced Mail ,
-the default, is base64-encoded.
-.Cm txt
-is plain text.
 .It Fl length Ar number
 Number of bytes to parse; the default is until end of file.
 .It Fl noout
@@ -971,25 +963,19 @@ Cipher suites using SHA1.
 .Op Fl fingerprint
 .Op Fl hash
 .Op Fl in Ar file
-.Op Fl inform Ar DER | PEM
+.Op Fl inform Cm der | pem
 .Op Fl issuer
 .Op Fl lastupdate
 .Op Fl nextupdate
 .Op Fl noout
 .Op Fl out Ar file
-.Op Fl outform Ar DER | PEM
+.Op Fl outform Cm der | pem
 .Op Fl text
 .nr nS 0
 .Pp
 The
 .Nm crl
 command processes CRL files in DER or PEM format.
-.Pp
-.Cm DER
-is a DER-encoded CRL structure.
-.Cm PEM ,
-the default,
-is a base64-encoded version of the DER form with header and footer lines.
 The PEM CRL format uses the header and footer lines:
 .Bd -unfilled -offset indent
 -----BEGIN X509 CRL-----
@@ -1015,7 +1001,7 @@ Output a hash of the issuer name.
 This can be used to look up CRLs in a directory by issuer name.
 .It Fl in Ar file
 The input file to read from, or standard input if not specified.
-.It Fl inform Cm DER | PEM
+.It Fl inform Cm der | pem
 The input format.
 .It Fl issuer
 Output the issuer name.
@@ -1031,7 +1017,7 @@ field.
 Don't output the encoded version of the CRL.
 .It Fl out Ar file
 The output file to write to, or standard output if not specified.
-.It Fl outform Cm DER | PEM
+.It Fl outform Cm der | pem
 The output format.
 .It Fl text
 Print out the CRL in text form.
@@ -9010,37 +8996,32 @@ This means that any directories using the old form
 must have their links rebuilt using
 .Ar c_rehash
 or similar.
-.Sh NOTES
-Several commands accept password arguments, typically using
+.Sh COMMON NOTATION
+Several commands share a common syntax,
+as detailed below.
+.Pp
+Password arguments, typically specified using
 .Fl passin
 and
 .Fl passout
-for input and output passwords, respectively.
-These allow the password to be obtained from a variety of sources.
-Both of these options take a single argument whose format is described below.
+for input and output passwords,
+allow passwords to be obtained from a variety of sources.
+Both of these options take a single argument, described below.
 If no password argument is given and a password is required,
 then the user is prompted to enter one:
 this will typically be read from the current terminal with echoing turned off.
-.Bl -tag -width "fd:number"
-.It Ar pass : Ns Ar password
+.Bl -tag -width "pass:password" -offset indent
+.It Cm pass : Ns Ar password
 The actual password is
 .Ar password .
-Since the password is visible to utilities
-(like
-.Xr ps 1
-under
-.Ux )
+Since the password is visible to utilities,
 this form should only be used where security is not important.
-.It Ar env : Ns Ar var
+.It Cm env : Ns Ar var
 Obtain the password from the environment variable
 .Ar var .
-Since the environment of other processes is visible on certain platforms
-(e.g.\&
-.Xr ps 1
-under certain
-.Ux
-OSes) this option should be used with caution.
-.It Ar file : Ns Ar path
+Since the environment of other processes is visible,
+this option should be used with caution.
+.It Cm file : Ns Ar path
 The first line of
 .Ar path
 is the password.
@@ -9055,17 +9036,37 @@ for the output password.
 .Ar path
 need not refer to a regular file:
 it could, for example, refer to a device or named pipe.
-.It Ar fd : Ns Ar number
+.It Cm fd : Ns Ar number
 Read the password from the file descriptor
 .Ar number .
-This can be used to send the data via a pipe for example.
-.It Ar stdin
+This can be used to send the data via a pipe, for example.
+.It Cm stdin
 Read the password from standard input.
 .El
+.Pp
+File formats,
+typically specified using
+.Fl inform
+and
+.Fl outform ,
+indicate the type of file being read from
+or the file format to write.
+The argument is case insensitive.
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It Cm der
+Distinguished Encoding Rules (DER)
+is a binary format.
+.It Cm pem
+Privacy Enhanced Mail (PEM)
+is base64-encoded.
+.It Cm txt
+Plain ASCII text.
+.El
 .Sh ENVIRONMENT
 The following environment variables affect the execution of
 .Nm openssl :
-.Bl -tag -width "OPENSSL_CONFXXX"
+.Bl -tag -width "/etc/ssl/openssl.cnf"
 .It Ev OPENSSL_CONF
 The location of the master configuration file.
 .El