doc: wrap

* README-hacking: Refill paragraphs.

README-hacking

@@ -9,19 +9,19 @@ Everything related to the development of Bison is on Savannah:
 * Administrivia
 
 ** If you incorporate a change from somebody on the net:
-First, if it is a large change, you must make sure they have signed
+First, if it is a large change, you must make sure they have signed the
-the appropriate paperwork.  Second, be sure to add their name and
+appropriate paperwork.  Second, be sure to add their name and email address
-email address to THANKS.
+to THANKS.
 
 ** If a change fixes a test, mention the test in the commit message.
 
 ** Bug reports
-If somebody reports a new bug, mention his name in the commit message
+If somebody reports a new bug, mention his name in the commit message and in
-and in the test case you write.  Put him into THANKS.
+the test case you write.  Put him into THANKS.
 
-The correct response to most actual bugs is to write a new test case
+The correct response to most actual bugs is to write a new test case which
-which demonstrates the bug.  Then fix the bug, re-run the test suite,
+demonstrates the bug.  Then fix the bug, re-run the test suite, and check
-and check everything in.
+everything in.
 
 
 * Hacking
@@ -30,17 +30,17 @@ and check everything in.
 Which include serious bug fixes, must be mentioned in NEWS.
 
 ** Translations
-Only user visible strings are to be translated: error messages, bits
+Only user visible strings are to be translated: error messages, bits of the
-of the .output file etc.  This excludes impossible error messages
+.output file etc.  This excludes impossible error messages (comparable to
-(comparable to assert/abort), and all the --trace output which is
+assert/abort), and all the --trace output which is meant for the maintainers
-meant for the maintainers only.
+only.
 
 ** Horizontal tabs
 Do not add horizontal tab characters to any file in Bison's repository
 except where required.  For example, do not use tabs to format C code.
-However, make files, ChangeLog, and some regular expressions require
+However, make files, ChangeLog, and some regular expressions require tabs.
-tabs.  Also, test cases might need to contain tabs to check that Bison
+Also, test cases might need to contain tabs to check that Bison properly
-properly processes tabs in its input.
+processes tabs in its input.
 
 
 * Working from the repository
@@ -139,13 +139,12 @@ explicitly by the user.
 *** Updating Bison
 
 If you pull a newer version of a branch, say via "git pull", you might
-import requests for updated submodules.  A simple "git diff" will
+import requests for updated submodules.  A simple "git diff" will reveal if
-reveal if the current version of the submodule (i.e., the actual
+the current version of the submodule (i.e., the actual contents of the
-contents of the gnulib directory) and the current request from the
+gnulib directory) and the current request from the subscriber (i.e., the
-subscriber (i.e., the reference of the version of gnulib that the
+reference of the version of gnulib that the Bison repository requests)
-Bison repository requests) differ.  To upgrade the submodules (i.e.,
+differ.  To upgrade the submodules (i.e., to check out the version that is
-to check out the version that is actually requested by the subscriber,
+actually requested by the subscriber, run "git submodule update".
-run "git submodule update".
 
         $ git pull
         $ git submodule update
@@ -169,8 +168,8 @@ Register your changes.
 
         $ git checkin ...
 
-For a suggestion of what gnulib commit might be stable enough for a
+For a suggestion of what gnulib commit might be stable enough for a formal
-formal release, see the ChangeLog in the latest gnulib snapshot at:
+release, see the ChangeLog in the latest gnulib snapshot at:
 
         http://erislabs.net/ianb/projects/gnulib/
 
@@ -180,9 +179,9 @@ The Autoconf files we use are currently:
         lib/m4sugar/m4sugar.m4
         lib/m4sugar/foreach.m4
 
-These files don't change very often in Autoconf, so it should be
+These files don't change very often in Autoconf, so it should be relatively
-relatively straight-forward to examine the differences in order to
+straight-forward to examine the differences in order to decide whether to
-decide whether to update.
+update.
 
 * Test suite
 
@@ -245,102 +244,99 @@ suite.  So currently, do not try to run valgrind on Mac OS X.
 Try to run the test suite with more severe conditions before a
 release:
 
-- Configure the package with --enable-gcc-warnings, so that one checks
+- Configure the package with --enable-gcc-warnings, so that one checks that
-  that 1. Bison compiles cleanly, 2. the parsers it produces compile
+  1. Bison compiles cleanly, 2. the parsers it produces compile cleanly too.
-  cleanly too.
 
-- Maybe build with -DGNULIB_POSIXCHECK, which suggests gnulib modules
+- Maybe build with -DGNULIB_POSIXCHECK, which suggests gnulib modules that
-  that can fix portability issues.  See if you really want to pay
+  can fix portability issues.  See if you really want to pay attention to
-  attention to its warnings; there's no need to obey blindly to it
+  its warnings; there's no need to obey blindly to it
   (<http://lists.gnu.org/archive/html/bison-patches/2012-05/msg00057.html>).
 
-- Check with "make syntax-check" if there are issues diagnosed by
+- Check with "make syntax-check" if there are issues diagnosed by gnulib.
-  gnulib.
 
 - run "make maintainer-check" which:
   - runs "valgrind -q bison" to run Bison under Valgrind.
   - runs the parsers under Valgrind.
   - runs the test suite with G++ as C compiler...
 
-- run "make maintainer-push-check", which runs "make maintainer-check"
+- run "make maintainer-push-check", which runs "make maintainer-check" while
-  while activating the push implementation and its pull interface wrappers
+  activating the push implementation and its pull interface wrappers in many
-  in many test cases that were originally written to exercise only the
+  test cases that were originally written to exercise only the pull
-  pull implementation.  This makes certain the push implementation can
+  implementation.  This makes certain the push implementation can perform
-  perform every task the pull implementation can.
+  every task the pull implementation can.
 
-- run "make maintainer-xml-check", which runs "make maintainer-check"
+- run "make maintainer-xml-check", which runs "make maintainer-check" while
-  while checking Bison's XML automaton report for every working grammar
+  checking Bison's XML automaton report for every working grammar passed to
-  passed to Bison in the test suite.  The check just diffs the output of
+  Bison in the test suite.  The check just diffs the output of Bison's
-  Bison's included XSLT style sheets with the output of --report=all and
+  included XSLT style sheets with the output of --report=all and --graph.
-  --graph.
 
 - running "make maintainer-release-check" takes care of running
   maintainer-check, maintainer-push-check and maintainer-xml-check.
 
-- Change tests/atlocal/CFLAGS to add your preferred options.  For
+- Change tests/atlocal/CFLAGS to add your preferred options.  For instance,
-  instance, "-traditional" to check that the parsers are K&R.  Note
+  "-traditional" to check that the parsers are K&R.  Note that it does not
-  that it does not make sense for glr.c, which should be ANSI, but
+  make sense for glr.c, which should be ANSI, but currently is actually GNU
-  currently is actually GNU C, nor for lalr1.cc.
+  C, nor for lalr1.cc.
 
-- Test with a very recent version of GCC for both C and C++.  Testing
+- Test with a very recent version of GCC for both C and C++.  Testing with
-  with older versions that are still in use is nice too.
+  older versions that are still in use is nice too.
 
 
 * Release Procedure
-This section needs to be updated to take into account features from
+This section needs to be updated to take into account features from gnulib.
-gnulib.  In particular, be sure to read README-release.
+In particular, be sure to read README-release.
 
 ** Update the submodules.  See above.
 
 ** Update maintainer tools, such as Autoconf.  See above.
 
 ** Try to get the *.pot files to the Translation Project at least one
-week before a stable release, to give them time to translate them.
+week before a stable release, to give them time to translate them.  Before
-Before generating the *.pot files, make sure that po/POTFILES.in and
+generating the *.pot files, make sure that po/POTFILES.in and
-runtime-po/POTFILES.in list all files with translatable strings.
+runtime-po/POTFILES.in list all files with translatable strings.  This
-This helps: grep -l '\<_(' *
+helps: grep -l '\<_(' *
 
 ** Tests
 See above.
 
 ** Update the foreign files
-Running "./bootstrap" in the top level should update them all for you.
+Running "./bootstrap" in the top level should update them all for you.  This
-This covers PO files too.  Sometimes a PO file contains problems that
+covers PO files too.  Sometimes a PO file contains problems that causes it
-causes it to be rejected by recent Gettext releases; please report
+to be rejected by recent Gettext releases; please report these to the
-these to the Translation Project.
+Translation Project.
 
 ** Update README
-Make sure the information in README is current.  Most notably, make sure
+Make sure the information in README is current.  Most notably, make sure it
-it recommends a version of GNU M4 that is compatible with the latest
+recommends a version of GNU M4 that is compatible with the latest Bison
-Bison sources.
+sources.
 
 ** Check copyright years.
-We update years in copyright statements throughout Bison once at the
+We update years in copyright statements throughout Bison once at the start
-start of every year by running "make update-copyright".  However, before
+of every year by running "make update-copyright".  However, before a
-a release, it's good to verify that it's actually been run.  Besides the
+release, it's good to verify that it's actually been run.  Besides the
-copyright statement for each Bison file, check the copyright statements
+copyright statement for each Bison file, check the copyright statements that
-that the skeletons insert into generated parsers, and check all
+the skeletons insert into generated parsers, and check all occurrences of
-occurrences of PACKAGE_COPYRIGHT_YEAR in configure.ac.
+PACKAGE_COPYRIGHT_YEAR in configure.ac.
 
 ** Update NEWS, commit and tag.
-See do-release-commit-and-tag in README-release.  For a while, we used
+See do-release-commit-and-tag in README-release.  For a while, we used beta
-beta names such as "2.6_rc1".  Now that we use gnulib in the release
+names such as "2.6_rc1".  Now that we use gnulib in the release procedure,
-procedure, we must use "2.5.90", which has the additional benefit of
+we must use "2.5.90", which has the additional benefit of being properly
-being properly sorted in "git tag -l".
+sorted in "git tag -l".
 
 ** make alpha, beta, or stable
 See README-release.
 
 ** Upload
-There are two ways to upload the tarballs to the GNU servers: using
+There are two ways to upload the tarballs to the GNU servers: using gnupload
-gnupload (from gnulib), or by hand.  Obviously prefer the former.  But
+(from gnulib), or by hand.  Obviously prefer the former.  But in either
-in either case, be sure to read the following paragraph.
+case, be sure to read the following paragraph.
 
 *** Setup
 You need "gnupg".
 
-Make sure your public key has been uploaded at least to
+Make sure your public key has been uploaded at least to keys.gnupg.net.  You
-keys.gnupg.net.  You can upload it with:
+can upload it with:
 
   gpg --keyserver keys.gnupg.net --send-keys F125BDF3
 
@@ -349,8 +345,8 @@ where F125BDF3 should be replaced with your key ID.
 *** Using gnupload
 You need "ncftp".
 
-At the end "make stable" (or alpha/beta) will display the procedure to
+At the end "make stable" (or alpha/beta) will display the procedure to run.
-run.  Just copy and paste it in your shell.
+Just copy and paste it in your shell.
 
 *** By hand
 
@@ -412,9 +408,9 @@ sections that have been removed or renamed):
    $ ls -lt
 
 Remove these files and commit their removal to CVS.  For each of these
-files, add a line to the file .symlinks.  This will ensure that
+files, add a line to the file .symlinks.  This will ensure that hyperlinks
-hyperlinks to the removed files will redirect to the entire manual; this
+to the removed files will redirect to the entire manual; this is better than
-is better than a 404 error.
+a 404 error.
 
 There is a problem with 'index.html' being written twice (once for POSIX
 function 'index', once for the table of contents); you can ignore this
@@ -433,19 +429,18 @@ Complete/fix the announcement file.  The generated list of recipients
 (info-gnu@gnu.org, bug-bison@gnu.org, help-bison@gnu.org,
 bison-patches@gnu.org, and coordinator@translationproject.org) is
 appropriate for a stable release or a "serious beta".  For any other
-release, drop at least info-gnu@gnu.org.  For an example of how to
+release, drop at least info-gnu@gnu.org.  For an example of how to fill out
-fill out the rest of the template, search the mailing list archives
+the rest of the template, search the mailing list archives for the most
-for the most recent release announcement.
+recent release announcement.
 
 For a stable release, send the same announcement on the comp.compilers
-newsgroup by sending email to compilers@iecc.com.  Do not make any Cc as
+newsgroup by sending email to compilers@iecc.com.  Do not make any Cc as the
-the moderator will throw away anything cross-posted or Cc'ed.  It really
+moderator will throw away anything cross-posted or Cc'ed.  It really needs
-needs to be a separate message.
+to be a separate message.
 
 ** Prepare NEWS
-So that developers don't accidentally add new items to the old NEWS
+So that developers don't accidentally add new items to the old NEWS entry,
-entry, create a new empty entry in line 3 (without the two leading
+create a new empty entry in line 3 (without the two leading spaces):
-spaces):
 
   * Noteworthy changes in release ?.? (????-??-??) [?]