argmatch: adjust columns for help2man

argmatch: adjust columns for help2man

[Akim Demaille]

Bison's man page included the following incorrect snippet (first four lines are not properly indented as a definition list):

>    FEATURES is a list of comma separated words that can include:
>               caret, diagnostics-show-caret
> 
>               show errors with carets
> 
>               fixit, diagnostics-parseable-fixits
> 
>               show machine-readable fixes
> 
>        syntax-only
>               do not generate any file
> 
>        all    all of the above
> 
>        none   disable all of the above

because --help looked like this:

> FEATURES is a list of comma separated words that can include:
>   caret, diagnostics-show-caret
>                show errors with carets
>   fixit, diagnostics-parseable-fixits
>                show machine-readable fixes
>   syntax-only  do not generate any file
>   all          all of the above
>   none         disable all of the above

But that format is not recognized by help2man.  Its author,
Brendan O'Dea, wrote to me:

> The heuristic help2man uses when mapping input to a tagged paragraph
> is fairly simple: it will match a term and a definition when:
> 
>  a) the term is indented by at least one character  AND
>  b) the definition either:
>     i) appears on the same line, separated by two or more spaces  OR
>     ii) is on the next line, indented by twenty or more spaces
> 
> Your first example is meeting (a) and (b i), your second fails (b ii).
> The requirement for twenty spaces is a bit arbitrary, but mostly seems
> to work OK, and has less false-positives than smaller indents which
> were experimented with (looooong ago).

The appended changes (pushed) generate this in bison --help:

> FEATURES is a list of comma separated words that can include:
>   caret, diagnostics-show-caret
>                     show errors with carets
>   fixit, diagnostics-parseable-fixits
>                     show machine-readable fixes
>   syntax-only       do not generate any file
>   all               all of the above
>   none              disable all of the above


which gives this in the man page.

>    FEATURES is a list of comma separated words that can include:
>        caret, diagnostics-show-caret
>               show errors with carets
> 
>        fixit, diagnostics-parseable-fixits
>               show machine-readable fixes
> 
>        syntax-only
>               do not generate any file
> 
>        all    all of the above
> 
>        none   disable all of the above

Cheers!


commit ee77e5c1fef322b8c0a6596aa9b2c43323eff4d1
Author: Akim Demaille <akim.demaille@gmail.com>
Date:   Sun Jul 7 12:12:25 2019 +0200

    argmatch: adjust columns for help2man.
    
    * lib/argmatch.h (argmatch_##Name##_doc_col): If some argument
    requires column 20 or more, return 20.

diff --git a/ChangeLog b/ChangeLog
index f7e031d9b..01696987f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2019-07-07  Akim Demaille  <akim@lrde.epita.fr>
+
+	argmatch: adjust columns for help2man.
+	* lib/argmatch.h (argmatch_##Name##_doc_col): If some argument
+	requires column 20 or more, return 20.
+
 2019-07-06  Paul Eggert  <eggert@cs.ucla.edu>
 
 	areadlink-with-size: avoid realloc when size==0
diff --git a/lib/argmatch.h b/lib/argmatch.h
index 57d131f32..897fa415d 100644
--- a/lib/argmatch.h
+++ b/lib/argmatch.h
@@ -264,9 +264,8 @@ char const *argmatch_to_argument (void const *value,
           for (int j = 0; g->args[j].arg; ++j)                          \
             if (! memcmp (&g->args[ival].val, &g->args[j].val, size))   \
               col += (col == 4 ? 0 : 2) + strlen (g->args[j].arg);      \
-        /* Ignore series that are too wide. */                          \
-        if (col <= 20 && res <= col)                                    \
-          res = col;                                                    \
+        if (res <= col)                                                 \
+          res = col <= 20 ? col : 20;                                   \
       }                                                                 \
     return res ? res : 20;                                              \
   }                                                                     \