Fix debugger walkthrough.

4 files changed, 106 insertions, 95 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index c93a266f..620ad769 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,6 +1,12 @@
+2014-09-02         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in: Corrections to walkthrough in debugger chapter.
+	Thanks to David "bamber" Ward <dlward134@gmail.com> for
+	the problem report.
+
 2014-09-01         Arnold D. Robbins     <arnold@skeeve.com>
 
-	* gaktexi.in: Add index entry for @ - @load, @include,
+	* gawktexi.in: Add index entry for @ - @load, @include,
 	and indirect function calls. Thanks to "Kenny McKormack" in
 	comp.lang.awk.
 
diff --git a/doc/gawk.info b/doc/gawk.info
index 8d71f77c..c8212732 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -20524,7 +20524,7 @@ options. (`gawk' is not designed to debug command-line programs, only
 programs contained in files.)  In our case, we invoke the debugger like
 this:
 
-     $ gawk -D -f getopt.awk -f join.awk -f uniq.awk inputfile
+     $ gawk -D -f getopt.awk -f join.awk -f uniq.awk -1 inputfile
 
 where both `getopt.awk' and `uniq.awk' are in `$AWKPATH'.  (Experienced
 users of GDB or similar debuggers should note that this syntax is
@@ -20576,7 +20576,7 @@ for a breakpoint in `uniq.awk' is at the beginning of the function
 To set the breakpoint, use the `b' (breakpoint) command:
 
      gawk> b are_equal
-     -| Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 64
+     -| Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 63
 
    The debugger tells us the file and line number where the breakpoint
 is.  Now type `r' or `run' and the program runs until it hits the
@@ -20586,8 +20586,8 @@ breakpoint for the first time:
      -| Starting program:
      -| Stopping in Rule ...
      -| Breakpoint 1, are_equal(n, m, clast, cline, alast, aline)
-              at `awklib/eg/prog/uniq.awk':64
-     -| 64          if (fcount == 0 && charcount == 0)
+              at `awklib/eg/prog/uniq.awk':63
+     -| 63          if (fcount == 0 && charcount == 0)
      gawk>
 
    Now we can look at what's going on inside our program.  First of all,
@@ -20597,11 +20597,11 @@ the current stack frames:
 
      gawk> bt
      -| #0  are_equal(n, m, clast, cline, alast, aline)
-              at `awklib/eg/prog/uniq.awk':69
-     -| #1  in main() at `awklib/eg/prog/uniq.awk':89
+              at `awklib/eg/prog/uniq.awk':68
+     -| #1  in main() at `awklib/eg/prog/uniq.awk':88
 
    This tells us that `are_equal()' was called by the main program at
-line 89 of `uniq.awk'.  (This is not a big surprise, since this is the
+line 88 of `uniq.awk'.  (This is not a big surprise, since this is the
 only call to `are_equal()' in the program, but in more complex
 programs, knowing who called a function and with what parameters can be
 the key to finding the source of the problem.)
@@ -20620,13 +20620,13 @@ function was called without arguments (*note Function Calls::).
    A more useful variable to display might be the current record:
 
      gawk> p $0
-     -| $0 = string ("gawk is a wonderful program!")
+     -| $0 = "gawk is a wonderful program!"
 
 This might be a bit puzzling at first since this is the second line of
 our test input above.  Let's look at `NR':
 
      gawk> p NR
-     -| NR = number (2)
+     -| NR = 2
 
 So we can see that `are_equal()' was only called for the second record
 of the file.  Of course, this is because our program contains a rule for
@@ -20640,7 +20640,7 @@ of the file.  Of course, this is because our program contains a rule for
    OK, let's just check that that rule worked correctly:
 
      gawk> p last
-     -| last = string ("awk is a wonderful program!")
+     -| last = "awk is a wonderful program!"
 
    Everything we have done so far has verified that the program has
 worked as planned, up to and including the call to `are_equal()', so
@@ -20649,38 +20649,39 @@ must begin "stepping through" the lines of `are_equal()'.  We start by
 typing `n' (for "next"):
 
      gawk> n
-     -| 67          if (fcount > 0) {
+     -| 66          if (fcount > 0) {
 
-   This tells us that `gawk' is now ready to execute line 67, which
+   This tells us that `gawk' is now ready to execute line 66, which
 decides whether to give the lines the special "field skipping" treatment
-indicated by the `-f' command-line option.  (Notice that we skipped
-from where we were before at line 64 to here, since the condition in
-line 64 `if (fcount == 0 && charcount == 0)' was false.)
+indicated by the `-1' command-line option.  (Notice that we skipped
+from where we were before at line 63 to here, since the condition in
+line 63 `if (fcount == 0 && charcount == 0)' was false.)
 
    Continuing to step, we now get to the splitting of the current and
 last records:
 
      gawk> n
-     -| 68              n = split(last, alast)
+     -| 67              n = split(last, alast)
      gawk> n
-     -| 69              m = split($0, aline)
+     -| 68              m = split($0, aline)
 
    At this point, we should be curious to see what our records were
 split into, so we try to look:
 
      gawk> p n m alast aline
-     -| n = number (5)
-     -| m = number (5)
+     -| n = 5
+     -| m = untyped variable
      -| alast = array, 5 elements
-     -| aline = array, 5 elements
+     -| aline = untyped variable
 
 (The `p' command can take more than one argument, similar to `awk''s
 `print' statement.)
 
    This is kind of disappointing, though.  All we found out is that
-there are five elements in each of our arrays.  Useful enough (we now
-know that none of the words were accidentally left out), but what if we
-want to see inside the array?
+there are five elements in `alast'; `m' and `aline' don't have values
+yet since we are at line 68 but haven't executed it yet.  This
+information is useful enough (we now know that none of the words were
+accidentally left out), but what if we want to see inside the array?
 
    The first choice would be to use subscripts:
 
@@ -20690,25 +20691,25 @@ want to see inside the array?
 Oops!
 
      gawk> p alast[1]
-     -| alast["1"] = string ("awk")
+     -| alast["1"] = "awk"
 
    This would be kind of slow for a 100-member array, though, so `gawk'
 provides a shortcut (reminiscent of another language not to be
 mentioned):
 
      gawk> p @alast
-     -| alast["1"] = string ("awk")
-     -| alast["2"] = string ("is")
-     -| alast["3"] = string ("a")
-     -| alast["4"] = string ("wonderful")
-     -| alast["5"] = string ("program!")
+     -| alast["1"] = "awk"
+     -| alast["2"] = "is"
+     -| alast["3"] = "a"
+     -| alast["4"] = "wonderful"
+     -| alast["5"] = "program!"
 
    It looks like we got this far OK.  Let's take another step or two:
 
      gawk> n
-     -| 70              clast = join(alast, fcount, n)
+     -| 69              clast = join(alast, fcount, n)
      gawk> n
-     -| 71              cline = join(aline, fcount, m)
+     -| 70              cline = join(aline, fcount, m)
 
    Well, here we are at our error (sorry to spoil the suspense).  What
 we had in mind was to join the fields starting from the second one to
@@ -20716,8 +20717,8 @@ make the virtual record to compare, and if the first field was numbered
 zero, this would work.  Let's look at what we've got:
 
      gawk> p cline clast
-     -| cline = string ("gawk is a wonderful program!")
-     -| clast = string ("awk is a wonderful program!")
+     -| cline = "gawk is a wonderful program!"
+     -| clast = "awk is a wonderful program!"
 
    Hey, those look pretty familiar!  They're just our original,
 unaltered, input records.  A little thinking (the human brain is still
@@ -34386,7 +34387,7 @@ Node: Debugging Terms825200
 Node: Awk Debugging827797
 Node: Sample Debugging Session828689
 Node: Debugger Invocation829209
-Node: Finding The Bug830542
+Node: Finding The Bug830545
 Node: List of Debugger Commands837024
 Node: Breakpoint Control838356
 Node: Debugger Execution Control842020
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 6226e735..7078a70e 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -28682,7 +28682,7 @@ to debug command-line programs, only programs contained in files.)
 In our case, we invoke the debugger like this:
 
 @example
-$ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk inputfile}
+$ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk -1 inputfile}
 @end example
 
 @noindent
@@ -28744,7 +28744,7 @@ the breakpoint, use the @code{b} (breakpoint) command:
 
 @example
 gawk> @kbd{b are_equal}
-@print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 64
+@print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 63
 @end example
 
 The debugger tells us the file and line number where the breakpoint is.
@@ -28756,8 +28756,8 @@ gawk> @kbd{r}
 @print{} Starting program:
 @print{} Stopping in Rule ...
 @print{} Breakpoint 1, are_equal(n, m, clast, cline, alast, aline)
-         at `awklib/eg/prog/uniq.awk':64
-@print{} 64          if (fcount == 0 && charcount == 0)
+         at `awklib/eg/prog/uniq.awk':63
+@print{} 63          if (fcount == 0 && charcount == 0)
 gawk>
 @end example
 
@@ -28769,12 +28769,12 @@ listing of the current stack frames:
 @example
 gawk> @kbd{bt}
 @print{} #0  are_equal(n, m, clast, cline, alast, aline)
-         at `awklib/eg/prog/uniq.awk':69
-@print{} #1  in main() at `awklib/eg/prog/uniq.awk':89
+         at `awklib/eg/prog/uniq.awk':68
+@print{} #1  in main() at `awklib/eg/prog/uniq.awk':88
 @end example
 
 This tells us that @code{are_equal()} was called by the main program at
-line 89 of @file{uniq.awk}.  (This is not a big surprise, since this
+line 88 of @file{uniq.awk}.  (This is not a big surprise, since this
 is the only call to @code{are_equal()} in the program, but in more complex
 programs, knowing who called a function and with what parameters can be
 the key to finding the source of the problem.)
@@ -28798,7 +28798,7 @@ A more useful variable to display might be the current record:
 
 @example
 gawk> @kbd{p $0}
-@print{} $0 = string ("gawk is a wonderful program!")
+@print{} $0 = "gawk is a wonderful program!"
 @end example
 
 @noindent
@@ -28807,7 +28807,7 @@ our test input above.  Let's look at @code{NR}:
 
 @example
 gawk> @kbd{p NR}
-@print{} NR = number (2)
+@print{} NR = 2
 @end example
 
 @noindent
@@ -28826,7 +28826,7 @@ OK, let's just check that that rule worked correctly:
 
 @example
 gawk> @kbd{p last}
-@print{} last = string ("awk is a wonderful program!")
+@print{} last = "awk is a wonderful program!"
 @end example
 
 Everything we have done so far has verified that the program has worked as
@@ -28837,13 +28837,13 @@ be inside this function.  To investigate further, we must begin
 
 @example
 gawk> @kbd{n}
-@print{} 67          if (fcount > 0) @{
+@print{} 66          if (fcount > 0) @{
 @end example
 
-This tells us that @command{gawk} is now ready to execute line 67, which
+This tells us that @command{gawk} is now ready to execute line 66, which
 decides whether to give the lines the special ``field skipping'' treatment
-indicated by the @option{-f} command-line option.  (Notice that we skipped
-from where we were before at line 64 to here, since the condition in line 64
+indicated by the @option{-1} command-line option.  (Notice that we skipped
+from where we were before at line 63 to here, since the condition in line 63
 @samp{if (fcount == 0 && charcount == 0)} was false.)
 
 Continuing to step, we now get to the splitting of the current and
@@ -28851,9 +28851,9 @@ last records:
 
 @example
 gawk> @kbd{n}
-@print{} 68              n = split(last, alast)
+@print{} 67              n = split(last, alast)
 gawk> @kbd{n}
-@print{} 69              m = split($0, aline)
+@print{} 68              m = split($0, aline)
 @end example
 
 At this point, we should be curious to see what our records were split
@@ -28861,10 +28861,10 @@ into, so we try to look:
 
 @example
 gawk> @kbd{p n m alast aline}
-@print{} n = number (5)
-@print{} m = number (5)
+@print{} n = 5
+@print{} m = untyped variable
 @print{} alast = array, 5 elements
-@print{} aline = array, 5 elements
+@print{} aline = untyped variable
 @end example
 
 @noindent
@@ -28872,7 +28872,9 @@ gawk> @kbd{p n m alast aline}
 @command{awk}'s @code{print} statement.)
 
 This is kind of disappointing, though.  All we found out is that there
-are five elements in each of our arrays.  Useful enough (we now know that
+are five elements in @code{alast}; @code{m} and @code{aline} don't have
+values yet since we are at line 68 but haven't executed it yet.
+This information is useful enough (we now know that
 none of the words were accidentally left out), but what if we want to see
 inside the array?
 
@@ -28888,7 +28890,7 @@ Oops!
 
 @example
 gawk> @kbd{p alast[1]}
-@print{} alast["1"] = string ("awk")
+@print{} alast["1"] = "awk"
 @end example
 
 This would be kind of slow for a 100-member array, though, so
@@ -28897,11 +28899,11 @@ not to be mentioned):
 
 @example
 gawk> @kbd{p @@alast}
-@print{} alast["1"] = string ("awk")
-@print{} alast["2"] = string ("is")
-@print{} alast["3"] = string ("a")
-@print{} alast["4"] = string ("wonderful")
-@print{} alast["5"] = string ("program!")
+@print{} alast["1"] = "awk"
+@print{} alast["2"] = "is"
+@print{} alast["3"] = "a"
+@print{} alast["4"] = "wonderful"
+@print{} alast["5"] = "program!"
 @end example
 
 It looks like we got this far OK.  Let's take another step
@@ -28909,9 +28911,9 @@ or two:
 
 @example
 gawk> @kbd{n}
-@print{} 70              clast = join(alast, fcount, n)
+@print{} 69              clast = join(alast, fcount, n)
 gawk> @kbd{n}
-@print{} 71              cline = join(aline, fcount, m)
+@print{} 70              cline = join(aline, fcount, m)
 @end example
 
 Well, here we are at our error (sorry to spoil the suspense).  What we
@@ -28921,8 +28923,8 @@ this would work.  Let's look at what we've got:
 
 @example
 gawk> @kbd{p cline clast}
-@print{} cline = string ("gawk is a wonderful program!")
-@print{} clast = string ("awk is a wonderful program!")
+@print{} cline = "gawk is a wonderful program!"
+@print{} clast = "awk is a wonderful program!"
 @end example
 
 Hey, those look pretty familiar!  They're just our original, unaltered,
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index d7867c45..ebd1ce17 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -27780,7 +27780,7 @@ to debug command-line programs, only programs contained in files.)
 In our case, we invoke the debugger like this:
 
 @example
-$ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk inputfile}
+$ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk -1 inputfile}
 @end example
 
 @noindent
@@ -27842,7 +27842,7 @@ the breakpoint, use the @code{b} (breakpoint) command:
 
 @example
 gawk> @kbd{b are_equal}
-@print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 64
+@print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 63
 @end example
 
 The debugger tells us the file and line number where the breakpoint is.
@@ -27854,8 +27854,8 @@ gawk> @kbd{r}
 @print{} Starting program:
 @print{} Stopping in Rule ...
 @print{} Breakpoint 1, are_equal(n, m, clast, cline, alast, aline)
-         at `awklib/eg/prog/uniq.awk':64
-@print{} 64          if (fcount == 0 && charcount == 0)
+         at `awklib/eg/prog/uniq.awk':63
+@print{} 63          if (fcount == 0 && charcount == 0)
 gawk>
 @end example
 
@@ -27867,12 +27867,12 @@ listing of the current stack frames:
 @example
 gawk> @kbd{bt}
 @print{} #0  are_equal(n, m, clast, cline, alast, aline)
-         at `awklib/eg/prog/uniq.awk':69
-@print{} #1  in main() at `awklib/eg/prog/uniq.awk':89
+         at `awklib/eg/prog/uniq.awk':68
+@print{} #1  in main() at `awklib/eg/prog/uniq.awk':88
 @end example
 
 This tells us that @code{are_equal()} was called by the main program at
-line 89 of @file{uniq.awk}.  (This is not a big surprise, since this
+line 88 of @file{uniq.awk}.  (This is not a big surprise, since this
 is the only call to @code{are_equal()} in the program, but in more complex
 programs, knowing who called a function and with what parameters can be
 the key to finding the source of the problem.)
@@ -27896,7 +27896,7 @@ A more useful variable to display might be the current record:
 
 @example
 gawk> @kbd{p $0}
-@print{} $0 = string ("gawk is a wonderful program!")
+@print{} $0 = "gawk is a wonderful program!"
 @end example
 
 @noindent
@@ -27905,7 +27905,7 @@ our test input above.  Let's look at @code{NR}:
 
 @example
 gawk> @kbd{p NR}
-@print{} NR = number (2)
+@print{} NR = 2
 @end example
 
 @noindent
@@ -27924,7 +27924,7 @@ OK, let's just check that that rule worked correctly:
 
 @example
 gawk> @kbd{p last}
-@print{} last = string ("awk is a wonderful program!")
+@print{} last = "awk is a wonderful program!"
 @end example
 
 Everything we have done so far has verified that the program has worked as
@@ -27935,13 +27935,13 @@ be inside this function.  To investigate further, we must begin
 
 @example
 gawk> @kbd{n}
-@print{} 67          if (fcount > 0) @{
+@print{} 66          if (fcount > 0) @{
 @end example
 
-This tells us that @command{gawk} is now ready to execute line 67, which
+This tells us that @command{gawk} is now ready to execute line 66, which
 decides whether to give the lines the special ``field skipping'' treatment
-indicated by the @option{-f} command-line option.  (Notice that we skipped
-from where we were before at line 64 to here, since the condition in line 64
+indicated by the @option{-1} command-line option.  (Notice that we skipped
+from where we were before at line 63 to here, since the condition in line 63
 @samp{if (fcount == 0 && charcount == 0)} was false.)
 
 Continuing to step, we now get to the splitting of the current and
@@ -27949,9 +27949,9 @@ last records:
 
 @example
 gawk> @kbd{n}
-@print{} 68              n = split(last, alast)
+@print{} 67              n = split(last, alast)
 gawk> @kbd{n}
-@print{} 69              m = split($0, aline)
+@print{} 68              m = split($0, aline)
 @end example
 
 At this point, we should be curious to see what our records were split
@@ -27959,10 +27959,10 @@ into, so we try to look:
 
 @example
 gawk> @kbd{p n m alast aline}
-@print{} n = number (5)
-@print{} m = number (5)
+@print{} n = 5
+@print{} m = untyped variable
 @print{} alast = array, 5 elements
-@print{} aline = array, 5 elements
+@print{} aline = untyped variable
 @end example
 
 @noindent
@@ -27970,7 +27970,9 @@ gawk> @kbd{p n m alast aline}
 @command{awk}'s @code{print} statement.)
 
 This is kind of disappointing, though.  All we found out is that there
-are five elements in each of our arrays.  Useful enough (we now know that
+are five elements in @code{alast}; @code{m} and @code{aline} don't have
+values yet since we are at line 68 but haven't executed it yet.
+This information is useful enough (we now know that
 none of the words were accidentally left out), but what if we want to see
 inside the array?
 
@@ -27986,7 +27988,7 @@ Oops!
 
 @example
 gawk> @kbd{p alast[1]}
-@print{} alast["1"] = string ("awk")
+@print{} alast["1"] = "awk"
 @end example
 
 This would be kind of slow for a 100-member array, though, so
@@ -27995,11 +27997,11 @@ not to be mentioned):
 
 @example
 gawk> @kbd{p @@alast}
-@print{} alast["1"] = string ("awk")
-@print{} alast["2"] = string ("is")
-@print{} alast["3"] = string ("a")
-@print{} alast["4"] = string ("wonderful")
-@print{} alast["5"] = string ("program!")
+@print{} alast["1"] = "awk"
+@print{} alast["2"] = "is"
+@print{} alast["3"] = "a"
+@print{} alast["4"] = "wonderful"
+@print{} alast["5"] = "program!"
 @end example
 
 It looks like we got this far OK.  Let's take another step
@@ -28007,9 +28009,9 @@ or two:
 
 @example
 gawk> @kbd{n}
-@print{} 70              clast = join(alast, fcount, n)
+@print{} 69              clast = join(alast, fcount, n)
 gawk> @kbd{n}
-@print{} 71              cline = join(aline, fcount, m)
+@print{} 70              cline = join(aline, fcount, m)
 @end example
 
 Well, here we are at our error (sorry to spoil the suspense).  What we
@@ -28019,8 +28021,8 @@ this would work.  Let's look at what we've got:
 
 @example
 gawk> @kbd{p cline clast}
-@print{} cline = string ("gawk is a wonderful program!")
-@print{} clast = string ("awk is a wonderful program!")
+@print{} cline = "gawk is a wonderful program!"
+@print{} clast = "awk is a wonderful program!"
 @end example
 
 Hey, those look pretty familiar!  They're just our original, unaltered,