[SCM] gawk branch, gawk-5.1-stable, updated. gawk-4.1.0-4389-gf77ab7d2

[Arnold Robbins]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".

The branch, gawk-5.1-stable has been updated
       via  f77ab7d2f009da2b9e60f17633a8b71488f85ceb (commit)
      from  0d4519f6aa19e7529f1b203cf1584a872b4011aa (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=f77ab7d2f009da2b9e60f17633a8b71488f85ceb

commit f77ab7d2f009da2b9e60f17633a8b71488f85ceb
Author: Arnold D. Robbins <arnold@skeeve.com>
Date:   Mon Apr 18 16:17:52 2022 +0300

    Doc updates.

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 6e703394..c366183c 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2022-04-18         Arnold D. Robbins     <arnold@skeeve.com>
+
+       * gawktexi.in (Adding Code): Update coding style instructions.
+
 2022-03-01         Arnold D. Robbins     <arnold@skeeve.com>
 
        * gawktexi.in: Typo fix. Thanks to Antonio Columbo for pointing
diff --git a/doc/gawk.info b/doc/gawk.info
index 516053f6..7fe24cdd 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -32299,11 +32299,16 @@ you want your changes to be incorporated into the 
'gawk' distribution,
 there are several steps that you need to take in order to make it
 possible to include them:
 
-  1. Before building the new feature into 'gawk' itself, consider
+  1. Discuss the proposed new feature with the 'gawk' maintainer.  The
+     bug list may be used for this.  Even if I don't wish to include
+     your feature, be aware that you are still free to add it and
+     distribute your own "fork" of 'gawk'.
+
+  2. Before building the new feature into 'gawk' itself, consider
      writing it as an extension (*note Dynamic Extensions::).  If that's
      not possible, continue with the rest of the steps in this list.
 
-  2. Be prepared to sign the appropriate paperwork.  In order for the
+  3. Be prepared to sign the appropriate paperwork.  In order for the
      FSF to distribute your changes, you must either place those changes
      in the public domain and submit a signed statement to that effect,
      or assign the copyright in your changes to the FSF. Both of these
@@ -32311,21 +32316,21 @@ possible to include them:
      you have questions, please contact me (*note Bugs::), or
      <assign@gnu.org>.
 
-  3. Get the latest version.  It is much easier for me to integrate
+  4. Get the latest version.  It is much easier for me to integrate
      changes if they are relative to the most recent distributed version
      of 'gawk', or better yet, relative to the latest code in the Git
      repository.  If your version of 'gawk' is very old, I may not be
      able to integrate your changes at all.  (*Note Getting::, for
      information on getting the latest version of 'gawk'.)
 
-  4. *Note Version: (standards)Top.  This document describes how GNU
+  5. *Note Version: (standards)Top.  This document describes how GNU
      software should be written.  If you haven't read it, please do so,
      preferably _before_ starting to modify 'gawk'.  (The 'GNU Coding
      Standards' are available from the GNU Project's website
      (https://www.gnu.org/prep/standards/).  Texinfo, Info, and DVI
      versions are also available.)
 
-  5. Use the 'gawk' coding style.  The C code for 'gawk' follows the
+  6. Use the 'gawk' coding style.  The C code for 'gawk' follows the
      instructions in the 'GNU Coding Standards', with minor exceptions.
      The code is formatted using the traditional "K&R" style,
      particularly as regards to the placement of braces and the use of
@@ -32343,7 +32348,9 @@ possible to include them:
           function.
 
         * Put spaces around parentheses used in control structures
-          ('if', 'while', 'for', 'do', 'switch', and 'return').
+          ('if', 'while', 'for', 'do', and 'switch').
+
+        * Do not parenthesize the expression used with 'return'.
 
         * Do not put spaces in front of parentheses used in function
           calls.
@@ -32364,6 +32371,12 @@ possible to include them:
           of 'switch' statements, instead of just the plain pointer or
           character value.
 
+        * Do not, _under any circumstances_, use the '-1 == foo' or '0
+          >= bar' style of comparison expressions.  I have known about
+          it for decades, and I understand why some people like it.
+          Nonetheless, I abhor it with a passion, and code that uses it
+          will never be accepted.
+
         * Use 'true' and 'false' for 'bool' values, the 'NULL' symbolic
           constant for pointer values, and the character constant ''\0''
           where appropriate, instead of '1' and '0'.
@@ -32388,7 +32401,7 @@ possible to include them:
           style used in 'gawk', I may not bother to integrate your
           changes at all.
 
-  6. Update the documentation.  Along with your new code, please supply
+  7. Update the documentation.  Along with your new code, please supply
      new sections and/or chapters for this Info file.  If at all
      possible, please use real Texinfo, instead of just supplying
      unformatted ASCII text (although even that is better than no
@@ -32400,7 +32413,7 @@ possible to include them:
      You will also have to sign paperwork for your documentation
      changes.
 
-  7. Submit changes as unified diffs.  Use 'diff -u -r -N' to compare
+  8. Submit changes as unified diffs.  Use 'diff -u -r -N' to compare
      the original 'gawk' source tree with your version.  I recommend
      using the GNU version of 'diff', or best of all, 'git diff' or 'git
      format-patch'.  Send the output produced by 'diff' to me when you
@@ -32412,7 +32425,7 @@ possible to include them:
      have to apply the changes manually, using a text editor, I may not
      do so, particularly if there are lots of changes.
 
-  8. Include an entry for the 'ChangeLog' file with your submission.
+  9. Include an entry for the 'ChangeLog' file with your submission.
      This helps further minimize the amount of work I have to do, making
      it easier for me to accept patches.  It is simplest if you just
      make this part of your diff.
@@ -36970,7 +36983,7 @@ Index
                                                               (line   6)
 * gawk, implementation issues, debugging: Compatibility Mode. (line   6)
 * gawk, features, adding:                Adding Code.         (line   6)
-* gawk, coding style in:                 Adding Code.         (line  37)
+* gawk, coding style in:                 Adding Code.         (line  42)
 * gawkextlib project:                    gawkextlib.          (line   6)
 * gawklibpath_append shell function:     Shell Startup Files. (line  29)
 * gawklibpath_default shell function:    Shell Startup Files. (line  22)
@@ -37036,7 +37049,7 @@ Index
 * git utility <1>:                       Other Versions.      (line  18)
 * git utility <2>:                       Accessing The Source.
                                                               (line  10)
-* git utility <3>:                       Adding Code.         (line 112)
+* git utility <3>:                       Adding Code.         (line 125)
 * Git, use of for gawk source code:      Derived Files.       (line   6)
 * global variables, show in debugger:    Debugger Info.       (line  48)
 * GMP values, API ownership of:          API Ownership of MPFR and GMP Values.
@@ -38358,7 +38371,7 @@ Index
 * Texinfo <3>:                           Extract Program.     (line  12)
 * Texinfo <4>:                           Distribution contents.
                                                               (line  89)
-* Texinfo <5>:                           Adding Code.         (line 100)
+* Texinfo <5>:                           Adding Code.         (line 113)
 * text, printing:                        Print.               (line  22)
 * text, printing, unduplicated lines of: Uniq Program.        (line   6)
 * TEXTDOMAIN variable:                   User-modified.       (line 154)
@@ -39200,31 +39213,31 @@ Node: Compatibility Mode1296973
 Node: Additions1297755
 Node: Accessing The Source1298680
 Node: Adding Code1300117
-Node: New Ports1306309
-Node: Derived Files1310684
-Ref: Derived Files-Footnote-11316344
-Ref: Derived Files-Footnote-21316379
-Ref: Derived Files-Footnote-31316977
-Node: Future Extensions1317091
-Node: Implementation Limitations1317749
-Node: Extension Design1318959
-Node: Old Extension Problems1320103
-Ref: Old Extension Problems-Footnote-11321621
-Node: Extension New Mechanism Goals1321678
-Ref: Extension New Mechanism Goals-Footnote-11325042
-Node: Extension Other Design Decisions1325231
-Node: Extension Future Growth1327344
-Node: Notes summary1327950
-Node: Basic Concepts1329108
-Node: Basic High Level1329789
-Ref: figure-general-flow1330071
-Ref: figure-process-flow1330757
-Ref: Basic High Level-Footnote-11334059
-Node: Basic Data Typing1334244
-Node: Glossary1337572
-Node: Copying1369457
-Node: GNU Free Documentation License1407000
-Node: Index1432120
+Node: New Ports1306932
+Node: Derived Files1311307
+Ref: Derived Files-Footnote-11316967
+Ref: Derived Files-Footnote-21317002
+Ref: Derived Files-Footnote-31317600
+Node: Future Extensions1317714
+Node: Implementation Limitations1318372
+Node: Extension Design1319582
+Node: Old Extension Problems1320726
+Ref: Old Extension Problems-Footnote-11322244
+Node: Extension New Mechanism Goals1322301
+Ref: Extension New Mechanism Goals-Footnote-11325665
+Node: Extension Other Design Decisions1325854
+Node: Extension Future Growth1327967
+Node: Notes summary1328573
+Node: Basic Concepts1329731
+Node: Basic High Level1330412
+Ref: figure-general-flow1330694
+Ref: figure-process-flow1331380
+Ref: Basic High Level-Footnote-11334682
+Node: Basic Data Typing1334867
+Node: Glossary1338195
+Node: Copying1370080
+Node: GNU Free Documentation License1407623
+Node: Index1432743
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 6b9cbbe5..17d3d9f1 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -43836,6 +43836,12 @@ distribution, there are several steps that you need to 
take in order to
 make it possible to include them:
 
 @enumerate 1
+@item
+Discuss the proposed new feature with the @command{gawk} maintainer.
+The bug list may be used for this.  Even if I don't
+wish to include your feature, be aware that you are still free to
+add it and distribute your own ``fork'' of @command{gawk}.
+
 @item
 Before building the new feature into @command{gawk} itself,
 consider writing it as an extension
@@ -43900,8 +43906,10 @@ line above the line with the name and arguments of the 
function.
 
 @item
 Put spaces around parentheses used in control structures
-(@code{if}, @code{while}, @code{for}, @code{do}, @code{switch},
-and @code{return}).
+(@code{if}, @code{while}, @code{for}, @code{do}, and @code{switch}).
+
+@item
+Do not parenthesize the expression used with @code{return}.
 
 @item
 Do not put spaces in front of parentheses used in function calls.
@@ -43925,6 +43933,12 @@ Use comparisons against @code{NULL} and @code{'\0'} in 
the conditions of
 of @code{switch} statements, instead of just the
 plain pointer or character value.
 
+@item
+Do not, @emph{under any circumstances}, use the @samp{-1 == foo} or
+@samp{0 >= bar} style of comparison expressions.  I have known about
+it for decades, and I understand why some people like it.  Nonetheless,
+I abhor it with a passion, and code that uses it will never be accepted.
+
 @item
 Use @code{true} and @code{false} for @code{bool} values,
 the @code{NULL} symbolic constant for pointer values,
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 06d800a2..94263ea5 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -42679,6 +42679,12 @@ distribution, there are several steps that you need to 
take in order to
 make it possible to include them:
 
 @enumerate 1
+@item
+Discuss the proposed new feature with the @command{gawk} maintainer.
+The bug list may be used for this.  Even if I don't
+wish to include your feature, be aware that you are still free to
+add it and distribute your own ``fork'' of @command{gawk}.
+
 @item
 Before building the new feature into @command{gawk} itself,
 consider writing it as an extension
@@ -42743,8 +42749,10 @@ line above the line with the name and arguments of the 
function.
 
 @item
 Put spaces around parentheses used in control structures
-(@code{if}, @code{while}, @code{for}, @code{do}, @code{switch},
-and @code{return}).
+(@code{if}, @code{while}, @code{for}, @code{do}, and @code{switch}).
+
+@item
+Do not parenthesize the expression used with @code{return}.
 
 @item
 Do not put spaces in front of parentheses used in function calls.
@@ -42768,6 +42776,12 @@ Use comparisons against @code{NULL} and @code{'\0'} in 
the conditions of
 of @code{switch} statements, instead of just the
 plain pointer or character value.
 
+@item
+Do not, @emph{under any circumstances}, use the @samp{-1 == foo} or
+@samp{0 >= bar} style of comparison expressions.  I have known about
+it for decades, and I understand why some people like it.  Nonetheless,
+I abhor it with a passion, and code that uses it will never be accepted.
+
 @item
 Use @code{true} and @code{false} for @code{bool} values,
 the @code{NULL} symbolic constant for pointer values,

-----------------------------------------------------------------------

Summary of changes:
 doc/ChangeLog   |  4 +++
 doc/gawk.info   | 87 +++++++++++++++++++++++++++++++++------------------------
 doc/gawk.texi   | 18 ++++++++++--
 doc/gawktexi.in | 18 ++++++++++--
 4 files changed, 86 insertions(+), 41 deletions(-)


hooks/post-receive
-- 
gawk