manywarnings: Overhaul documentation

[Bruno Haible]

When using the 'manywarnings' module for the first time, I looked at an
example use, such as this one from grep/configure.ac:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # This, $nw, is the list of warnings we disable.
  nw="$nw -Wvla"                    # suppress a warning in regexec.h
  nw="$nw -Winline"                 # suppress warnings from streq.h's streq5
  nw="$nw -Wsystem-headers"         # Don't let system headers trigger warnings
  nw="$nw -Wstack-protector"        # generates false alarms for useful code

  gl_MANYWARN_ALL_GCC([ws])
  gl_MANYWARN_COMPLEMENT([ws], [$ws], [$nw])
  for w in $ws; do
    gl_WARN_ADD([$w])
  done
  gl_WARN_ADD([-Wno-missing-field-initializers]) # We need this one
  gl_WARN_ADD([-Wno-sign-compare])     # Too many warnings for now
  gl_WARN_ADD([-Wno-unused-parameter]) # Too many warnings for now
  gl_WARN_ADD([-Wno-cast-function-type]) # sig-handler.h's sa_handler_t cast
  gl_WARN_ADD([-Wno-deprecated-declarations]) # clang complains about sprintf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

and had a hard time understanding why some unwanted warning options are added
positively to 'nw', while some others are
  - negated (-Wno-...),
  - added via gl_WARN_ADD rather than a shell variable,
  - handled at the end, unlike the others, which are listed at the beginning.

The distinction comes from the list of warning options that are embedded in
m4/manywarnings.m4. But
  1) This distinction is not documented.
  2) It is cumbersome for a package maintainer to look up, for each warning type
     he wants to silence, whether this warning option is listed in
     m4/manywarnings.m4 or not.

The distinction can be automated by a single additional gl_MANYWARN_COMPLEMENT
invocation.

I'm therefore updating the sample of 'manywarnings' in the documentation to
be easier to understand and maintain. Also, let me add some other
recommendations, based on recent discussions and my recent experience.

Note: I'm for the first time using a TeXinfo style where newlines are present
after every sentence's full stop. It's being said that this is a reasonable
compromise between having small doc diffs in the future and readability at
the .texi level. See
<https://lists.gnu.org/archive/html/help-texinfo/2023-05/msg00011.html>


2023-06-04  Bruno Haible  <bruno@clisp.org>

        manywarnings: Overhaul documentation.
        * doc/manywarnings.texi: In the example, put all unwanted warning
        options into 'nw', and use a second gl_MANYWARN_COMPLEMENT invocation to
        sort out how these options need to get added to WARN_FLAGS.
        Describe the first-time use in more detail: Recommend a new GCC.
        Recommend to test builds with -O2 and with -O0. Suggest to sort the
        warning by warning option. Add reference to the GCC pragma's
        documentation.

diff --git a/doc/manywarnings.texi b/doc/manywarnings.texi
index 01e23116cc..19b58f8e47 100644
--- a/doc/manywarnings.texi
+++ b/doc/manywarnings.texi
@@ -12,48 +12,112 @@
      'expensive' in addition generates expensive warnings.])])
 
 AS_IF([test "$enable_gcc_warnings" != no],
-  [gl_MANYWARN_ALL_GCC([warnings])
-
+  [
    # Set up the list of unwanted warning options.
    nw=
    if test "$enable_gcc_warnings" != expensive; then
      nw="$nw -fanalyzer"
    fi
-   nw="$nw -Winline"           # It's OK to not inline.
-   nw="$nw -Wstrict-overflow"  # It's OK to optimize strictly.
-   nw="$nw -Wsystem-headers"   # Don't warn in system headers.
-
-   # Enable all GCC warnings not in this list.
-   gl_MANYWARN_COMPLEMENT([warnings], [$warnings], [$nw])
-   for w in $warnings; do
+   nw="$nw -Wbad-function-cast" # Casting a function's result is not more
+                                # dangerous than casting any other value.
+   nw="$nw -Winline"            # It's OK to not inline.
+   nw="$nw -Wsign-compare"      # Too many false alarms.
+   nw="$nw -Wstrict-overflow"   # It's OK to optimize strictly.
+   nw="$nw -Wsystem-headers"    # Don't warn in system headers.
+
+   # Setup the list of meaningful warning options for the C compiler.
+   # The list comes from manywarnings.m4. Warning options that are not
+   # generally meaningful have already been filtered out (cf.
+   # build-aux/gcc-warning.spec).
+   gl_MANYWARN_ALL_GCC([possible_warning_options])
+
+   # Compute the list of warning options that are desired.
+   gl_MANYWARN_COMPLEMENT([desired_warning_options],
+                          [$possible_warning_options], [$nw])
+   # Compute the list of remaining undesired warning options.
+   # Namely those, that were not in manywarnings.m4 because they were
+   # already listed in build-aux/gcc-warning.spec; this includes those
+   # that are implied by -Wall.
+   gl_MANYWARN_COMPLEMENT([remaining_undesired_warning_options],
+                          [$nw], [$possible_warning_options])
+
+   # Add the desired warning options to WARN_CFLAGS.
+   for w in $desired_warning_options; do
      gl_WARN_ADD([$w])
    done
 
-   # Disable unwanted warnings enabled by default, -Wall, -Wextra.
-   gl_WARN_ADD([-Wno-sign-compare]) # Too many false alarms.
+   # Add the opposites of the remaining undesired warning options to
+   # WARN_CFLAGS.
+   for w in `echo "$remaining_undesired_warning_options" | sed -e 
's/-W/-Wno-/g'`; do
+     gl_WARN_ADD([$w])
+   done
 ])
 @end smallexample
 
 This module sets up many GCC warning options.
-When you start to use it, you can set the
-list of undesired warnings (@samp{nw} in the example above) to empty, and
-compile the package with all possible warnings enabled.  Then you will
-go through the list of warnings. You will likely deactivate warnings that
-occur often and don't point to mistakes in the code, by adding them to the
-@samp{nw} variable, then reconfiguring and recompiling. When warnings point
-to real mistakes and bugs in the code, you will of course not disable
-them but fix your code to silence the warning instead.
-
-Many GCC warning options usually don't point to mistakes
-in the code; these warnings enforce a certain programming style. It is a
-project management decision whether you want your code to follow any of these
-styles. Note that some of these programming styles are conflicting. You
-cannot have them all; you have to choose among them.
-
-When a new version of GCC is released, you can add the warning options
-that it introduces into the @code{gl_MANYWARN_ALL_GCC} macro (and submit your
-modification to the Gnulib maintainers), and enjoy the benefits of the
-new warnings, while adding the undesired ones to the @samp{nw} variable.
+
+When you use it for the first time, it is common practice to do it as
+follows:
+
+@itemize @bullet
+@item
+Start with the newest major release of GCC.
+This will save you time, because some warning options produce many false
+alarms with older versions of GCC (such as @code{-Wstrict-overflow} or
+@code{-Wunsafe-loop-optimizations}).
+@item
+Compile the package with an empty @code{nw} value, that is, with all
+possible warnings enabled.
+Do this once with optimizations (@code{CPPFLAGS=-O2}) and once with no
+optimizations (@code{CPPFLAGS=-O0} or @code{CPPFLAGS=-ggdb}).
+The exercise with optimizations will catch more bugs, because the
+compiler does a better static analysis of the program when optimizing.
+Also, some warning options that diagnose suboptimal code generation,
+such as @code{-Winline}, are not effective when not optimizing.
+On the other hand, it's frequent to build the package without
+optimizations, for debugging purposes, and you don't want to see
+undesired warnings in these phases of development either.
+@item
+Then you will go through the list of warnings.
+Since there are likely many warnings, the first time, it's a good idea
+to sort them by warning option first:
+@smallexample
+$ grep warning: make-output.log \
+  | sed -e 's/^\(.*\) \[\(-W.*\)\]$/\2  \1/' | sort -k1
+@end smallexample
+@item
+You will likely deactivate warnings that occur often and don't point to
+mistakes in the code, by adding them to the @samp{nw} variable, then
+reconfiguring and recompiling.
+When warnings point to real mistakes and bugs in the code, you will of
+course not disable them but fix your code to silence the warning
+instead.
+
+Many GCC warning options usually don't point to mistakes in the code;
+these warnings enforce a certain programming style.
+It is a project management decision whether you want your code to follow
+any of these styles.
+Note that some of these programming styles are conflicting.
+You cannot have them all; you have to choose among them.
+
+When a warning option pinpoints real bugs occasionally, but it also
+whines about a few code locations which are fine, we recommend to leave
+the warning option enabled.
+Whether you then live with the remaining few warnings, or choose to
+disable them one-by-one through
+@code{#pragma GCC diagnostic ignored "@var{option}"}
+(@pxref{Diagnostic Pragmas,,, gcc, Using the GNU Compiler Collection},
+@url{https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html}),
+is again a project management decision.
+@end itemize
+
+When a new major version of GCC is released, the Gnulib maintainers add
+the newly available warning options into the @code{gl_MANYWARN_ALL_GCC}
+macro.
+You will then enjoy the benefits of the new warnings, simply by updating
+to the newest Gnulib.
+If some of the new warnings are undesired, you can add them to the
+@samp{nw} variable, as described above.
 
 Comments on particular warning flags: