find-doc-nits: Check that man1 SYNOPSIS and OPTIONS contain same options

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15299)

diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 3b47ae97298006f7c998cb451666e92ab766fcf2..78b98ab7a6b0ebd8eb62850e757474426deb46d6 100644 (file)
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -13,13 +13,13 @@ I<command>
 
 B<openssl>
 B<list>
-B<standard-commands> |
-B<digest-commands> |
-B<cipher-commands> |
-B<cipher-algorithms> |
-B<digest-algorithms> |
-B<mac-algorithms> |
-B<public-key-algorithms>
+B<-standard-commands> |
+B<-digest-commands> |
+B<-cipher-commands> |
+B<-cipher-algorithms> |
+B<-digest-algorithms> |
+B<-mac-algorithms> |
+B<-public-key-algorithms>
 
 B<openssl> B<no->I<XXX> [ I<options> ]
 

diff --git a/util/find-doc-nits b/util/find-doc-nits
index 8a2776486d44263d460da84f2040688b3fb8495f..7d68f70c0294d111006f4be71fdc4cf18351b5e2 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -549,8 +549,10 @@ sub option_check {
         err($id, "Malformed option [1] in SYNOPSIS: $&");
     }
 
+    my @synopsis;
     while ( $synopsis =~ /$markup_re/msg ) {
         my $found = $&;
+        push @synopsis, $found if $found =~ /^B<-/;
         print STDERR "$id:DEBUG[option_check] SYNOPSIS: found $found\n"
             if $debug;
         my $option_uw = normalise_option($id, $filename, $found);
@@ -560,6 +562,7 @@ sub option_check {
 
     # In OPTIONS, we look for =item paragraphs.
     # (?=^\s*$) detects an empty line.
+    my @options;
     while ( $options =~ /=item\s+(.*?)(?=^\s*$)/msg ) {
         my $item = $&;
 
@@ -573,8 +576,19 @@ sub option_check {
             my $option_uw = normalise_option($id, $filename, $found);
             err($id, "Malformed option in OPTIONS: $found")
                 if defined $option_uw && $option_uw eq '';
+            if ($found =~ /^B<-/) {
+                push @options, $found;
+                err($id, "OPTIONS entry $found missing from SYNOPSIS")
+                    unless (grep /^\Q$found\E$/, @synopsis)
+                         || $id =~ /(openssl|-options)\.pod:1:$/;
+            }
         }
     }
+    foreach (@synopsis) {
+        my $option = $_;
+        err($id, "SYNOPSIS entry $option missing from OPTIONS")
+            unless (grep /^\Q$option\E$/, @options);
+    }
 }
 
 # Normal symbol form