cmdline/docs: add a required 'multi' keyword for each option

The keyword specifies how option works when specified multiple times:

 - single: the last provided value replaces the earlier ones
 - append: it supports being provided multiple times
 - boolean: on/off values
 - mutex: flag-like option that disable anoter flag

The 'gen.pl' script then outputs the proper and unified language for
each option's multi-use behavior in the generated man page.

The multi: header is requires in each .d file and will cause build error
if missing or set to an unknown value.

Closes #9759

1 files changed, 38 insertions, 0 deletions

diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl
index 01f9cf61a..fe3e43e06 100755
--- a/docs/cmdline-opts/gen.pl
+++ b/docs/cmdline-opts/gen.pl
@@ -204,6 +204,8 @@ sub single {
     my @examples; # there can be more than one
     my $magic; # cmdline special option
     my $line;
+    my $multi;
+    my $experimental;
     while(<F>) {
         $line++;
         if(/^Short: *(.)/i) {
@@ -242,6 +244,12 @@ sub single {
         elsif(/^Example: *(.*)/i) {
             push @examples, $1;
         }
+        elsif(/^Multi: *(.*)/i) {
+            $multi=$1;
+        }
+        elsif(/^Experimental: yes/i) {
+            $experimental=1;
+        }
         elsif(/^C: (.*)/i) {
             $copyright=$1;
         }
@@ -256,6 +264,10 @@ sub single {
                 print STDERR "ERROR: no 'Long:' in $f\n";
                 return 1;
             }
+            if($multi !~ /(single|append|boolean|mutex)/) {
+                print STDERR "ERROR: bad 'Multi:' in $f\n";
+                return 1;
+            }
             if(!$category) {
                 print STDERR "ERROR: no 'Category:' in $f\n";
                 return 2;
@@ -326,9 +338,35 @@ sub single {
         print ".SH DESCRIPTION\n";
     }
 
+    if($experimental) {
+        print "**WARNING**: this option is experimental. Do not use in production.\n\n";
+    }
+
     printdesc(@desc);
     undef @desc;
 
+    if($multi eq "single") {
+        print "\nIf --$long is provided several times, the last set ".
+            "value will be used.\n";
+    }
+    elsif($multi eq "append") {
+        print "\n--$long can be used several times in a command line\n";
+    }
+    elsif($multi eq "boolean") {
+        my $rev = "no-$long";
+        # for options that start with "no-" the reverse is then without
+        # the no- prefix
+        if($long =~ /^no-/) {
+            $rev = $long;
+            $rev =~ s/^no-//;
+        }
+        print "\nProviding --$long multiple times has no extra effect.\n".
+            "Disable it again with --$rev.\n";
+    }
+    elsif($multi eq "mutex") {
+        print "\nProviding --$long multiple times has no extra effect.\n";
+    }
+
     my @foot;
     if($seealso) {
         my @m=split(/ /, $seealso);