From 4b5371913ed9bb4bfd8a55a30458932799296ab9 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Tue, 18 Feb 2020 11:52:12 -0500 Subject: [PATCH] DOCS: Use "command" not "tool" or "utility" Reviewed-by: Paul Yang Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/11123) --- doc/man1/openssl-asn1parse.pod.in | 2 +- doc/man1/openssl-ca.pod.in | 9 +++++---- doc/man1/openssl-ciphers.pod.in | 4 ++-- doc/man1/openssl-cms.pod.in | 2 +- doc/man1/openssl-crl.pod.in | 2 +- doc/man1/openssl-ocsp.pod.in | 2 +- doc/man1/openssl-pkcs12.pod.in | 2 +- doc/man1/openssl-pkcs7.pod.in | 2 +- doc/man1/openssl-pkcs8.pod.in | 2 +- doc/man1/openssl-pkey.pod.in | 2 +- doc/man1/openssl-pkeyparam.pod.in | 2 +- doc/man1/openssl-pkeyutl.pod.in | 2 +- doc/man1/openssl-req.pod.in | 2 +- doc/man1/openssl-rsa.pod.in | 2 +- doc/man1/openssl-rsautl.pod.in | 4 ++-- doc/man1/openssl-sess_id.pod.in | 2 +- doc/man1/openssl-smime.pod.in | 2 +- doc/man1/openssl-spkac.pod.in | 2 +- doc/man1/openssl-storeutl.pod.in | 2 +- doc/man1/openssl-ts.pod.in | 2 +- doc/man1/openssl-verify.pod.in | 2 +- doc/man1/openssl-x509.pod.in | 4 ++-- doc/man1/openssl.pod | 20 ++++++++++---------- util/find-doc-nits | 7 +++++++ 24 files changed, 46 insertions(+), 38 deletions(-) diff --git a/doc/man1/openssl-asn1parse.pod.in b/doc/man1/openssl-asn1parse.pod.in index 9b95966440..e1c7f261a5 100644 --- a/doc/man1/openssl-asn1parse.pod.in +++ b/doc/man1/openssl-asn1parse.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-asn1parse - ASN.1 parsing tool +openssl-asn1parse - ASN.1 parsing command =head1 SYNOPSIS diff --git a/doc/man1/openssl-ca.pod.in b/doc/man1/openssl-ca.pod.in index a3c83d8076..5192b25fa5 100644 --- a/doc/man1/openssl-ca.pod.in +++ b/doc/man1/openssl-ca.pod.in @@ -155,8 +155,9 @@ Names and values of these options are algorithm-specific. =for openssl foreign manual ps(1) The password used to encrypt the private key. Since on some -systems the command line arguments are visible (e.g. Unix with -the L utility) this option should be used with caution. +systems the command line arguments are visible (e.g., when using +L on Unix), +this option should be used with caution. =item B<-selfsign> @@ -712,8 +713,8 @@ numbers of certificates are present because, as the name implies the database has to be kept in memory. This command really needs rewriting or the required functionality -exposed at either a command or interface level so a more friendly utility -(perl script or GUI) can handle things properly. The script +exposed at either a command or interface level so that a more user-friendly +replacement could handle things properly. The script B helps a little but not very much. Any fields in a request that are not present in a policy are silently diff --git a/doc/man1/openssl-ciphers.pod.in b/doc/man1/openssl-ciphers.pod.in index 6e6b150d24..690c28705c 100644 --- a/doc/man1/openssl-ciphers.pod.in +++ b/doc/man1/openssl-ciphers.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-ciphers - SSL cipher display and cipher list tool +openssl-ciphers - SSL cipher display and cipher list command =head1 SYNOPSIS @@ -31,7 +31,7 @@ B B =head1 DESCRIPTION This command converts textual OpenSSL cipher lists into -ordered SSL cipher preference lists. It can be used as a test tool to +ordered SSL cipher preference lists. It can be used to determine the appropriate cipherlist. =head1 OPTIONS diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in index 944135bbed..5cf8172f2c 100644 --- a/doc/man1/openssl-cms.pod.in +++ b/doc/man1/openssl-cms.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-cms - CMS utility +openssl-cms - CMS command =head1 SYNOPSIS diff --git a/doc/man1/openssl-crl.pod.in b/doc/man1/openssl-crl.pod.in index c1bd31a4a2..fd50602bc7 100644 --- a/doc/man1/openssl-crl.pod.in +++ b/doc/man1/openssl-crl.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-crl - CRL utility +openssl-crl - CRL command =head1 SYNOPSIS diff --git a/doc/man1/openssl-ocsp.pod.in b/doc/man1/openssl-ocsp.pod.in index efa627b8a9..2edbfc8887 100644 --- a/doc/man1/openssl-ocsp.pod.in +++ b/doc/man1/openssl-ocsp.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-ocsp - Online Certificate Status Protocol utility +openssl-ocsp - Online Certificate Status Protocol command =head1 SYNOPSIS diff --git a/doc/man1/openssl-pkcs12.pod.in b/doc/man1/openssl-pkcs12.pod.in index 631eec7282..655f718001 100644 --- a/doc/man1/openssl-pkcs12.pod.in +++ b/doc/man1/openssl-pkcs12.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-pkcs12 - PKCS#12 file utility +openssl-pkcs12 - PKCS#12 file command =head1 SYNOPSIS diff --git a/doc/man1/openssl-pkcs7.pod.in b/doc/man1/openssl-pkcs7.pod.in index 0a12d2379a..d31ae2a0a7 100644 --- a/doc/man1/openssl-pkcs7.pod.in +++ b/doc/man1/openssl-pkcs7.pod.in @@ -7,7 +7,7 @@ =head1 NAME -openssl-pkcs7 - PKCS#7 utility +openssl-pkcs7 - PKCS#7 command =head1 SYNOPSIS diff --git a/doc/man1/openssl-pkcs8.pod.in b/doc/man1/openssl-pkcs8.pod.in index f9e5fb1dcb..38b50a6d14 100644 --- a/doc/man1/openssl-pkcs8.pod.in +++ b/doc/man1/openssl-pkcs8.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-pkcs8 - PKCS#8 format private key conversion tool +openssl-pkcs8 - PKCS#8 format private key conversion command =head1 SYNOPSIS diff --git a/doc/man1/openssl-pkey.pod.in b/doc/man1/openssl-pkey.pod.in index 8460aed1fa..2785f29857 100644 --- a/doc/man1/openssl-pkey.pod.in +++ b/doc/man1/openssl-pkey.pod.in @@ -7,7 +7,7 @@ =head1 NAME -openssl-pkey - public or private key processing tool +openssl-pkey - public or private key processing command =head1 SYNOPSIS diff --git a/doc/man1/openssl-pkeyparam.pod.in b/doc/man1/openssl-pkeyparam.pod.in index 7f9d351ac2..d5ea4012b4 100644 --- a/doc/man1/openssl-pkeyparam.pod.in +++ b/doc/man1/openssl-pkeyparam.pod.in @@ -7,7 +7,7 @@ =head1 NAME -openssl-pkeyparam - public key algorithm parameter processing tool +openssl-pkeyparam - public key algorithm parameter processing command =head1 SYNOPSIS diff --git a/doc/man1/openssl-pkeyutl.pod.in b/doc/man1/openssl-pkeyutl.pod.in index 0bca483871..583ea68734 100644 --- a/doc/man1/openssl-pkeyutl.pod.in +++ b/doc/man1/openssl-pkeyutl.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-pkeyutl - public key algorithm utility +openssl-pkeyutl - public key algorithm command =head1 SYNOPSIS diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in index 7587cb5a71..ca3416e799 100644 --- a/doc/man1/openssl-req.pod.in +++ b/doc/man1/openssl-req.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-req - PKCS#10 certificate request and certificate generating utility +openssl-req - PKCS#10 certificate request and certificate generating command =head1 SYNOPSIS diff --git a/doc/man1/openssl-rsa.pod.in b/doc/man1/openssl-rsa.pod.in index e2c0b24a1a..fa1a20ea45 100644 --- a/doc/man1/openssl-rsa.pod.in +++ b/doc/man1/openssl-rsa.pod.in @@ -7,7 +7,7 @@ =head1 NAME -openssl-rsa - RSA key processing tool +openssl-rsa - RSA key processing command =head1 SYNOPSIS diff --git a/doc/man1/openssl-rsautl.pod.in b/doc/man1/openssl-rsautl.pod.in index d28e672817..0bb0a136d3 100644 --- a/doc/man1/openssl-rsautl.pod.in +++ b/doc/man1/openssl-rsautl.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-rsautl - RSA utility +openssl-rsautl - RSA command =head1 SYNOPSIS @@ -167,7 +167,7 @@ encrypt and decrypt the block would have been of type 2 (the second byte) and random padding data visible instead of the 0xff bytes. It is possible to analyse the signature of certificates using this -utility in conjunction with L. Consider the self signed +command in conjunction with L. Consider the self signed example in F. Running L as follows yields: diff --git a/doc/man1/openssl-sess_id.pod.in b/doc/man1/openssl-sess_id.pod.in index f68f180739..e18ef6f9c2 100644 --- a/doc/man1/openssl-sess_id.pod.in +++ b/doc/man1/openssl-sess_id.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-sess_id - SSL/TLS session handling utility +openssl-sess_id - SSL/TLS session handling command =head1 SYNOPSIS diff --git a/doc/man1/openssl-smime.pod.in b/doc/man1/openssl-smime.pod.in index c6775505a9..69bf918743 100644 --- a/doc/man1/openssl-smime.pod.in +++ b/doc/man1/openssl-smime.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-smime - S/MIME utility +openssl-smime - S/MIME command =head1 SYNOPSIS diff --git a/doc/man1/openssl-spkac.pod.in b/doc/man1/openssl-spkac.pod.in index 4ea15fa57a..77e4d7ce08 100644 --- a/doc/man1/openssl-spkac.pod.in +++ b/doc/man1/openssl-spkac.pod.in @@ -7,7 +7,7 @@ =head1 NAME -openssl-spkac - SPKAC printing and generating utility +openssl-spkac - SPKAC printing and generating command =head1 SYNOPSIS diff --git a/doc/man1/openssl-storeutl.pod.in b/doc/man1/openssl-storeutl.pod.in index 75c30651fc..3de2059e0c 100644 --- a/doc/man1/openssl-storeutl.pod.in +++ b/doc/man1/openssl-storeutl.pod.in @@ -7,7 +7,7 @@ =head1 NAME -openssl-storeutl - STORE utility +openssl-storeutl - STORE command =head1 SYNOPSIS diff --git a/doc/man1/openssl-ts.pod.in b/doc/man1/openssl-ts.pod.in index 8d5e66e6d6..38fcf530fe 100644 --- a/doc/man1/openssl-ts.pod.in +++ b/doc/man1/openssl-ts.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-ts - Time Stamping Authority tool (client/server) +openssl-ts - Time Stamping Authority command =head1 SYNOPSIS diff --git a/doc/man1/openssl-verify.pod.in b/doc/man1/openssl-verify.pod.in index fd41bbeb37..7a15e73721 100644 --- a/doc/man1/openssl-verify.pod.in +++ b/doc/man1/openssl-verify.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-verify - Utility to verify certificates +openssl-verify - certificate verification command =head1 SYNOPSIS diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in index 8cf03d937e..98b4e71231 100644 --- a/doc/man1/openssl-x509.pod.in +++ b/doc/man1/openssl-x509.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-x509 - Certificate display and signing utility +openssl-x509 - Certificate display and signing command =head1 SYNOPSIS @@ -81,7 +81,7 @@ B B =head1 DESCRIPTION -This command is a multi purpose certificate utility. It can +This command is a multi-purposes certificate command. It can be used to display certificate information, convert certificates to various forms, sign certificate requests like a "mini CA" or edit certificate trust settings. diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index ff66846337..c05fc29f67 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -2,7 +2,7 @@ =head1 NAME -openssl - OpenSSL command line tool +openssl - OpenSSL command line program =head1 SYNOPSIS @@ -29,7 +29,7 @@ OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) network protocols and related cryptography standards required by them. -The B program is a command line tool for using the various +The B program is a command line program for using the various cryptography functions of OpenSSL's B library from the shell. It can be used for @@ -104,7 +104,7 @@ Cipher Suite Description Determination. =item B -CMS (Cryptographic Message Syntax) utility. +CMS (Cryptographic Message Syntax) command. =item B @@ -196,7 +196,7 @@ Create or examine a Netscape certificate sequence. =item B -Online Certificate Status Protocol utility. +Online Certificate Status Protocol command. =item B @@ -212,7 +212,7 @@ PKCS#7 Data Management. =item B -PKCS#8 format private key conversion tool. +PKCS#8 format private key conversion command. =item B @@ -224,7 +224,7 @@ Public key algorithm parameter management. =item B -Public key algorithm cryptographic operation utility. +Public key algorithm cryptographic operation command. =item B @@ -252,7 +252,7 @@ RSA key management. =item B -RSA utility for signing, verification, encryption, and decryption. Superseded +RSA command for signing, verification, encryption, and decryption. Superseded by L. =item B @@ -289,7 +289,7 @@ Algorithm Speed Measurement. =item B -SPKAC printing and generating utility. +SPKAC printing and generating command. =item B @@ -297,11 +297,11 @@ Maintain SRP password file. =item B -Utility to list and display certificates, keys, CRLs, etc. +Command to list and display certificates, keys, CRLs, etc. =item B -Time Stamping Authority tool (client/server). +Time Stamping Authority command. =item B diff --git a/util/find-doc-nits b/util/find-doc-nits index f02edabcef..c508e242fe 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -601,6 +601,13 @@ sub wording { } err($id, "found 'epoch' should use 'Epoch'") if $contents =~ /\bepoch\b/; + if ( $id =~ m@man1/@ ) { + err($id, "found 'tool' in NAME, should use 'command'") + if $contents =~ /=head1 NAME.*\btool\b.*=head1 SYNOPSIS/s; + err($id, "found 'utility' in NAME, should use 'command'") + if $contents =~ /NAME.*\butility\b.*=head1 SYNOPSIS/s; + + } } # Perform all sorts of nit/error checks on a manpage -- 2.34.1