Finish documenting bool in the manual.

1 files changed, 33 insertions, 21 deletions

diff --git a/doc/gawk.texi b/doc/gawk.texi
index 280b3168..6a7feaaa 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -18385,15 +18385,18 @@ two arguments 11 and 10.
 @subsection Generating Boolean Values
 @cindex boolean function
 
-This functions is specific to @command{gawk}. It is not
+This function is specific to @command{gawk}. It is not
 available in compatibility mode (@pxref{Options}):
 
 @c @asis for docbook
 @table @asis
 @item @code{bool(@var{expression})}
 @cindexgawkfunc{bool}
-
-blah blah
+Return a Boolean-typed value based on the regular Boolean value
+of @var{expression}.  Boolean ``true'' values have numeric value one
+and string value @code{"TRUE"}. Boolean ``false'' values have numeric
+zero and string value @code{"FALSE"}.  This is discussed in more
+detail in @ref{Boolean Typed Values}.
 @end table
 
 @node Numeric Functions
@@ -20912,6 +20915,9 @@ Return one of the following strings, depending upon the type of @var{x}:
 @item "array"
 @var{x} is an array.
 
+@item "bool"
+@var{x} is a Boolean typed value (@pxref{Boolean Typed Values}).
+
 @item "regexp"
 @var{x} is a strongly typed regexp (@pxref{Strong Regexp Constants}).
 
@@ -29475,19 +29481,19 @@ This option may disappear in a future version of @command{gawk}.
 @node Boolean Typed Values
 @section Boolean Typed Values
 
-This @value{SECTION} describes an advanced, @command{gawk}-specific extension.
-
 Scalar values in @command{awk} are either numbers or strings.
-@command{gawk} also supports values of type @code{regexp} (FIXME pxref).
+@command{gawk} also supports values of type @code{regexp}
+(@pxref{Strong Regexp Constants}).
 
-As seen in FIXME @@ref@{@} here, Boolean values in @command{awk} don't have a separate
-type: a value counts as ``true'' if it is nonzero or non-null, and as
-``false'' otherwise.
+As described in @ref{Truth Values}, Boolean values in @command{awk}
+don't have a separate type: a value counts as ``true'' if it is nonzero
+or non-null, and as ``false'' otherwise.
 
 When interchanging data with languages that do have a real Boolean type,
 using a standard format such as JSON or XML, the lack of a true Boolean
-type in @command{awk} is problematic.  (FIXME: xref to gawkextlib json
-extension)
+type in @command{awk} is problematic.
+(See, for example, the @code{json} extension provided by
+@uref{https://sourceforge.net/projects/gawkextlib, the @code{gawkextlib} project}.)
 
 It's easy to import Boolean data into @command{awk}, but then the fact
 that it was originally Boolean is lost.  Exporting data is even harder;
@@ -29497,16 +29503,22 @@ To solve this problem, @command{gawk} provides a function named @code{bool()}.
 It takes one argument, which is any @command{awk} expression, and it
 returns a value of Boolean type.
 
-The returned values are different than
-normal @command{awk} values. When treated as numbers, they are either
-one or zero, depending upon the truth value of the expression passed
-in the call. When treated as strings, they are either @code{"TRUE"}
-or @code{"FALSE"}, again depending upon the truth value of the expression passed
-in the call. The value for ``false'' is thus unusual; it is zero numerically,
-but not empty when treated as a string.
-
-The @code{typeof()} function (FIXME pxref here) returns @code{"bool"}
-for these values.
+The returned values are different than normal @command{awk} values. When
+treated as numbers, they are either one or zero, depending upon the truth
+value of the original expression passed in the call to @code{bool()}. When
+treated as strings, they are either @code{"TRUE"} or @code{"FALSE"},
+again depending upon the truth value of the expression passed in the
+call to @code{bool()}. The value for ``false'' is thus unusual; it is
+zero numerically, but not empty when treated as a string.
+
+The @code{typeof()} function (@pxref{Type Functions}) returns
+@code{"bool"} for these values.
+
+While it would have been possible to add two new built-in variables
+of Boolean type named @code{TRUE} and @code{FALSE}, doing so would
+undoubtedly have broken many existing @command{awk} programs.  Instead,
+having a ``generator'' function that creates Boolean values gives
+flexibility, without breaking any existing code.
 
 @node Array Sorting
 @section Controlling Array Traversal and Array Sorting