apps/pkey.c: Re-order help output and option documentation

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13712)

1 files changed, 81 insertions, 58 deletions

diff --git a/doc/man1/openssl-pkey.pod.in b/doc/man1/openssl-pkey.pod.in
index 2900fc24c7..f48471bc40 100644
--- a/doc/man1/openssl-pkey.pod.in
+++ b/doc/man1/openssl-pkey.pod.in
@@ -13,120 +13,147 @@ openssl-pkey - public or private key processing command
 
 B<openssl> B<pkey>
 [B<-help>]
-[B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
-[B<-outform> B<DER>|B<PEM>]
+{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
+[B<-check>]
+[B<-pubcheck>]
 [B<-in> I<filename>|I<uri>]
+[B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
 [B<-passin> I<arg>]
+[B<-pubin>]
 [B<-out> I<filename>]
+[B<-outform> B<DER>|B<PEM>]
+[B<-I<cipher>>]
 [B<-passout> I<arg>]
 [B<-traditional>]
-[B<-I<cipher>>]
-[B<-text>]
-[B<-text_pub>]
-[B<-noout>]
-[B<-pubin>]
 [B<-pubout>]
-[B<-check>]
-[B<-pubcheck>]
+[B<-noout>]
+[B<-text_pub>]
+[B<-text>]
 [B<-ec_conv_form> I<arg>]
 [B<-ec_param_enc> I<arg>]
-{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
 
 =for openssl ifdef engine
 
 =head1 DESCRIPTION
 
 This command processes public or private keys. They can be
-converted between various forms and their components printed out.
+converted between various forms and their components printed.
 
 =head1 OPTIONS
 
+=head2 General options
+
 =over 4
 
 =item B<-help>
 
 Print out a usage message.
 
+{- $OpenSSL::safe::opt_engine_item -}
+
+{- $OpenSSL::safe::opt_provider_item -}
+
+=item B<-check>
+
+This option checks the consistency of a key pair for both public and private
+components.
+
+=item B<-pubcheck>
+
+This option checks the correctness of either a public key
+or the public component of a key pair.
+
+=back
+
+=head2 Input options
+
+=over 4
+
+=item B<-in> I<filename>|I<uri>
+
+This specifies the input to read a key from
+or standard input if this option is not specified.
+If the key is encrypted and B<-passin> is not given
+a pass phrase will be prompted for.
+
 =item B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
 The key input format; the default is B<PEM>.
 The only value with effect is B<ENGINE>; all others have become obsolete.
 See L<openssl-format-options(1)> for details.
 
-=item B<-outform> B<DER>|B<PEM>
+=item B<-passin> I<arg>
 
-The key output formats; the default is B<PEM>.
-See L<openssl-format-options(1)> for details.
+The password source for the key input.
 
-=item B<-in> I<filename>|I<uri>
+For more information about the format of B<arg>
+see L<openssl-passphrase-options(1)>.
 
-This specifies the input to read a key from or standard input if this
-option is not specified. If the key is encrypted a pass phrase will be
-prompted for.
+=item B<-pubin>
 
-=item B<-passin> I<arg>, B<-passout> I<arg>
+By default a private key is read from the input file: with this
+option a public key is read instead.
 
-The password source for the input and output file.
-The -passout option is not supported for DER output.
+=back
 
-For more information about the format of B<arg>
-see L<openssl-passphrase-options(1)>.
+=head2 Output options
+
+=over 4
 
 =item B<-out> I<filename>
 
-This specifies the output filename to write a key to or standard output if this
-option is not specified. If any encryption options are set then a pass phrase
-will be prompted for. The output filename should B<not> be the same as the input
-filename.
+This specifies the output filename to write a key to
+or standard output if this option is not specified.
+If any encryption option is set but no B<-passout> is given
+then a pass phrase will be prompted for.
+The output filename should B<not> be the same as the input filename.
 
-=item B<-traditional>
+=item B<-outform> B<DER>|B<PEM>
 
-Normally a private key is written using standard format: this is PKCS#8 form
-with the appropriate encryption algorithm (if any). If the B<-traditional>
-option is specified then the older "traditional" format is used instead.
+The key output format; the default is B<PEM>.
+See L<openssl-format-options(1)> for details.
 
 =item B<-I<cipher>>
 
 These options encrypt the private key with the supplied cipher. Any algorithm
-name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
+name accepted by EVP_get_cipherbyname() is acceptable such as B<aes128>.
 
-=item B<-text>
-
-Prints out the various public or private key components in
-plain text in addition to the encoded version.
+=item B<-passout> I<arg>
 
-=item B<-text_pub>
+The password source for the output file.
+The -passout option is not supported for DER output.
 
-Print out only public key components even if a private key is being processed.
+For more information about the format of B<arg>
+see L<openssl-passphrase-options(1)>.
 
-=item B<-noout>
+=item B<-traditional>
 
-Do not output the encoded version of the key.
+Normally a private key is written using standard format: this is PKCS#8 form
+with the appropriate encryption algorithm (if any). If the B<-traditional>
+option is specified then the older "traditional" format is used instead.
 
-=item B<-pubin>
+=item B<-pubout>
 
-By default a private key is read from the input file: with this
-option a public key is read instead.
+By default the encoded private key is output:
+with this option the encoded public key will be output instead.
+This option is automatically set if the input is a public key.
 
-=item B<-pubout>
+=item B<-noout>
 
-By default a private key is output: with this option a public
-key will be output instead. This option is automatically set if
-the input is a public key.
+Do not output the encoded version of the key.
 
-=item B<-check>
+=item B<-text>
 
-This option checks the consistency of a key pair for both public and private
-components.
+Output the various public or private key components in
+plain text (possibly in addition to the encoded version).
 
-=item B<-pubcheck>
+=item B<-text_pub>
 
-This option checks the correctness of either a public key or the public component
-of a key pair.
+Output in text form the public key components (also for private keys).
 
 =item B<-ec_conv_form> I<arg>
 
-This option only applies to elliptic curve based public and private keys.
+This option only applies to elliptic-curve based keys.
 
 This specifies how the points on the elliptic curve are converted
 into octet strings. Possible values are: B<compressed> (the default
@@ -148,10 +175,6 @@ EC parameters structures). The default value is B<named_curve>.
 B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
 is currently not implemented in OpenSSL.
 
-{- $OpenSSL::safe::opt_engine_item -}
-
-{- $OpenSSL::safe::opt_provider_item -}
-
 =back
 
 =head1 EXAMPLES