aboutsummaryrefslogtreecommitdiffstats
path: root/doc/gawk.texi
diff options
context:
space:
mode:
authorArnold D. Robbins <arnold@skeeve.com>2014-11-17 11:11:29 +0200
committerArnold D. Robbins <arnold@skeeve.com>2014-11-17 11:11:29 +0200
commitf35c7514dda9bf9cf06580ab5870af13e0e58103 (patch)
tree7ac3710b27e4cf64be5b3160784bf3f2fedce0b6 /doc/gawk.texi
parent52edf49564243b1d6392477e7c447eeb0d8558c0 (diff)
downloadegawk-f35c7514dda9bf9cf06580ab5870af13e0e58103.tar.gz
egawk-f35c7514dda9bf9cf06580ab5870af13e0e58103.tar.bz2
egawk-f35c7514dda9bf9cf06580ab5870af13e0e58103.zip
Rebuild derived doc files, add ChangeLog entry.
Diffstat (limited to 'doc/gawk.texi')
-rw-r--r--doc/gawk.texi2609
1 files changed, 1367 insertions, 1242 deletions
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 52fd2003..7573c993 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -56,7 +56,7 @@
@set PATCHLEVEL 2
@ifset FOR_PRINT
-@set TITLE Effective AWK Programming
+@set TITLE Effective Awk Programming
@end ifset
@ifclear FOR_PRINT
@set TITLE GAWK: Effective AWK Programming
@@ -175,12 +175,24 @@
@macro DBREF{text}
@ref{\text\}
@end macro
+@macro DBXREF{text}
+@xref{\text\}
+@end macro
+@macro DBPXREF{text}
+@pxref{\text\}
+@end macro
@end ifdocbook
@ifnotdocbook
@macro DBREF{text}
@ref{\text\},
@end macro
+@macro DBXREF{text}
+@xref{\text\},
+@end macro
+@macro DBPXREF{text}
+@pxref{\text\},
+@end macro
@end ifnotdocbook
@ifclear FOR_PRINT
@@ -315,7 +327,7 @@ A copy of the license is included in the section entitled
A copy of the license
may be found on the Internet at
@uref{http://www.gnu.org/software/gawk/manual/html_node/GNU-Free-Documentation-License.html,
-the GNU Project's web site}.
+the GNU Project's website}.
@end ifset
@enumerate a
@@ -383,10 +395,10 @@ ISBN 1-882114-28-0 @*
@sp 9
@center @i{To my parents, for their love, and for the wonderful example they set for me.}
@sp 1
-@center @i{To my wife Miriam, for making me complete.
+@center @i{To my wife, Miriam, for making me complete.
Thank you for building your life together with me.}
@sp 1
-@center @i{To our children Chana, Rivka, Nachum and Malka, for enrichening our lives in innumerable ways.}
+@center @i{To our children, Chana, Rivka, Nachum, and Malka, for enrichening our lives in innumerable ways.}
@sp 1
@w{ }
@page
@@ -1075,7 +1087,7 @@ for enrichening our lives in innumerable ways.
<!-- can't put mawk into command tags. sigh. -->
<affiliation><jobtitle>Author of mawk</jobtitle></affiliation>
</author>
- <date>March, 2001</date>
+ <date>March 2001</date>
</prefaceinfo>
@end docbook
@@ -1087,21 +1099,23 @@ The circumstances started a couple of years
earlier. I was working at a new job and noticed an unplugged
Unix computer sitting in the corner. No one knew how to use it,
and neither did I. However,
-a couple of days later it was running, and
+a couple of days later, it was running, and
I was @code{root} and the one-and-only user.
That day, I began the transition from statistician to Unix programmer.
On one of many trips to the library or bookstore in search of
-books on Unix, I found the gray AWK book, a.k.a.@: Aho, Kernighan and
-Weinberger, @cite{The AWK Programming Language}, Addison-Wesley,
-1988. AWK's simple programming paradigm---find a pattern in the
+books on Unix, I found the gray AWK book, a.k.a.@:
+Alfred V.@: Aho, Brian W.@: Kernighan, and
+Peter J.@: Weinberger's @cite{The AWK Programming Language} (Addison-Wesley,
+1988). @command{awk}'s simple programming paradigm---find a pattern in the
input and then perform an action---often reduced complex or tedious
data manipulations to a few lines of code. I was excited to try my
hand at programming in AWK.
Alas, the @command{awk} on my computer was a limited version of the
-language described in the AWK book. I discovered that my computer
-had ``old @command{awk}'' and the AWK book described ``new @command{awk}.''
+language described in the gray book. I discovered that my computer
+had ``old @command{awk}'' and the book described
+``new @command{awk}.''
I learned that this was typical; the old version refused to step
aside or relinquish its name. If a system had a new @command{awk}, it was
invariably called @command{nawk}, and few systems had it.
@@ -1119,7 +1133,7 @@ My Unix system started out unplugged from the wall; it certainly was not
plugged into a network. So, oblivious to the existence of @command{gawk}
and the Unix community in general, and desiring a new @command{awk}, I wrote
my own, called @command{mawk}.
-Before I was finished I knew about @command{gawk},
+Before I was finished, I knew about @command{gawk},
but it was too late to stop, so I eventually posted
to a @code{comp.sources} newsgroup.
@@ -1128,7 +1142,7 @@ from Arnold introducing
himself. He suggested we share design and algorithms and
attached a draft of the POSIX standard so
that I could update @command{mawk} to support language extensions added
-after publication of the AWK book.
+after publication of @cite{The AWK Programming Language}.
Frankly, if our roles had
been reversed, I would not have been so open and we probably would
@@ -1147,7 +1161,7 @@ standard.
On the other hand, the novice AWK programmer can study
a wealth of practical programs that emphasize
the power of AWK's basic idioms:
-data driven control-flow, pattern matching with regular expressions,
+data-driven control flow, pattern matching with regular expressions,
and associative arrays.
Those looking for something new can try out @command{gawk}'s
interface to network protocols via special @file{/inet} files.
@@ -1208,7 +1222,7 @@ AWK or want to learn how, then read this book.
@display
Michael Brennan
Author of @command{mawk}
-March, 2001
+March 2001
@end display
@end ifnotdocbook
@@ -1226,7 +1240,7 @@ March, 2001
<!-- can't put mawk into command tags. sigh. -->
<affiliation><jobtitle>Author of mawk</jobtitle></affiliation>
</author>
- <date>October, 2014</date>
+ <date>October 2014</date>
</prefaceinfo>
@end docbook
@@ -1260,7 +1274,7 @@ details, and as expected, many examples to help you learn the ins and outs.
@display
Michael Brennan
Author of @command{mawk}
-October, 2014
+October 2014
@end display
@end ifnotdocbook
@@ -1280,9 +1294,9 @@ October, 2014
<firstname>Arnold</firstname>
<surname>Robbins</surname>
<affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation>
- <affiliation><jobtitle>ISRAEL</jobtitle></affiliation>
+ <affiliation><jobtitle>Israel</jobtitle></affiliation>
</author>
- <date>December, 2014</date>
+ <date>December 2014</date>
</prefaceinfo>
@end docbook
@@ -1294,7 +1308,7 @@ The @command{awk} utility interprets a special-purpose programming
language that makes it easy to handle simple data-reformatting jobs.
The GNU implementation of @command{awk} is called @command{gawk}; if you
-invoke it with the proper options or environment variables
+invoke it with the proper options or environment variables,
it is fully compatible with
the POSIX@footnote{The 2008 POSIX standard is accessible online at
@w{@url{http://www.opengroup.org/onlinepubs/9699919799/}.}}
@@ -1401,10 +1415,10 @@ has been removed.}
@unnumberedsec History of @command{awk} and @command{gawk}
@cindex recipe for a programming language
@cindex programming language, recipe for
-@cindex sidebar, Recipe For A Programming Language
+@cindex sidebar, Recipe for a Programming Language
@ifdocbook
@docbook
-<sidebar><title>Recipe For A Programming Language</title>
+<sidebar><title>Recipe for a Programming Language</title>
@end docbook
@@ -1426,7 +1440,7 @@ more parts C. Document very well and release.
@ifnotdocbook
@cartouche
-@center @b{Recipe For A Programming Language}
+@center @b{Recipe for a Programming Language}
@@ -1448,7 +1462,7 @@ more parts C. Document very well and release.
@cindex Kernighan, Brian
@cindex @command{awk}, history of
The name @command{awk} comes from the initials of its designers: Alfred V.@:
-Aho, Peter J.@: Weinberger and Brian W.@: Kernighan. The original version of
+Aho, Peter J.@: Weinberger, and Brian W.@: Kernighan. The original version of
@command{awk} was written in 1977 at AT&T Bell Laboratories.
In 1985, a new version made the programming
language more powerful, introducing user-defined functions, multiple input
@@ -1474,7 +1488,7 @@ Circa 1994, I became the primary maintainer.
Current development focuses on bug fixes,
performance improvements, standards compliance and, occasionally, new features.
-In May of 1997, J@"urgen Kahrs felt the need for network access
+In May 1997, J@"urgen Kahrs felt the need for network access
from @command{awk}, and with a little help from me, set about adding
features to do this for @command{gawk}. At that time, he also
wrote the bulk of
@@ -1487,7 +1501,7 @@ John Haque rewrote the @command{gawk} internals, in the process providing
an @command{awk}-level debugger. This version became available as
@command{gawk} @value{PVERSION} 4.0, in 2011.
-@xref{Contributors},
+@DBXREF{Contributors}
for a full list of those who made important contributions to @command{gawk}.
@node Names
@@ -1497,7 +1511,7 @@ for a full list of those who made important contributions to @command{gawk}.
The @command{awk} language has evolved over the years. Full details are
provided in @ref{Language History}.
The language described in this @value{DOCUMENT}
-is often referred to as ``new @command{awk}''.
+is often referred to as ``new @command{awk}.''
By analogy, the original version of @command{awk} is
referred to as ``old @command{awk}.''
@@ -1576,12 +1590,15 @@ Most of the time, the examples use complete @command{awk} programs.
Some of the more advanced sections show only the part of the @command{awk}
program that illustrates the concept being described.
-While this @value{DOCUMENT} is aimed principally at people who have not been
+Although this @value{DOCUMENT} is aimed principally at people who have not been
exposed
to @command{awk}, there is a lot of information here that even the @command{awk}
expert should find useful. In particular, the description of POSIX
@command{awk} and the example programs in
-@ref{Library Functions}, and in
+@ref{Library Functions}, and
+@ifnotdocbook
+in
+@end ifnotdocbook
@ref{Sample Programs},
should be of interest.
@@ -1589,22 +1606,30 @@ This @value{DOCUMENT} is split into several parts, as follows:
@c FULLXREF ON
+@itemize @value{BULLET}
+@item
Part I describes the @command{awk} language and @command{gawk} program in detail.
It starts with the basics, and continues through all of the features of @command{awk}.
It contains the following chapters:
+@c nested
+@itemize @value{MINUS}
+@item
@ref{Getting Started},
provides the essentials you need to know to begin using @command{awk}.
+@item
@ref{Invoking Gawk},
describes how to run @command{gawk}, the meaning of its
command-line options, and how it finds @command{awk}
program source files.
+@item
@ref{Regexp},
introduces regular expressions in general, and in particular the flavors
supported by POSIX @command{awk} and @command{gawk}.
+@item
@ref{Reading Files},
describes how @command{awk} reads your data.
It introduces the concepts of records and fields, as well
@@ -1612,46 +1637,62 @@ as the @code{getline} command.
I/O redirection is first described here.
Network I/O is also briefly introduced here.
+@item
@ref{Printing},
describes how @command{awk} programs can produce output with
@code{print} and @code{printf}.
+@item
@ref{Expressions},
describes expressions, which are the basic building blocks
for getting most things done in a program.
+@item
@ref{Patterns and Actions},
describes how to write patterns for matching records, actions for
doing something when a record is matched, and the predefined variables
@command{awk} and @command{gawk} use.
+@item
@ref{Arrays},
covers @command{awk}'s one-and-only data structure: associative arrays.
Deleting array elements and whole arrays is also described, as well as
sorting arrays in @command{gawk}. It also describes how @command{gawk}
provides arrays of arrays.
+@item
@ref{Functions},
describes the built-in functions @command{awk} and @command{gawk} provide,
as well as how to define your own functions. It also discusses how
@command{gawk} lets you call functions indirectly.
+@end itemize
+@item
Part II shows how to use @command{awk} and @command{gawk} for problem solving.
There is lots of code here for you to read and learn from.
It contains the following chapters:
+@c nested
+@itemize @value{MINUS}
+@item
@ref{Library Functions}, which provides a number of functions meant to
be used from main @command{awk} programs.
+@item
@ref{Sample Programs},
which provides many sample @command{awk} programs.
+@end itemize
Reading these two chapters allows you to see @command{awk}
solving real problems.
+@item
Part III focuses on features specific to @command{gawk}.
It contains the following chapters:
+@c nested
+@itemize @value{MINUS}
+@item
@ref{Advanced Features},
describes a number of advanced features.
Of particular note
@@ -1660,18 +1701,24 @@ have two-way communications with another process,
perform TCP/IP networking, and
profile your @command{awk} programs.
+@item
@ref{Internationalization},
describes special features for translating program
messages into different languages at runtime.
+@item
@ref{Debugger}, describes the @command{gawk} debugger.
+@item
@ref{Arbitrary Precision Arithmetic},
describes advanced arithmetic facilities.
+@item
@ref{Dynamic Extensions}, describes how to add new variables and
functions to @command{gawk} by writing extensions in C or C++.
+@end itemize
+@item
@ifclear FOR_PRINT
Part IV provides the appendices, the Glossary, and two licenses that cover
the @command{gawk} source code and this @value{DOCUMENT}, respectively.
@@ -1682,11 +1729,14 @@ Part IV provides the following appendices,
including the GNU General Public License:
@end ifset
+@itemize @value{MINUS}
+@item
@ref{Language History},
describes how the @command{awk} language has evolved since
its first release to present. It also describes how @command{gawk}
has acquired features over time.
+@item
@ref{Installation},
describes how to get @command{gawk}, how to compile it
on POSIX-compatible systems,
@@ -1694,17 +1744,22 @@ and how to compile and use it on different
non-POSIX systems. It also describes how to report bugs
in @command{gawk} and where to get other freely
available @command{awk} implementations.
+@end itemize
@ifset FOR_PRINT
-
+@itemize @value{MINUS}
+@item
@ref{Copying},
presents the license that covers the @command{gawk} source code.
+@end itemize
The version of this @value{DOCUMENT} distributed with @command{gawk}
contains additional appendices and other end material.
To save space, we have omitted them from the
printed edition. You may find them online, as follows:
+@itemize @value{BULLET}
+@item
@uref{http://www.gnu.org/software/gawk/manual/html_node/Notes.html,
The appendix on implementation notes}
describes how to disable @command{gawk}'s extensions, how to contribute
@@ -1712,44 +1767,54 @@ new code to @command{gawk}, where to find information on some possible
future directions for @command{gawk} development, and the design decisions
behind the extension API.
+@item
@uref{http://www.gnu.org/software/gawk/manual/html_node/Basic-Concepts.html,
The appendix on basic concepts}
provides some very cursory background material for those who
are completely unfamiliar with computer programming.
+@item
@uref{http://www.gnu.org/software/gawk/manual/html_node/Glossary.html,
The Glossary}
-defines most, if not all, the significant terms used
+defines most, if not all of, the significant terms used
throughout the @value{DOCUMENT}. If you find terms that you aren't familiar with,
try looking them up here.
+@item
@uref{http://www.gnu.org/software/gawk/manual/html_node/GNU-Free-Documentation-License.html,
The GNU FDL}
is the license that covers this @value{DOCUMENT}.
+@end itemize
Some of the chapters have exercise sections; these have also been
omitted from the print edition but are available online.
@end ifset
@ifclear FOR_PRINT
+@itemize @value{MINUS}
+@item
@ref{Notes},
describes how to disable @command{gawk}'s extensions, as
well as how to contribute new code to @command{gawk},
and some possible future directions for @command{gawk} development.
+@item
@ref{Basic Concepts},
provides some very cursory background material for those who
are completely unfamiliar with computer programming.
-The @ref{Glossary}, defines most, if not all, the significant terms used
+The @ref{Glossary}, defines most, if not all of, the significant terms used
throughout the @value{DOCUMENT}. If you find terms that you aren't familiar with,
try looking them up here.
+@item
@ref{Copying}, and
@ref{GNU Free Documentation License},
present the licenses that cover the @command{gawk} source code
and this @value{DOCUMENT}, respectively.
+@end itemize
@end ifclear
+@end itemize
@c FULLXREF OFF
@@ -1812,7 +1877,7 @@ pressing the @kbd{d} key and finally releasing both keys.
For the sake of brevity, throughout this @value{DOCUMENT}, we refer to
Brian Kernighan's version of @command{awk} as ``BWK @command{awk}.''
-(@xref{Other Versions}, for information on his and other versions.)
+(@DBXREF{Other Versions} for information on his and other versions.)
@ifset FOR_PRINT
@quotation NOTE
@@ -1828,7 +1893,7 @@ Cautionary or warning notes look like this.
@unnumberedsubsec Dark Corners
@cindex Kernighan, Brian
@quotation
-@i{Dark corners are basically fractal --- no matter how much
+@i{Dark corners are basically fractal---no matter how much
you illuminate, there's always a smaller but darker one.}
@author Brian Kernighan
@end quotation
@@ -1898,7 +1963,7 @@ The GPL applies to the C language source code for @command{gawk}.
To find out more about the FSF and the GNU Project online,
see @uref{http://www.gnu.org, the GNU Project's home page}.
This @value{DOCUMENT} may also be read from
-@uref{http://www.gnu.org/software/gawk/manual/, their web site}.
+@uref{http://www.gnu.org/software/gawk/manual/, GNU's website}.
@ifclear FOR_PRINT
A shell, an editor (Emacs), highly portable optimizing C, C++, and
@@ -1935,10 +2000,10 @@ License in @ref{GNU Free Documentation License}.)
@cindex Close, Diane
The @value{DOCUMENT} itself has gone through multiple previous editions.
Paul Rubin wrote the very first draft of @cite{The GAWK Manual};
-it was around 40 pages in size.
+it was around 40 pages long.
Diane Close and Richard Stallman improved it, yielding a
version that was
-around 90 pages long and barely described the original, ``old''
+around 90 pages and barely described the original, ``old''
version of @command{awk}.
I started working with that version in the fall of 1988.
@@ -1971,17 +2036,17 @@ and the major new additions are @ref{Arbitrary Precision Arithmetic},
and @ref{Dynamic Extensions}.
This @value{DOCUMENT} will undoubtedly continue to evolve. If you
-find an error in this @value{DOCUMENT}, please report it! @xref{Bugs},
+find an error in this @value{DOCUMENT}, please report it! @DBXREF{Bugs}
for information on submitting problem reports electronically.
@ifset FOR_PRINT
@c fakenode --- for prepinfo
@unnumberedsec How to Stay Current
-It may be you have a version of @command{gawk} which is newer than the
+You may have a newer version of @command{gawk} than the
one described here. To find out what has changed,
you should first look at the @file{NEWS} file in the @command{gawk}
-distribution, which provides a high level summary of what changed in
+distribution, which provides a high-level summary of what changed in
each release.
You can then look at the @uref{http://www.gnu.org/software/gawk/manual/,
@@ -2006,13 +2071,13 @@ contributed code: the archive did not grow and the domain went unused
for several years.
Late in 2008, a volunteer took on the task of setting up
-an @command{awk}-related web site---@uref{http://awk.info}---and did a very
+an @command{awk}-related website---@uref{http://awk.info}---and did a very
nice job.
If you have written an interesting @command{awk} program, or have written
a @command{gawk} extension that you would like to share with the rest
of the world, please see @uref{http://awk.info/?contribute} for how to
-contribute it to the web site.
+contribute it to the website.
@ignore
As of this writing, this website is in search of a maintainer; please
@@ -2159,7 +2224,7 @@ portable program it is today. It has been and continues to be a pleasure
working with this team of fine people.
Notable code and documentation contributions were made by
-a number of people. @xref{Contributors}, for the full list.
+a number of people. @DBXREF{Contributors} for the full list.
@ifset FOR_PRINT
@cindex Oram, Andy
@@ -2178,7 +2243,7 @@ the Texinfo markup language sane.
@cindex Kernighan, Brian
@cindex Brennan, Michael
@cindex Day, Robert P.J.@:
-Robert P.J.@: Day, Michael Brennan and Brian Kernighan kindly acted as
+Robert P.J.@: Day, Michael Brennan, and Brian Kernighan kindly acted as
reviewers for the 2015 edition of this @value{DOCUMENT}. Their feedback
helped improve the final work.
@@ -2190,7 +2255,7 @@ or its documentation without his help.
Brian is in a class by himself as a programmer and technical
author. I have to thank him (yet again) for his ongoing friendship
-and the role model he has been for me for close to 30 years!
+and for being a role model to me for close to 30 years!
Having him as a reviewer is an exciting privilege. It has also
been extremely humbling@enddots{}
@@ -2211,8 +2276,8 @@ take advantage of those opportunities.
@noindent
Arnold Robbins @*
Nof Ayalon @*
-ISRAEL @*
-December, 2014
+Israel @*
+December 2014
@end iftex
@ifnotinfo
@@ -2229,31 +2294,31 @@ following chapters:
@itemize @value{BULLET}
@item
-@ref{Getting Started}.
+@ref{Getting Started}
@item
-@ref{Invoking Gawk}.
+@ref{Invoking Gawk}
@item
-@ref{Regexp}.
+@ref{Regexp}
@item
-@ref{Reading Files}.
+@ref{Reading Files}
@item
-@ref{Printing}.
+@ref{Printing}
@item
-@ref{Expressions}.
+@ref{Expressions}
@item
-@ref{Patterns and Actions}.
+@ref{Patterns and Actions}
@item
-@ref{Arrays}.
+@ref{Arrays}
@item
-@ref{Functions}.
+@ref{Functions}
@end itemize
@end ifdocbook
@@ -2268,17 +2333,17 @@ following chapters:
The basic function of @command{awk} is to search files for lines (or other
units of text) that contain certain patterns. When a line matches one
of the patterns, @command{awk} performs specified actions on that line.
-@command{awk} keeps processing input lines in this way until it reaches
+@command{awk} continues to process input lines in this way until it reaches
the end of the input files.
@cindex @command{awk}, uses for
@cindex programming languages@comma{} data-driven vs.@: procedural
@cindex @command{awk} programs
Programs in @command{awk} are different from programs in most other languages,
-because @command{awk} programs are @dfn{data-driven}; that is, you describe
-the data you want to work with and then what to do when you find it.
+because @command{awk} programs are @dfn{data driven} (i.e., you describe
+the data you want to work with and then what to do when you find it).
Most other languages are @dfn{procedural}; you have to describe, in great
-detail, every step the program is to take. When working with procedural
+detail, every step the program should take. When working with procedural
languages, it is usually much
harder to clearly describe the data your program will process.
For this reason, @command{awk} programs are often refreshingly easy to
@@ -2288,9 +2353,9 @@ read and write.
@cindex rule, definition of
When you run @command{awk}, you specify an @command{awk} @dfn{program} that
tells @command{awk} what to do. The program consists of a series of
-@dfn{rules}. (It may also contain @dfn{function definitions},
-an advanced feature that we will ignore for now.
-@xref{User-defined}.) Each rule specifies one
+@dfn{rules} (it may also contain @dfn{function definitions},
+an advanced feature that we will ignore for now;
+@pxref{User-defined}). Each rule specifies one
pattern to search for and one action to perform
upon finding the pattern.
@@ -2390,10 +2455,11 @@ programs from shell scripts, because it avoids the need for a separate
file for the @command{awk} program. A self-contained shell script is more
reliable because there are no other files to misplace.
+Later in this chapter,
+@ifdocbook
+the section
+@end ifdocbook
@ref{Very Simple},
-@ifnotinfo
-later in this @value{CHAPTER},
-@end ifnotinfo
presents several short,
self-contained programs.
@@ -2452,7 +2518,7 @@ startup file.
This next simple @command{awk} program
emulates the @command{cat} utility; it copies whatever you type on the
-keyboard to its standard output (why this works is explained shortly).
+keyboard to its standard output (why this works is explained shortly):
@example
$ @kbd{awk '@{ print @}'}
@@ -2537,7 +2603,7 @@ affect the execution of the @command{awk} program but it does make
Once you have learned @command{awk}, you may want to write self-contained
@command{awk} scripts, using the @samp{#!} script mechanism. You can do
this on many systems.@footnote{The @samp{#!} mechanism works on
-GNU/Linux systems, BSD-based systems and commercial Unix systems.}
+GNU/Linux systems, BSD-based systems, and commercial Unix systems.}
For example, you could update the file @file{advice} to look like this:
@example
@@ -2581,7 +2647,7 @@ according to the instructions in your program. (This is different
from a @dfn{compiled} language such as C, where your program is first
compiled into machine code that is executed directly by your system's
processor.) The @command{awk} utility is thus termed an @dfn{interpreter}.
-Many modern languages are interperted.
+Many modern languages are interpreted.
The line beginning with @samp{#!} lists the full @value{FN} of an
interpreter to run and a single optional initial command-line argument
@@ -2631,7 +2697,7 @@ according to the instructions in your program. (This is different
from a @dfn{compiled} language such as C, where your program is first
compiled into machine code that is executed directly by your system's
processor.) The @command{awk} utility is thus termed an @dfn{interpreter}.
-Many modern languages are interperted.
+Many modern languages are interpreted.
The line beginning with @samp{#!} lists the full @value{FN} of an
interpreter to run and a single optional initial command-line argument
@@ -2678,14 +2744,14 @@ can explain what the program does and how it works. Nearly all
programming languages have provisions for comments, as programs are
typically hard to understand without them.
-In the @command{awk} language, a comment starts with the sharp sign
+In the @command{awk} language, a comment starts with the number sign
character (@samp{#}) and continues to the end of the line.
The @samp{#} does not have to be the first character on the line. The
-@command{awk} language ignores the rest of a line following a sharp sign.
+@command{awk} language ignores the rest of a line following a number sign.
For example, we could have put the following into @file{advice}:
@example
-# This program prints a nice friendly message. It helps
+# This program prints a nice, friendly message. It helps
# keep novice users from being afraid of the computer.
BEGIN @{ print "Don't Panic!" @}
@end example
@@ -2701,7 +2767,8 @@ when reading it at a later time.
@quotation CAUTION
As mentioned in
@ref{One-shot},
-you can enclose small to medium programs in single quotes, in order to keep
+you can enclose short to medium-sized programs in single quotes,
+in order to keep
your shell scripts self-contained. When doing so, @emph{don't} put
an apostrophe (i.e., a single quote) into a comment (or anywhere else
in your program). The shell interprets the quote as the closing
@@ -2730,7 +2797,7 @@ $ @kbd{awk '@{ print "hello" @} # let's be cute'}
@cindex @code{\} (backslash)
@cindex backslash (@code{\})
Putting a backslash before the single quote in @samp{let's} wouldn't help,
-since backslashes are not special inside single quotes.
+because backslashes are not special inside single quotes.
The next @value{SUBSECTION} describes the shell's quoting rules.
@end quotation
@@ -2742,7 +2809,7 @@ The next @value{SUBSECTION} describes the shell's quoting rules.
* DOS Quoting:: Quoting in Windows Batch Files.
@end menu
-For short to medium length @command{awk} programs, it is most convenient
+For short to medium-length @command{awk} programs, it is most convenient
to enter the program on the @command{awk} command line.
This is best done by enclosing the entire program in single quotes.
This is true whether you are entering the program interactively at
@@ -2766,8 +2833,8 @@ or empty, string.
The null string is character data that has no value.
In other words, it is empty. It is written in @command{awk} programs
like this: @code{""}. In the shell, it can be written using single
-or double quotes: @code{""} or @code{''}. While the null string has
-no characters in it, it does exist. Consider this command:
+or double quotes: @code{""} or @code{''}. Although the null string has
+no characters in it, it does exist. For example, consider this command:
@example
$ @kbd{echo ""}
@@ -2777,8 +2844,7 @@ $ @kbd{echo ""}
Here, the @command{echo} utility receives a single argument, even
though that argument has no characters in it. In the rest of this
@value{DOCUMENT}, we use the terms @dfn{null string} and @dfn{empty string}
-interchangeably. Now, on to the quoting rules.
-
+interchangeably. Now, on to the quoting rules:
@itemize @value{BULLET}
@item
@@ -2801,7 +2867,7 @@ The shell does no interpretation of the quoted text, passing it on verbatim
to the command.
It is @emph{impossible} to embed a single quote inside single-quoted text.
Refer back to
-@ref{Comments},
+@DBREF{Comments}
for an example of what happens if you try.
@item
@@ -2811,7 +2877,7 @@ Double quotes protect most things between the opening and closing quotes.
The shell does at least variable and command substitution on the quoted text.
Different shells may do additional kinds of processing on double-quoted text.
-Since certain characters within double-quoted text are processed by the shell,
+Because certain characters within double-quoted text are processed by the shell,
they must be @dfn{escaped} within the text. Of note are the characters
@samp{$}, @samp{`}, @samp{\}, and @samp{"}, all of which must be preceded by
a backslash within double-quoted text if they are to be passed on literally
@@ -2873,7 +2939,7 @@ $ @kbd{awk 'BEGIN @{ print "Here is a single quote <'"'"'>" @}'}
@noindent
This program consists of three concatenated quoted strings. The first and the
-third are single-quoted, the second is double-quoted.
+third are single quoted, the second is double quoted.
This can be ``simplified'' to:
@@ -2918,7 +2984,7 @@ escapes mean.
A fourth option is to use command-line variable assignment, like this:
@example
-$ awk -v sq="'" 'BEGIN @{ print "Here is a single quote <" sq ">" @}'
+$ @kbd{awk -v sq="'" 'BEGIN @{ print "Here is a single quote <" sq ">" @}'}
@print{} Here is a single quote <'>
@end example
@@ -2989,7 +3055,7 @@ information about monthly shipments. In both files,
each line is considered to be one @dfn{record}.
In @file{mail-list}, each record contains the name of a person,
-his/her phone number, his/her email-address, and a code for their relationship
+his/her phone number, his/her email address, and a code for his/her relationship
with the author of the list.
The columns are aligned using spaces.
An @samp{A} in the last column
@@ -3110,8 +3176,8 @@ empty action that does nothing (i.e., no lines are printed).
Many practical @command{awk} programs are just a line or two. Following is a
collection of useful, short programs to get you started. Some of these
programs contain constructs that haven't been covered yet. (The description
-of the program will give you a good idea of what is going on, but please
-read the rest of the @value{DOCUMENT} to become an @command{awk} expert!)
+of the program will give you a good idea of what is going on, but you'll
+need to read the rest of the @value{DOCUMENT} to become an @command{awk} expert!)
Most of the examples use a @value{DF} named @file{data}. This is just a
placeholder; if you use these programs yourself, substitute
your own @value{FN}s for @file{data}.
@@ -3152,7 +3218,7 @@ expand data | awk '@{ if (x < length($0)) x = length($0) @}
@end example
This example differs slightly from the previous one:
-The input is processed by the @command{expand} utility to change TABs
+the input is processed by the @command{expand} utility to change TABs
into spaces, so the widths compared are actually the right-margin columns,
as opposed to the number of input characters on each line.
@@ -3406,7 +3472,7 @@ lines in the middle of a regular expression or a string.
with the C shell.} It works for @command{awk} programs in files and
for one-shot programs, @emph{provided} you are using a POSIX-compliant
shell, such as the Unix Bourne shell or Bash. But the C shell behaves
-differently! There, you must use two backslashes in a row, followed by
+differently! There you must use two backslashes in a row, followed by
a newline. Note also that when using the C shell, @emph{every} newline
in your @command{awk} program must be escaped with a backslash. To illustrate:
@@ -3447,9 +3513,9 @@ starts a comment, it ignores @emph{everything} on the rest of the
line. For example:
@example
-$ gawk 'BEGIN @{ print "dont panic" # a friendly \
-> BEGIN rule
-> @}'
+$ @kbd{gawk 'BEGIN @{ print "dont panic" # a friendly \}
+> @kbd{ BEGIN rule}
+> @kbd{@}'}
@error{} gawk: cmd. line:2: BEGIN rule
@error{} gawk: cmd. line:2: ^ syntax error
@end example
@@ -3499,7 +3565,7 @@ and array sorting.
As we develop our presentation of the @command{awk} language, we introduce
most of the variables and many of the functions. They are described
-systematically in @ref{Built-in Variables}, and in
+systematically in @DBREF{Built-in Variables} and in
@ref{Built-in}.
@node When
@@ -3533,8 +3599,8 @@ eight-bit microprocessors,
@end ifset
and a microcode assembler for a special-purpose Prolog
computer.
-While the original @command{awk}'s capabilities were strained by tasks
-of such complexity, modern versions are more capable.
+The original @command{awk}'s capabilities were strained by tasks
+of such complexity, but modern versions are more capable.
@cindex @command{awk} programs, complex
If you find yourself writing @command{awk} scripts of more than, say,
@@ -3589,7 +3655,7 @@ a comma, open brace, question mark, colon,
This @value{CHAPTER} covers how to run @command{awk}, both POSIX-standard
and @command{gawk}-specific command-line options, and what
@command{awk} and
-@command{gawk} do with non-option arguments.
+@command{gawk} do with nonoption arguments.
It then proceeds to cover how @command{gawk} searches for source files,
reading standard input along with other files, @command{gawk}'s
environment variables, @command{gawk}'s exit status, using include files,
@@ -3633,7 +3699,7 @@ enclosed in [@dots{}] in these templates are optional:
@cindex GNU long options
@cindex long options
@cindex options, long
-Besides traditional one-letter POSIX-style options, @command{gawk} also
+In addition to traditional one-letter POSIX-style options, @command{gawk} also
supports GNU long options.
@cindex dark corner, invoking @command{awk}
@@ -3696,7 +3762,7 @@ Set the @code{FS} variable to @var{fs}
@cindex @option{--file} option
@cindex @command{awk} programs, location of
Read @command{awk} program source from @var{source-file}
-instead of in the first non-option argument.
+instead of in the first nonoption argument.
This option may be given multiple times; the @command{awk}
program consists of the concatenation of the contents of
each specified @var{source-file}.
@@ -3956,7 +4022,7 @@ care to search for all occurrences of each inappropriate construct. As
@itemx @option{--bignum}
@cindex @option{-M} option
@cindex @option{--bignum} option
-Force arbitrary precision arithmetic on numbers. This option has no effect
+Force arbitrary-precision arithmetic on numbers. This option has no effect
if @command{gawk} is not compiled to use the GNU MPFR and MP libraries
(@pxref{Arbitrary Precision Arithmetic}).
@@ -3972,10 +4038,8 @@ values in input data
(@pxref{Nondecimal Data}).
@quotation CAUTION
-This option can severely break old programs.
-Use with care.
-
-This option may disappear in a future version of @command{gawk}.
+This option can severely break old programs. Use with care. Also note
+that this option may disappear in a future version of @command{gawk}.
@end quotation
@item @option{-N}
@@ -4009,7 +4073,7 @@ pretty-print the program and not run it.
@cindex @option{--optimize} option
@cindex @option{-O} option
Enable some optimizations on the internal representation of the program.
-At the moment this includes just simple constant folding.
+At the moment, this includes just simple constant folding.
@item @option{-p}[@var{file}]
@itemx @option{--profile}[@code{=}@var{file}]
@@ -4086,8 +4150,8 @@ Allow interval expressions
(@pxref{Regexp Operators})
in regexps.
This is now @command{gawk}'s default behavior.
-Nevertheless, this option remains both for backward compatibility,
-and for use in combination with @option{--traditional}.
+Nevertheless, this option remains (both for backward compatibility
+and for use in combination with @option{--traditional}).
@item @option{-S}
@itemx @option{--sandbox}
@@ -4140,7 +4204,7 @@ If it is, @command{awk} reads its program source from all of the named files, as
if they had been concatenated together into one big file. This is
useful for creating libraries of @command{awk} functions. These functions
can be written once and then retrieved from a standard place, instead
-of having to be included into each individual program.
+of having to be included in each individual program.
The @option{-i} option is similar in this regard.
(As mentioned in
@ref{Definition Syntax},
@@ -4151,7 +4215,7 @@ if the program is entered at the keyboard,
by specifying @samp{-f /dev/tty}. After typing your program,
type @kbd{Ctrl-d} (the end-of-file character) to terminate it.
(You may also use @samp{-f -} to read program source from the standard
-input but then you will not be able to also use the standard input as a
+input, but then you will not be able to also use the standard input as a
source of data.)
Because it is clumsy using the standard @command{awk} mechanisms to mix
@@ -4164,7 +4228,7 @@ options may also be used multiple times on the command line.
@cindex @option{-e} option
If no @option{-f} or @option{-e} option is specified, then @command{gawk}
-uses the first non-option command-line argument as the text of the
+uses the first nonoption command-line argument as the text of the
program source code.
@cindex @env{POSIXLY_CORRECT} environment variable
@@ -4231,7 +4295,7 @@ All the command-line arguments are made available to your @command{awk} program
and the program text (if present) are omitted from @code{ARGV}.
All other arguments, including variable assignments, are
included. As each element of @code{ARGV} is processed, @command{gawk}
-sets the variable @code{ARGIND} to the index in @code{ARGV} of the
+sets @code{ARGIND} to the index in @code{ARGV} of the
current element.
@c FIXME: One day, move the ARGC and ARGV node closer to here.
@@ -4408,7 +4472,7 @@ value of @env{AWKPATH}.
@code{ENVIRON["AWKPATH"]}. This provides access to the actual search
path value from within an @command{awk} program.
-While you can change @code{ENVIRON["AWKPATH"]} within your @command{awk}
+Although you can change @code{ENVIRON["AWKPATH"]} within your @command{awk}
program, this has no effect on the running program's behavior. This makes
sense: the @env{AWKPATH} environment variable is used to find the program
source files. Once your program is running, all the files have been
@@ -4444,7 +4508,7 @@ path value from within an @command{awk} program.
A number of other environment variables affect @command{gawk}'s
behavior, but they are more specialized. Those in the following
-list are meant to be used by regular users.
+list are meant to be used by regular users:
@table @env
@item GAWK_MSEC_SLEEP
@@ -4464,7 +4528,7 @@ retry a two-way TCP/IP (socket) connection before giving up.
@xref{TCP/IP Networking}.
@item POSIXLY_CORRECT
-Causes @command{gawk} to switch to POSIX compatibility
+Causes @command{gawk} to switch to POSIX-compatibility
mode, disabling all traditional and GNU extensions.
@xref{Options}.
@end table
@@ -4496,11 +4560,11 @@ for debugging problems on filesystems on non-POSIX operating systems
where I/O is performed in records, not in blocks.
@item GAWK_MSG_SRC
-If this variable exists, @command{gawk} includes the file
-name and line number within the @command{gawk} source code
+If this variable exists, @command{gawk} includes the @value{FN}
+and line number within the @command{gawk} source code
from which warning and/or fatal messages
are generated. Its purpose is to help isolate the source of a
-message, since there are multiple places which produce the
+message, as there are multiple places which produce the
same warning or error message.
@item GAWK_NO_DFA
@@ -4512,8 +4576,8 @@ supposed to be differences, but occasionally theory and practice don't
coordinate with each other.)
@item GAWK_NO_PP_RUN
-If this variable exists, then when invoked with the @option{--pretty-print}
-option, @command{gawk} skips running the program.
+When @command{gawk} is invoked with the @option{--pretty-print} option,
+it will not run the program if this environment variable exists.
@quotation CAUTION
This variable will not survive into the next major release.
@@ -4552,11 +4616,11 @@ If an error occurs, @command{gawk} exits with the value of
the C constant @code{EXIT_FAILURE}. This is usually one.
If @command{gawk} exits because of a fatal error, the exit
-status is 2. On non-POSIX systems, this value may be mapped
+status is two. On non-POSIX systems, this value may be mapped
to @code{EXIT_FAILURE}.
@node Include Files
-@section Including Other Files Into Your Program
+@section Including Other Files into Your Program
@c Panos Papadopoulos <panos1962@gmail.com> contributed the original
@c text for this section.
@@ -4605,9 +4669,9 @@ $ @kbd{gawk -f test2}
@print{} This is script test2.
@end example
-@code{gawk} runs the @file{test2} script which includes @file{test1}
+@code{gawk} runs the @file{test2} script, which includes @file{test1}
using the @code{@@include}
-keyword. So, to include external @command{awk} source files you just
+keyword. So, to include external @command{awk} source files, you just
use @code{@@include} followed by the name of the file to be included,
enclosed in double quotes.
@@ -4644,26 +4708,26 @@ The @value{FN} can, of course, be a pathname. For example:
@end example
@noindent
-or:
+and:
@example
@@include "/usr/awklib/network"
@end example
@noindent
-are valid. The @env{AWKPATH} environment variable can be of great
+are both valid. The @env{AWKPATH} environment variable can be of great
value when using @code{@@include}. The same rules for the use
of the @env{AWKPATH} variable in command-line file searches
(@pxref{AWKPATH Variable}) apply to
@code{@@include} also.
This is very helpful in constructing @command{gawk} function libraries.
-If you have a large script with useful, general purpose @command{awk}
+If you have a large script with useful, general-purpose @command{awk}
functions, you can break it down into library files and put those files
in a special directory. You can then include those ``libraries,'' using
either the full pathnames of the files, or by setting the @env{AWKPATH}
environment variable accordingly and then using @code{@@include} with
-just the file part of the full pathname. Of course you can have more
+just the file part of the full pathname. Of course, you can have more
than one directory to keep library files; the more complex the working
environment is, the more directories you may need to organize the files
to be included.
@@ -4681,7 +4745,7 @@ searched first for source files, before searching in @env{AWKPATH},
and this also applies to files named with @code{@@include}.
@node Loading Shared Libraries
-@section Loading Dynamic Extensions Into Your Program
+@section Loading Dynamic Extensions into Your Program
This @value{SECTION} describes a feature that is specific to @command{gawk}.
@@ -4691,7 +4755,7 @@ This @value{SECTION} describes a feature that is specific to @command{gawk}.
The @code{@@load} keyword can be used to read external @command{awk} extensions
(stored as system shared libraries).
This allows you to link in compiled code that may offer superior
-performance and/or give you access to extended capabilities not supported
+performance and/or give you access to extended capabilities not supported
by the @command{awk} language. The @env{AWKLIBPATH} variable is used to
search for the extension. Using @code{@@load} is completely equivalent
to using the @option{-l} command-line option.
@@ -4699,7 +4763,7 @@ to using the @option{-l} command-line option.
If the extension is not initially found in @env{AWKLIBPATH}, another
search is conducted after appending the platform's default shared library
suffix to the @value{FN}. For example, on GNU/Linux systems, the suffix
-@samp{.so} is used.
+@samp{.so} is used:
@example
$ @kbd{gawk '@@load "ordchr"; BEGIN @{print chr(65)@}'}
@@ -4834,13 +4898,13 @@ The three standard options for all versions of @command{awk} are
and many others, as well as corresponding GNU-style long options.
@item
-Non-option command-line arguments are usually treated as @value{FN}s,
+Nonoption command-line arguments are usually treated as @value{FN}s,
unless they have the form @samp{@var{var}=@var{value}}, in which case
they are taken as variable assignments to be performed at that point
in processing the input.
@item
-All non-option command-line arguments, excluding the program text,
+All nonoption command-line arguments, excluding the program text,
are placed in the @code{ARGV} array. Adjusting @code{ARGC} and @code{ARGV}
affects how @command{awk} processes input.
@@ -4889,7 +4953,7 @@ belongs to that set.
The simplest regular expression is a sequence of letters, numbers, or
both. Such a regexp matches any string that contains that sequence.
Thus, the regexp @samp{foo} matches any string containing @samp{foo}.
-Therefore, the pattern @code{/foo/} matches any input record containing
+Thus, the pattern @code{/foo/} matches any input record containing
the three adjacent characters @samp{foo} @emph{anywhere} in the record. Other
kinds of regexps let you specify more complicated classes of strings.
@@ -4952,17 +5016,16 @@ and @samp{!~} perform regular expression comparisons. Expressions
using these operators can be used as patterns, or in @code{if},
@code{while}, @code{for}, and @code{do} statements.
(@xref{Statements}.)
-For example:
+For example, the following is true if the expression @var{exp} (taken
+as a string) matches @var{regexp}:
@example
@var{exp} ~ /@var{regexp}/
@end example
@noindent
-is true if the expression @var{exp} (taken as a string)
-matches @var{regexp}. The following example matches, or selects,
-all input records with the uppercase letter @samp{J} somewhere in the
-first field:
+This example matches, or selects, all input records with the uppercase
+letter @samp{J} somewhere in the first field:
@example
$ @kbd{awk '$1 ~ /J/' inventory-shipped}
@@ -5032,9 +5095,9 @@ string or regexp. Thus, the string whose contents are the two characters
@samp{"} and @samp{\} must be written @code{"\"\\"}.
Other escape sequences represent unprintable characters
-such as TAB or newline. While there is nothing to stop you from entering most
+such as TAB or newline. There is nothing to stop you from entering most
unprintable characters directly in a string constant or regexp constant,
-they may look ugly.
+but they may look ugly.
The following list presents
all the escape sequences used in @command{awk} and
@@ -5107,7 +5170,7 @@ undefined results. (The @samp{\x} escape sequence is not allowed in
POSIX @command{awk}.)
@quotation CAUTION
-The next major relase of @command{gawk} will change, such
+The next major release of @command{gawk} will change, such
that a maximum of two hexadecimal digits following the
@samp{\x} will be used.
@end quotation
@@ -5119,7 +5182,7 @@ A literal slash (necessary for regexp constants only).
This sequence is used when you want to write a regexp
constant that contains a slash
(such as @code{/.*:\/home\/[[:alnum:]]+:.*/}; the @samp{[[:alnum:]]}
-notation is discussed shortly, in @ref{Bracket Expressions}).
+notation is discussed in @ref{Bracket Expressions}).
Because the regexp is delimited by
slashes, you need to escape any slash that is part of the pattern,
in order to tell @command{awk} to keep processing the rest of the regexp.
@@ -5142,7 +5205,7 @@ with a backslash have special meaning in regexps.
In a regexp, a backslash before any character that is not in the previous list
and not listed in
-@ref{GNU Regexp Operators},
+@DBREF{GNU Regexp Operators}
means that the next character should be taken literally, even if it would
normally be a regexp operator. For example, @code{/a\+b/} matches the three
characters @samp{a+b}.
@@ -5153,25 +5216,7 @@ characters @samp{a+b}.
For complete portability, do not use a backslash before any character not
shown in the previous list and that is not an operator.
-To summarize:
-
-@itemize @value{BULLET}
-@item
-The escape sequences in the list above are always processed first,
-for both string constants and regexp constants. This happens very early,
-as soon as @command{awk} reads your program.
-
-@item
-@command{gawk} processes both regexp constants and dynamic regexps
-(@pxref{Computed Regexps}),
-for the special operators listed in
-@ref{GNU Regexp Operators}.
-
-@item
-A backslash before any other character means to treat that character
-literally.
-@end itemize
-
+@c 11/2014: Moved so as to not stack sidebars
@cindex sidebar, Backslash Before Regular Characters
@ifdocbook
@docbook
@@ -5256,6 +5301,25 @@ In such implementations, typing @code{"a\qc"} is the same as typing
@end cartouche
@end ifnotdocbook
+To summarize:
+
+@itemize @value{BULLET}
+@item
+The escape sequences in the preceding list are always processed first,
+for both string constants and regexp constants. This happens very early,
+as soon as @command{awk} reads your program.
+
+@item
+@command{gawk} processes both regexp constants and dynamic regexps
+(@pxref{Computed Regexps}),
+for the special operators listed in
+@ref{GNU Regexp Operators}.
+
+@item
+A backslash before any other character means to treat that character
+literally.
+@end itemize
+
@cindex sidebar, Escape Sequences for Metacharacters
@ifdocbook
@docbook
@@ -5337,7 +5401,7 @@ sequences and that are not listed in the following stand for themselves:
@cindex backslash (@code{\}), regexp operator
@cindex @code{\} (backslash), regexp operator
@item @code{\}
-This is used to suppress the special meaning of a character when
+This suppresses the special meaning of a character when
matching. For example, @samp{\$}
matches the character @samp{$}.
@@ -5346,8 +5410,9 @@ matches the character @samp{$}.
@cindex @code{^} (caret), regexp operator
@cindex caret (@code{^}), regexp operator
@item @code{^}
-This matches the beginning of a string. For example, @samp{^@@chapter}
-matches @samp{@@chapter} at the beginning of a string and can be used
+This matches the beginning of a string. @samp{^@@chapter}
+matches @samp{@@chapter} at the beginning of a string,
+for example, and can be used
to identify chapter beginnings in Texinfo source files.
The @samp{^} is known as an @dfn{anchor}, because it anchors the pattern to
match only at the beginning of the string.
@@ -5453,7 +5518,7 @@ There are two subtle points to understand about how @samp{*} works.
First, the @samp{*} applies only to the single preceding regular expression
component (e.g., in @samp{ph*}, it applies just to the @samp{h}).
To cause @samp{*} to apply to a larger sub-expression, use parentheses:
-@samp{(ph)*} matches @samp{ph}, @samp{phph}, @samp{phphph} and so on.
+@samp{(ph)*} matches @samp{ph}, @samp{phph}, @samp{phphph}, and so on.
Second, @samp{*} finds as many repetitions as possible. If the text
to be matched is @samp{phhhhhhhhhhhhhhooey}, @samp{ph*} matches all of
@@ -5553,7 +5618,7 @@ expressions are not available in regular expressions.
@cindex range expressions (regexps)
@cindex character lists in regular expression
-As mentioned earlier, a bracket expression matches any character amongst
+As mentioned earlier, a bracket expression matches any character among
those listed between the opening and closing square brackets.
Within a bracket expression, a @dfn{range expression} consists of two
@@ -5611,23 +5676,23 @@ a keyword denoting the class, and @samp{:]}.
POSIX standard.
@float Table,table-char-classes
-@caption{POSIX Character Classes}
+@caption{POSIX character classes}
@multitable @columnfractions .15 .85
@headitem Class @tab Meaning
-@item @code{[:alnum:]} @tab Alphanumeric characters.
-@item @code{[:alpha:]} @tab Alphabetic characters.
-@item @code{[:blank:]} @tab Space and TAB characters.
-@item @code{[:cntrl:]} @tab Control characters.
-@item @code{[:digit:]} @tab Numeric characters.
-@item @code{[:graph:]} @tab Characters that are both printable and visible.
-(A space is printable but not visible, whereas an @samp{a} is both.)
-@item @code{[:lower:]} @tab Lowercase alphabetic characters.
-@item @code{[:print:]} @tab Printable characters (characters that are not control characters).
-@item @code{[:punct:]} @tab Punctuation characters (characters that are not letters, digits,
-control characters, or space characters).
-@item @code{[:space:]} @tab Space characters (such as space, TAB, and formfeed, to name a few).
-@item @code{[:upper:]} @tab Uppercase alphabetic characters.
-@item @code{[:xdigit:]} @tab Characters that are hexadecimal digits.
+@item @code{[:alnum:]} @tab Alphanumeric characters
+@item @code{[:alpha:]} @tab Alphabetic characters
+@item @code{[:blank:]} @tab Space and TAB characters
+@item @code{[:cntrl:]} @tab Control characters
+@item @code{[:digit:]} @tab Numeric characters
+@item @code{[:graph:]} @tab Characters that are both printable and visible
+(a space is printable but not visible, whereas an @samp{a} is both)
+@item @code{[:lower:]} @tab Lowercase alphabetic characters
+@item @code{[:print:]} @tab Printable characters (characters that are not control characters)
+@item @code{[:punct:]} @tab Punctuation characters (characters that are not letters, digits
+control characters, or space characters)
+@item @code{[:space:]} @tab Space characters (such as space, TAB, and formfeed, to name a few)
+@item @code{[:upper:]} @tab Uppercase alphabetic characters
+@item @code{[:xdigit:]} @tab Characters that are hexadecimal digits
@end multitable
@end float
@@ -5642,7 +5707,7 @@ and numeric characters in your character set.
@c Thanks to
@c Date: Tue, 01 Jul 2014 07:39:51 +0200
@c From: Hermann Peifer <peifer@gmx.eu>
-Some utilities that match regular expressions provide a non-standard
+Some utilities that match regular expressions provide a nonstandard
@code{[:ascii:]} character class; @command{awk} does not. However, you
can simulate such a construct using @code{[\x00-\x7F]}. This matches
all values numerically between zero and 127, which is the defined
@@ -5833,7 +5898,7 @@ $ @kbd{awk '$0 ~ "[ \t\n]"'}
@error{} ]...
@error{} source line number 1
@error{} context is
-@error{} $0 ~ "[ >>> \t\n]" <<<
+@error{} $0 ~ "[ >>> \t\n]" <<<
@end example
@cindex newlines, in regexp constants
@@ -5871,7 +5936,7 @@ $ @kbd{awk '$0 ~ "[ \t\n]"'}
@error{} ]...
@error{} source line number 1
@error{} context is
-@error{} $0 ~ "[ >>> \t\n]" <<<
+@error{} $0 ~ "[ >>> \t\n]" <<<
@end example
@cindex newlines, in regexp constants
@@ -5982,9 +6047,9 @@ word-constituent characters. For example,
@cindex regular expressions, operators, for buffers
@cindex operators, string-matching, for buffers
There are two other operators that work on buffers. In Emacs, a
-@dfn{buffer} is, naturally, an Emacs buffer. For other programs,
-@command{gawk}'s regexp library routines consider the entire
-string to match as the buffer.
+@dfn{buffer} is, naturally, an Emacs buffer.
+Other GNU programs, including @command{gawk},
+consider the entire string to match as the buffer.
The operators are:
@table @code
@@ -6045,16 +6110,16 @@ in @ref{Regexp Operators}.
@end ifnottex
@item @code{--posix}
-Only POSIX regexps are supported; the GNU operators are not special
+Match only POSIX regexps; the GNU operators are not special
(e.g., @samp{\w} matches a literal @samp{w}). Interval expressions
are allowed.
@cindex Brian Kernighan's @command{awk}
@item @code{--traditional}
-Traditional Unix @command{awk} regexps are matched. The GNU operators
+Match traditional Unix @command{awk} regexps. The GNU operators
are not special, and interval expressions are not available.
-The POSIX character classes (@samp{[[:alnum:]]}, etc.) are supported,
-as BWK @command{awk} supports them.
+Because BWK @command{awk} supports them,
+the POSIX character classes (@samp{[[:alnum:]]}, etc.) are available.
Characters described by octal and hexadecimal escape sequences are
treated literally, even if they represent regexp metacharacters.
@@ -6114,7 +6179,7 @@ When @code{IGNORECASE} is not zero, @emph{all} regexp and string
operations ignore case.
Changing the value of @code{IGNORECASE} dynamically controls the
-case-sensitivity of the program as it runs. Case is significant by
+case sensitivity of the program as it runs. Case is significant by
default because @code{IGNORECASE} (like most variables) is initialized
to zero:
@@ -6127,7 +6192,7 @@ if (x ~ /ab/) @dots{} # now it will succeed
@end example
In general, you cannot use @code{IGNORECASE} to make certain rules
-case-insensitive and other rules case-sensitive, because there is no
+case insensitive and other rules case sensitive, as there is no
straightforward way
to set @code{IGNORECASE} just for the pattern of
a particular rule.@footnote{Experienced C and C++ programmers will note
@@ -6138,13 +6203,13 @@ and
However, this is somewhat obscure and we don't recommend it.}
To do this, use either bracket expressions or @code{tolower()}. However, one
thing you can do with @code{IGNORECASE} only is dynamically turn
-case-sensitivity on or off for all the rules at once.
+case sensitivity on or off for all the rules at once.
@code{IGNORECASE} can be set on the command line or in a @code{BEGIN} rule
(@pxref{Other Arguments}; also
@pxref{Using BEGIN/END}).
Setting @code{IGNORECASE} from the command line is a way to make
-a program case-insensitive without having to edit it.
+a program case insensitive without having to edit it.
@c @cindex ISO 8859-1
@c @cindex ISO Latin-1
@@ -6181,12 +6246,12 @@ in conditional expressions, or as part of matching expressions
using the @samp{~} and @samp{!~} operators.
@item
-Escape sequences let you represent non-printable characters and
+Escape sequences let you represent nonprintable characters and
also let you represent regexp metacharacters as literal characters
to be matched.
@item
-Regexp operators provide grouping, alternation and repetition.
+Regexp operators provide grouping, alternation, and repetition.
@item
Bracket expressions give you a shorthand for specifying sets
@@ -6201,8 +6266,8 @@ the match, such as for text substitution and when the record separator
is a regexp.
@item
-Matching expressions may use dynamic regexps, that is, string values
-treated as regular expressions.
+Matching expressions may use dynamic regexps (i.e., string values
+treated as regular expressions).
@item
@command{gawk}'s @code{IGNORECASE} variable lets you control the
@@ -6276,7 +6341,7 @@ used with it do not have to be named on the @command{awk} command line
@command{awk} divides the input for your program into records and fields.
It keeps track of the number of records that have been read so far from
the current input file. This value is stored in a predefined variable
-called @code{FNR} which is reset to zero every time a new file is started.
+called @code{FNR}, which is reset to zero every time a new file is started.
Another predefined variable, @code{NR}, records the total number of input
records read so far from all @value{DF}s. It starts at zero, but is
never automatically reset to zero.
@@ -6287,7 +6352,7 @@ never automatically reset to zero.
@end menu
@node awk split records
-@subsection Record Splitting With Standard @command{awk}
+@subsection Record Splitting with Standard @command{awk}
@cindex separators, for records
@cindex record separators
@@ -6304,7 +6369,7 @@ the value of @code{RS} can be changed in the @command{awk} program
with the assignment operator, @samp{=}
(@pxref{Assignment Ops}).
The new record-separator character should be enclosed in quotation marks,
-which indicate a string constant. Often the right time to do this is
+which indicate a string constant. Often, the right time to do this is
at the beginning of execution, before any input is processed,
so that the very first record is read with the proper separator.
To do this, use the special @code{BEGIN} pattern
@@ -6318,7 +6383,7 @@ awk 'BEGIN @{ RS = "u" @}
@noindent
changes the value of @code{RS} to @samp{u}, before reading any input.
-This is a string whose first character is the letter ``u;'' as a result, records
+This is a string whose first character is the letter ``u''; as a result, records
are separated by the letter ``u.'' Then the input file is read, and the second
rule in the @command{awk} program (the action with no pattern) prints each
record. Because each @code{print} statement adds a newline at the end of
@@ -6366,7 +6431,7 @@ $ @kbd{awk 'BEGIN @{ RS = "u" @}}
@print{} m@@ny
@print{} .ed
@print{} R
-@print{}
+@print{}
@end example
@noindent
@@ -6412,7 +6477,7 @@ being fully POSIX-compliant (@pxref{Options}).
Then, the following (extreme) pipeline prints a surprising @samp{1}:
@example
-$ echo | gawk --posix 'BEGIN @{ RS = "a" @} ; @{ print NF @}'
+$ @kbd{echo | gawk --posix 'BEGIN @{ RS = "a" @} ; @{ print NF @}'}
@print{} 1
@end example
@@ -6434,7 +6499,7 @@ The empty string @code{""} (a string without any characters)
has a special meaning
as the value of @code{RS}. It means that records are separated
by one or more blank lines and nothing else.
-@xref{Multiple Line}, for more details.
+@DBXREF{Multiple Line} for more details.
If you change the value of @code{RS} in the middle of an @command{awk} run,
the new value is used to delimit subsequent records, but the record
@@ -6454,7 +6519,7 @@ sets the variable @code{RT} to the text in the input that matched
@code{RS}.
@node gawk split records
-@subsection Record Splitting With @command{gawk}
+@subsection Record Splitting with @command{gawk}
@cindex common extensions, @code{RS} as a regexp
@cindex extensions, common@comma{} @code{RS} as a regexp
@@ -6498,11 +6563,11 @@ $ @kbd{echo record 1 AAAA record 2 BBBB record 3 |}
The square brackets delineate the contents of @code{RT}, letting you
see the leading and trailing whitespace. The final value of
@code{RT} is a newline.
-@xref{Simple Sed}, for a more useful example
+@DBXREF{Simple Sed} for a more useful example
of @code{RS} as a regexp and @code{RT}.
If you set @code{RS} to a regular expression that allows optional
-trailing text, such as @samp{RS = "abc(XYZ)?"} it is possible, due
+trailing text, such as @samp{RS = "abc(XYZ)?"}, it is possible, due
to implementation constraints, that @command{gawk} may match the leading
part of the regular expression, but not the trailing part, particularly
if the input text that could match the trailing part is fairly long.
@@ -6570,9 +6635,9 @@ character as a record separator. However, this is a special case:
@cindex records, treating files as
@cindex treating files, as single records
-@xref{Readfile Function}, for an interesting way to read
-whole files. If you are using @command{gawk}, see @ref{Extension Sample
-Readfile}, for another option.
+@DBXREF{Readfile Function} for an interesting way to read
+whole files. If you are using @command{gawk}, see @DBREF{Extension Sample
+Readfile} for another option.
@docbook
</sidebar>
@@ -6621,9 +6686,9 @@ character as a record separator. However, this is a special case:
@cindex records, treating files as
@cindex treating files, as single records
-@xref{Readfile Function}, for an interesting way to read
-whole files. If you are using @command{gawk}, see @ref{Extension Sample
-Readfile}, for another option.
+@DBXREF{Readfile Function} for an interesting way to read
+whole files. If you are using @command{gawk}, see @DBREF{Extension Sample
+Readfile} for another option.
@end cartouche
@end ifnotdocbook
@c ENDOFRANGE inspl
@@ -6646,9 +6711,9 @@ called @dfn{fields}. By default, fields are separated by @dfn{whitespace},
like words in a line.
Whitespace in @command{awk} means any string of one or more spaces,
TABs, or newlines;@footnote{In POSIX @command{awk}, newlines are not
-considered whitespace for separating fields.} other characters, such as
-formfeed, vertical tab, etc., that are
-considered whitespace by other languages, are @emph{not} considered
+considered whitespace for separating fields.} other characters
+that are considered whitespace by other languages
+(such as formfeed, vertical tab, etc.) are @emph{not} considered
whitespace by @command{awk}.
The purpose of fields is to make it more convenient for you to refer to
@@ -6665,7 +6730,7 @@ to refer to a field in an @command{awk} program,
followed by the number of the field you want. Thus, @code{$1}
refers to the first field, @code{$2} to the second, and so on.
(Unlike the Unix shells, the field numbers are not limited to single digits.
-@code{$127} is the one hundred twenty-seventh field in the record.)
+@code{$127} is the 127th field in the record.)
For example, suppose the following is a line of input:
@example
@@ -6735,7 +6800,7 @@ awk '@{ print $NR @}'
@noindent
Recall that @code{NR} is the number of records read so far: one in the
-first record, two in the second, etc. So this example prints the first
+first record, two in the second, and so on. So this example prints the first
field of the first record, the second field of the second record, and so
on. For the twentieth record, field number 20 is printed; most likely,
the record has fewer than 20 fields, so this prints a blank line.
@@ -6752,7 +6817,7 @@ The parentheses are used so that the multiplication is done before the
@samp{$} operation; they are necessary whenever there is a binary
operator@footnote{A @dfn{binary operator}, such as @samp{*} for
multiplication, is one that takes two operands. The distinction
-is required, since @command{awk} also has unary (one-operand)
+is required, because @command{awk} also has unary (one-operand)
and ternary (three-operand) operators.}
in the field-number expression. This example, then, prints the
type of relationship (the fourth field) for every line of the file
@@ -6826,7 +6891,7 @@ $ @kbd{awk '@{ $2 = $2 - 10; print $0 @}' inventory-shipped}
@dots{}
@end example
-It is also possible to also assign contents to fields that are out
+It is also possible to assign contents to fields that are out
of range. For example:
@example
@@ -6877,9 +6942,9 @@ else
@noindent
should print @samp{everything is normal}, because @code{NF+1} is certain
-to be out of range. (@xref{If Statement},
+to be out of range. (@DBXREF{If Statement}
for more information about @command{awk}'s @code{if-else} statements.
-@xref{Typing and Comparison},
+@DBXREF{Typing and Comparison}
for more information about the @samp{!=} operator.)
It is important to note that making an assignment to an existing field
@@ -6919,8 +6984,8 @@ after the new value of @code{NF} and recomputes @code{$0}.
Here is an example:
@example
-$ echo a b c d e f | awk '@{ print "NF =", NF;
-> NF = 3; print $0 @}'
+$ @kbd{echo a b c d e f | awk '@{ print "NF =", NF;}
+> @kbd{ NF = 3; print $0 @}'}
@print{} NF = 6
@print{} a b c
@end example
@@ -6969,7 +7034,7 @@ in a record simply by setting @code{FS} and @code{OFS}, and then
expecting a plain @samp{print} or @samp{print $0} to print the
modified record.
-But this does not work, since nothing was done to change the record
+But this does not work, because nothing was done to change the record
itself. Instead, you must force the record to be rebuilt, typically
with a statement such as @samp{$1 = $1}, as described earlier.
@@ -6994,7 +7059,7 @@ in a record simply by setting @code{FS} and @code{OFS}, and then
expecting a plain @samp{print} or @samp{print $0} to print the
modified record.
-But this does not work, since nothing was done to change the record
+But this does not work, because nothing was done to change the record
itself. Instead, you must force the record to be rebuilt, typically
with a statement such as @samp{$1 = $1}, as described earlier.
@end cartouche
@@ -7047,7 +7112,7 @@ the Unix Bourne shell, @command{sh}, or Bash).
@cindex @code{FS} variable, changing value of
The value of @code{FS} can be changed in the @command{awk} program with the
assignment operator, @samp{=} (@pxref{Assignment Ops}).
-Often the right time to do this is at the beginning of execution
+Often, the right time to do this is at the beginning of execution
before any input has been processed, so that the very first record
is read with the proper separator. To do this, use the special
@code{BEGIN} pattern
@@ -7203,7 +7268,7 @@ statement prints the new @code{$0}.
@cindex dark corner, @code{^}, in @code{FS}
There is an additional subtlety to be aware of when using regular expressions
for field splitting.
-It is not well-specified in the POSIX standard, or anywhere else, what @samp{^}
+It is not well specified in the POSIX standard, or anywhere else, what @samp{^}
means when splitting fields. Does the @samp{^} match only at the beginning of
the entire record? Or is each field separator a new string? It turns out that
different @command{awk} versions answer this question differently, and you
@@ -7369,11 +7434,11 @@ awk -F: '$5 == ""' /etc/passwd
@end example
@node Full Line Fields
-@subsection Making The Full Line Be A Single Field
+@subsection Making the Full Line Be a Single Field
Occasionally, it's useful to treat the whole input line as a
single field. This can be done easily and portably simply by
-setting @code{FS} to @code{"\n"} (a newline).@footnote{Thanks to
+setting @code{FS} to @code{"\n"} (a newline):@footnote{Thanks to
Andrew Schorr for this tip.}
@example
@@ -7383,42 +7448,6 @@ awk -F'\n' '@var{program}' @var{files @dots{}}
@noindent
When you do this, @code{$1} is the same as @code{$0}.
-@node Field Splitting Summary
-@subsection Field-Splitting Summary
-
-It is important to remember that when you assign a string constant
-as the value of @code{FS}, it undergoes normal @command{awk} string
-processing. For example, with Unix @command{awk} and @command{gawk},
-the assignment @samp{FS = "\.."} assigns the character string @code{".."}
-to @code{FS} (the backslash is stripped). This creates a regexp meaning
-``fields are separated by occurrences of any two characters.''
-If instead you want fields to be separated by a literal period followed
-by any single character, use @samp{FS = "\\.."}.
-
-The following list summarizes how fields are split, based on the value
-of @code{FS} (@samp{==} means ``is equal to''):
-
-@table @code
-@item FS == " "
-Fields are separated by runs of whitespace. Leading and trailing
-whitespace are ignored. This is the default.
-
-@item FS == @var{any other single character}
-Fields are separated by each occurrence of the character. Multiple
-successive occurrences delimit empty fields, as do leading and
-trailing occurrences.
-The character can even be a regexp metacharacter; it does not need
-to be escaped.
-
-@item FS == @var{regexp}
-Fields are separated by occurrences of characters that match @var{regexp}.
-Leading and trailing matches of @var{regexp} delimit empty fields.
-
-@item FS == ""
-Each individual character in the record becomes a separate field.
-(This is a common extension; it is not specified by the POSIX standard.)
-@end table
-
@cindex sidebar, Changing @code{FS} Does Not Affect the Fields
@ifdocbook
@docbook
@@ -7523,6 +7552,42 @@ root:nSijPlPhZZwgE:0:0:Root:/:
@end cartouche
@end ifnotdocbook
+@node Field Splitting Summary
+@subsection Field-Splitting Summary
+
+It is important to remember that when you assign a string constant
+as the value of @code{FS}, it undergoes normal @command{awk} string
+processing. For example, with Unix @command{awk} and @command{gawk},
+the assignment @samp{FS = "\.."} assigns the character string @code{".."}
+to @code{FS} (the backslash is stripped). This creates a regexp meaning
+``fields are separated by occurrences of any two characters.''
+If instead you want fields to be separated by a literal period followed
+by any single character, use @samp{FS = "\\.."}.
+
+The following list summarizes how fields are split, based on the value
+of @code{FS} (@samp{==} means ``is equal to''):
+
+@table @code
+@item FS == " "
+Fields are separated by runs of whitespace. Leading and trailing
+whitespace are ignored. This is the default.
+
+@item FS == @var{any other single character}
+Fields are separated by each occurrence of the character. Multiple
+successive occurrences delimit empty fields, as do leading and
+trailing occurrences.
+The character can even be a regexp metacharacter; it does not need
+to be escaped.
+
+@item FS == @var{regexp}
+Fields are separated by occurrences of characters that match @var{regexp}.
+Leading and trailing matches of @var{regexp} delimit empty fields.
+
+@item FS == ""
+Each individual character in the record becomes a separate field.
+(This is a common extension; it is not specified by the POSIX standard.)
+@end table
+
@cindex sidebar, @code{FS} and @code{IGNORECASE}
@ifdocbook
@docbook
@@ -7546,7 +7611,7 @@ print $1
@noindent
The output is @samp{aCa}. If you really want to split fields on an
alphabetic character while ignoring case, use a regexp that will
-do it for you. E.g., @samp{FS = "[c]"}. In this case, @code{IGNORECASE}
+do it for you (e.g., @samp{FS = "[c]"}). In this case, @code{IGNORECASE}
will take effect.
@docbook
@@ -7576,7 +7641,7 @@ print $1
@noindent
The output is @samp{aCa}. If you really want to split fields on an
alphabetic character while ignoring case, use a regexp that will
-do it for you. E.g., @samp{FS = "[c]"}. In this case, @code{IGNORECASE}
+do it for you (e.g., @samp{FS = "[c]"}). In this case, @code{IGNORECASE}
will take effect.
@end cartouche
@end ifnotdocbook
@@ -7587,20 +7652,20 @@ will take effect.
@node Constant Size
@section Reading Fixed-Width Data
-@quotation NOTE
+@cindex data, fixed-width
+@cindex fixed-width data
+@cindex advanced features, fixed-width data
+
+@c O'Reilly doesn't like it as a note the first thing in the section.
This @value{SECTION} discusses an advanced
feature of @command{gawk}. If you are a novice @command{awk} user,
you might want to skip it on the first reading.
-@end quotation
-@cindex data, fixed-width
-@cindex fixed-width data
-@cindex advanced features, fixed-width data
-@command{gawk} provides a facility for dealing with
-fixed-width fields with no distinctive field separator. For example,
-data of this nature arises in the input for old Fortran programs where
-numbers are run together, or in the output of programs that did not
-anticipate the use of their output as input for other programs.
+@command{gawk} provides a facility for dealing with fixed-width fields
+with no distinctive field separator. For example, data of this nature
+arises in the input for old Fortran programs where numbers are run
+together, or in the output of programs that did not anticipate the use
+of their output as input for other programs.
An example of the latter is a table where all the columns are lined up by
the use of a variable number of spaces and @emph{empty fields are just
@@ -7639,15 +7704,10 @@ dave ttyq4 26Jun9115days 46 46 wnewmail
@end group
@end example
-The following program takes the above input, converts the idle time to
+The following program takes this input, converts the idle time to
number of seconds, and prints out the first two fields and the calculated
idle time:
-@quotation NOTE
-This program uses a number of @command{awk} features that
-haven't been introduced yet.
-@end quotation
-
@example
BEGIN @{ FIELDWIDTHS = "9 6 10 6 7 7 35" @}
NR > 2 @{
@@ -7666,6 +7726,11 @@ NR > 2 @{
@}
@end example
+@quotation NOTE
+The preceding program uses a number of @command{awk} features that
+haven't been introduced yet.
+@end quotation
+
Running the program on the data produces the following results:
@example
@@ -7711,17 +7776,16 @@ else
This information is useful when writing a function
that needs to temporarily change @code{FS} or @code{FIELDWIDTHS},
read some records, and then restore the original settings
-(@pxref{Passwd Functions},
+(@DBPXREF{Passwd Functions}
for an example of such a function).
@node Splitting By Content
-@section Defining Fields By Content
+@section Defining Fields by Content
-@quotation NOTE
+@c O'Reilly doesn't like it as a note the first thing in the section.
This @value{SECTION} discusses an advanced
feature of @command{gawk}. If you are a novice @command{awk} user,
you might want to skip it on the first reading.
-@end quotation
@cindex advanced features, specifying field content
Normally, when using @code{FS}, @command{gawk} defines the fields as the
@@ -7732,12 +7796,12 @@ However, there are times when you really want to define the fields by
what they are, and not by what they are not.
The most notorious such case
-is so-called @dfn{comma separated value} (CSV) data. Many spreadsheet programs,
+is so-called @dfn{comma-separated values} (CSV) data. Many spreadsheet programs,
for example, can export their data into text files, where each record is
terminated with a newline, and fields are separated by commas. If only
commas separated the data, there wouldn't be an issue. The problem comes when
-one of the fields contains an @emph{embedded} comma. While there is no
-formal standard specification for CSV data@footnote{At least, we don't know of one.},
+one of the fields contains an @emph{embedded} comma. Although there is no
+formal standard specification for CSV data,@footnote{At least, we don't know of one.}
in such cases, most programs embed the field in double quotes. So we might
have data like this:
@@ -7753,7 +7817,7 @@ The @code{FPAT} variable offers a solution for cases like this.
The value of @code{FPAT} should be a string that provides a regular expression.
This regular expression describes the contents of each field.
-In the case of CSV data as presented above, each field is either ``anything that
+In the case of CSV data as presented here, each field is either ``anything that
is not a comma,'' or ``a double quote, anything that is not a double quote, and a
closing double quote.'' If written as a regular expression constant
(@pxref{Regexp}),
@@ -7818,10 +7882,10 @@ will be @code{"FPAT"} if content-based field splitting is being used.
@quotation NOTE
Some programs export CSV data that contains embedded newlines between
the double quotes. @command{gawk} provides no way to deal with this.
-Since there is no formal specification for CSV data, there isn't much
+Because no formal specification for CSV data exists, there isn't much
more to be done;
the @code{FPAT} mechanism provides an elegant solution for the majority
-of cases, and the @command{gawk} developers are satisfied with that.
+of cases, and the @command{gawk} developers are satisfied with that.
@end quotation
As written, the regexp used for @code{FPAT} requires that each field
@@ -7975,7 +8039,7 @@ $ @kbd{awk -f addrs.awk addresses}
@dots{}
@end example
-@xref{Labels Program}, for a more realistic program that deals with
+@DBXREF{Labels Program} for a more realistic program dealing with
address lists. The following list summarizes how records are split,
based on the value of
@ifinfo
@@ -8070,7 +8134,7 @@ represents a shell command.
@quotation NOTE
When @option{--sandbox} is specified (@pxref{Options}),
-reading lines from files, pipes and coprocesses is disabled.
+reading lines from files, pipes, and coprocesses is disabled.
@end quotation
@menu
@@ -8213,7 +8277,7 @@ free
@end example
The @code{getline} command used in this way sets only the variables
-@code{NR}, @code{FNR} and @code{RT} (and of course, @var{var}).
+@code{NR}, @code{FNR}, and @code{RT} (and of course, @var{var}).
The record is not
split into fields, so the values of the fields (including @code{$0}) and
the value of @code{NF} do not change.
@@ -8267,7 +8331,7 @@ you want your program to be portable to all @command{awk} implementations.
Use @samp{getline @var{var} < @var{file}} to read input
from the file
-@var{file}, and put it in the variable @var{var}. As above, @var{file}
+@var{file}, and put it in the variable @var{var}. As earlier, @var{file}
is a string-valued expression that specifies the file from which to read.
In this version of @code{getline}, none of the predefined variables are
@@ -8303,7 +8367,7 @@ One deficiency of this program is that it does not process nested
@code{@@include} statements
(i.e., @code{@@include} statements in included files)
the way a true macro preprocessor would.
-@xref{Igawk Program}, for a program
+@DBXREF{Igawk Program} for a program
that does handle nested @code{@@include} statements.
@node Getline/Pipe
@@ -8602,7 +8666,7 @@ and whether the variant is standard or a @command{gawk} extension.
Note: for each variant, @command{gawk} sets the @code{RT} predefined variable.
@float Table,table-getline-variants
-@caption{@code{getline} Variants and What They Set}
+@caption{@code{getline} variants and what they set}
@multitable @columnfractions .33 .38 .27
@headitem Variant @tab Effect @tab @command{awk} / @command{gawk}
@item @code{getline} @tab Sets @code{$0}, @code{NF}, @code{FNR}, @code{NR}, and @code{RT} @tab @command{awk}
@@ -8620,7 +8684,7 @@ Note: for each variant, @command{gawk} sets the @code{RT} predefined variable.
@c ENDOFRANGE infir
@node Read Timeout
-@section Reading Input With A Timeout
+@section Reading Input with a Timeout
@cindex timeout, reading input
@cindex differences in @command{awk} and @command{gawk}, read timeouts
@@ -8628,7 +8692,7 @@ This @value{SECTION} describes a feature that is specific to @command{gawk}.
You may specify a timeout in milliseconds for reading input from the keyboard,
a pipe, or two-way communication, including TCP/IP sockets. This can be done
-on a per input, command or connection basis, by setting a special element
+on a per input, command, or connection basis, by setting a special element
in the @code{PROCINFO} array (@pxref{Auto-set}):
@example
@@ -8702,11 +8766,11 @@ You should not assume that the read operation will block
exactly after the tenth record has been printed. It is possible that
@command{gawk} will read and buffer more than one record's
worth of data the first time. Because of this, changing the value
-of timeout like in the above example is not very useful.
+of timeout like in the preceding example is not very useful.
@end quotation
-If the @code{PROCINFO} element is not present and the environment
-variable @env{GAWK_READ_TIMEOUT} exists,
+If the @code{PROCINFO} element is not present and the
+@env{GAWK_READ_TIMEOUT} environment variable exists,
@command{gawk} uses its value to initialize the timeout value.
The exclusive use of the environment variable to specify timeout
has the disadvantage of not being able to control it
@@ -8727,7 +8791,7 @@ or the attempt to open a FIFO special file for reading can block
indefinitely until some other process opens it for writing.
@node Command-line directories
-@section Directories On The Command Line
+@section Directories on the Command Line
@cindex differences in @command{awk} and @command{gawk}, command-line directories
@cindex directories, command-line
@cindex command line, directories on
@@ -8742,14 +8806,14 @@ command line, but otherwise ignores it. This makes it easier to use
shell wildcards with your @command{awk} program:
@example
-$ @kbd{gawk -f whizprog.awk *} @ii{Directories could kill this progam}
+$ @kbd{gawk -f whizprog.awk *} @ii{Directories could kill this program}
@end example
If either of the @option{--posix}
or @option{--traditional} options is given, then @command{gawk} reverts
to treating a directory on the command line as a fatal error.
-@xref{Extension Sample Readdir}, for a way to treat directories
+@DBXREF{Extension Sample Readdir} for a way to treat directories
as usable data from an @command{awk} program.
@node Input Summary
@@ -8776,7 +8840,7 @@ The possibilities are as follows:
@item
After splitting the input into records, @command{awk} further splits
-the record into individual fields, named @code{$1}, @code{$2} and so
+the record into individual fields, named @code{$1}, @code{$2}, and so
on. @code{$0} is the whole record, and @code{NF} indicates how many
fields there are. The default way to split fields is between whitespace
characters.
@@ -8790,7 +8854,7 @@ greater than @code{NF} creates the field and rebuilds the record, using
thing. Decrementing @code{NF} throws away fields and rebuilds the record.
@item
-Field splitting is more complicated than record splitting.
+Field splitting is more complicated than record splitting:
@multitable @columnfractions .40 .45 .15
@headitem Field separator value @tab Fields are split @dots{} @tab @command{awk} / @command{gawk}
@@ -8863,7 +8927,7 @@ The @code{print} statement is not limited when
computing @emph{which} values to print. However, with two exceptions,
you cannot specify @emph{how} to print them---how many
columns, whether to use exponential notation or not, and so on.
-(For the exceptions, @pxref{Output Separators}, and
+(For the exceptions, @DBPXREF{Output Separators} and
@ref{OFMT}.)
For printing with specifications, you need the @code{printf} statement
(@pxref{Printf}).
@@ -9060,14 +9124,14 @@ separated by single spaces. However, this doesn't need to be the case;
a single space is simply the default. Any string of
characters may be used as the @dfn{output field separator} by setting the
predefined variable @code{OFS}. The initial value of this variable
-is the string @w{@code{" "}}---that is, a single space.
+is the string @w{@code{" "}} (i.e., a single space).
-The output from an entire @code{print} statement is called an
-@dfn{output record}. Each @code{print} statement outputs one output
-record, and then outputs a string called the @dfn{output record separator}
-(or @code{ORS}). The initial
-value of @code{ORS} is the string @code{"\n"}; i.e., a newline
-character. Thus, each @code{print} statement normally makes a separate line.
+The output from an entire @code{print} statement is called an @dfn{output
+record}. Each @code{print} statement outputs one output record, and
+then outputs a string called the @dfn{output record separator} (or
+@code{ORS}). The initial value of @code{ORS} is the string @code{"\n"}
+(i.e., a newline character). Thus, each @code{print} statement normally
+makes a separate line.
@cindex output, records
@cindex output record separator, See @code{ORS} variable
@@ -9090,27 +9154,27 @@ newline:
$ @kbd{awk 'BEGIN @{ OFS = ";"; ORS = "\n\n" @}}
> @kbd{@{ print $1, $2 @}' mail-list}
@print{} Amelia;555-5553
-@print{}
+@print{}
@print{} Anthony;555-3412
-@print{}
+@print{}
@print{} Becky;555-7685
-@print{}
+@print{}
@print{} Bill;555-1675
-@print{}
+@print{}
@print{} Broderick;555-0542
-@print{}
+@print{}
@print{} Camilla;555-2912
-@print{}
+@print{}
@print{} Fabius;555-1234
-@print{}
+@print{}
@print{} Julie;555-6699
-@print{}
+@print{}
@print{} Martin;555-6480
-@print{}
+@print{}
@print{} Samuel;555-3430
-@print{}
+@print{}
@print{} Jean-Paul;555-2127
-@print{}
+@print{}
@end example
If the value of @code{ORS} does not contain a newline, the program's output
@@ -9191,7 +9255,7 @@ printf @var{format}, @var{item1}, @var{item2}, @dots{}
@end example
@noindent
-As print @code{print}, the entire list of arguments may optionally be
+As for @code{print}, the entire list of arguments may optionally be
enclosed in parentheses. Here too, the parentheses are necessary if any
of the item expressions use the @samp{>} relational operator; otherwise,
it can be confused with an output redirection (@pxref{Redirection}).
@@ -9299,7 +9363,7 @@ which follow the decimal point.
(The @samp{4.3} represents two modifiers,
discussed in the next @value{SUBSECTION}.)
-On systems supporting IEEE 754 floating point format, values
+On systems supporting IEEE 754 floating-point format, values
representing negative
infinity are formatted as
@samp{-inf} or @samp{-infinity},
@@ -9330,7 +9394,7 @@ Print a string.
@item @code{%u}
Print an unsigned decimal integer.
(This format is of marginal use, because all numbers in @command{awk}
-are floating-point; it is provided primarily for compatibility with C.)
+are floating point; it is provided primarily for compatibility with C.)
@item @code{%x}, @code{%X}
Print an unsigned hexadecimal integer;
@@ -9423,7 +9487,7 @@ says to always supply a sign for numeric conversions, even if the data
to format is positive. The @samp{+} overrides the space modifier.
@item #
-Use an ``alternate form'' for certain control letters.
+Use an ``alternative form'' for certain control letters.
For @code{%o}, supply a leading zero.
For @code{%x} and @code{%X}, supply a leading @code{0x} or @samp{0X} for
a nonzero result.
@@ -9440,7 +9504,7 @@ value to print.
@item '
A single quote or apostrophe character is a POSIX extension to ISO C.
-It indicates that the integer part of a floating point value, or the
+It indicates that the integer part of a floating-point value, or the
entire part of an integer decimal value, should have a thousands-separator
character in it. This only works in locales that support such characters.
For example:
@@ -9521,7 +9585,7 @@ prints @samp{foob}.
@end table
The C library @code{printf}'s dynamic @var{width} and @var{prec}
-capability (for example, @code{"%*.*s"}) is supported. Instead of
+capability (e.g., @code{"%*.*s"}) is supported. Instead of
supplying explicit @var{width} and/or @var{prec} values in the format
string, they are passed in the argument list. For example:
@@ -9621,7 +9685,7 @@ awk 'BEGIN @{ print "Name Number"
@{ printf "%-10s %s\n", $1, $2 @}' mail-list
@end example
-The above example mixes @code{print} and @code{printf} statements in
+The preceding example mixes @code{print} and @code{printf} statements in
the same program. Using just @code{printf} statements can produce the
same results:
@@ -9768,7 +9832,7 @@ close(report)
The @code{close()} function is called here because it's a good idea to close
the pipe as soon as all the intended output has been sent to it.
-@xref{Close Files And Pipes},
+@DBXREF{Close Files And Pipes}
for more information.
This example also illustrates the use of a variable to represent
@@ -9792,9 +9856,9 @@ but subsidiary to, the @command{awk} program.
This feature is a @command{gawk} extension, and is not available in
POSIX @command{awk}.
-@xref{Getline/Coprocess},
+@DBXREF{Getline/Coprocess}
for a brief discussion.
-@xref{Two-way I/O},
+@DBXREF{Two-way I/O}
for a more complete discussion.
@end table
@@ -9818,7 +9882,7 @@ print "Avoid improbability generators" >> "guide.txt"
@noindent
This is indeed how redirections must be used from the shell. But in
@command{awk}, it isn't necessary. In this kind of case, a program should
-use @samp{>} for all the @code{print} statements, since the output file
+use @samp{>} for all the @code{print} statements, because the output file
is only opened once. (It happens that if you mix @samp{>} and @samp{>>}
that output is produced in the expected order. However, mixing the operators
for the same file is definitely poor style, and is confusing to readers
@@ -9872,7 +9936,7 @@ The program builds up a list of command lines,
using the @command{mv} utility to rename the files.
It then sends the list to the shell for execution.
-@xref{Shell Quoting}, for a function that can help in generating
+@DBXREF{Shell Quoting} for a function that can help in generating
command lines to be fed to the shell.
@docbook
@@ -9907,7 +9971,7 @@ The program builds up a list of command lines,
using the @command{mv} utility to rename the files.
It then sends the list to the shell for execution.
-@xref{Shell Quoting}, for a function that can help in generating
+@DBXREF{Shell Quoting} for a function that can help in generating
command lines to be fed to the shell.
@end cartouche
@end ifnotdocbook
@@ -9973,7 +10037,7 @@ that happens, writing to the screen is not correct. In fact, if
terminal at all.
Then opening @file{/dev/tty} fails.
-@command{gawk}, BWK @command{awk} and @command{mawk} provide
+@command{gawk}, BWK @command{awk}, and @command{mawk} provide
special @value{FN}s for accessing the three standard streams.
If the @value{FN} matches one of these special names when @command{gawk}
(or one of the others) redirects input or output, then it directly uses
@@ -10016,7 +10080,7 @@ It is a common error to omit the quotes, which leads
to confusing results.
@command{gawk} does not treat these @value{FN}s as special when
-in POSIX compatibility mode. However, since BWK @command{awk}
+in POSIX-compatibility mode. However, because BWK @command{awk}
supports them, @command{gawk} does support them even when
invoked with the @option{--traditional} option (@pxref{Options}).
@@ -10025,7 +10089,7 @@ invoked with the @option{--traditional} option (@pxref{Options}).
@c STARTOFRANGE gfn
@cindex @command{gawk}, file names in
-Besides access to standard input, stanard output, and standard error,
+Besides access to standard input, standard output, and standard error,
@command{gawk} provides access to any open file descriptor.
Additionally, there are special @value{FN}s reserved for
TCP/IP networking.
@@ -10074,7 +10138,7 @@ This is done using a special @value{FN} of the form:
@file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}
@end example
-The @var{net-type} is one of @samp{inet}, @samp{inet4} or @samp{inet6}.
+The @var{net-type} is one of @samp{inet}, @samp{inet4}, or @samp{inet6}.
The @var{protocol} is one of @samp{tcp} or @samp{udp},
and the other fields represent the other essential pieces of information
for making a networking connection.
@@ -10263,7 +10327,7 @@ is not closed and released until @code{close()} is called or
@command{awk} exits.
@code{close()} silently does nothing if given an argument that
-does not represent a file, pipe or coprocess that was opened with
+does not represent a file, pipe, or coprocess that was opened with
a redirection. In such a case, it returns a negative value,
indicating an error. In addition, @command{gawk} sets @code{ERRNO}
to a string indicating the error.
@@ -10302,9 +10366,10 @@ which describes it in more detail and gives an example.
@cindex Unix @command{awk}, @code{close()} function and
In many older versions of Unix @command{awk}, the @code{close()} function
-is actually a statement. It is a syntax error to try and use the return
-value from @code{close()}:
+is actually a statement.
@value{DARKCORNER}
+It is a syntax error to try and use the return
+value from @code{close()}:
@example
command = "@dots{}"
@@ -10358,9 +10423,10 @@ when closing a pipe.
@cindex Unix @command{awk}, @code{close()} function and
In many older versions of Unix @command{awk}, the @code{close()} function
-is actually a statement. It is a syntax error to try and use the return
-value from @code{close()}:
+is actually a statement.
@value{DARKCORNER}
+It is a syntax error to try and use the return
+value from @code{close()}:
@example
command = "@dots{}"
@@ -10424,11 +10490,11 @@ Output from both @code{print} and @code{printf} may be redirected to
files, pipes, and coprocesses.
@item
-@command{gawk} provides special file names for access to standard input,
-output and error, and for network communications.
+@command{gawk} provides special @value{FN}s for access to standard input,
+output, and error, and for network communications.
@item
-Use @code{close()} to close open file, pipe and coprocess redirections.
+Use @code{close()} to close open file, pipe, and coprocess redirections.
For coprocesses, it is possible to close only one direction of the
communications.
@@ -10496,7 +10562,7 @@ combinations of these with various operators.
@end menu
@node Values
-@section Constants, Variables and Conversions
+@section Constants, Variables, and Conversions
Expressions are built up from values and the operations performed
upon them. This @value{SECTION} describes the elementary objects
@@ -10522,7 +10588,7 @@ string, and regular expression.
Each is used in the appropriate context when you need a data
value that isn't going to change. Numeric constants can
-have different forms, but are stored identically internally.
+have different forms, but are internally stored in an identical manner.
@menu
* Scalar Constants:: Numeric and string constants.
@@ -10538,7 +10604,7 @@ have different forms, but are stored identically internally.
A @dfn{numeric constant} stands for a number. This number can be an
integer, a decimal fraction, or a number in scientific (exponential)
notation.@footnote{The internal representation of all numbers,
-including integers, uses double precision floating-point numbers.
+including integers, uses double-precision floating-point numbers.
On most modern systems, these are in IEEE 754 standard format.
@xref{Arbitrary Precision Arithmetic}, for much more information.}
Here are some examples of numeric constants that all
@@ -10552,7 +10618,7 @@ have the same value:
@cindex string constants
A string constant consists of a sequence of characters enclosed in
-double-quotation marks. For example:
+double quotation marks. For example:
@example
"parrot"
@@ -10574,13 +10640,13 @@ implementations may have difficulty with some character codes.
@cindex numbers, octal
@cindex numbers, hexadecimal
-In @command{awk}, all numbers are in decimal; i.e., base 10. Many other
+In @command{awk}, all numbers are in decimal (i.e., base 10). Many other
programming languages allow you to specify numbers in other bases, often
octal (base 8) and hexadecimal (base 16).
-In octal, the numbers go 0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, etc.
+In octal, the numbers go 0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, and so on.
Just as @samp{11}, in decimal, is 1 times 10 plus 1, so
@samp{11}, in octal, is 1 times 8, plus 1. This equals 9 in decimal.
-In hexadecimal, there are 16 digits. Since the everyday decimal
+In hexadecimal, there are 16 digits. Because the everyday decimal
number system only has ten digits (@samp{0}--@samp{9}), the letters
@samp{a} through @samp{f} are used to represent the rest.
(Case in the letters is usually irrelevant; hexadecimal @samp{a} and @samp{A}
@@ -10632,11 +10698,12 @@ you can use the @code{strtonum()} function
to convert the data into a number.
Most of the time, you will want to use octal or hexadecimal constants
when working with the built-in bit manipulation functions;
-see @ref{Bitwise Functions},
+see @DBREF{Bitwise Functions}
for more information.
-Unlike some early C implementations, @samp{8} and @samp{9} are not valid
-in octal constants; e.g., @command{gawk} treats @samp{018} as decimal 18:
+Unlike some early C implementations, @samp{8} and @samp{9} are not
+valid in octal constants. For example, @command{gawk} treats @samp{018}
+as decimal 18:
@example
$ @kbd{gawk 'BEGIN @{ print "021 is", 021 ; print 018 @}'}
@@ -10722,7 +10789,7 @@ matched.
However, regexp constants (such as @code{/foo/}) may be used like simple expressions.
When a
regexp constant appears by itself, it has the same meaning as if it appeared
-in a pattern, i.e., @samp{($0 ~ /foo/)}
+in a pattern (i.e., @samp{($0 ~ /foo/)}).
@value{DARKCORNER}
@xref{Expression Patterns}.
This means that the following two code segments:
@@ -10819,7 +10886,7 @@ either @code{sub()} or @code{gsub()}. However, what really happens is that
the @code{pat} parameter is either one or zero, depending upon whether
or not @code{$0} matches @code{/hi/}.
@command{gawk} issues a warning when it sees a regexp constant used as
-a parameter to a user-defined function, since passing a truth value in
+a parameter to a user-defined function, because passing a truth value in
this way is probably not what was intended.
@c ENDOFRANGE rec
@@ -10859,7 +10926,7 @@ variable's current value. Variables are given new values with
@dfn{decrement operators}.
@xref{Assignment Ops}.
In addition, the @code{sub()} and @code{gsub()} functions can
-change a variable's value, and the @code{match()}, @code{split()}
+change a variable's value, and the @code{match()}, @code{split()},
and @code{patsplit()} functions can change the contents of their
array parameters. @xref{String Functions}.
@@ -10867,7 +10934,7 @@ array parameters. @xref{String Functions}.
@cindex variables, initializing
A few variables have special built-in meanings, such as @code{FS} (the
field separator), and @code{NF} (the number of fields in the current input
-record). @xref{Built-in Variables}, for a list of the predefined variables.
+record). @DBXREF{Built-in Variables} for a list of the predefined variables.
These predefined variables can be used and assigned just like all other
variables, but their values are also used or changed automatically by
@command{awk}. All predefined variables' names are entirely uppercase.
@@ -10908,7 +10975,7 @@ as in the following:
the variable is set at the very beginning, even before the
@code{BEGIN} rules execute. The @option{-v} option and its assignment
must precede all the @value{FN} arguments, as well as the program text.
-(@xref{Options}, for more information about
+(@DBXREF{Options} for more information about
the @option{-v} option.)
Otherwise, the variable assignment is performed at a time determined by
its position among the input file arguments---after the processing of the
@@ -10948,7 +11015,7 @@ sequences
@node Conversion
@subsection Conversion of Strings and Numbers
-Number to string and string to number conversion are generally
+Number-to-string and string-to-number conversion are generally
straightforward. There can be subtleties to be aware of;
this @value{SECTION} discusses this important facet of @command{awk}.
@@ -10959,7 +11026,7 @@ this @value{SECTION} discusses this important facet of @command{awk}.
@end menu
@node Strings And Numbers
-@subsubsection How @command{awk} Converts Between Strings And Numbers
+@subsubsection How @command{awk} Converts Between Strings and Numbers
@cindex converting, strings to numbers
@cindex strings, converting
@@ -10990,7 +11057,7 @@ string, concatenate that number with the empty string, @code{""}.
To force a string to be converted to a number, add zero to that string.
A string is converted to a number by interpreting any numeric prefix
of the string as numerals:
-@code{"2.5"} converts to 2.5, @code{"1e3"} converts to 1000, and @code{"25fix"}
+@code{"2.5"} converts to 2.5, @code{"1e3"} converts to 1,000, and @code{"25fix"}
has a numeric value of 25.
Strings that can't be interpreted as valid numbers convert to zero.
@@ -11030,10 +11097,10 @@ b = a ""
@code{b} has the value @code{"12"}, not @code{"12.00"}.
@value{DARKCORNER}
-@cindex sidebar, Pre-POSIX @command{awk} Used @code{OFMT} For String Conversion
+@cindex sidebar, Pre-POSIX @command{awk} Used @code{OFMT} for String Conversion
@ifdocbook
@docbook
-<sidebar><title>Pre-POSIX @command{awk} Used @code{OFMT} For String Conversion</title>
+<sidebar><title>Pre-POSIX @command{awk} Used @code{OFMT} for String Conversion</title>
@end docbook
@cindex POSIX @command{awk}, @code{OFMT} variable and
@@ -11047,7 +11114,7 @@ specifies the output format to use when printing numbers with @code{print}.
conversion from the semantics of printing. Both @code{CONVFMT} and
@code{OFMT} have the same default value: @code{"%.6g"}. In the vast majority
of cases, old @command{awk} programs do not change their behavior.
-@xref{Print}, for more information on the @code{print} statement.
+@DBXREF{Print} for more information on the @code{print} statement.
@docbook
</sidebar>
@@ -11056,7 +11123,7 @@ of cases, old @command{awk} programs do not change their behavior.
@ifnotdocbook
@cartouche
-@center @b{Pre-POSIX @command{awk} Used @code{OFMT} For String Conversion}
+@center @b{Pre-POSIX @command{awk} Used @code{OFMT} for String Conversion}
@cindex POSIX @command{awk}, @code{OFMT} variable and
@@ -11070,7 +11137,7 @@ specifies the output format to use when printing numbers with @code{print}.
conversion from the semantics of printing. Both @code{CONVFMT} and
@code{OFMT} have the same default value: @code{"%.6g"}. In the vast majority
of cases, old @command{awk} programs do not change their behavior.
-@xref{Print}, for more information on the @code{print} statement.
+@DBXREF{Print} for more information on the @code{print} statement.
@end cartouche
@end ifnotdocbook
@@ -11093,7 +11160,7 @@ The POSIX standard says that @command{awk} always uses the period as the decimal
point when reading the @command{awk} program source code, and for
command-line variable assignments (@pxref{Other Arguments}). However,
when interpreting input data, for @code{print} and @code{printf} output,
-and for number to string conversion, the local decimal point character
+and for number-to-string conversion, the local decimal point character
is used. @value{DARKCORNER} In all cases, numbers in source code and
in input data cannot have a thousands separator. Here are some examples
indicating the difference in behavior, on a GNU/Linux system:
@@ -11118,7 +11185,7 @@ as the full number including the fractional part, 4.321.
Some earlier versions of @command{gawk} fully complied with this aspect
of the standard. However, many users in non-English locales complained
-about this behavior, since their data used a period as the decimal
+about this behavior, because their data used a period as the decimal
point, so the default behavior was restored to use a period as the
decimal point character. You can use the @option{--use-lc-numeric}
option (@pxref{Options}) to force @command{gawk} to use the locale's
@@ -11131,7 +11198,7 @@ point character is used and when a period is used. Some of these
features have not been described yet.
@float Table,table-locale-affects
-@caption{Locale Decimal Point versus A Period}
+@caption{Locale decimal point versus a period}
@multitable @columnfractions .15 .20 .45
@headitem Feature @tab Default @tab @option{--posix} or @option{--use-lc-numeric}
@item @code{%'g} @tab Use locale @tab Use locale
@@ -11141,13 +11208,13 @@ features have not been described yet.
@end multitable
@end float
-Finally, modern day formal standards and IEEE standard floating point
+Finally, modern day formal standards and IEEE standard floating-point
representation can have an unusual but important effect on the way
@command{gawk} converts some special string values to numbers. The details
are presented in @ref{POSIX Floating Point Problems}.
@node All Operators
-@section Operators: Doing Something With Values
+@section Operators: Doing Something with Values
This @value{SECTION} introduces the @dfn{operators} which make use
of the values provided by constants and variables.
@@ -11226,7 +11293,7 @@ Multiplication.
Division; because all numbers in @command{awk} are floating-point
numbers, the result is @emph{not} rounded to an integer---@samp{3 / 4} has
the value 0.75. (It is a common mistake, especially for C programmers,
-to forget that @emph{all} numbers in @command{awk} are floating-point,
+to forget that @emph{all} numbers in @command{awk} are floating point,
and that division of integer-looking constants produces a real number,
not an integer.)
@@ -11311,7 +11378,7 @@ $ @kbd{awk '@{ print "Field number one:" $1 @}' mail-list}
@cindex troubleshooting, string concatenation
Because string concatenation does not have an explicit operator, it is
-often necessary to insure that it happens at the right time by using
+often necessary to ensure that it happens at the right time by using
parentheses to enclose the items to concatenate. For example,
you might expect that the
following code fragment concatenates @code{file} and @code{name}:
@@ -11573,7 +11640,14 @@ The indices of @code{bar} are practically guaranteed to be different, because
@code{rand()} returns different values each time it is called.
(Arrays and the @code{rand()} function haven't been covered yet.
@xref{Arrays},
-and see @ref{Numeric Functions}, for more information).
+and
+@ifnotdocbook
+@DBPXREF{Numeric Functions}
+@end ifnotdocbook
+@ifdocbook
+@DBREF{Numeric Functions}
+@end ifdocbook
+for more information).
This example illustrates an important fact about assignment
operators: the lefthand expression is only evaluated @emph{once}.
@@ -11606,20 +11680,20 @@ to a number.
@cindex @code{*} (asterisk), @code{**=} operator
@cindex asterisk (@code{*}), @code{**=} operator
@float Table,table-assign-ops
-@caption{Arithmetic Assignment Operators}
+@caption{Arithmetic assignment operators}
@multitable @columnfractions .30 .70
@headitem Operator @tab Effect
-@item @var{lvalue} @code{+=} @var{increment} @tab Add @var{increment} to the value of @var{lvalue}.
-@item @var{lvalue} @code{-=} @var{decrement} @tab Subtract @var{decrement} from the value of @var{lvalue}.
-@item @var{lvalue} @code{*=} @var{coefficient} @tab Multiply the value of @var{lvalue} by @var{coefficient}.
-@item @var{lvalue} @code{/=} @var{divisor} @tab Divide the value of @var{lvalue} by @var{divisor}.
-@item @var{lvalue} @code{%=} @var{modulus} @tab Set @var{lvalue} to its remainder by @var{modulus}.
+@item @var{lvalue} @code{+=} @var{increment} @tab Add @var{increment} to the value of @var{lvalue}
+@item @var{lvalue} @code{-=} @var{decrement} @tab Subtract @var{decrement} from the value of @var{lvalue}
+@item @var{lvalue} @code{*=} @var{coefficient} @tab Multiply the value of @var{lvalue} by @var{coefficient}
+@item @var{lvalue} @code{/=} @var{divisor} @tab Divide the value of @var{lvalue} by @var{divisor}
+@item @var{lvalue} @code{%=} @var{modulus} @tab Set @var{lvalue} to its remainder by @var{modulus}
@cindex common extensions, @code{**=} operator
@cindex extensions, common@comma{} @code{**=} operator
@cindex @command{awk} language, POSIX version
@cindex POSIX @command{awk}
@item @var{lvalue} @code{^=} @var{power} @tab
-@item @var{lvalue} @code{**=} @var{power} @tab Raise @var{lvalue} to the power @var{power}. @value{COMMONEXT}
+@item @var{lvalue} @code{**=} @var{power} @tab Raise @var{lvalue} to the power @var{power} @value{COMMONEXT}
@end multitable
@end float
@@ -11655,7 +11729,7 @@ This is most notable in some commercial @command{awk} versions.
For example:
@example
-$ awk /==/ /dev/null
+$ @kbd{awk /==/ /dev/null}
@error{} awk: syntax error at source line 1
@error{} context is
@error{} >>> /= <<<
@@ -11701,7 +11775,7 @@ This is most notable in some commercial @command{awk} versions.
For example:
@example
-$ awk /==/ /dev/null
+$ @kbd{awk /==/ /dev/null}
@error{} awk: syntax error at source line 1
@error{} context is
@error{} >>> /= <<<
@@ -11754,7 +11828,7 @@ but with the side effect of incrementing it.
The post-increment @samp{foo++} is nearly the same as writing @samp{(foo
+= 1) - 1}. It is not perfectly equivalent because all numbers in
-@command{awk} are floating-point---in floating-point, @samp{foo + 1 - 1} does
+@command{awk} are floating point---in floating point, @samp{foo + 1 - 1} does
not necessarily equal @code{foo}. But the difference is minute as
long as you stick to numbers that are fairly small (less than
@iftex
@@ -11917,8 +11991,8 @@ You should avoid such things in your own programs.
@node Truth Values and Conditions
@section Truth Values and Conditions
-In certain contexts, expression values also serve as ``truth values;'' i.e.,
-they determine what should happen next as the program runs. This
+In certain contexts, expression values also serve as ``truth values''; (i.e.,
+they determine what should happen next as the program runs). This
@value{SECTION} describes how @command{awk} defines ``true'' and ``false''
and how values are compared.
@@ -11974,7 +12048,7 @@ the string constant @code{"0"} is actually true, because it is non-null.
@subsection Variable Typing and Comparison Expressions
@quotation
@i{The Guide is definitive. Reality is frequently inaccurate.}
-@author The Hitchhiker's Guide to the Galaxy
+@author Douglas Adams, @cite{The Hitchhiker's Guide to the Galaxy}
@end quotation
@c STARTOFRANGE comex
@@ -12002,7 +12076,7 @@ compares variables.
@end menu
@node Variable Typing
-@subsubsection String Type Versus Numeric Type
+@subsubsection String Type versus Numeric Type
@cindex numeric, strings
@cindex strings, numeric
@@ -12028,7 +12102,7 @@ attribute.
@item
Fields, @code{getline} input, @code{FILENAME}, @code{ARGV} elements,
@code{ENVIRON} elements, and the elements of an array created by
-@code{match()}, @code{split()} and @code{patsplit()} that are numeric
+@code{match()}, @code{split()}, and @code{patsplit()} that are numeric
strings have the @var{strnum} attribute. Otherwise, they have
the @var{string} attribute. Uninitialized variables also have the
@var{strnum} attribute.
@@ -12229,18 +12303,18 @@ operators}, which are a superset of those in C.
@cindex exclamation point (@code{!}), @code{!~} operator
@cindex @code{in} operator
@float Table,table-relational-ops
-@caption{Relational Operators}
+@caption{Relational operators}
@multitable @columnfractions .25 .75
@headitem Expression @tab Result
-@item @var{x} @code{<} @var{y} @tab True if @var{x} is less than @var{y}.
-@item @var{x} @code{<=} @var{y} @tab True if @var{x} is less than or equal to @var{y}.
-@item @var{x} @code{>} @var{y} @tab True if @var{x} is greater than @var{y}.
-@item @var{x} @code{>=} @var{y} @tab True if @var{x} is greater than or equal to @var{y}.
-@item @var{x} @code{==} @var{y} @tab True if @var{x} is equal to @var{y}.
-@item @var{x} @code{!=} @var{y} @tab True if @var{x} is not equal to @var{y}.
-@item @var{x} @code{~} @var{y} @tab True if the string @var{x} matches the regexp denoted by @var{y}.
-@item @var{x} @code{!~} @var{y} @tab True if the string @var{x} does not match the regexp denoted by @var{y}.
-@item @var{subscript} @code{in} @var{array} @tab True if the array @var{array} has an element with the subscript @var{subscript}.
+@item @var{x} @code{<} @var{y} @tab True if @var{x} is less than @var{y}
+@item @var{x} @code{<=} @var{y} @tab True if @var{x} is less than or equal to @var{y}
+@item @var{x} @code{>} @var{y} @tab True if @var{x} is greater than @var{y}
+@item @var{x} @code{>=} @var{y} @tab True if @var{x} is greater than or equal to @var{y}
+@item @var{x} @code{==} @var{y} @tab True if @var{x} is equal to @var{y}
+@item @var{x} @code{!=} @var{y} @tab True if @var{x} is not equal to @var{y}
+@item @var{x} @code{~} @var{y} @tab True if the string @var{x} matches the regexp denoted by @var{y}
+@item @var{x} @code{!~} @var{y} @tab True if the string @var{x} does not match the regexp denoted by @var{y}
+@item @var{subscript} @code{in} @var{array} @tab True if the array @var{array} has an element with the subscript @var{subscript}
@end multitable
@end float
@@ -12278,24 +12352,24 @@ The following list of expressions illustrates the kinds of comparisons
@table @code
@item 1.5 <= 2.0
-numeric comparison (true)
+Numeric comparison (true)
@item "abc" >= "xyz"
-string comparison (false)
+String comparison (false)
@item 1.5 != " +2"
-string comparison (true)
+String comparison (true)
@item "1e2" < "3"
-string comparison (true)
+String comparison (true)
@item a = 2; b = "2"
@itemx a == b
-string comparison (true)
+String comparison (true)
@item a = 2; b = " +2"
@itemx a == b
-string comparison (false)
+String comparison (false)
@end table
In this example:
@@ -12348,7 +12422,7 @@ dynamic regexp (@pxref{Regexp Usage}; also
@cindex @command{awk}, regexp constants and
@cindex regexp constants
A constant regular
-expression in slashes by itself is also an expression. The regexp
+expression in slashes by itself is also an expression.
@code{/@var{regexp}/} is an abbreviation for the following comparison expression:
@example
@@ -12362,7 +12436,7 @@ One special place where @code{/foo/} is @emph{not} an abbreviation for
where this is discussed in more detail.
@node POSIX String Comparison
-@subsubsection String Comparison With POSIX Rules
+@subsubsection String Comparison with POSIX Rules
The POSIX standard says that string comparison is performed based
on the locale's @dfn{collating order}. This is the order in which
@@ -12618,13 +12692,13 @@ example, the function @code{sqrt()} computes the square root of a number.
@cindex functions, built-in
A fixed set of functions are @dfn{built-in}, which means they are
available in every @command{awk} program. The @code{sqrt()} function is one
-of these. @xref{Built-in}, for a list of built-in
+of these. @DBXREF{Built-in} for a list of built-in
functions and their descriptions. In addition, you can define
functions for use in your program.
-@xref{User-defined},
+@DBXREF{User-defined}
for instructions on how to do this.
Finally, @command{gawk} lets you write functions in C or C++
-that may be called from your program: see @ref{Dynamic Extensions}.
+that may be called from your program (@pxref{Dynamic Extensions}).
@cindex arguments, in function calls
The way to use a function is with a @dfn{function call} expression,
@@ -12643,7 +12717,7 @@ rand() @ii{no arguments}
@cindex troubleshooting, function call syntax
@quotation CAUTION
-Do not put any space between the function name and the open-parenthesis!
+Do not put any space between the function name and the opening parenthesis!
A user-defined function name looks just like the name of a
variable---a space would make the expression look like concatenation of
a variable with an expression inside parentheses.
@@ -12664,7 +12738,7 @@ Some of the built-in functions have one or
more optional arguments.
If those arguments are not supplied, the functions
use a reasonable default value.
-@xref{Built-in}, for full details. If arguments
+@DBXREF{Built-in} for full details. If arguments
are omitted in calls to user-defined functions, then those arguments are
treated as local variables. Such local variables act like the
empty string if referenced where a string value is required,
@@ -12819,7 +12893,7 @@ Multiplication, division, remainder.
@item @code{+ -}
Addition, subtraction.
-@item String Concatenation
+@item String concatenation
There is no special symbol for concatenation.
The operands are simply written side by side
(@pxref{Concatenation}).
@@ -12858,7 +12932,7 @@ statements belong to the statement level, not to expressions. The
redirection does not produce an expression that could be the operand of
another operator. As a result, it does not make sense to use a
redirection operator near another operator of lower precedence without
-parentheses. Such combinations (for example, @samp{print foo > a ? b : c}),
+parentheses. Such combinations (e.g., @samp{print foo > a ? b : c}),
result in syntax errors.
The correct way to write this statement is @samp{print foo > (a ? b : c)}.
@@ -12916,7 +12990,7 @@ For maximum portability, do not use them.
@c ENDOFRANGE oppr
@node Locales
-@section Where You Are Makes A Difference
+@section Where You Are Makes a Difference
@cindex locale, definition of
Modern systems support the notion of @dfn{locales}: a way to tell the
@@ -12936,7 +13010,7 @@ character}, to find the record terminator.
Locales can affect how dates and times are formatted (@pxref{Time
Functions}). For example, a common way to abbreviate the date September
-4, 2015 in the United States is ``9/4/15.'' In many countries in
+4, 2015, in the United States is ``9/4/15.'' In many countries in
Europe, however, it is abbreviated ``4.9.15.'' Thus, the @code{%x}
specification in a @code{"US"} locale might produce @samp{9/4/15},
while in a @code{"EUROPE"} locale, it might produce @samp{4.9.15}.
@@ -12955,13 +13029,13 @@ in @ref{Conversion}.
@itemize @value{BULLET}
@item
Expressions are the basic elements of computation in programs. They are
-built from constants, variables, function calls and combinations of the
+built from constants, variables, function calls, and combinations of the
various kinds of values with operators.
@item
@command{awk} supplies three kinds of constants: numeric, string, and
regexp. @command{gawk} lets you specify numeric constants in octal
-and hexadecimal (bases 8 and 16) in addition to decimal (base 10).
+and hexadecimal (bases 8 and 16) as well as decimal (base 10).
In certain contexts, a standalone regexp constant such as @code{/foo/}
has the same meaning as @samp{$0 ~ /foo/}.
@@ -13003,8 +13077,8 @@ or numeric).
Function calls return a value which may be used as part of a larger
expression. Expressions used to pass parameter values are fully
evaluated before the function is called. @command{awk} provides
-built-in and user-defined functions; this is described later on in this
-@value{DOCUMENT}.
+built-in and user-defined functions; this is described in
+@ref{Functions}.
@item
Operator precedence specifies the order in which operations are performed,
@@ -13217,7 +13291,7 @@ The subexpressions of a Boolean operator in a pattern can be constant regular
expressions, comparisons, or any other @command{awk} expressions. Range
patterns are not expressions, so they cannot appear inside Boolean
patterns. Likewise, the special patterns @code{BEGIN}, @code{END},
-@code{BEGINFILE} and @code{ENDFILE},
+@code{BEGINFILE}, and @code{ENDFILE},
which never match any input record, are not expressions and cannot
appear inside Boolean patterns.
@@ -13328,7 +13402,7 @@ They supply startup and cleanup actions for @command{awk} programs.
@code{BEGIN} and @code{END} rules must have actions; there is no default
action for these rules because there is no current record when they run.
@code{BEGIN} and @code{END} rules are often referred to as
-``@code{BEGIN} and @code{END} blocks'' by long-time @command{awk}
+``@code{BEGIN} and @code{END} blocks'' by longtime @command{awk}
programmers.
@menu
@@ -13359,7 +13433,7 @@ $ @kbd{awk '}
This program finds the number of records in the input file @file{mail-list}
that contain the string @samp{li}. The @code{BEGIN} rule prints a title
for the report. There is no need to use the @code{BEGIN} rule to
-initialize the counter @code{n} to zero, since @command{awk} does this
+initialize the counter @code{n} to zero, as @command{awk} does this
automatically (@pxref{Variables}).
The second rule increments the variable @code{n} every time a
record containing the pattern @samp{li} is read. The @code{END} rule
@@ -13387,7 +13461,7 @@ The order in which library functions are named on the command line
controls the order in which their @code{BEGIN} and @code{END} rules are
executed. Therefore, you have to be careful when writing such rules in
library files so that the order in which they are executed doesn't matter.
-@xref{Options}, for more information on
+@DBXREF{Options} for more information on
using library functions.
@xref{Library Functions},
for a number of useful library functions.
@@ -13436,11 +13510,11 @@ of Unix @command{awk} do not.
The third point follows from the first two. The meaning of @samp{print}
inside a @code{BEGIN} or @code{END} rule is the same as always:
@samp{print $0}. If @code{$0} is the null string, then this prints an
-empty record. Many long time @command{awk} programmers use an unadorned
+empty record. Many longtime @command{awk} programmers use an unadorned
@samp{print} in @code{BEGIN} and @code{END} rules, to mean @samp{@w{print ""}},
relying on @code{$0} being null. Although one might generally get away with
this in @code{BEGIN} rules, it is a very bad idea in @code{END} rules,
-at least in @command{gawk}. It is also poor style, since if an empty
+at least in @command{gawk}. It is also poor style, because if an empty
line is needed in the output, the program should print one explicitly.
@cindex @code{next} statement, @code{BEGIN}/@code{END} patterns and
@@ -13450,9 +13524,14 @@ line is needed in the output, the program should print one explicitly.
Finally, the @code{next} and @code{nextfile} statements are not allowed
in a @code{BEGIN} rule, because the implicit
read-a-record-and-match-against-the-rules loop has not started yet. Similarly, those statements
-are not valid in an @code{END} rule, since all the input has been read.
-(@xref{Next Statement}, and see
-@ref{Nextfile Statement}.)
+are not valid in an @code{END} rule, because all the input has been read.
+(@DBXREF{Next Statement} and
+@ifnotdocbook
+@DBPXREF{Nextfile Statement}.)
+@end ifnotdocbook
+@ifdocbook
+@DBREF{Nextfile Statement}.)
+@end ifdocbook
@c ENDOFRANGE beg
@c ENDOFRANGE end
@@ -13605,9 +13684,9 @@ awk "/$pattern/ "'@{ nmatches++ @}
@noindent
The @command{awk} program consists of two pieces of quoted text
that are concatenated together to form the program.
-The first part is double-quoted, which allows substitution of
+The first part is double quoted, which allows substitution of
the @code{pattern} shell variable inside the quotes.
-The second part is single-quoted.
+The second part is single quoted.
Variable substitution via quoting works, but can be potentially
messy. It requires a good understanding of the shell's quoting rules
@@ -13636,7 +13715,7 @@ The assignment @samp{-v pat="$pattern"} still requires double quotes,
in case there is whitespace in the value of @code{$pattern}.
The @command{awk} variable @code{pat} could be named @code{pattern}
too, but that would be more confusing. Using a variable also
-provides more flexibility, since the variable can be used anywhere inside
+provides more flexibility, as the variable can be used anywhere inside
the program---for printing, as an array subscript, or for any other
use---without requiring the quoting tricks at every point in the program.
@@ -13709,7 +13788,7 @@ is used in order to put several statements together in the body of an
Use the @code{getline} command
(@pxref{Getline}).
Also supplied in @command{awk} are the @code{next}
-statement (@pxref{Next Statement}),
+statement (@pxref{Next Statement})
and the @code{nextfile} statement
(@pxref{Nextfile Statement}).
@@ -13797,7 +13876,7 @@ else
print "x is odd"
@end example
-In this example, if the expression @samp{x % 2 == 0} is true (that is,
+In this example, if the expression @samp{x % 2 == 0} is true (i.e.,
if the value of @code{x} is evenly divisible by two), then the first
@code{print} statement is executed; otherwise, the second @code{print}
statement is executed.
@@ -13876,7 +13955,7 @@ field is printed. Then the @samp{i++} increments the value of @code{i}
and the loop repeats. The loop terminates when @code{i} reaches four.
A newline is not required between the condition and the
-body; however using one makes the program clearer unless the body is a
+body; however, using one makes the program clearer unless the body is a
compound statement or else is very simple. The newline after the open-brace
that begins the compound statement is not required either, but the
program is harder to read without it.
@@ -13923,7 +14002,7 @@ The following is an example of a @code{do} statement:
@noindent
This program prints each input record 10 times. However, it isn't a very
-realistic example, since in this case an ordinary @code{while} would do
+realistic example, because in this case an ordinary @code{while} would do
just as well. This situation reflects actual experience; only
occasionally is there a real use for a @code{do} statement.
@@ -14020,7 +14099,7 @@ very common in loops. It can be easier to think of this counting as part
of looping rather than as something to do inside the loop.
@cindex @code{in} operator
-There is an alternate version of the @code{for} loop, for iterating over
+There is an alternative version of the @code{for} loop, for iterating over
all the indices of an array:
@example
@@ -14029,7 +14108,7 @@ for (i in array)
@end example
@noindent
-@xref{Scanning an Array},
+@DBXREF{Scanning an Array}
for more information on this version of the @code{for} loop.
@node Switch Statement
@@ -14049,7 +14128,7 @@ are checked for a match in the order they are defined. If no suitable
Each @code{case} contains a single constant, be it numeric, string, or
regexp. The @code{switch} expression is evaluated, and then each
-@code{case}'s constant is compared against the result in turn. The type of constant
+@code{case}'s constant is compared against the result in turn. The type of constant
determines the comparison: numeric or string do the usual comparisons.
A regexp constant does a regular expression match against the string
value of the original expression. The general form of the @code{switch}
@@ -14096,9 +14175,9 @@ while ((c = getopt(ARGC, ARGV, "aksx")) != -1) @{
@}
@end example
-Note that if none of the statements specified above halt execution
+Note that if none of the statements specified here halt execution
of a matched @code{case} statement, execution falls through to the
-next @code{case} until execution halts. In the above example, the
+next @code{case} until execution halts. In this example, the
@code{case} for @code{"?"} falls through to the @code{default}
case, which is to call a function named @code{usage()}.
(The @code{getopt()} function being called here is
@@ -14225,7 +14304,7 @@ BEGIN @{
@end example
@noindent
-This program loops forever once @code{x} reaches 5, since
+This program loops forever once @code{x} reaches 5, because
the increment (@samp{x++}) is never reached.
@c @cindex @code{continue}, outside of loops
@@ -14286,7 +14365,7 @@ Because of the @code{next} statement,
the program's subsequent rules won't see the bad record. The error
message is redirected to the standard error output stream, as error
messages should be.
-For more detail see
+For more detail, see
@ref{Special Files}.
If the @code{next} statement causes the end of the input to be reached,
@@ -14352,7 +14431,7 @@ rule to skip over a file that would otherwise cause @command{gawk}
to exit with a fatal error. In this case, @code{ENDFILE} rules are not
executed. @xref{BEGINFILE/ENDFILE}.
-While one might think that @samp{close(FILENAME)} would accomplish
+Although it might seem that @samp{close(FILENAME)} would accomplish
the same as @code{nextfile}, this isn't true. @code{close()} is
reserved for closing files, pipes, and coprocesses that are
opened with redirections. It is not related to the main processing that
@@ -14360,7 +14439,7 @@ opened with redirections. It is not related to the main processing that
@quotation NOTE
For many years, @code{nextfile} was a
-common extension. In September, 2012, it was accepted for
+common extension. In September 2012, it was accepted for
inclusion into the POSIX standard.
See @uref{http://austingroupbugs.net/view.php?id=607, the Austin Group website}.
@end quotation
@@ -14409,7 +14488,7 @@ In such a case,
if you don't want the @code{END} rule to do its job, set a variable
to nonzero before the @code{exit} statement and check that variable in
the @code{END} rule.
-@xref{Assert Function},
+@DBXREF{Assert Function}
for an example that does this.
@cindex dark corner, @code{exit} statement
@@ -14420,7 +14499,7 @@ In the case where an argument
is supplied to a first @code{exit} statement, and then @code{exit} is
called a second time from an @code{END} rule with no argument,
@command{awk} uses the previously supplied exit value. @value{DARKCORNER}
-@xref{Exit Status}, for more information.
+@DBXREF{Exit Status} for more information.
@cindex programming conventions, @code{exit} statement
For example, suppose an error condition occurs that is difficult or
@@ -14480,7 +14559,7 @@ their areas of activity.
@end menu
@node User-modified
-@subsection Built-in Variables That Control @command{awk}
+@subsection Built-In Variables That Control @command{awk}
@c STARTOFRANGE bvaru
@cindex predefined variables, user-modifiable
@c STARTOFRANGE nmbv
@@ -14537,7 +14616,7 @@ A space-separated list of columns that tells @command{gawk}
how to split input with fixed columnar boundaries.
Assigning a value to @code{FIELDWIDTHS}
overrides the use of @code{FS} and @code{FPAT} for field splitting.
-@xref{Constant Size}, for more information.
+@DBXREF{Constant Size} for more information.
@cindex @command{gawk}, @code{FPAT} variable in
@cindex @code{FPAT} variable
@@ -14549,7 +14628,7 @@ A regular expression (as a string) that tells @command{gawk}
to create the fields based on text that matches the regular expression.
Assigning a value to @code{FPAT}
overrides the use of @code{FS} and @code{FIELDWIDTHS} for field splitting.
-@xref{Splitting By Content}, for more information.
+@DBXREF{Splitting By Content} for more information.
@cindex @code{FS} variable
@cindex separators, field
@@ -14659,12 +14738,12 @@ character. (@xref{Output Separators}.)
@cindex @code{PREC} variable
@item PREC #
-The working precision of arbitrary precision floating-point numbers,
+The working precision of arbitrary-precision floating-point numbers,
53 bits by default (@pxref{Setting precision}).
@cindex @code{ROUNDMODE} variable
@item ROUNDMODE #
-The rounding mode to use for arbitrary precision arithmetic on
+The rounding mode to use for arbitrary-precision arithmetic on
numbers, by default @code{"N"} (@samp{roundTiesToEven} in
the IEEE 754 standard; @pxref{Setting the rounding mode}).
@@ -14706,7 +14785,7 @@ really accesses @code{foo["A\034B"]}
Used for internationalization of programs at the
@command{awk} level. It sets the default text domain for specially
marked string constants in the source text, as well as for the
-@code{dcgettext()}, @code{dcngettext()} and @code{bindtextdomain()} functions
+@code{dcgettext()}, @code{dcngettext()}, and @code{bindtextdomain()} functions
(@pxref{Internationalization}).
The default value of @code{TEXTDOMAIN} is @code{"messages"}.
@end table
@@ -14716,7 +14795,7 @@ The default value of @code{TEXTDOMAIN} is @code{"messages"}.
@c ENDOFRANGE nmbv
@node Auto-set
-@subsection Built-in Variables That Convey Information
+@subsection Built-In Variables That Convey Information
@c STARTOFRANGE bvconi
@cindex predefined variables, conveying information
@@ -14729,7 +14808,7 @@ information to your program.
The variables that are specific to @command{gawk} are marked with a pound
sign (@samp{#}). These variables are @command{gawk} extensions. In other
@command{awk} implementations or if @command{gawk} is in compatibility
-mode (@pxref{Options}), they are not special.
+mode (@pxref{Options}), they are not special:
@c @asis for docbook
@table @asis
@@ -14770,7 +14849,7 @@ method of accessing command-line arguments.
The value of @code{ARGV[0]} can vary from system to system.
Also, you should note that the program text is @emph{not} included in
@code{ARGV}, nor are any of @command{awk}'s command-line options.
-@xref{ARGC and ARGV}, for information
+@DBXREF{ARGC and ARGV} for information
about how @command{awk} uses these variables.
@value{DARKCORNER}
@@ -14808,8 +14887,13 @@ Some operating systems may not have environment variables.
On such systems, the @code{ENVIRON} array is empty (except for
@w{@code{ENVIRON["AWKPATH"]}} and
@w{@code{ENVIRON["AWKLIBPATH"]}};
-@pxref{AWKPATH Variable}, and
+@DBPXREF{AWKPATH Variable} and
+@ifdocbook
+@DBREF{AWKLIBPATH Variable}).
+@end ifdocbook
+@ifnotdocbook
@pxref{AWKLIBPATH Variable}).
+@end ifnotdocbook
@cindex @command{gawk}, @code{ERRNO} variable in
@cindex @code{ERRNO} variable
@@ -14838,7 +14922,7 @@ The name of the current input file. When no @value{DF}s are listed
on the command line, @command{awk} reads from the standard input and
@code{FILENAME} is set to @code{"-"}. @code{FILENAME} changes each
time a new file is read (@pxref{Reading Files}). Inside a @code{BEGIN}
-rule, the value of @code{FILENAME} is @code{""}, since there are no input
+rule, the value of @code{FILENAME} is @code{""}, because there are no input
files being processed yet.@footnote{Some early implementations of Unix
@command{awk} initialized @code{FILENAME} to @code{"-"}, even if there
were @value{DF}s to be processed. This behavior was incorrect and should
@@ -14870,7 +14954,7 @@ current record. @xref{Changing Fields}.
@cindex differences in @command{awk} and @command{gawk}, @code{FUNCTAB} variable
@item @code{FUNCTAB #}
An array whose indices and corresponding values are the names of all
-the built-in, user-defined and extension functions in the program.
+the built-in, user-defined, and extension functions in the program.
@quotation NOTE
Attempting to use the @code{delete} statement with the @code{FUNCTAB}
@@ -14964,7 +15048,7 @@ The parent process ID of the current process.
If this element exists in @code{PROCINFO}, its value controls the
order in which array indices will be processed by
@samp{for (@var{indx} in @var{array})} loops.
-Since this is an advanced feature, we defer the
+This is an advanced feature, so we defer the
full description until later; see
@ref{Scanning an Array}.
@@ -14984,10 +15068,10 @@ The version of @command{gawk}.
The following additional elements in the array
are available to provide information about the MPFR and GMP libraries
-if your version of @command{gawk} supports arbitrary precision arithmetic
-(@pxref{Arbitrary Precision Arithmetic}):
+if your version of @command{gawk} supports arbitrary-precision arithmetic
+(@pxref{Arbitrary Precision Arithmetic}):
-@table @code
+@table @code
@cindex version of GNU MPFR library
@item PROCINFO["mpfr_version"]
The version of the GNU MPFR library.
@@ -15035,7 +15119,7 @@ The @code{PROCINFO} array has the following additional uses:
@item
It may be used to provide a timeout when reading from any
open input file, pipe, or coprocess.
-@xref{Read Timeout}, for more information.
+@DBXREF{Read Timeout} for more information.
@item
It may be used to cause coprocesses to communicate over pseudo-ttys
@@ -15280,8 +15364,14 @@ use the @code{delete} statement to remove elements from
All of these actions are typically done in the @code{BEGIN} rule,
before actual processing of the input begins.
-@xref{Split Program}, and see
-@ref{Tee Program}, for examples
+@DBXREF{Split Program} and
+@ifnotdocbook
+@DBPXREF{Tee Program}
+@end ifnotdocbook
+@ifdocbook
+@DBREF{Tee Program}
+@end ifdocbook
+for examples
of each way of removing elements from @code{ARGV}.
To actually get options into an @command{awk} program,
@@ -15293,7 +15383,7 @@ awk -f myprog.awk -- -v -q file1 file2 @dots{}
@end example
The following fragment processes @code{ARGV} in order to examine, and
-then remove, the above command-line options:
+then remove, the previously mentioned command-line options:
@example
BEGIN @{
@@ -15329,14 +15419,21 @@ gawk -f myprog.awk -q -v file1 file2 @dots{}
@noindent
Because @option{-q} is not a valid @command{gawk} option, it and the
following @option{-v} are passed on to the @command{awk} program.
-(@xref{Getopt Function}, for an @command{awk} library function that
+(@DBXREF{Getopt Function} for an @command{awk} library function that
parses command-line options.)
When designing your program, you should choose options that don't
-conflict with @command{gawk}'s, since it will process any options
+conflict with @command{gawk}'s, because it will process any options
that it accepts before passing the rest of the command line on to
your program. Using @samp{#!} with the @option{-E} option may help
-(@pxref{Executable Scripts}, and @pxref{Options}).
+(@DBXREF{Executable Scripts}
+and
+@ifnotdocbook
+@DBPXREF{Options}).
+@end ifnotdocbook
+@ifdocbook
+@DBREF{Options}).
+@end ifdocbook
@node Pattern Action Summary
@section Summary
@@ -15502,7 +15599,7 @@ as shown in @inlineraw{docbook, <xref linkend="figure-array-elements"/>}:
@ifnotdocbook
@float Figure,figure-array-elements
-@caption{A Contiguous Array}
+@caption{A contiguous array}
@ifinfo
@center @image{array-elements, , , Basic Program Stages, txt}
@end ifinfo
@@ -15514,7 +15611,7 @@ as shown in @inlineraw{docbook, <xref linkend="figure-array-elements"/>}:
@docbook
<figure id="figure-array-elements" float="0">
-<title>A Contiguous Array</title>
+<title>A contiguous array</title>
<mediaobject>
<imageobject role="web"><imagedata fileref="array-elements.png" format="PNG"/></imageobject>
</mediaobject>
@@ -15533,7 +15630,7 @@ position with zero elements before it.
@cindex associative arrays
@cindex arrays, associative
Arrays in @command{awk} are different---they are @dfn{associative}. This means
-that each array is a collection of pairs: an index and its corresponding
+that each array is a collection of pairs---an index and its corresponding
array element value:
@ifnotdocbook
@@ -15714,7 +15811,7 @@ numbers and strings as indices.
There are some subtleties to how numbers work when used as
array subscripts; this is discussed in more detail in
@ref{Numeric Array Subscripts}.)
-Here, the number @code{1} isn't double-quoted, since @command{awk}
+Here, the number @code{1} isn't double quoted, because @command{awk}
automatically converts it to a string.
@cindex @command{gawk}, @code{IGNORECASE} variable in
@@ -15799,7 +15896,7 @@ This expression tests whether the particular index @var{indx} exists,
without the side effect of creating that element if it is not present.
The expression has the value one (true) if @code{@var{array}[@var{indx}]}
exists and zero (false) if it does not exist.
-(We use @var{indx} here, since @samp{index} is the name of a built-in
+(We use @var{indx} here, because @samp{index} is the name of a built-in
function.)
For example, this statement tests whether the array @code{frequencies}
contains the index @samp{2}:
@@ -15942,7 +16039,7 @@ the word as index. The second rule scans the elements of @code{used} to
find all the distinct words that appear in the input. It prints each
word that is more than 10 characters long and also prints the number of
such words.
-@xref{String Functions},
+@DBXREF{String Functions}
for more information on the built-in function @code{length()}.
@example
@@ -15965,7 +16062,7 @@ END @{
@end example
@noindent
-@xref{Word Sorting},
+@DBXREF{Word Sorting}
for a more detailed example of this type.
@cindex arrays, elements, order of access by @code{in} operator
@@ -16020,7 +16117,7 @@ $ @kbd{nawk -f loopcheck.awk}
@end example
@node Controlling Scanning
-@subsection Using Predefined Array Scanning Orders With @command{gawk}
+@subsection Using Predefined Array Scanning Orders with @command{gawk}
This @value{SUBSECTION} describes a feature that is specific to @command{gawk}.
@@ -16045,7 +16142,7 @@ We describe this now.
@item
Set @code{PROCINFO["sorted_in"]} to the name of a user-defined function
to use for comparison of array elements. This advanced feature
-is described later, in @ref{Array Sorting}.
+is described later in @ref{Array Sorting}.
@end itemize
@cindex @code{PROCINFO}, values of @code{sorted_in}
@@ -16063,7 +16160,7 @@ the index is @code{"10"} rather than numeric 10.)
@item "@@ind_num_asc"
Order by indices in ascending order but force them to be treated as numbers in the process.
-Any index with a non-numeric value will end up positioned as if it were zero.
+Any index with a non-numeric value will end up positioned as if it were zero.
@item "@@val_type_asc"
Order by element values in ascending order (rather than by indices).
@@ -16075,11 +16172,11 @@ which in turn come before all subarrays.
@pxref{Arrays of Arrays}.)
@item "@@val_str_asc"
-Order by element values in ascending order (rather than by indices). Scalar values are
+Order by element values in ascending order (rather than by indices). Scalar values are
compared as strings. Subarrays, if present, come out last.
@item "@@val_num_asc"
-Order by element values in ascending order (rather than by indices). Scalar values are
+Order by element values in ascending order (rather than by indices). Scalar values are
compared as numbers. Subarrays, if present, come out last.
When numeric values are equal, the string values are used to provide
an ordering: this guarantees consistent results across different
@@ -16140,11 +16237,11 @@ $ @kbd{gawk '}
When sorting an array by element values, if a value happens to be
a subarray then it is considered to be greater than any string or
numeric value, regardless of what the subarray itself contains,
-and all subarrays are treated as being equal to each other. Their
+and all subarrays are treated as being equal to each other. Their
order relative to each other is determined by their index strings.
Here are some additional things to bear in mind about sorted
-array traversal.
+array traversal:
@itemize @value{BULLET}
@item
@@ -16164,7 +16261,7 @@ if (save_sorted)
@end example
@item
-As mentioned, the default array traversal order is represented by
+As already mentioned, the default array traversal order is represented by
@code{"@@unsorted"}. You can also get the default behavior by assigning
the null string to @code{PROCINFO["sorted_in"]} or by just deleting the
@code{"sorted_in"} element from the @code{PROCINFO} array with
@@ -16209,7 +16306,7 @@ The program then changes
the value of @code{CONVFMT}. The test @samp{(xyz in data)} generates a new
string value from @code{xyz}---this time @code{"12.15"}---because the value of
@code{CONVFMT} only allows two significant digits. This test fails,
-since @code{"12.15"} is different from @code{"12.153"}.
+because @code{"12.15"} is different from @code{"12.153"}.
@cindex converting integer array subscripts
@cindex integer array indices
@@ -16227,19 +16324,19 @@ for (i = 1; i <= maxsub; i++)
The ``integer values always convert to strings as integers'' rule
has an additional consequence for array indexing.
Octal and hexadecimal constants
+@ifnotdocbook
(@pxref{Nondecimal-numbers})
+@end ifnotdocbook
+@ifdocbook
+(covered in @pref{Nondecimal-numbers})
+@end ifdocbook
are converted internally into numbers, and their original form
-is forgotten.
-This means, for example, that
-@code{array[17]},
-@code{array[021]},
-and
-@code{array[0x11]}
-all refer to the same element!
+is forgotten. This means, for example, that @code{array[17]},
+@code{array[021]}, and @code{array[0x11]} all refer to the same element!
As with many things in @command{awk}, the majority of the time
things work as you would expect them to. But it is useful to have a precise
-knowledge of the actual rules since they can sometimes have a subtle
+knowledge of the actual rules, as they can sometimes have a subtle
effect on your programs.
@node Uninitialized Subscripts
@@ -16382,7 +16479,7 @@ by a number of other implementations.
@cindex Brian Kernighan's @command{awk}
@quotation NOTE
For many years, using @code{delete} without a subscript was a common
-extension. In September, 2012, it was accepted for inclusion into the
+extension. In September 2012, it was accepted for inclusion into the
POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=544,
the Austin Group website}.
@end quotation
@@ -16424,7 +16521,7 @@ a = 3
@cindex subscripts in arrays, multidimensional
@cindex arrays, multidimensional
-A multidimensional array is an array in which an element is identified
+A @dfn{multidimensional array} is an array in which an element is identified
by a sequence of indices instead of a single index. For example, a
two-dimensional array requires two indices. The usual way (in many
languages, including @command{awk}) to refer to an element of a
@@ -16466,7 +16563,7 @@ stored as @samp{foo["a@@b@@c"]}.
@cindex @code{in} operator, index existence in multidimensional arrays
To test whether a particular index sequence exists in a
multidimensional array, use the same operator (@code{in}) that is
-used for single dimensional arrays. Write the whole sequence of indices
+used for single-dimensional arrays. Write the whole sequence of indices
in parentheses, separated by commas, as the left operand:
@example
@@ -16590,7 +16687,7 @@ This simulates a true two-dimensional array. Each subarray element can
contain another subarray as a value, which in turn can hold other arrays
as well. In this way, you can create arrays of three or more dimensions.
The indices can be any @command{awk} expression, including scalars
-separated by commas (that is, a regular @command{awk} simulated
+separated by commas (i.e., a regular @command{awk} simulated
multidimensional subscript). So the following is valid in
@command{gawk}:
@@ -16608,8 +16705,8 @@ is itself an array and not a scalar:
@example
a[4] = "An element in a jagged array"
@end example
-
-The terms @dfn{dimension}, @dfn{row} and @dfn{column} are
+
+The terms @dfn{dimension}, @dfn{row}, and @dfn{column} are
meaningless when applied
to such an array, but we will use ``dimension'' henceforth to imply the
maximum number of indices needed to refer to an existing element. The
@@ -16665,14 +16762,14 @@ The @samp{for (item in array)} statement (@pxref{Scanning an Array})
can be nested to scan all the
elements of an array of arrays if it is rectangular in structure. In order
to print the contents (scalar values) of a two-dimensional array of arrays
-(i.e., in which each first-level element is itself an
-array, not necessarily of the same length)
+(i.e., in which each first-level element is itself an
+array, not necessarily of the same length)
you could use the following code:
@example
for (i in array)
for (j in array[i])
- print array[i][j]
+ print array[i][j]
@end example
The @code{isarray()} function (@pxref{Type Functions})
@@ -16682,7 +16779,7 @@ lets you test if an array element is itself an array:
for (i in array) @{
if (isarray(array[i]) @{
for (j in array[i]) @{
- print array[i][j]
+ print array[i][j]
@}
@}
else
@@ -16692,7 +16789,7 @@ for (i in array) @{
If the structure of a jagged array of arrays is known in advance,
you can often devise workarounds using control statements. For example,
-the following code prints the elements of our main array @code{a}:
+the following code prints the elements of our main array @code{a}:
@example
for (i in a) @{
@@ -16702,13 +16799,13 @@ for (i in a) @{
print a[i][j][k]
@} else
print a[i][j]
- @}
+ @}
@}
@end example
@noindent
-@xref{Walking Arrays}, for a user-defined function that ``walks'' an
-arbitrarily-dimensioned array of arrays.
+@DBXREF{Walking Arrays} for a user-defined function that ``walks'' an
+arbitrarily dimensioned array of arrays.
Recall that a reference to an uninitialized array element yields a value
of @code{""}, the null string. This has one important implication when you
@@ -16758,8 +16855,9 @@ special predefined values to @code{PROCINFO["sorted_in"]}.
@item
Use @samp{delete @var{array}[@var{indx}]} to delete an individual element.
-You may also use @samp{delete @var{array}} to delete all of the elements
-in the array. This latter feature has been a common extension for many
+To delete all of the elements in an array,
+use @samp{delete @var{array}}.
+This latter feature has been a common extension for many
years and is now standard, but may not be supported by all commercial
versions of @command{awk}.
@@ -16812,7 +16910,7 @@ The second half of this @value{CHAPTER} describes these
@end menu
@node Built-in
-@section Built-in Functions
+@section Built-In Functions
@dfn{Built-in} functions are always available for
your @command{awk} program to call. This @value{SECTION} defines all
@@ -16835,7 +16933,7 @@ but are summarized here for your convenience.
@end menu
@node Calling Built-in
-@subsection Calling Built-in Functions
+@subsection Calling Built-In Functions
To call one of @command{awk}'s built-in functions, write the name of
the function followed
@@ -16845,7 +16943,7 @@ is a call to the function @code{atan2()} and has two arguments.
@cindex programming conventions, functions, calling
@cindex whitespace, functions@comma{} calling
Whitespace is ignored between the built-in function name and the
-open parenthesis, but nonetheless it is good practice to avoid using whitespace
+opening parenthesis, but nonetheless it is good practice to avoid using whitespace
there. User-defined functions do not permit whitespace in this way, and
it is easier to avoid mistakes by following a simple
convention that always works---no whitespace after a function name.
@@ -16925,7 +17023,6 @@ depends on your machine's floating-point representation.
@cindex round to nearest integer
Return the nearest integer to @var{x}, located between @var{x} and zero and
truncated toward zero.
-
For example, @code{int(3)} is 3, @code{int(3.9)} is 3, @code{int(-3.9)}
is @minus{}3, and @code{int(-3)} is @minus{}3 as well.
@@ -17015,7 +17112,7 @@ for generating random numbers to the value @var{x}.
Each seed value leads to a particular sequence of random
numbers.@footnote{Computer-generated random numbers really are not truly
random. They are technically known as ``pseudorandom.'' This means
-that while the numbers in a sequence appear to be random, you can in
+that although the numbers in a sequence appear to be random, you can in
fact generate the same sequence of random numbers over and over again.}
Thus, if the seed is set to the same value a second time,
the same sequence of random numbers is produced again.
@@ -17065,7 +17162,7 @@ doing index calculations, particularly if you are used to C.
In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).}
Several functions perform string substitution; the full discussion is
provided in the description of the @code{sub()} function, which comes
-towards the end since the list is presented alphabetically.
+toward the end, because the list is presented alphabetically.
Those functions that are specific to @command{gawk} are marked with a
pound sign (@samp{#}). They are not available in compatibility mode
@@ -17091,10 +17188,10 @@ These two functions are similar in behavior, so they are described
together.
@quotation NOTE
-The following description ignores the third argument, @var{how}, since it
+The following description ignores the third argument, @var{how}, as it
requires understanding features that we have not discussed yet. Thus,
the discussion here is a deliberate simplification. (We do provide all
-the details later on: @xref{Array Sorting Functions}, for the full story.)
+the details later on; see @DBREF{Array Sorting Functions} for the full story.)
@end quotation
Both functions return the number of elements in the array @var{source}.
@@ -17341,7 +17438,7 @@ at which that substring begins (one, if it starts at the beginning of
The @var{regexp} argument may be either a regexp constant
(@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}).
In the latter case, the string is treated as a regexp to be matched.
-@xref{Computed Regexps}, for a
+@DBXREF{Computed Regexps} for a
discussion of the difference between the two forms, and the
implications for writing your program correctly.
@@ -17434,7 +17531,7 @@ $ @kbd{echo foooobazbarrrrr |}
@end example
There may not be subscripts for the start and index for every parenthesized
-subexpression, since they may not all have matched text; thus they
+subexpression, because they may not all have matched text; thus they
should be tested for with the @code{in} operator
(@pxref{Reference to Elements}).
@@ -17481,15 +17578,15 @@ a regexp describing where to split @var{string} (much as @code{FS} can
be a regexp describing where to split input records).
If @var{fieldsep} is omitted, the value of @code{FS} is used.
@code{split()} returns the number of elements created.
-@var{seps} is a @command{gawk} extension with @code{@var{seps}[@var{i}]}
+@var{seps} is a @command{gawk} extension with @code{@var{seps}[@var{i}]}
being the separator string
-between @code{@var{array}[@var{i}]} and @code{@var{array}[@var{i}+1]}.
+between @code{@var{array}[@var{i}]} and @code{@var{array}[@var{i}+1]}.
If @var{fieldsep} is a single
-space then any leading whitespace goes into @code{@var{seps}[0]} and
+space then any leading whitespace goes into @code{@var{seps}[0]} and
any trailing
-whitespace goes into @code{@var{seps}[@var{n}]} where @var{n} is the
-return value of
-@code{split()} (that is, the number of elements in @var{array}).
+whitespace goes into @code{@var{seps}[@var{n}]} where @var{n} is the
+return value of
+@code{split()} (i.e., the number of elements in @var{array}).
The @code{split()} function splits strings into pieces in a
manner similar to the way input lines are split into fields. For example:
@@ -17525,7 +17622,7 @@ As with input field-splitting, when the value of @var{fieldsep} is
the elements of
@var{array} but not in @var{seps}, and the elements
are separated by runs of whitespace.
-Also as with input field-splitting, if @var{fieldsep} is the null string, each
+Also, as with input field-splitting, if @var{fieldsep} is the null string, each
individual character in the string is split into its own array element.
@value{COMMONEXT}
@@ -17539,7 +17636,7 @@ the third argument to be a regexp constant (@code{/abc/}) as well as a
string.
@value{DARKCORNER}
The POSIX standard allows this as well.
-@xref{Computed Regexps}, for a
+@DBXREF{Computed Regexps} for a
discussion of the difference between using a string constant or a regexp constant,
and the implications for writing your program correctly.
@@ -17590,7 +17687,7 @@ Using the @code{strtonum()} function is @emph{not} the same as adding zero
to a string value; the automatic coercion of strings to numbers
works only for decimal data, not for octal or hexadecimal.@footnote{Unless
you use the @option{--non-decimal-data} option, which isn't recommended.
-@xref{Nondecimal Data}, for more information.}
+@DBXREF{Nondecimal Data} for more information.}
Note also that @code{strtonum()} uses the current locale's decimal point
for recognizing numbers (@pxref{Locales}).
@@ -17608,7 +17705,7 @@ Return the number of substitutions made (zero or one).
The @var{regexp} argument may be either a regexp constant
(@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}).
In the latter case, the string is treated as a regexp to be matched.
-@xref{Computed Regexps}, for a
+@DBXREF{Computed Regexps} for a
discussion of the difference between the two forms, and the
implications for writing your program correctly.
@@ -17827,7 +17924,7 @@ Although this makes a certain amount of sense, it can be surprising.
@node Gory Details
-@subsubsection More About @samp{\} and @samp{&} with @code{sub()}, @code{gsub()}, and @code{gensub()}
+@subsubsection More about @samp{\} and @samp{&} with @code{sub()}, @code{gsub()}, and @code{gensub()}
@cindex escape processing, @code{gsub()}/@code{gensub()}/@code{sub()} functions
@cindex @code{sub()} function, escape processing
@@ -17874,7 +17971,7 @@ through unchanged. This is illustrated in @ref{table-sub-escapes}.
@c Thank to Karl Berry for help with the TeX stuff.
@float Table,table-sub-escapes
-@caption{Historical Escape Sequence Processing for @code{sub()} and @code{gsub()}}
+@caption{Historical escape sequence processing for @code{sub()} and @code{gsub()}}
@tex
\vbox{\bigskip
% We need more characters for escape and tab ...
@@ -17946,7 +18043,7 @@ This is shown in
@ref{table-sub-proposed}.
@float Table,table-sub-proposed
-@caption{GNU @command{awk} Rules For @code{sub()} And Backslash}
+@caption{GNU @command{awk} rules for @code{sub()} and backslash}
@tex
\vbox{\bigskip
% We need more characters for escape and tab ...
@@ -18009,7 +18106,7 @@ by anything else is not special; the @samp{\} is placed straight into the output
These rules are presented in @ref{table-posix-sub}.
@float Table,table-posix-sub
-@caption{POSIX Rules For @code{sub()} And @code{gsub()}}
+@caption{POSIX rules for @code{sub()} and @code{gsub()}}
@tex
\vbox{\bigskip
% We need more characters for escape and tab ...
@@ -18058,12 +18155,12 @@ is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}.
Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules
when @option{--posix} is specified (@pxref{Options}). Otherwise,
-it continued to follow the proposed rules, since
+it continued to follow the proposed rules, as
that had been its behavior for many years.
When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer
made the POSIX rules the default, breaking well over a decade's worth
-of backwards compatibility.@footnote{This was rather naive of him, despite
+of backward compatibility.@footnote{This was rather naive of him, despite
there being a note in this section indicating that the next major version
would move to the POSIX rules.} Needless to say, this was a bad idea,
and as of @value{PVERSION} 4.0.1, @command{gawk} resumed its historical
@@ -18078,7 +18175,7 @@ appears in the generated text and the @samp{\} does not,
as shown in @ref{table-gensub-escapes}.
@float Table,table-gensub-escapes
-@caption{Escape Sequence Processing For @code{gensub()}}
+@caption{Escape sequence processing for @code{gensub()}}
@tex
\vbox{\bigskip
% We need more characters for escape and tab ...
@@ -18145,7 +18242,7 @@ Optional parameters are enclosed in square brackets ([ ]):
Close the file @var{filename} for input or output. Alternatively, the
argument may be a shell command that was used for creating a coprocess, or
for redirecting to or from a pipe; then the coprocess or pipe is closed.
-@xref{Close Files And Pipes},
+@DBXREF{Close Files And Pipes}
for more information.
When closing a coprocess, it is occasionally useful to first close
@@ -18169,13 +18266,13 @@ a pipe or coprocess.
@cindex buffers, flushing
@cindex output, buffering
-Many utility programs @dfn{buffer} their output; i.e., they save information
+Many utility programs @dfn{buffer} their output (i.e., they save information
to write to a disk file or the screen in memory until there is enough
-for it to be worthwhile to send the data to the output device.
+for it to be worthwhile to send the data to the output device).
This is often more efficient than writing
every little bit of information as soon as it is ready. However, sometimes
-it is necessary to force a program to @dfn{flush} its buffers; that is,
-write the information to its destination, even if a buffer is not full.
+it is necessary to force a program to @dfn{flush} its buffers (i.e.,
+write the information to its destination, even if a buffer is not full).
This is the purpose of the @code{fflush()} function---@command{gawk} also
buffers its output and the @code{fflush()} function forces
@command{gawk} to flush its buffers.
@@ -18183,11 +18280,11 @@ buffers its output and the @code{fflush()} function forces
@cindex extensions, common@comma{} @code{fflush()} function
@cindex Brian Kernighan's @command{awk}
Brian Kernighan added @code{fflush()} to his @command{awk} in April
-of 1992. For two decades, it was a common extension. In December,
+1992. For two decades, it was a common extension. In December
2012, it was accepted for inclusion into the POSIX standard.
See @uref{http://austingroupbugs.net/view.php?id=634, the Austin Group website}.
-POSIX standardizes @code{fflush()} as follows: If there
+POSIX standardizes @code{fflush()} as follows: if there
is no argument, or if the argument is the null string (@w{@code{""}}),
then @command{awk} flushes the buffers for @emph{all} open output files
and pipes.
@@ -18219,53 +18316,6 @@ a file or pipe that was opened for reading (such as with @code{getline}),
or if @var{filename} is not an open file, pipe, or coprocess.
In such a case, @code{fflush()} returns @minus{}1, as well.
-@item @code{system(@var{command})}
-@cindexawkfunc{system}
-@cindex invoke shell command
-@cindex interacting with other programs
-Execute the operating-system
-command @var{command} and then return to the @command{awk} program.
-Return @var{command}'s exit status.
-
-For example, if the following fragment of code is put in your @command{awk}
-program:
-
-@example
-END @{
- system("date | mail -s 'awk run done' root")
-@}
-@end example
-
-@noindent
-the system administrator is sent mail when the @command{awk} program
-finishes processing input and begins its end-of-input processing.
-
-Note that redirecting @code{print} or @code{printf} into a pipe is often
-enough to accomplish your task. If you need to run many commands, it
-is more efficient to simply print them down a pipeline to the shell:
-
-@example
-while (@var{more stuff to do})
- print @var{command} | "/bin/sh"
-close("/bin/sh")
-@end example
-
-@noindent
-@cindex troubleshooting, @code{system()} function
-@cindex @option{--sandbox} option, disabling @code{system()} function
-However, if your @command{awk}
-program is interactive, @code{system()} is useful for running large
-self-contained programs, such as a shell or an editor.
-Some operating systems cannot implement the @code{system()} function.
-@code{system()} causes a fatal error if it is not supported.
-
-@quotation NOTE
-When @option{--sandbox} is specified, the @code{system()} function is disabled
-(@pxref{Options}).
-@end quotation
-
-@end table
-
@cindex sidebar, Interactive Versus Noninteractive Buffering
@ifdocbook
@docbook
@@ -18275,15 +18325,15 @@ When @option{--sandbox} is specified, the @code{system()} function is disabled
@cindex buffering, interactive vs.@: noninteractive
As a side point, buffering issues can be even more confusing, depending
-upon whether your program is @dfn{interactive}, i.e., communicating
-with a user sitting at a keyboard.@footnote{A program is interactive
+upon whether your program is @dfn{interactive} (i.e., communicating
+with a user sitting at a keyboard).@footnote{A program is interactive
if the standard output is connected to a terminal device. On modern
systems, this means your keyboard and screen.}
@c Thanks to Walter.Mecky@dresdnerbank.de for this example, and for
@c motivating me to write this section.
-Interactive programs generally @dfn{line buffer} their output; i.e., they
-write out every line. Noninteractive programs wait until they have
+Interactive programs generally @dfn{line buffer} their output (i.e., they
+write out every line). Noninteractive programs wait until they have
a full buffer, which may be many lines of output.
Here is an example of the difference:
@@ -18326,15 +18376,15 @@ it is all buffered and sent down the pipe to @command{cat} in one shot.
@cindex buffering, interactive vs.@: noninteractive
As a side point, buffering issues can be even more confusing, depending
-upon whether your program is @dfn{interactive}, i.e., communicating
-with a user sitting at a keyboard.@footnote{A program is interactive
+upon whether your program is @dfn{interactive} (i.e., communicating
+with a user sitting at a keyboard).@footnote{A program is interactive
if the standard output is connected to a terminal device. On modern
systems, this means your keyboard and screen.}
@c Thanks to Walter.Mecky@dresdnerbank.de for this example, and for
@c motivating me to write this section.
-Interactive programs generally @dfn{line buffer} their output; i.e., they
-write out every line. Noninteractive programs wait until they have
+Interactive programs generally @dfn{line buffer} their output (i.e., they
+write out every line). Noninteractive programs wait until they have
a full buffer, which may be many lines of output.
Here is an example of the difference:
@@ -18366,6 +18416,53 @@ it is all buffered and sent down the pipe to @command{cat} in one shot.
@end cartouche
@end ifnotdocbook
+@item @code{system(@var{command})}
+@cindexawkfunc{system}
+@cindex invoke shell command
+@cindex interacting with other programs
+Execute the operating-system
+command @var{command} and then return to the @command{awk} program.
+Return @var{command}'s exit status.
+
+For example, if the following fragment of code is put in your @command{awk}
+program:
+
+@example
+END @{
+ system("date | mail -s 'awk run done' root")
+@}
+@end example
+
+@noindent
+the system administrator is sent mail when the @command{awk} program
+finishes processing input and begins its end-of-input processing.
+
+Note that redirecting @code{print} or @code{printf} into a pipe is often
+enough to accomplish your task. If you need to run many commands, it
+is more efficient to simply print them down a pipeline to the shell:
+
+@example
+while (@var{more stuff to do})
+ print @var{command} | "/bin/sh"
+close("/bin/sh")
+@end example
+
+@noindent
+@cindex troubleshooting, @code{system()} function
+@cindex @option{--sandbox} option, disabling @code{system()} function
+However, if your @command{awk}
+program is interactive, @code{system()} is useful for running large
+self-contained programs, such as a shell or an editor.
+Some operating systems cannot implement the @code{system()} function.
+@code{system()} causes a fatal error if it is not supported.
+
+@quotation NOTE
+When @option{--sandbox} is specified, the @code{system()} function is disabled
+(@pxref{Options}).
+@end quotation
+
+@end table
+
@cindex sidebar, Controlling Output Buffering with @code{system()}
@ifdocbook
@docbook
@@ -18389,7 +18486,7 @@ system("") # flush output
@command{gawk} treats this use of the @code{system()} function as a special
case and is smart enough not to run a shell (or other command
interpreter) with the empty command. Therefore, with @command{gawk}, this
-idiom is not only useful, it is also efficient. While this method should work
+idiom is not only useful, it is also efficient. Although this method should work
with other @command{awk} implementations, it does not necessarily avoid
starting an unnecessary shell. (Other implementations may only
flush the buffer associated with the standard output and not necessarily
@@ -18454,7 +18551,7 @@ system("") # flush output
@command{gawk} treats this use of the @code{system()} function as a special
case and is smart enough not to run a shell (or other command
interpreter) with the empty command. Therefore, with @command{gawk}, this
-idiom is not only useful, it is also efficient. While this method should work
+idiom is not only useful, it is also efficient. Although this method should work
with other @command{awk} implementations, it does not necessarily avoid
starting an unnecessary shell. (Other implementations may only
flush the buffer associated with the standard output and not necessarily
@@ -18594,14 +18691,14 @@ Mean Time). Otherwise, the value is formatted for the local time zone.
The @var{timestamp} is in the same format as the value returned by the
@code{systime()} function. If no @var{timestamp} argument is supplied,
@command{gawk} uses the current time of day as the timestamp.
-If no @var{format} argument is supplied, @code{strftime()} uses
+Without a @var{format} argument, @code{strftime()} uses
the value of @code{PROCINFO["strftime"]} as the format string
(@pxref{Built-in Variables}).
The default string value is
@code{@w{"%a %b %e %H:%M:%S %Z %Y"}}. This format string produces
output that is equivalent to that of the @command{date} utility.
You can assign a new value to @code{PROCINFO["strftime"]} to
-change the default format; see below for the various format directives.
+change the default format; see the following list for the various format directives.
@item @code{systime()}
@cindexgawkfunc{systime}
@@ -18678,9 +18775,9 @@ This is the ISO 8601 date format.
@item %g
The year modulo 100 of the ISO 8601 week number, as a decimal number (00--99).
-For example, January 1, 2012 is in week 53 of 2011. Thus, the year
+For example, January 1, 2012, is in week 53 of 2011. Thus, the year
of its ISO 8601 week number is 2011, even though its year is 2012.
-Similarly, December 31, 2012 is in week 1 of 2013. Thus, the year
+Similarly, December 31, 2012, is in week 1 of 2013. Thus, the year
of its ISO week number is 2013, even though its year is 2012.
@item %G
@@ -18776,7 +18873,7 @@ no time zone is determinable.
@item %Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH
@itemx %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy
-``Alternate representations'' for the specifications
+``Alternative representations'' for the specifications
that use only the second letter (@code{%c}, @code{%C},
and so on).@footnote{If you don't understand any of this, don't worry about
it; these facilities are meant to make it easier to ``internationalize''
@@ -18789,7 +18886,7 @@ Other internationalization features are described in
A literal @samp{%}.
@end table
-If a conversion specifier is not one of the above, the behavior is
+If a conversion specifier is not one of those just listed, the behavior is
undefined.@footnote{This is because ISO C leaves the
behavior of the C version of @code{strftime()} undefined and @command{gawk}
uses the system's version of @code{strftime()} if it's there.
@@ -18833,7 +18930,7 @@ The date in VMS format (e.g., @samp{20-JUN-1991}).
@end table
@c ENDOFRANGE strf
-Additionally, the alternate representations are recognized but their
+Additionally, the alternative representations are recognized but their
normal representations are used.
@cindex @code{date} utility, POSIX
@@ -18847,7 +18944,7 @@ interprets the current time according to the format specifiers in
the string. For example:
@example
-$ date '+Today is %A, %B %d, %Y.'
+$ @kbd{date '+Today is %A, %B %d, %Y.'}
@print{} Today is Monday, September 22, 2014.
@end example
@@ -18911,8 +19008,10 @@ each successive pair of bits in the operands.
Three common operations are bitwise AND, OR, and XOR.
The operations are described in @ref{table-bitwise-ops}.
+@c 11/2014: Postprocessing turns the docbook informaltable
+@c into a table. Hurray for scripting!
@float Table,table-bitwise-ops
-@caption{Bitwise Operations}
+@caption{Bitwise operations}
@ifnottex
@ifnotdocbook
@display
@@ -19080,7 +19179,7 @@ Return the value of @var{val}, shifted right by @var{count} bits.
Return the bitwise XOR of the arguments. There must be at least two.
@end table
-For all of these functions, first the double precision floating-point value is
+For all of these functions, first the double-precision floating-point value is
converted to the widest C unsigned integer type, then the bitwise operation is
performed. If the result cannot be represented exactly as a C @code{double},
leading nonzero bits are removed one by one until it can be represented
@@ -19179,7 +19278,7 @@ Otherwise, a @code{"0"} is added.
The value is then shifted right by one bit and the loop continues
until there are no more 1 bits.
-If the initial value is zero it returns a simple @code{"0"}.
+If the initial value is zero, it returns a simple @code{"0"}.
Otherwise, at the end, it pads the value with zeros to represent multiples
of 8-bit quantities. This is typical in modern computers.
@@ -19216,8 +19315,8 @@ an array or not. The second is inside the body of a user-defined function
array or not.
@quotation NOTE
-Using @code{isarray()} at the global level to test
-variables makes no sense. Since you are the one writing the program, you
+Using @code{isarray()} at the global level to test
+variables makes no sense. Because you are the one writing the program, you
are supposed to know if your variables are arrays or not. And in fact,
due to the way @command{gawk} works, if you pass the name of a variable
that has not been previously used to @code{isarray()}, @command{gawk}
@@ -19285,7 +19384,7 @@ The default value for @var{category} is @code{"LC_MESSAGES"}.
Complicated @command{awk} programs can often be simplified by defining
your own functions. User-defined functions can be called just like
built-in ones (@pxref{Function Calls}), but it is up to you to define
-them, i.e., to tell @command{awk} what they should do.
+them (i.e., to tell @command{awk} what they should do).
@menu
* Definition Syntax:: How to write definitions and what they mean.
@@ -19424,13 +19523,13 @@ func foo() @{ a = sqrt($1) ; print a @}
@end example
@noindent
-Instead it defines a rule that, for each record, concatenates the value
+Instead, it defines a rule that, for each record, concatenates the value
of the variable @samp{func} with the return value of the function @samp{foo}.
If the resulting string is non-null, the action is executed.
This is probably not what is desired. (@command{awk} accepts this input as
syntactically valid, because functions may be used before they are defined
in @command{awk} programs.@footnote{This program won't actually run,
-since @code{foo()} is undefined.})
+because @code{foo()} is undefined.})
@cindex portability, functions@comma{} defining
To ensure that your @command{awk} programs are portable, always use the
@@ -19501,7 +19600,7 @@ The following is an example of a recursive function. It takes a string
as an input parameter and returns the string in backwards order.
Recursive functions must always have a test that stops the recursion.
In this case, the recursion terminates when the input string is
-already empty.
+already empty:
@c 8/2014: Thanks to Mike Brennan for the improved formulation
@cindex @code{rev()} user-defined function
@@ -19549,7 +19648,7 @@ function ctime(ts, format)
@end example
You might think that @code{ctime()} could use @code{PROCINFO["strftime"]}
-for its format string. That would be a mistake, since @code{ctime()} is
+for its format string. That would be a mistake, because @code{ctime()} is
supposed to return the time formatted in a standard fashion, and user-level
code could have changed @code{PROCINFO["strftime"]}.
@c ENDOFRANGE fdef
@@ -19570,7 +19669,7 @@ the function.
@end menu
@node Calling A Function
-@subsubsection Writing A Function Call
+@subsubsection Writing a Function Call
A function call consists of the function name followed by the arguments
in parentheses. @command{awk} expressions are what you write in the
@@ -19585,7 +19684,7 @@ foo(x y, "lose", 4 * z)
@quotation CAUTION
Whitespace characters (spaces and TABs) are not allowed
-between the function name and the open-parenthesis of the argument list.
+between the function name and the opening parenthesis of the argument list.
If you write whitespace by mistake, @command{awk} might think that you mean
to concatenate a variable with an expression in parentheses. However, it
notices that you used a function name and not a variable name, and reports
@@ -19625,7 +19724,7 @@ function foo(j)
print "foo's i=" i
@}
-BEGIN @{
+BEGIN @{
i = 10
print "top's i=" i
foo(0)
@@ -19648,13 +19747,13 @@ top's i=3
@end example
If you want @code{i} to be local to both @code{foo()} and @code{bar()} do as
-follows (the extra-space before @code{i} is a coding convention to
+follows (the extra space before @code{i} is a coding convention to
indicate that @code{i} is a local variable, not an argument):
@example
function bar( i)
@{
- for (i = 0; i < 3; i++)
+ for (i = 0; i < 3; i++)
print "bar's i=" i
@}
@@ -19666,10 +19765,10 @@ function foo(j, i)
print "foo's i=" i
@}
-BEGIN @{
+BEGIN @{
i = 10
print "top's i=" i
- foo(0)
+ foo(0)
print "top's i=" i
@}
@end example
@@ -19728,21 +19827,16 @@ At level 2, index 2 is found in a
@end example
@node Pass By Value/Reference
-@subsubsection Passing Function Arguments By Value Or By Reference
+@subsubsection Passing Function Arguments by Value Or by Reference
In @command{awk}, when you declare a function, there is no way to
declare explicitly whether the arguments are passed @dfn{by value} or
@dfn{by reference}.
-Instead the passing convention is determined at runtime when
+Instead, the passing convention is determined at runtime when
the function is called according to the following rule:
-
-@itemize
-@item
-If the argument is an array variable, then it is passed by reference,
-@item
-Otherwise the argument is passed by value.
-@end itemize
+if the argument is an array variable, then it is passed by reference.
+Otherwise, the argument is passed by value.
@cindex call by value
Passing an argument by value means that when a function is called, it
@@ -19845,7 +19939,13 @@ If @option{--lint} is specified
Some @command{awk} implementations generate a runtime
error if you use either the @code{next} statement
or the @code{nextfile} statement
-(@pxref{Next Statement}, also @pxref{Nextfile Statement})
+(@pxref{Next Statement}, and
+@ifdocbook
+@ref{Nextfile Statement})
+@end ifdocbook
+@ifnotdocbook
+@pxref{Nextfile Statement})
+@end ifnotdocbook
inside a user-defined function.
@command{gawk} does not have this limitation.
@c ENDOFRANGE fudc
@@ -19901,8 +20001,8 @@ function maxelt(vec, i, ret)
@noindent
You call @code{maxelt()} with one argument, which is an array name. The local
variables @code{i} and @code{ret} are not intended to be arguments;
-while there is nothing to stop you from passing more than one argument
-to @code{maxelt()}, the results would be strange. The extra space before
+there is nothing to stop you from passing more than one argument
+to @code{maxelt()} but the results would be strange. The extra space before
@code{i} in the function parameter list indicates that @code{i} and
@code{ret} are local variables.
You should follow this convention when defining functions.
@@ -20039,8 +20139,8 @@ variable as the @emph{name} of the function to call.
@cindex indirect function calls, @code{@@}-notation
@cindex function calls, indirect, @code{@@}-notation for
The syntax is similar to that of a regular function call: an identifier
-immediately followed by a left parenthesis, any arguments, and then
-a closing right parenthesis, with the addition of a leading @samp{@@}
+immediately followed by an opening parenthesis, any arguments, and then
+a closing parenthesis, with the addition of a leading @samp{@@}
character:
@example
@@ -20049,7 +20149,7 @@ result = @@the_func() # calls the sum() function
@end example
Here is a full program that processes the previously shown data,
-using indirect function calls.
+using indirect function calls:
@example
@c file eg/prog/indirectcall.awk
@@ -20090,7 +20190,7 @@ function sum(first, last, ret, i)
These two functions expect to work on fields; thus the parameters
@code{first} and @code{last} indicate where in the fields to start and end.
-Otherwise they perform the expected computations and are not unusual.
+Otherwise they perform the expected computations and are not unusual:
@example
@c file eg/prog/indirectcall.awk
@@ -20135,11 +20235,11 @@ $ @kbd{gawk -f indirectcall.awk class_data1}
@print{} Biology 101:
@print{} sum: <352.8>
@print{} average: <88.2>
-@print{}
+@print{}
@print{} Chemistry 305:
@print{} sum: <356.4>
@print{} average: <89.1>
-@print{}
+@print{}
@print{} English 401:
@print{} sum: <376.1>
@print{} average: <94.025>
@@ -20261,7 +20361,7 @@ function do_sort(first, last, compare, data, i, retval)
retval = data[1]
for (i = 2; i in data; i++)
retval = retval " " data[i]
-
+
return retval
@}
@c endfile
@@ -20307,13 +20407,13 @@ $ @kbd{gawk -f quicksort.awk -f indirectcall.awk class_data2}
@print{} average: <88.2>
@print{} sort: <78.5 87.0 92.4 94.9>
@print{} rsort: <94.9 92.4 87.0 78.5>
-@print{}
+@print{}
@print{} Chemistry 305:
@print{} sum: <356.4>
@print{} average: <89.1>
@print{} sort: <75.2 88.2 94.7 98.3>
@print{} rsort: <98.3 94.7 88.2 75.2>
-@print{}
+@print{}
@print{} English 401:
@print{} sum: <376.1>
@print{} average: <94.025>
@@ -20416,7 +20516,7 @@ functions.
POSIX @command{awk} provides three kinds of built-in functions: numeric,
string, and I/O. @command{gawk} provides functions that sort arrays, work
with values representing time, do bit manipulation, determine variable
-type (array vs.@: scalar), and internationalize and localize programs.
+type (array versus scalar), and internationalize and localize programs.
@command{gawk} also provides several extensions to some of standard
functions, typically in the form of additional arguments.
@@ -20472,7 +20572,7 @@ program. This is equivalent to function pointers in C and C++.
@c ENDOFRANGE funcud
@ifnotinfo
-@part @value{PART2}Problem Solving With @command{awk}
+@part @value{PART2}Problem Solving with @command{awk}
@end ifnotinfo
@ifdocbook
@@ -20482,10 +20582,10 @@ It contains the following chapters:
@itemize @value{BULLET}
@item
-@ref{Library Functions}.
+@ref{Library Functions}
@item
-@ref{Sample Programs}.
+@ref{Sample Programs}
@end itemize
@end ifdocbook
@@ -20546,9 +20646,9 @@ and would like to contribute them to the @command{awk} user community, see
@cindex portability, example programs
The programs in this @value{CHAPTER} and in
@ref{Sample Programs},
-freely use features that are @command{gawk}-specific.
+freely use @command{gawk}-specific features.
Rewriting these programs for different implementations of @command{awk}
-is pretty straightforward.
+is pretty straightforward:
@itemize @value{BULLET}
@item
@@ -20618,7 +20718,7 @@ Library functions often need to have global variables that they can use to
preserve state information between calls to the function---for example,
@code{getopt()}'s variable @code{_opti}
(@pxref{Getopt Function}).
-Such variables are called @dfn{private}, since the only functions that need to
+Such variables are called @dfn{private}, as the only functions that need to
use them are the ones in the library.
When writing a library function, you should try to choose names for your
@@ -20640,10 +20740,10 @@ In addition, several of the library functions use a prefix that helps
indicate what function or set of functions use the variables---for example,
@code{_pw_byname()} in the user database routines
(@pxref{Passwd Functions}).
-This convention is recommended, since it even further decreases the
+This convention is recommended, as it even further decreases the
chance of inadvertent conflict among variable names. Note that this
convention is used equally well for variable names and for private
-function names.@footnote{While all the library routines could have
+function names.@footnote{Although all the library routines could have
been rewritten to use this convention, this was not done, in order to
show how our own @command{awk} programming style has evolved and to
provide some basis for this discussion.}
@@ -20716,7 +20816,7 @@ programming use.
@end menu
@node Strtonum Function
-@subsection Converting Strings To Numbers
+@subsection Converting Strings to Numbers
The @code{strtonum()} function (@pxref{String Functions})
is a @command{gawk} extension. The following function
@@ -20784,7 +20884,7 @@ function mystrtonum(str, ret, n, i, k, c)
# a[6] = "1.e3"
# a[7] = "1.32"
# a[8] = "1.32E2"
-#
+#
# for (i = 1; i in a; i++)
# print a[i], strtonum(a[i]), mystrtonum(a[i])
# @}
@@ -20798,7 +20898,7 @@ string. It sets @code{k} to the index in @code{"1234567"} of the current
octal digit.
The return value will either be the same number as the digit, or zero
if the character is not there, which will be true for a @samp{0}.
-This is safe, since the regexp test in the @code{if} ensures that
+This is safe, because the regexp test in the @code{if} ensures that
only octal values are converted.
Similar logic applies to the code that checks for and converts a
@@ -21145,7 +21245,7 @@ is always 1. This means that on those systems, characters
have numeric values from 128 to 255.
Finally, large mainframe systems use the EBCDIC character set, which
uses all 256 values.
-While there are other character sets in use on some older systems,
+There are other character sets in use on some older systems, but
they are not really worth worrying about:
@example
@@ -21199,7 +21299,7 @@ Good function design is important; this function needs to be general but it
should also have a reasonable default behavior. It is called with an array
as well as the beginning and ending indices of the elements in the array to be
merged. This assumes that the array indices are numeric---a reasonable
-assumption since the array was likely created with @code{split()}
+assumption, as the array was likely created with @code{split()}
(@pxref{String Functions}):
@cindex @code{join()} user-defined function
@@ -21252,7 +21352,7 @@ more difficult than they really need to be.}
The @code{systime()} and @code{strftime()} functions described in
@DBREF{Time Functions}
provide the minimum functionality necessary for dealing with the time of day
-in human readable form. While @code{strftime()} is extensive, the control
+in human-readable form. Although @code{strftime()} is extensive, the control
formats are not necessarily easy to remember or intuitively obvious when
reading a program.
@@ -21343,7 +21443,7 @@ allowed the user to supply an optional timestamp value to use instead
of the current time.
@node Readfile Function
-@subsection Reading A Whole File At Once
+@subsection Reading a Whole File At Once
Often, it is convenient to have the entire contents of a file available
in memory as a single string. A straightforward but naive way to
@@ -21403,7 +21503,7 @@ will never match if the file has contents. @command{gawk} reads data from
the file into @code{tmp} attempting to match @code{RS}. The match fails
after each read, but fails quickly, such that @command{gawk} fills
@code{tmp} with the entire contents of the file.
-(@xref{Records}, for information on @code{RT} and @code{RS}.)
+(@DBXREF{Records} for information on @code{RT} and @code{RS}.)
In the case that @code{file} is empty, the return value is the null
string. Thus calling code may use something like:
@@ -21421,7 +21521,7 @@ test would be @samp{contents == ""}.
also reads an entire file into memory.
@node Shell Quoting
-@subsection Quoting Strings to Pass to The Shell
+@subsection Quoting Strings to Pass to the Shell
@c included by permission
@ignore
@@ -21463,7 +21563,7 @@ chmod -w file.flac
Note the need for shell quoting. The function @code{shell_quote()}
does it. @code{SINGLE} is the one-character string @code{"'"} and
-@code{QSINGLE} is the three-character string @code{"\"'\""}.
+@code{QSINGLE} is the three-character string @code{"\"'\""}:
@example
@c file eg/lib/shellquote.awk
@@ -21523,7 +21623,7 @@ command-line @value{DF}s.
@cindex files, managing, data file boundaries
@cindex files, initialization and cleanup
-The @code{BEGIN} and @code{END} rules are each executed exactly once at
+The @code{BEGIN} and @code{END} rules are each executed exactly once, at
the beginning and end of your @command{awk} program, respectively
(@pxref{BEGIN/END}).
We (the @command{gawk} authors) once had a user who mistakenly thought that the
@@ -21595,7 +21695,7 @@ The following version solves the problem:
@example
@c file eg/lib/ftrans.awk
-# ftrans.awk --- handle data file transitions
+# ftrans.awk --- handle datafile transitions
#
# user supplies beginfile() and endfile() functions
@c endfile
@@ -21623,10 +21723,10 @@ END @{ endfile(_filename_) @}
shows how this library function can be used and
how it simplifies writing the main program.
-@cindex sidebar, So Why Does @command{gawk} have @code{BEGINFILE} and @code{ENDFILE}?
+@cindex sidebar, So Why Does @command{gawk} Have @code{BEGINFILE} and @code{ENDFILE}?
@ifdocbook
@docbook
-<sidebar><title>So Why Does @command{gawk} have @code{BEGINFILE} and @code{ENDFILE}?</title>
+<sidebar><title>So Why Does @command{gawk} Have @code{BEGINFILE} and @code{ENDFILE}?</title>
@end docbook
@@ -21636,7 +21736,7 @@ functions can do the job, why does @command{gawk} have
Good question. Normally, if @command{awk} cannot open a file, this
causes an immediate fatal error. In this case, there is no way for a
-user-defined function to deal with the problem, since the mechanism for
+user-defined function to deal with the problem, as the mechanism for
calling it relies on the file being open and at the first record. Thus,
the main reason for @code{BEGINFILE} is to give you a ``hook'' to catch
files that cannot be processed. @code{ENDFILE} exists for symmetry,
@@ -21649,7 +21749,7 @@ and because it provides an easy way to do per-file cleanup processing.
@ifnotdocbook
@cartouche
-@center @b{So Why Does @command{gawk} have @code{BEGINFILE} and @code{ENDFILE}?}
+@center @b{So Why Does @command{gawk} Have @code{BEGINFILE} and @code{ENDFILE}?}
@@ -21659,7 +21759,7 @@ functions can do the job, why does @command{gawk} have
Good question. Normally, if @command{awk} cannot open a file, this
causes an immediate fatal error. In this case, there is no way for a
-user-defined function to deal with the problem, since the mechanism for
+user-defined function to deal with the problem, as the mechanism for
calling it relies on the file being open and at the first record. Thus,
the main reason for @code{BEGINFILE} is to give you a ``hook'' to catch
files that cannot be processed. @code{ENDFILE} exists for symmetry,
@@ -21718,8 +21818,8 @@ The @code{rewind()} function relies on the @code{ARGIND} variable
(@pxref{Auto-set}), which is specific to @command{gawk}. It also
relies on the @code{nextfile} keyword (@pxref{Nextfile Statement}).
Because of this, you should not call it from an @code{ENDFILE} rule.
-(This isn't necessary anyway, since as soon as an @code{ENDFILE} rule
-finishes @command{gawk} goes to the next file!)
+(This isn't necessary anyway, because @command{gawk} goes to the next
+file as soon as an @code{ENDFILE} rule finishes!)
@node File Checking
@subsection Checking for Readable @value{DDF}s
@@ -21767,19 +21867,19 @@ BEGIN @{
@cindex troubleshooting, @code{getline} function
This works, because the @code{getline} won't be fatal.
Removing the element from @code{ARGV} with @code{delete}
-skips the file (since it's no longer in the list).
+skips the file (because it's no longer in the list).
See also @ref{ARGC and ARGV}.
-The regular expression check purposely does not use character classes
+Because @command{awk} variable names only allow the English letters,
+the regular expression check purposely does not use character classes
such as @samp{[:alpha:]} and @samp{[:alnum:]}
(@pxref{Bracket Expressions})
-since @command{awk} variable names only allow the English letters.
@node Empty Files
@subsection Checking for Zero-length Files
All known @command{awk} implementations silently skip over zero-length files.
-This is a by-product of @command{awk}'s implicit
+This is a by-product of @command{awk}'s implicit
read-a-record-and-match-against-the-rules loop: when @command{awk}
tries to read a record from an empty file, it immediately receives an
end of file indication, closes the file, and proceeds on to the next
@@ -21915,12 +22015,12 @@ are left alone.
@c STARTOFRANGE clibf
@cindex functions, library, C library
@cindex arguments, processing
-Most utilities on POSIX compatible systems take options on
+Most utilities on POSIX-compatible systems take options on
the command line that can be used to change the way a program behaves.
@command{awk} is an example of such a program
(@pxref{Options}).
-Often, options take @dfn{arguments}; i.e., data that the program needs to
-correctly obey the command-line option. For example, @command{awk}'s
+Often, options take @dfn{arguments} (i.e., data that the program needs to
+correctly obey the command-line option). For example, @command{awk}'s
@option{-F} option requires a string to use as the field separator.
The first occurrence on the command line of either @option{--} or a
string that does not begin with @samp{-} ends the options.
@@ -22024,7 +22124,7 @@ necessary for accessing individual characters
(@pxref{String Functions}).@footnote{This
function was written before @command{gawk} acquired the ability to
split strings into single characters using @code{""} as the separator.
-We have left it alone, since using @code{substr()} is more portable.}
+We have left it alone, as using @code{substr()} is more portable.}
The discussion that follows walks through the code a bit at a time:
@@ -22192,9 +22292,9 @@ next element in @code{argv}. If neither condition is true, then only
on the next call to @code{getopt()}.
The @code{BEGIN} rule initializes both @code{Opterr} and @code{Optind} to one.
-@code{Opterr} is set to one, since the default behavior is for @code{getopt()}
+@code{Opterr} is set to one, because the default behavior is for @code{getopt()}
to print a diagnostic message upon seeing an invalid option. @code{Optind}
-is set to one, since there's no reason to look at the program name, which is
+is set to one, because there's no reason to look at the program name, which is
in @code{ARGV[0]}:
@example
@@ -22244,16 +22344,22 @@ etc., as its own options.
@quotation NOTE
After @code{getopt()} is through,
-user level code must clear out all the elements of @code{ARGV} from 1
+user-level code must clear out all the elements of @code{ARGV} from 1
to @code{Optind}, so that @command{awk} does not try to process the
command-line options as @value{FN}s.
@end quotation
Using @samp{#!} with the @option{-E} option may help avoid
conflicts between your program's options and @command{gawk}'s options,
-since @option{-E} causes @command{gawk} to abandon processing of
+as @option{-E} causes @command{gawk} to abandon processing of
further options
-(@pxref{Executable Scripts}, and @pxref{Options}).
+(@DBPXREF{Executable Scripts} and
+@ifnotdocbook
+@pxref{Options}).
+@end ifnotdocbook
+@ifdocbook
+@ref{Options}).
+@end ifdocbook
Several of the sample programs presented in
@ref{Sample Programs},
@@ -22283,7 +22389,7 @@ However, because these are numbers, they do not provide very useful
information to the average user. There needs to be some way to find the
user information associated with the user and group ID numbers. This
@value{SECTION} presents a suite of functions for retrieving information from the
-user database. @xref{Group Functions},
+user database. @DBXREF{Group Functions}
for a similar suite that retrieves information from the group database.
@cindex @code{getpwent()} function (C library)
@@ -22302,7 +22408,7 @@ The ``password'' comes from the original user database file,
encrypted passwords (hence the name).
@cindex @command{pwcat} program
-While an @command{awk} program could simply read @file{/etc/passwd}
+Although an @command{awk} program could simply read @file{/etc/passwd}
directly, this file may not contain complete information about the
system's set of users.@footnote{It is often the case that password
information is stored in a network database.} To be sure you are able to
@@ -22397,12 +22503,12 @@ The user's encrypted password. This may not be available on some systems.
@item User-ID
The user's numeric user ID number.
-(On some systems it's a C @code{long}, and not an @code{int}. Thus
+(On some systems, it's a C @code{long}, and not an @code{int}. Thus
we cast it to @code{long} for all cases.)
@item Group-ID
The user's numeric group ID number.
-(Similar comments about @code{long} vs.@: @code{int} apply here.)
+(Similar comments about @code{long} versus @code{int} apply here.)
@item Full name
The user's full name, and perhaps other information associated with the
@@ -22503,7 +22609,7 @@ The function @code{_pw_init()} fills three copies of the user information
into three associative arrays. The arrays are indexed by username
(@code{_pw_byname}), by user ID number (@code{_pw_byuid}), and by order of
occurrence (@code{_pw_bycount}).
-The variable @code{_pw_inited} is used for efficiency, since @code{_pw_init()}
+The variable @code{_pw_inited} is used for efficiency, as @code{_pw_init()}
needs to be called only once.
@cindex @code{PROCINFO} array, testing the field splitting
@@ -22512,7 +22618,7 @@ Because this function uses @code{getline} to read information from
@command{pwcat}, it first saves the values of @code{FS}, @code{RS}, and @code{$0}.
It notes in the variable @code{using_fw} whether field splitting
with @code{FIELDWIDTHS} is in effect or not.
-Doing so is necessary, since these functions could be called
+Doing so is necessary, as these functions could be called
from anywhere within a user's program, and the user may have his
or her own way of splitting records and fields.
This makes it possible to restore the correct
@@ -22614,7 +22720,7 @@ In turn, calling @code{_pw_init()} is not too expensive, because the
once. If you are worried about squeezing every last cycle out of your
@command{awk} program, the check of @code{_pw_inited} could be moved out of
@code{_pw_init()} and duplicated in all the other functions. In practice,
-this is not necessary, since most @command{awk} programs are I/O-bound,
+this is not necessary, as most @command{awk} programs are I/O-bound,
and such a change would clutter up the code.
The @command{id} program in @DBREF{Id Program}
@@ -22753,7 +22859,7 @@ the association of name to number must be unique within the file.
we cast it to @code{long} for all cases.)
@item Group Member List
-A comma-separated list of user names. These users are members of the group.
+A comma-separated list of usernames. These users are members of the group.
Modern Unix systems allow users to be members of several groups
simultaneously. If your system does, then there are elements
@code{"group1"} through @code{"group@var{N}"} in @code{PROCINFO}
@@ -22868,7 +22974,7 @@ is being used, and to restore the appropriate field splitting mechanism.
The group information is stored is several associative arrays.
The arrays are indexed by group name (@code{@w{_gr_byname}}), by group ID number
(@code{@w{_gr_bygid}}), and by position in the database (@code{@w{_gr_bycount}}).
-There is an additional array indexed by user name (@code{@w{_gr_groupsbyuser}}),
+There is an additional array indexed by username (@code{@w{_gr_groupsbyuser}}),
which is a space-separated list of groups to which each user belongs.
Unlike the user database, it is possible to have multiple records in the
@@ -22881,7 +22987,7 @@ tvpeople:*:101:david,conan,tom,joan
@end example
For this reason, @code{_gr_init()} looks to see if a group name or
-group ID number is already seen. If it is, then the user names are
+group ID number is already seen. If it is, the usernames are
simply concatenated onto the previous list of users.@footnote{There is actually a
subtle problem with the code just presented. Suppose that
the first time there were no names. This code adds the names with
@@ -22927,7 +23033,7 @@ function getgrgid(gid)
@cindex @code{getgruser()} function (C library)
The @code{getgruser()} function does not have a C counterpart. It takes a
-user name and returns the list of groups that have the user as a member:
+username and returns the list of groups that have the user as a member:
@cindex @code{getgruser()} function, user-defined
@example
@@ -23070,7 +23176,7 @@ The functions presented here fit into the following categories:
@c nested list
@table @asis
@item General problems
-Number to string conversion, assertions, rounding, random number
+Number-to-string conversion, assertions, rounding, random number
generation, converting characters to numbers, joining strings, getting
easily usable time-of-day information, and reading a whole file in
one shot.
@@ -23130,7 +23236,7 @@ ARGIND != Argind @{
@}
END @{
if (ARGIND < ARGC - 1)
- ARGIND = ARGC - 1
+ ARGIND = ARGC - 1
if (ARGIND > Argind)
for (Argind++; Argind <= ARGIND; Argind++)
zerofile(ARGV[Argind], Argind)
@@ -23266,7 +23372,7 @@ The programs are presented in alphabetical order.
@end menu
@node Cut Program
-@subsection Cutting out Fields and Columns
+@subsection Cutting Out Fields and Columns
@cindex @command{cut} utility
@c STARTOFRANGE cut
@@ -23543,7 +23649,7 @@ function set_charlist( field, i, j, f, g, n, m, t,
@c endfile
@end example
-Next is the rule that actually processes the data. If the @option{-s} option
+Next is the rule that processes the data. If the @option{-s} option
is given, then @code{suppress} is true. The first @code{if} statement
makes sure that the input record does have the field separator. If
@command{cut} is processing fields, @code{suppress} is true, and the field
@@ -23575,9 +23681,9 @@ written out between the fields:
@end example
This version of @command{cut} relies on @command{gawk}'s @code{FIELDWIDTHS}
-variable to do the character-based cutting. While it is possible in
+variable to do the character-based cutting. It is possible in
other @command{awk} implementations to use @code{substr()}
-(@pxref{String Functions}),
+(@pxref{String Functions}), but
it is also extremely painful.
The @code{FIELDWIDTHS} variable supplies an elegant solution to the problem
of picking the input line apart by characters.
@@ -23722,7 +23828,7 @@ matched lines in the output:
@c endfile
@end example
-The last two lines are commented out, since they are not needed in
+The last two lines are commented out, as they are not needed in
@command{gawk}. They should be uncommented if you have to use another version
of @command{awk}.
@@ -23732,7 +23838,7 @@ into lowercase if the @option{-i} option is specified.@footnote{It
also introduces a subtle bug;
if a match happens, we output the translated line, not the original.}
The rule is
-commented out since it is not necessary with @command{gawk}:
+commented out as it is not necessary with @command{gawk}:
@example
@c file eg/prog/egrep.awk
@@ -23869,7 +23975,7 @@ function usage()
@c ENDOFRANGE egrep
@node Id Program
-@subsection Printing out User Information
+@subsection Printing Out User Information
@cindex printing, user information
@cindex users, information about, printing
@@ -23984,7 +24090,7 @@ function pr_first_field(str, a)
The test in the @code{for} loop is worth noting.
Any supplementary groups in the @code{PROCINFO} array have the
indices @code{"group1"} through @code{"group@var{N}"} for some
-@var{N}, i.e., the total number of supplementary groups.
+@var{N} (i.e., the total number of supplementary groups).
However, we don't know in advance how many of these groups
there are.
@@ -24024,10 +24130,10 @@ aims to demonstrate.}
By default,
the output files are named @file{xaa}, @file{xab}, and so on. Each file has
-1000 lines in it, with the likely exception of the last file. To change the
+1,000 lines in it, with the likely exception of the last file. To change the
number of lines in each file, supply a number on the command line
-preceded with a minus; e.g., @samp{-500} for files with 500 lines in them
-instead of 1000. To change the name of the output files to something like
+preceded with a minus (e.g., @samp{-500} for files with 500 lines in them
+instead of 1,000). To change the name of the output files to something like
@file{myfileaa}, @file{myfileab}, and so on, supply an additional
argument that specifies the @value{FN} prefix.
@@ -24075,7 +24181,7 @@ BEGIN @{
@}
# test argv in case reading from stdin instead of file
if (i in ARGV)
- i++ # skip data file name
+ i++ # skip datafile name
if (i in ARGV) @{
outfile = ARGV[i]
ARGV[i] = ""
@@ -24169,8 +24275,8 @@ truncating them and starting over.
The @code{BEGIN} rule first makes a copy of all the command-line arguments
into an array named @code{copy}.
-@code{ARGV[0]} is not copied, since it is not needed.
-@code{tee} cannot use @code{ARGV} directly, since @command{awk} attempts to
+@code{ARGV[0]} is not needed, so it is not copied.
+@code{tee} cannot use @code{ARGV} directly, because @command{awk} attempts to
process each @value{FN} in @code{ARGV} as input data.
@cindex flag variables
@@ -24219,7 +24325,7 @@ BEGIN @{
@c endfile
@end example
-The following single rule does all the work. Since there is no pattern, it is
+The following single rule does all the work. Because there is no pattern, it is
executed for each line of input. The body of the rule simply prints the
line into each file on the command line, and then to the standard output:
@@ -24250,7 +24356,7 @@ for (i in copy)
@end example
@noindent
-This is more concise but it is also less efficient. The @samp{if} is
+This is more concise, but it is also less efficient. The @samp{if} is
tested for each record and for each output file. By duplicating the loop
body, the @samp{if} is only tested once for each input record. If there are
@var{N} input records and @var{M} output files, the first method only
@@ -24470,10 +24576,10 @@ The second rule does the work. The variable @code{equal} is one or zero,
depending upon the results of @code{are_equal()}'s comparison. If @command{uniq}
is counting repeated lines, and the lines are equal, then it increments the @code{count} variable.
Otherwise, it prints the line and resets @code{count},
-since the two lines are not equal.
+because the two lines are not equal.
If @command{uniq} is not counting, and if the lines are equal, @code{count} is incremented.
-Nothing is printed, since the point is to remove duplicates.
+Nothing is printed, as the point is to remove duplicates.
Otherwise, if @command{uniq} is counting repeated lines and more than
one line is seen, or if @command{uniq} is counting nonrepeated lines
and only one line is seen, then the line is printed, and @code{count}
@@ -24542,7 +24648,7 @@ Brian Kernighan suggests that
``an alternative approach to state machines is to just read
the input into an array, then use indexing. It's almost always
easier code, and for most inputs where you would use this, just
-as fast.'' Consider how to rewrite the logic to follow this
+as fast.'' Consider how to rewrite the logic to follow this
suggestion.
@end ifset
@@ -24594,7 +24700,7 @@ Count only characters.
@end table
Implementing @command{wc} in @command{awk} is particularly elegant,
-since @command{awk} does a lot of the work for us; it splits lines into
+because @command{awk} does a lot of the work for us; it splits lines into
words (i.e., fields) and counts them, it counts lines (i.e., records),
and it can easily tell us how long a line is.
@@ -24699,7 +24805,7 @@ function endfile(file)
@end example
There is one rule that is executed for each line. It adds the length of
-the record, plus one, to @code{chars}.@footnote{Since @command{gawk}
+the record, plus one, to @code{chars}.@footnote{Because @command{gawk}
understands multibyte locales, this code counts characters, not bytes.}
Adding one plus the record length
is needed because the newline character separating records (the value
@@ -25047,8 +25153,8 @@ often used to map uppercase letters into lowercase for further processing:
@command{tr} requires two lists of characters.@footnote{On some older
systems, including Solaris, the system version of @command{tr} may require
that the lists be written as range expressions enclosed in square brackets
-(@samp{[a-z]}) and quoted, to prevent the shell from attempting a file
-name expansion. This is not a feature.} When processing the input, the
+(@samp{[a-z]}) and quoted, to prevent the shell from attempting a
+@value{FN} expansion. This is not a feature.} When processing the input, the
first character in the first list is replaced with the first character
in the second list, the second character in the first list is replaced
with the second character in the second list, and so on. If there are
@@ -25163,9 +25269,9 @@ BEGIN @{
@c endfile
@end example
-While it is possible to do character transliteration in a user-level
-function, it is not necessarily efficient, and we (the @command{gawk}
-authors) started to consider adding a built-in function. However,
+It is possible to do character transliteration in a user-level
+function, but it is not necessarily efficient, and we (the @command{gawk}
+developers) started to consider adding a built-in function. However,
shortly after writing this program, we learned that Brian Kernighan
had added the @code{toupper()} and @code{tolower()} functions to his
@command{awk} (@pxref{String Functions}). These functions handle the
@@ -25209,7 +25315,7 @@ the @code{line} array and printing the page when 20 labels have been read.
The @code{BEGIN} rule simply sets @code{RS} to the empty string, so that
@command{awk} splits records at blank lines
(@pxref{Records}).
-It sets @code{MAXLINES} to 100, since 100 is the maximum number
+It sets @code{MAXLINES} to 100, because 100 is the maximum number
of lines on the page
@iftex
(@math{20 @cdot 5 = 100}).
@@ -25366,9 +25472,9 @@ useful on real text files:
@item
The @command{awk} language considers upper- and lowercase characters to be
distinct. Therefore, ``bartender'' and ``Bartender'' are not treated
-as the same word. This is undesirable, since in normal text, words
-are capitalized if they begin sentences, and a frequency analyzer should not
-be sensitive to capitalization.
+as the same word. This is undesirable, because words are capitalized
+if they begin sentences in normal text, and a frequency analyzer should
+not be sensitive to capitalization.
@item
Words are detected using the @command{awk} convention that fields are
@@ -25549,7 +25655,7 @@ The nodes
and @ref{Sample Programs},
are the top level nodes for a large number of @command{awk} programs.
@end ifinfo
-If you want to experiment with these programs, it is tedious to have to type
+If you want to experiment with these programs, it is tedious to type
them in by hand. Here we present a program that can extract parts of a
Texinfo input file into separate files.
@@ -25627,7 +25733,7 @@ It also prints some final advice:
@@example
@@c file examples/messages.awk
-END @@@{ print "Always avoid bored archeologists!" @@@}
+END @@@{ print "Always avoid bored archaeologists!" @@@}
@@c end file
@@end example
@dots{}
@@ -25799,7 +25905,7 @@ The @command{sed} utility is a stream editor, a program that reads a
stream of data, makes changes to it, and passes it on.
It is often used to make global changes to a large file or to a stream
of data generated by a pipeline of commands.
-While @command{sed} is a complicated program in its own right, its most common
+Although @command{sed} is a complicated program in its own right, its most common
use is to perform global substitutions in the middle of a pipeline:
@example
@@ -25808,7 +25914,7 @@ use is to perform global substitutions in the middle of a pipeline:
Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp
@samp{old} on each input line and globally replace it with the text
-@samp{new}, i.e., all the occurrences on a line. This is similar to
+@samp{new} (i.e., all the occurrences on a line). This is similar to
@command{awk}'s @code{gsub()} function
(@pxref{String Functions}).
@@ -25892,7 +25998,7 @@ not treated as @value{FN}s
(@pxref{ARGC and ARGV}).
The @code{usage()} function prints an error message and exits.
-Finally, the single rule handles the printing scheme outlined above,
+Finally, the single rule handles the printing scheme outlined earlier,
using @code{print} or @code{printf} as appropriate, depending upon the
value of @code{RT}.
@c ENDOFRANGE awksed
@@ -25936,8 +26042,8 @@ BEGIN @{
The following program, @file{igawk.sh}, provides this service.
It simulates @command{gawk}'s searching of the @env{AWKPATH} variable
-and also allows @dfn{nested} includes; i.e., a file that is included
-with @code{@@include} can contain further @code{@@include} statements.
+and also allows @dfn{nested} includes (i.e., a file that is included
+with @code{@@include} can contain further @code{@@include} statements).
@command{igawk} makes an effort to only include files once, so that nested
includes don't accidentally include a library function twice.
@@ -25967,10 +26073,10 @@ Literal text, provided with @option{-e} or @option{--source}. This
text is just appended directly.
@item
-Source @value{FN}s, provided with @option{-f}. We use a neat trick and append
-@samp{@@include @var{filename}} to the shell variable's contents. Since the file-inclusion
-program works the way @command{gawk} does, this gets the text
-of the file included into the program at the correct point.
+Source @value{FN}s, provided with @option{-f}. We use a neat trick and
+append @samp{@@include @var{filename}} to the shell variable's contents.
+Because the file-inclusion program works the way @command{gawk} does, this
+gets the text of the file included in the program at the correct point.
@end enumerate
@item
@@ -26269,9 +26375,10 @@ EOF
@c endfile
@end example
-The shell construct @samp{@var{command} << @var{marker}} is called a @dfn{here document}.
-Everything in the shell script up to the @var{marker} is fed to @var{command} as input.
-The shell processes the contents of the here document for variable and command substitution
+The shell construct @samp{@var{command} << @var{marker}} is called
+a @dfn{here document}. Everything in the shell script up to the
+@var{marker} is fed to @var{command} as input. The shell processes
+the contents of the here document for variable and command substitution
(and possibly other things as well, depending upon the shell).
The shell construct @samp{$(@dots{})} is called @dfn{command substitution}.
@@ -26286,14 +26393,16 @@ It's done in these steps:
@enumerate
@item
Run @command{gawk} with the @code{@@include}-processing program (the
-value of the @code{expand_prog} shell variable) on standard input.
+value of the @code{expand_prog} shell variable) reading standard input.
@item
-Standard input is the contents of the user's program, from the shell variable @code{program}.
-Its contents are fed to @command{gawk} via a here document.
+Standard input is the contents of the user's program,
+from the shell variable @code{program}.
+Feed its contents to @command{gawk} via a here document.
@item
-The results of this processing are saved in the shell variable @code{processed_program} by using command substitution.
+Save the results of this processing in the shell variable
+@code{processed_program} by using command substitution.
@end enumerate
The last step is to call @command{gawk} with the expanded program,
@@ -26369,7 +26478,7 @@ of @command{awk} programs as Web CGI scripts.}
@c ENDOFRANGE igawk
@node Anagram Program
-@subsection Finding Anagrams From A Dictionary
+@subsection Finding Anagrams from a Dictionary
@cindex anagrams, finding
An interesting programming challenge is to
@@ -26378,17 +26487,17 @@ word list (such as
@file{/usr/share/dict/words} on many GNU/Linux systems).
One word is an anagram of another if both words contain
the same letters
-(for example, ``babbling'' and ``blabbing'').
+(e.g., ``babbling'' and ``blabbing'').
-Column 2, Problem C of Jon Bentley's @cite{Programming Pearls}, second
-edition, presents an elegant algorithm. The idea is to give words that
+Column 2, Problem C, of Jon Bentley's @cite{Programming Pearls}, Second
+Edition, presents an elegant algorithm. The idea is to give words that
are anagrams a common signature, sort all the words together by their
signature, and then print them. Dr.@: Bentley observes that taking the
letters in each word and sorting them produces that common signature.
The following program uses arrays of arrays to bring together
words with the same signature and array sorting to print the words
-in sorted order.
+in sorted order:
@c STARTOFRANGE anagram
@cindex @code{anagram.awk} program
@@ -26460,7 +26569,7 @@ function word2key(word, a, i, n, result)
Finally, the @code{END} rule traverses the array
and prints out the anagram lists. It sends the output
-to the system @command{sort} command, since otherwise
+to the system @command{sort} command because otherwise
the anagrams would appear in arbitrary order:
@example
@@ -26488,21 +26597,21 @@ Here is some partial output when the program is run:
@example
$ @kbd{gawk -f anagram.awk /usr/share/dict/words | grep '^b'}
@dots{}
-babbled blabbed
-babbler blabber brabble
-babblers blabbers brabbles
-babbling blabbing
-babbly blabby
-babel bable
-babels beslab
-babery yabber
+babbled blabbed
+babbler blabber brabble
+babblers blabbers brabbles
+babbling blabbing
+babbly blabby
+babel bable
+babels beslab
+babery yabber
@dots{}
@end example
@c ENDOFRANGE anagram
@node Signature Program
-@subsection And Now For Something Completely Different
+@subsection And Now for Something Completely Different
@cindex signature program
@cindex Brini, Davide
@@ -26542,28 +26651,28 @@ Subject: The GNU Awk User's Guide, Section 13.3.11
From: "Chris Johansen" <johansen@main.nc.us>
Message-ID: <op.v0iw6wlv7finx3@asusodin.thrudvang.lan>
-Arnold, you don't know me, but we have a tenuous connection. My wife is
+Arnold, you don't know me, but we have a tenuous connection. My wife is
Barbara A. Field, FAIA, GIT '65 (B. Arch.).
-I have had a couple of paper copies of "Effective Awk Programming" for
-years, and now I'm going through a Kindle version of "The GNU Awk User's
-Guide" again. When I got to section 13.3.11, I reformatted and lightly
+I have had a couple of paper copies of "Effective Awk Programming" for
+years, and now I'm going through a Kindle version of "The GNU Awk User's
+Guide" again. When I got to section 13.3.11, I reformatted and lightly
commented Davide Brin's signature script to understand its workings.
-It occurs to me that this might have pedagogical value as an example
-(although imperfect) of the value of whitespace and comments, and a
-starting point for that discussion. It certainly helped _me_ understand
-what's going on. You are welcome to it, as-is or modified (subject to
+It occurs to me that this might have pedagogical value as an example
+(although imperfect) of the value of whitespace and comments, and a
+starting point for that discussion. It certainly helped _me_ understand
+what's going on. You are welcome to it, as-is or modified (subject to
Davide's constraints, of course, which I think I have met).
-If I were to include it in a future edition, I would put it at some
-distance from section 13.3.11, say, as a note or an appendix, so as not to
+If I were to include it in a future edition, I would put it at some
+distance from section 13.3.11, say, as a note or an appendix, so as not to
be a "spoiler" to the puzzle.
Best regards,
---
+--
Chris Johansen {johansen at main dot nc dot us}
- . . . collapsing the probability wave function, sending ripples of
+ . . . collapsing the probability wave function, sending ripples of
certainty through the space-time continuum.
@@ -26572,7 +26681,7 @@ certainty through the space-time continuum.
# From "13.3.11 And Now For Something Completely Different"
# http://www.gnu.org/software/gawk/manual/html_node/Signature-Program.html#Signature-Program
-# Copyright © 2008 Davide Brini
+# Copyright © 2008 Davide Brini
# Copying and distribution of the code published in this page, with
# or without modification, are permitted in any medium without
@@ -26691,7 +26800,7 @@ Brian Kernighan suggests that
``an alternative approach to state machines is to just read
the input into an array, then use indexing. It's almost always
easier code, and for most inputs where you would use this, just
-as fast.'' Rewrite the logic to follow this
+as fast.'' Rewrite the logic to follow this
suggestion.
@@ -26792,7 +26901,7 @@ the use of the external @command{sort} utility.
@c EXCLUDE END
@ifnotinfo
-@part @value{PART3}Moving Beyond Standard @command{awk} With @command{gawk}
+@part @value{PART3}Moving Beyond Standard @command{awk} with @command{gawk}
@end ifnotinfo
@ifdocbook
@@ -26801,19 +26910,19 @@ It contains the following chapters:
@itemize @value{BULLET}
@item
-@ref{Advanced Features}.
+@ref{Advanced Features}
@item
-@ref{Internationalization}.
+@ref{Internationalization}
@item
-@ref{Debugger}.
+@ref{Debugger}
@item
-@ref{Arbitrary Precision Arithmetic}.
+@ref{Arbitrary Precision Arithmetic}
@item
-@ref{Dynamic Extensions}.
+@ref{Dynamic Extensions}
@end itemize
@end ifdocbook
@@ -26972,7 +27081,7 @@ in a particular order that you, the programmer, choose. @command{gawk}
lets you do this.
@DBREF{Controlling Scanning} describes how you can assign special,
-pre-defined values to @code{PROCINFO["sorted_in"]} in order to
+predefined values to @code{PROCINFO["sorted_in"]} in order to
control the order in which @command{gawk} traverses an array
during a @code{for} loop.
@@ -26996,7 +27105,7 @@ Here, @var{i1} and @var{i2} are the indices, and @var{v1} and @var{v2}
are the corresponding values of the two elements being compared.
Either @var{v1} or @var{v2}, or both, can be arrays if the array being
traversed contains subarrays as values.
-(@xref{Arrays of Arrays}, for more information about subarrays.)
+(@DBXREF{Arrays of Arrays} for more information about subarrays.)
The three possible return values are interpreted as follows:
@table @code
@@ -27039,7 +27148,7 @@ function cmp_str_val(i1, v1, i2, v2)
The third
comparison function makes all numbers, and numeric strings without
-any leading or trailing spaces, come out first during loop traversal:
+any leading or trailing spaces, come out first during loop traversal:
@example
function cmp_num_str_val(i1, v1, i2, v2, n1, n2)
@@ -27047,10 +27156,10 @@ function cmp_num_str_val(i1, v1, i2, v2, n1, n2)
# numbers before string value comparison, ascending order
n1 = v1 + 0
n2 = v2 + 0
- if (n1 == v1)
+ if (n1 == v1)
return (n2 == v2) ? (n1 - n2) : -1
else if (n2 == v2)
- return 1
+ return 1
return (v1 < v2) ? -1 : (v1 != v2)
@}
@end example
@@ -27065,7 +27174,7 @@ BEGIN @{
data[10] = "one"
data[100] = 100
data[20] = "two"
-
+
f[1] = "cmp_num_idx"
f[2] = "cmp_str_val"
f[3] = "cmp_num_str_val"
@@ -27089,14 +27198,14 @@ $ @kbd{gawk -f compdemo.awk}
@print{} data[10] = one
@print{} data[20] = two
@print{} data[100] = 100
-@print{}
+@print{}
@print{} Sort function: cmp_str_val @ii{Sort by element values as strings}
@print{} data[one] = 10
@print{} data[100] = 100 @ii{String 100 is less than string 20}
@print{} data[two] = 20
@print{} data[10] = one
@print{} data[20] = two
-@print{}
+@print{}
@print{} Sort function: cmp_num_str_val @ii{Sort all numeric values before all strings}
@print{} data[one] = 10
@print{} data[two] = 20
@@ -27107,7 +27216,7 @@ $ @kbd{gawk -f compdemo.awk}
Consider sorting the entries of a GNU/Linux system password file
according to login name. The following program sorts records
-by a specific field position and can be used for this purpose:
+by a specific field position and can be used for this purpose:
@example
# passwd-sort.awk --- simple program to sort by field position
@@ -27153,7 +27262,7 @@ $ @kbd{gawk -v POS=1 -F: -f sort.awk /etc/passwd}
The comparison should normally always return the same value when given a
specific pair of array elements as its arguments. If inconsistent
-results are returned then the order is undefined. This behavior can be
+results are returned, then the order is undefined. This behavior can be
exploited to introduce random order into otherwise seemingly
ordered data:
@@ -27165,7 +27274,7 @@ function cmp_randomize(i1, v1, i2, v2)
@}
@end example
-As mentioned above, the order of the indices is arbitrary if two
+As already mentioned, the order of the indices is arbitrary if two
elements compare equal. This is usually not a problem, but letting
the tied elements come out in arbitrary order can be an issue, especially
when comparing item values. The partial ordering of the equal elements
@@ -27206,10 +27315,10 @@ When string comparisons are made during a sort, either for element
values where one or both aren't numbers, or for element indices
handled as strings, the value of @code{IGNORECASE}
(@pxref{Built-in Variables}) controls whether
-the comparisons treat corresponding uppercase and lowercase letters as
+the comparisons treat corresponding upper- and lowercase letters as
equivalent or distinct.
-Another point to keep in mind is that in the case of subarrays
+Another point to keep in mind is that in the case of subarrays,
the element values can themselves be arrays; a production comparison
function should use the @code{isarray()} function
(@pxref{Type Functions}),
@@ -27217,7 +27326,7 @@ to check for this, and choose a defined sorting order for subarrays.
All sorting based on @code{PROCINFO["sorted_in"]}
is disabled in POSIX mode,
-since the @code{PROCINFO} array is not special in that case.
+because the @code{PROCINFO} array is not special in that case.
As a side note, sorting the array indices before traversing
the array has been reported to add 15% to 20% overhead to the
@@ -27238,8 +27347,8 @@ sorted array traversal is not the default.
@cindex @code{asorti()} function (@command{gawk}), arrays@comma{} sorting
@cindex sort function, arrays, sorting
In most @command{awk} implementations, sorting an array requires writing
-a @code{sort()} function. While this can be educational for exploring
-different sorting algorithms, usually that's not the point of the program.
+a @code{sort()} function. This can be educational for exploring
+different sorting algorithms, but usually that's not the point of the program.
@command{gawk} provides the built-in @code{asort()} and @code{asorti()}
functions (@pxref{String Functions}) for sorting arrays. For example:
@@ -27335,8 +27444,8 @@ Because @code{IGNORECASE} affects string comparisons, the value
of @code{IGNORECASE} also affects sorting for both @code{asort()} and @code{asorti()}.
Note also that the locale's sorting order does @emph{not}
come into play; comparisons are based on character values only.@footnote{This
-is true because locale-based comparison occurs only when in POSIX
-compatibility mode, and since @code{asort()} and @code{asorti()} are
+is true because locale-based comparison occurs only when in
+POSIX-compatibility mode, and because @code{asort()} and @code{asorti()} are
@command{gawk} extensions, they are not available in that case.}
@node Two-way I/O
@@ -27412,7 +27521,7 @@ remain more difficult to use than two-way pipes.} @c 8/2014
@cindex @command{csh} utility, @code{|&} operator, comparison with
However, with @command{gawk}, it is possible to
open a @emph{two-way} pipe to another process. The second process is
-termed a @dfn{coprocess}, since it runs in parallel with @command{gawk}.
+termed a @dfn{coprocess}, as it runs in parallel with @command{gawk}.
The two-way connection is created using the @samp{|&} operator
(borrowed from the Korn shell, @command{ksh}):@footnote{This is very
different from the same operator in the C shell and in Bash.}
@@ -27572,7 +27681,7 @@ You can think of this as just a @emph{very long} two-way pipeline to
a coprocess.
The way @command{gawk} decides that you want to use TCP/IP networking is
by recognizing special @value{FN}s that begin with one of @samp{/inet/},
-@samp{/inet4/} or @samp{/inet6/}.
+@samp{/inet4/}, or @samp{/inet6/}.
The full syntax of the special @value{FN} is
@file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}.
@@ -27601,7 +27710,7 @@ or @samp{http}, in which case @command{gawk} attempts to determine
the predefined port number using the C @code{getaddrinfo()} function.
@item remote-host
-The IP address or fully-qualified domain name of the Internet
+The IP address or fully qualified domain name of the Internet
host to which you want to connect.
@item remote-port
@@ -27675,12 +27784,12 @@ gawk --profile=myprog.prof -f myprog.awk data1 data2
@end example
@noindent
-In the above example, @command{gawk} places the profile in
+In the preceding example, @command{gawk} places the profile in
@file{myprog.prof} instead of in @file{awkprof.out}.
-Here is a sample session showing a simple @command{awk} program, its input data, and the
-results from running @command{gawk} with the @option{--profile} option.
-First, the @command{awk} program:
+Here is a sample session showing a simple @command{awk} program,
+its input data, and the results from running @command{gawk} with the
+@option{--profile} option. First, the @command{awk} program:
@example
BEGIN @{ print "First BEGIN rule" @}
@@ -27838,7 +27947,7 @@ the body of an @code{if}, @code{else}, or loop is only a single statement.
@item
Parentheses are used only where needed, as indicated by the structure
of the program and the precedence rules.
-For example, @samp{(3 + 5) * 4} means add three plus five, then multiply
+For example, @samp{(3 + 5) * 4} means add three and five, then multiply
the total by four. However, @samp{3 + 5 * 4} has no parentheses, and
means @samp{3 + (5 * 4)}.
@@ -28097,8 +28206,7 @@ following steps, in this order:
@enumerate
@item
-The programmer goes
-through the source for all of @command{guide}'s components
+The programmer reviews the source for all of @command{guide}'s components
and marks each string that is a candidate for translation.
For example, @code{"`-F': option required"} is a good candidate for translation.
A table with strings of option names is not (e.g., @command{gawk}'s
@@ -28218,8 +28326,8 @@ if necessary. (It is almost never necessary to supply a different category.)
@cindex sorting characters in different languages
@cindex @code{LC_COLLATE} locale category
@item LC_COLLATE
-Text-collation information; i.e., how different characters
-and/or groups of characters sort in a given language.
+Text-collation information (i.e., how different characters
+and/or groups of characters sort in a given language).
@cindex @code{LC_CTYPE} locale category
@item LC_CTYPE
@@ -28438,7 +28546,7 @@ BEGIN @{
@end enumerate
-@xref{I18N Example},
+@DBXREF{I18N Example}
for an example program showing the steps to create
and use translations from @command{awk}.
@@ -28499,7 +28607,7 @@ second argument to @code{dcngettext()}.@footnote{The
You should distribute the generated @file{.pot} file with
your @command{awk} program; translators will eventually use it
to provide you translations that you can also then distribute.
-@xref{I18N Example},
+@DBXREF{I18N Example}
for the full list of steps to go through to create and test
translations for @command{guide}.
@c ENDOFRANGE portobfi
@@ -28627,7 +28735,7 @@ change:
@cindex @code{TEXTDOMAIN} variable, portability and
@item
Assignments to @code{TEXTDOMAIN} won't have any effect,
-since @code{TEXTDOMAIN} is not special in other @command{awk} implementations.
+because @code{TEXTDOMAIN} is not special in other @command{awk} implementations.
@item
Non-GNU versions of @command{awk} treat marked strings
@@ -28675,8 +28783,8 @@ enough arguments are supplied in the function call. Many versions of
underlying C library version of @code{sprintf()}, but only one format and
argument at a time. What happens if a positional specification is
used is anybody's guess.
-However, since the positional specifications are primarily for use in
-@emph{translated} format strings, and since non-GNU @command{awk}s never
+However, because the positional specifications are primarily for use in
+@emph{translated} format strings, and because non-GNU @command{awk}s never
retrieve the translated string, this should not be a problem in practice.
@end itemize
@c ENDOFRANGE inap
@@ -28739,7 +28847,7 @@ called ``Hippy.'' Ah, well.}
@example
@group
-$ cp guide.pot guide-mellow.po
+$ @kbd{cp guide.pot guide-mellow.po}
@var{Add translations to} guide-mellow.po @dots{}
@end group
@end example
@@ -28765,7 +28873,7 @@ msgstr "Like, the scoop is"
The next step is to make the directory to hold the binary message object
file and then to create the @file{guide.mo} file.
We pretend that our file is to be used in the @code{en_US.UTF-8} locale,
-since we have to use a locale name known to the C @command{gettext} routines.
+because we have to use a locale name known to the C @command{gettext} routines.
The directory layout shown here is standard for GNU @command{gettext} on
GNU/Linux systems. Other versions of @command{gettext} may use a different
layout:
@@ -28802,7 +28910,7 @@ $ @kbd{gawk -f guide.awk}
@print{} Pardon me, Zaphod who?
@end example
-If the three replacement functions for @code{dcgettext()}, @code{dcngettext()}
+If the three replacement functions for @code{dcgettext()}, @code{dcngettext()},
and @code{bindtextdomain()}
(@pxref{I18N Portability})
are in a file named @file{libintl.awk},
@@ -28904,7 +29012,7 @@ how to use @command{gawk} for debugging your program is easy.
@end menu
@node Debugging
-@section Introduction to The @command{gawk} Debugger
+@section Introduction to the @command{gawk} Debugger
This @value{SECTION} introduces debugging in general and begins
the discussion of debugging in @command{gawk}.
@@ -28922,8 +29030,8 @@ the discussion of debugging in @command{gawk}.
ahead to the next section on the specific features of the @command{gawk}
debugger.)
-Of course, a debugging program cannot remove bugs for you, since it has
-no way of knowing what you or your users consider a ``bug'' and what is a
+Of course, a debugging program cannot remove bugs for you, because it has
+no way of knowing what you or your users consider a ``bug'' versus a
``feature.'' (Sometimes, we humans have a hard time with this ourselves.)
In that case, what can you expect from such a tool? The answer to that
depends on the language being debugged, but in general, you can expect at
@@ -28944,7 +29052,7 @@ having to change your source files.
@item
The chance to see the values of data in the program at any point in
execution, and also to change that data on the fly, to see how that
-affects what happens afterwards. (This often includes the ability
+affects what happens afterward. (This often includes the ability
to look at internal data structures besides the variables you actually
defined in your code.)
@@ -28964,11 +29072,11 @@ functional program that you or someone else wrote).
Before diving in to the details, we need to introduce several
important concepts that apply to just about all debuggers.
The following list defines terms used throughout the rest of
-this @value{CHAPTER}.
+this @value{CHAPTER}:
@table @dfn
@cindex stack frame
-@item Stack Frame
+@item Stack frame
Programs generally call functions during the course of their execution.
One function can call another, or a function can call itself (recursion).
You can view the chain of called functions (main program calls A, which
@@ -29003,7 +29111,7 @@ as many breakpoints as you like.
A watchpoint is similar to a breakpoint. The difference is that
breakpoints are oriented around the code: stop when a certain point in the
code is reached. A watchpoint, however, specifies that program execution
-should stop when a @emph{data value} is changed. This is useful, since
+should stop when a @emph{data value} is changed. This is useful, as
sometimes it happens that a variable receives an erroneous value, and it's
hard to track down where this happens just by looking at the code.
By using a watchpoint, you can stop whenever a variable is assigned to,
@@ -29017,13 +29125,13 @@ Debugging an @command{awk} program has some specific aspects that are
not shared with other programming languages.
First of all, the fact that @command{awk} programs usually take input
-line-by-line from a file or files and operate on those lines using specific
+line by line from a file or files and operate on those lines using specific
rules makes it especially useful to organize viewing the execution of
the program in terms of these rules. As we will see, each @command{awk}
rule is treated almost like a function call, with its own specific block
of instructions.
-In addition, since @command{awk} is by design a very concise language,
+In addition, because @command{awk} is by design a very concise language,
it is easy to lose sight of everything that is going on ``inside''
each line of @command{awk} code. The debugger provides the opportunity
to look at the individual primitive instructions carried out
@@ -29150,7 +29258,7 @@ gawk> @kbd{bt}
@end example
This tells us that @code{are_equal()} was called by the main program at
-line 88 of @file{uniq.awk}. (This is not a big surprise, since this
+line 88 of @file{uniq.awk}. (This is not a big surprise, because 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.)
@@ -29167,7 +29275,7 @@ gawk> @kbd{p n}
@end example
@noindent
-In this case, @code{n} is an uninitialized local variable, since the
+In this case, @code{n} is an uninitialized local variable, because the
function was called without arguments (@pxref{Function Calls}).
A more useful variable to display might be the current record:
@@ -29178,8 +29286,8 @@ gawk> @kbd{p $0}
@end example
@noindent
-This might be a bit puzzling at first since this is the second line of
-our test input above. Let's look at @code{NR}:
+This might be a bit puzzling at first, as this is the second line of
+our test input. Let's look at @code{NR}:
@example
gawk> @kbd{p NR}
@@ -29219,7 +29327,7 @@ gawk> @kbd{n}
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{-1} command-line option. (Notice that we skipped
-from where we were before at line 63 to here, since the condition in line 63
+from where we were before at line 63 to here, because 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
@@ -29249,7 +29357,7 @@ gawk> @kbd{p n m alast aline}
This is kind of disappointing, though. All we found out is that there
are five elements in @code{alast}; @code{m} and @code{aline} don't have
-values since we are at line 68 but haven't executed it yet.
+values because 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?
@@ -29358,8 +29466,9 @@ show the abbreviation on a second description line.
A debugger command name may also be truncated if that partial
name is unambiguous. The debugger has the built-in capability to
automatically repeat the previous command just by hitting @key{Enter}.
-This works for the commands @code{list}, @code{next}, @code{nexti}, @code{step}, @code{stepi}
-and @code{continue} executed without any argument.
+This works for the commands @code{list}, @code{next}, @code{nexti},
+@code{step}, @code{stepi}, and @code{continue} executed without any
+argument.
@menu
* Breakpoint Control:: Control of Breakpoints.
@@ -29374,9 +29483,9 @@ and @code{continue} executed without any argument.
@node Breakpoint Control
@subsection Control of Breakpoints
-As we saw above, the first thing you probably want to do in a debugging
-session is to get your breakpoints set up, since otherwise your program
-will just run as if it was not under the debugger. The commands for
+As we saw earlier, the first thing you probably want to do in a debugging
+session is to get your breakpoints set up, because your program
+will otherwise just run as if it was not under the debugger. The commands for
controlling breakpoints are:
@table @asis
@@ -29447,8 +29556,8 @@ that the debugger evaluates
whenever the breakpoint or watchpoint is reached. If the condition is true, then
the debugger stops execution and prompts for a command. Otherwise,
the debugger continues executing the program. If the condition expression is
-not specified, any existing condition is removed; i.e., the breakpoint or
-watchpoint is made unconditional.
+not specified, any existing condition is removed (i.e., the breakpoint or
+watchpoint is made unconditional).
@cindex debugger commands, @code{d} (@code{delete})
@cindex debugger commands, @code{delete}
@@ -29589,7 +29698,7 @@ Execute one (or @var{count}) instruction(s), stepping over function calls.
@item @code{return} [@var{value}]
Cancel execution of a function call. If @var{value} (either a string or a
number) is specified, it is used as the function's return value. If used in a
-frame other than the innermost one (the currently executing function, i.e.,
+frame other than the innermost one (the currently executing function; i.e.,
frame number 0), discard all inner frames in addition to the selected one,
and the caller of that frame becomes the innermost frame.
@@ -29655,7 +29764,7 @@ gawk> @kbd{display x}
@end example
@noindent
-displays the assigned item number, the variable name and its current value.
+This displays the assigned item number, the variable name, and its current value.
If the display variable refers to a function parameter, it is silently
deleted from the list as soon as the execution reaches a context where
no such variable of the given name exists.
@@ -29723,7 +29832,7 @@ or field.
String values must be enclosed between double quotes (@code{"}@dots{}@code{"}).
You can also set special @command{awk} variables, such as @code{FS},
-@code{NF}, @code{NR}, etc.
+@code{NF}, @code{NR}, and son on.
@cindex debugger commands, @code{w} (@code{watch})
@cindex debugger commands, @code{watch}
@@ -29786,7 +29895,7 @@ Print a backtrace of all function calls (stack frames), or innermost @var{count}
frames if @var{count} > 0. Print the outermost @var{count} frames if
@var{count} < 0. The backtrace displays the name and arguments to each
function, the source @value{FN}, and the line number.
-The alias @code{where} for @code{backtrace} is provided for long-time
+The alias @code{where} for @code{backtrace} is provided for longtime
GDB users who may be used to that command.
@cindex debugger commands, @code{down}
@@ -29815,7 +29924,7 @@ Then select and print the frame.
@end table
@node Debugger Info
-@subsection Obtaining Information about the Program and the Debugger State
+@subsection Obtaining Information About the Program and the Debugger State
Besides looking at the values of variables, there is often a need to get
other sorts of information about the state of your program and of the
@@ -29983,51 +30092,51 @@ partial dump of Davide Brini's obfuscated code
@smallexample
gawk> @kbd{dump}
@print{} # BEGIN
-@print{}
-@print{} [ 1:0xfcd340] Op_rule : [in_rule = BEGIN] [source_file = brini.awk]
-@print{} [ 1:0xfcc240] Op_push_i : "~" [MALLOC|STRING|STRCUR]
-@print{} [ 1:0xfcc2a0] Op_push_i : "~" [MALLOC|STRING|STRCUR]
-@print{} [ 1:0xfcc280] Op_match :
-@print{} [ 1:0xfcc1e0] Op_store_var : O
-@print{} [ 1:0xfcc2e0] Op_push_i : "==" [MALLOC|STRING|STRCUR]
-@print{} [ 1:0xfcc340] Op_push_i : "==" [MALLOC|STRING|STRCUR]
-@print{} [ 1:0xfcc320] Op_equal :
-@print{} [ 1:0xfcc200] Op_store_var : o
-@print{} [ 1:0xfcc380] Op_push : o
-@print{} [ 1:0xfcc360] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER]
-@print{} [ 1:0xfcc220] Op_push_lhs : o [do_reference = true]
-@print{} [ 1:0xfcc300] Op_assign_plus :
-@print{} [ :0xfcc2c0] Op_pop :
-@print{} [ 1:0xfcc400] Op_push : O
-@print{} [ 1:0xfcc420] Op_push_i : "" [MALLOC|STRING|STRCUR]
-@print{} [ :0xfcc4a0] Op_no_op :
-@print{} [ 1:0xfcc480] Op_push : O
-@print{} [ :0xfcc4c0] Op_concat : [expr_count = 3] [concat_flag = 0]
-@print{} [ 1:0xfcc3c0] Op_store_var : x
-@print{} [ 1:0xfcc440] Op_push_lhs : X [do_reference = true]
-@print{} [ 1:0xfcc3a0] Op_postincrement :
-@print{} [ 1:0xfcc4e0] Op_push : x
-@print{} [ 1:0xfcc540] Op_push : o
-@print{} [ 1:0xfcc500] Op_plus :
-@print{} [ 1:0xfcc580] Op_push : o
-@print{} [ 1:0xfcc560] Op_plus :
-@print{} [ 1:0xfcc460] Op_leq :
-@print{} [ :0xfcc5c0] Op_jmp_false : [target_jmp = 0xfcc5e0]
-@print{} [ 1:0xfcc600] Op_push_i : "%c" [MALLOC|STRING|STRCUR]
-@print{} [ :0xfcc660] Op_no_op :
-@print{} [ 1:0xfcc520] Op_assign_concat : c
-@print{} [ :0xfcc620] Op_jmp : [target_jmp = 0xfcc440]
-@print{}
-@dots{}
-@print{}
+@print{}
+@print{} [ 1:0xfcd340] Op_rule : [in_rule = BEGIN] [source_file = brini.awk]
+@print{} [ 1:0xfcc240] Op_push_i : "~" [MALLOC|STRING|STRCUR]
+@print{} [ 1:0xfcc2a0] Op_push_i : "~" [MALLOC|STRING|STRCUR]
+@print{} [ 1:0xfcc280] Op_match :
+@print{} [ 1:0xfcc1e0] Op_store_var : O
+@print{} [ 1:0xfcc2e0] Op_push_i : "==" [MALLOC|STRING|STRCUR]
+@print{} [ 1:0xfcc340] Op_push_i : "==" [MALLOC|STRING|STRCUR]
+@print{} [ 1:0xfcc320] Op_equal :
+@print{} [ 1:0xfcc200] Op_store_var : o
+@print{} [ 1:0xfcc380] Op_push : o
+@print{} [ 1:0xfcc360] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER]
+@print{} [ 1:0xfcc220] Op_push_lhs : o [do_reference = true]
+@print{} [ 1:0xfcc300] Op_assign_plus :
+@print{} [ :0xfcc2c0] Op_pop :
+@print{} [ 1:0xfcc400] Op_push : O
+@print{} [ 1:0xfcc420] Op_push_i : "" [MALLOC|STRING|STRCUR]
+@print{} [ :0xfcc4a0] Op_no_op :
+@print{} [ 1:0xfcc480] Op_push : O
+@print{} [ :0xfcc4c0] Op_concat : [expr_count = 3] [concat_flag = 0]
+@print{} [ 1:0xfcc3c0] Op_store_var : x
+@print{} [ 1:0xfcc440] Op_push_lhs : X [do_reference = true]
+@print{} [ 1:0xfcc3a0] Op_postincrement :
+@print{} [ 1:0xfcc4e0] Op_push : x
+@print{} [ 1:0xfcc540] Op_push : o
+@print{} [ 1:0xfcc500] Op_plus :
+@print{} [ 1:0xfcc580] Op_push : o
+@print{} [ 1:0xfcc560] Op_plus :
+@print{} [ 1:0xfcc460] Op_leq :
+@print{} [ :0xfcc5c0] Op_jmp_false : [target_jmp = 0xfcc5e0]
+@print{} [ 1:0xfcc600] Op_push_i : "%c" [MALLOC|STRING|STRCUR]
+@print{} [ :0xfcc660] Op_no_op :
+@print{} [ 1:0xfcc520] Op_assign_concat : c
+@print{} [ :0xfcc620] Op_jmp : [target_jmp = 0xfcc440]
+@print{}
+@dots{}
+@print{}
@print{} [ 2:0xfcc5a0] Op_K_printf : [expr_count = 17] [redir_type = ""]
-@print{} [ :0xfcc140] Op_no_op :
-@print{} [ :0xfcc1c0] Op_atexit :
-@print{} [ :0xfcc640] Op_stop :
-@print{} [ :0xfcc180] Op_no_op :
-@print{} [ :0xfcd150] Op_after_beginfile :
-@print{} [ :0xfcc160] Op_no_op :
-@print{} [ :0xfcc1a0] Op_after_endfile :
+@print{} [ :0xfcc140] Op_no_op :
+@print{} [ :0xfcc1c0] Op_atexit :
+@print{} [ :0xfcc640] Op_stop :
+@print{} [ :0xfcc180] Op_no_op :
+@print{} [ :0xfcd150] Op_after_beginfile :
+@print{} [ :0xfcc160] Op_no_op :
+@print{} [ :0xfcc1a0] Op_after_endfile :
gawk>
@end smallexample
@@ -30084,7 +30193,7 @@ function @var{function}. This command may change the current source file.
@itemx @code{q}
Exit the debugger. Debugging is great fun, but sometimes we all have
to tend to other obligations in life, and sometimes we find the bug,
-and are free to go on to the next one! As we saw above, if you are
+and are free to go on to the next one! As we saw earlier, if you are
running a program, the debugger warns you if you accidentally type
@samp{q} or @samp{quit}, to make sure you really want to quit.
@@ -30161,7 +30270,7 @@ If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands}
(or if you are already familiar with @command{gawk} internals),
you will realize that much of the internal manipulation of data
in @command{gawk}, as in many interpreters, is done on a stack.
-@code{Op_push}, @code{Op_pop}, etc., are the ``bread and butter'' of
+@code{Op_push}, @code{Op_pop}, and the like, are the ``bread and butter'' of
most @command{gawk} code.
Unfortunately, as of now, the @command{gawk}
@@ -30175,8 +30284,8 @@ change back to obscure, perhaps more optimal code later.
@item
There is no way to look ``inside'' the process of compiling
regular expressions to see if you got it right. As an @command{awk}
-programmer, you are expected to know what @code{/[^[:alnum:][:blank:]]/}
-means.
+programmer, you are expected to know the meaning of
+@code{/[^[:alnum:][:blank:]]/}.
@item
The @command{gawk} debugger is designed to be used by running a program (with all its
@@ -30228,7 +30337,7 @@ and editing.
@end itemize
@node Arbitrary Precision Arithmetic
-@chapter Arithmetic and Arbitrary Precision Arithmetic with @command{gawk}
+@chapter Arithmetic and Arbitrary-Precision Arithmetic with @command{gawk}
@cindex arbitrary precision
@cindex multiple precision
@cindex infinite precision
@@ -30238,9 +30347,9 @@ This @value{CHAPTER} introduces some basic concepts relating to
how computers do arithmetic and defines some important terms.
It then proceeds to describe floating-point arithmetic,
which is what @command{awk} uses for all its computations, including a
-discussion of arbitrary precision floating point arithmetic, which is
+discussion of arbitrary-precision floating-point arithmetic, which is
a feature available only in @command{gawk}. It continues on to present
-arbitrary precision integers, and concludes with a description of some
+arbitrary-precision integers, and concludes with a description of some
points where @command{gawk} and the POSIX standard are not quite in
agreement.
@@ -30303,51 +30412,51 @@ The disadvantage is that their range is limited.
@cindex integers, unsigned
In computers, integer values come in two flavors: @dfn{signed} and
@dfn{unsigned}. Signed values may be negative or positive, whereas
-unsigned values are always positive (that is, greater than or equal
+unsigned values are always positive (i.e., greater than or equal
to zero).
In computer systems, integer arithmetic is exact, but the possible
range of values is limited. Integer arithmetic is generally faster than
-floating point arithmetic.
+floating-point arithmetic.
-@item Floating point arithmetic
+@item Floating-point arithmetic
Floating-point numbers represent what were called in school ``real''
-numbers; i.e., those that have a fractional part, such as 3.1415927.
+numbers (i.e., those that have a fractional part, such as 3.1415927).
The advantage to floating-point numbers is that they can represent a
much larger range of values than can integers. The disadvantage is that
there are numbers that they cannot represent exactly.
-Modern systems support floating point arithmetic in hardware, with a
+Modern systems support floating-point arithmetic in hardware, with a
limited range of values. There are software libraries that allow
-the use of arbitrary precision floating point calculations.
+the use of arbitrary-precision floating-point calculations.
-POSIX @command{awk} uses @dfn{double precision} floating-point numbers, which
-can hold more digits than @dfn{single precision} floating-point numbers.
-@command{gawk} has facilities for performing arbitrary precision floating
-point arithmetic, which we describe in more detail shortly.
+POSIX @command{awk} uses @dfn{double-precision} floating-point numbers, which
+can hold more digits than @dfn{single-precision} floating-point numbers.
+@command{gawk} has facilities for performing arbitrary-precision
+floating-point arithmetic, which we describe in more detail shortly.
@end table
-Computers work with integer and floating point values of different
-ranges. Integer values are usually either 32 or 64 bits in size. Single
-precision floating point values occupy 32 bits, whereas double precision
-floating point values occupy 64 bits. Floating point values are always
+Computers work with integer and floating-point values of different
+ranges. Integer values are usually either 32 or 64 bits in size.
+Single-precision floating-point values occupy 32 bits, whereas double-precision
+floating-point values occupy 64 bits. Floating-point values are always
signed. The possible ranges of values are shown in @ref{table-numeric-ranges}.
@float Table,table-numeric-ranges
-@caption{Value Ranges for Different Numeric Representations}
+@caption{Value ranges for different numeric representations}
@multitable @columnfractions .34 .33 .33
@headitem Numeric representation @tab Minimum value @tab Maximum value
@item 32-bit signed integer @tab @minus{}2,147,483,648 @tab 2,147,483,647
@item 32-bit unsigned integer @tab 0 @tab 4,294,967,295
@item 64-bit signed integer @tab @minus{}9,223,372,036,854,775,808 @tab 9,223,372,036,854,775,807
@item 64-bit unsigned integer @tab 0 @tab 18,446,744,073,709,551,615
-@item Single precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38}
-@item Double precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308}
+@item Single-precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38}
+@item Double-precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308}
@end multitable
@end float
@node Math Definitions
-@section Other Stuff To Know
+@section Other Stuff to Know
The rest of this @value{CHAPTER} uses a number of terms. Here are some
informal definitions that should help you work your way through the material
@@ -30424,7 +30533,7 @@ How numbers are rounded up or down when necessary.
More details are provided later.
@item Significand
-A floating point value consists the significand multiplied by 10
+A floating-point value consists the significand multiplied by 10
to the power of the exponent. For example, in @code{1.2345e67},
the significand is @code{1.2345}.
@@ -30442,19 +30551,19 @@ on some of those terms.
On modern systems, floating-point hardware uses the representation and
operations defined by the IEEE 754 standard.
Three of the standard IEEE 754 types are 32-bit single precision,
-64-bit double precision and 128-bit quadruple precision.
+64-bit double precision, and 128-bit quadruple precision.
The standard also specifies extended precision formats
to allow greater precisions and larger exponent ranges.
-(@command{awk} uses only the 64-bit double precision format.)
+(@command{awk} uses only the 64-bit double-precision format.)
@ref{table-ieee-formats} lists the precision and exponent
field values for the basic IEEE 754 binary formats:
@float Table,table-ieee-formats
-@caption{Basic IEEE Format Values}
+@caption{Basic IEEE format values}
@multitable @columnfractions .20 .20 .20 .20 .20
@headitem Name @tab Total bits @tab Precision @tab Minimum exponent @tab Maximum exponent
-@item Single @tab 32 @tab 24 @tab @minus{}126 @tab +127
+@item Single @tab 32 @tab 24 @tab @minus{}126 @tab +127
@item Double @tab 64 @tab 53 @tab @minus{}1022 @tab +1023
@item Quadruple @tab 128 @tab 113 @tab @minus{}16382 @tab +16383
@end multitable
@@ -30466,14 +30575,14 @@ one extra bit of significand.
@end quotation
@node MPFR features
-@section Arbitrary Precision Arithmetic Features In @command{gawk}
+@section Arbitrary-Precision Arithmetic Features in @command{gawk}
-By default, @command{gawk} uses the double precision floating-point values
+By default, @command{gawk} uses the double-precision floating-point values
supplied by the hardware of the system it runs on. However, if it was
-compiled to do so, @command{gawk} uses the @uref{http://www.mpfr.org
-GNU MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for arbitrary
-precision arithmetic on numbers. You can see if MPFR support is available
-like so:
+compiled to do so, @command{gawk} uses the @uref{http://www.mpfr.org,
+GNU MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for
+arbitrary-precision arithmetic on numbers. You can see if MPFR support
+is available like so:
@example
$ @kbd{gawk --version}
@@ -30501,11 +30610,11 @@ Two predefined variables, @code{PREC} and @code{ROUNDMODE},
provide control over the working precision and the rounding mode.
The precision and the rounding mode are set globally for every operation
to follow.
-@xref{Setting precision}, and @ref{Setting the rounding mode},
+@DBXREF{Setting precision} and @DBREF{Setting the rounding mode}
for more information.
@node FP Math Caution
-@section Floating Point Arithmetic: Caveat Emptor!
+@section Floating-Point Arithmetic: Caveat Emptor!
@quotation
@i{Math class is tough!}
@@ -30538,17 +30647,17 @@ rely just on what we tell you.
@end menu
@node Inexactness of computations
-@subsection Floating Point Arithmetic Is Not Exact
+@subsection Floating-Point Arithmetic Is Not Exact
Binary floating-point representations and arithmetic are inexact.
Simple values like 0.1 cannot be precisely represented using
binary floating-point numbers, and the limited precision of
floating-point numbers means that slight changes in
the order of operations or the precision of intermediate storage
-can change the result. To make matters worse, with arbitrary precision
-floating-point, you can set the precision before starting a computation,
-but then you cannot be sure of the number of significant decimal places
-in the final result.
+can change the result. To make matters worse, with arbitrary-precision
+floating-point arithmetic, you can set the precision before starting a
+computation, but then you cannot be sure of the number of significant
+decimal places in the final result.
@menu
* Inexact representation:: Numbers are not exactly represented.
@@ -30570,7 +30679,7 @@ y = 0.425
Unlike the number in @code{y}, the number stored in @code{x}
is exactly representable
-in binary since it can be written as a finite sum of one or
+in binary because it can be written as a finite sum of one or
more fractions whose denominators are all powers of two.
When @command{gawk} reads a floating-point number from
program source, it automatically rounds that number to whatever
@@ -30596,7 +30705,7 @@ Because the underlying representation can be a little bit off from the exact val
comparing floating-point values to see if they are exactly equal is generally a bad idea.
Here is an example where it does not work like you would expect:
-@example
+@example
$ @kbd{gawk 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'}
@print{} 0
@end example
@@ -30605,7 +30714,7 @@ The general wisdom when comparing floating-point values is to see if
they are within some small range of each other (called a @dfn{delta},
or @dfn{tolerance}).
You have to decide how small a delta is important to you. Code to do
-this looks something like this:
+this looks something like the following:
@example
delta = 0.00001 # for example
@@ -30625,7 +30734,7 @@ else
The loss of accuracy during a single computation with floating-point
numbers usually isn't enough to worry about. However, if you compute a
-value which is the result of a sequence of floating point operations,
+value which is the result of a sequence of floating-point operations,
the error can accumulate and greatly affect the computation itself.
Here is an attempt to compute the value of @value{PI} using one of its
many series representations:
@@ -30671,9 +30780,9 @@ $ @kbd{gawk 'BEGIN @{}
@end example
@node Getting Accuracy
-@subsection Getting The Accuracy You Need
+@subsection Getting the Accuracy You Need
-Can arbitrary precision arithmetic give exact results? There are
+Can arbitrary-precision arithmetic give exact results? There are
no easy answers. The standard rules of algebra often do not apply
when using floating-point arithmetic.
Among other things, the distributive and associative laws
@@ -30682,12 +30791,12 @@ for your computation. Rounding error, cumulative precision loss
and underflow are often troublesome.
When @command{gawk} tests the expressions @samp{0.1 + 12.2} and
-@samp{12.3} for equality using the machine double precision arithmetic,
+@samp{12.3} for equality using the machine double-precision arithmetic,
it decides that they are not equal! (@xref{Comparing FP Values}.)
You can get the result you want by increasing the precision; 56 bits in
this case does the job:
-@example
+@example
$ @kbd{gawk -M -v PREC=56 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'}
@print{} 1
@end example
@@ -30696,7 +30805,7 @@ If adding more bits is good, perhaps adding even more bits of
precision is better?
Here is what happens if we use an even larger value of @code{PREC}:
-@example
+@example
$ @kbd{gawk -M -v PREC=201 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'}
@print{} 0
@end example
@@ -30705,15 +30814,15 @@ This is not a bug in @command{gawk} or in the MPFR library.
It is easy to forget that the finite number of bits used to store the value
is often just an approximation after proper rounding.
The test for equality succeeds if and only if @emph{all} bits in the two operands
-are exactly the same. Since this is not necessarily true after floating-point
+are exactly the same. Because this is not necessarily true after floating-point
computations with a particular precision and effective rounding mode,
a straight test for equality may not work. Instead, compare the
two numbers to see if they are within the desirable delta of each other.
In applications where 15 or fewer decimal places suffice,
-hardware double precision arithmetic can be adequate, and is usually much faster.
+hardware double-precision arithmetic can be adequate, and is usually much faster.
But you need to keep in mind that every floating-point operation
-can suffer a new rounding error with catastrophic consequences as illustrated
+can suffer a new rounding error with catastrophic consequences, as illustrated
by our earlier attempt to compute the value of @value{PI}.
Extra precision can greatly enhance the stability and the accuracy
of your computation in such cases.
@@ -30737,9 +30846,9 @@ an arbitrarily large value for @code{PREC}. Reformulation of
the problem at hand is often the correct approach in such situations.
@node Try To Round
-@subsection Try A Few Extra Bits of Precision and Rounding
+@subsection Try a Few Extra Bits of Precision and Rounding
-Instead of arbitrary precision floating-point arithmetic,
+Instead of arbitrary-precision floating-point arithmetic,
often all you need is an adjustment of your logic
or a different order for the operations in your calculation.
The stability and the accuracy of the computation of @value{PI}
@@ -30751,7 +30860,7 @@ simple algebraic transformation:
@end example
@noindent
-After making this, change the program converges to
+After making this change, the program converges to
@value{PI} in under 30 iterations:
@example
@@ -30767,7 +30876,7 @@ $ @kbd{gawk -f pi2.awk}
@end example
@node Setting precision
-@subsection Setting The Precision
+@subsection Setting the Precision
@command{gawk} uses a global working precision; it does not keep track of
the precision or accuracy of individual numbers. Performing an arithmetic
@@ -30779,14 +30888,14 @@ shown in @ref{table-predefined-precision-strings},
to emulate an IEEE 754 binary format.
@float Table,table-predefined-precision-strings
-@caption{Predefined Precision Strings For @code{PREC}}
+@caption{Predefined precision strings for @code{PREC}}
@multitable {@code{"double"}} {12345678901234567890123456789012345}
@headitem @code{PREC} @tab IEEE 754 Binary Format
-@item @code{"half"} @tab 16-bit half-precision.
-@item @code{"single"} @tab Basic 32-bit single precision.
-@item @code{"double"} @tab Basic 64-bit double precision.
-@item @code{"quad"} @tab Basic 128-bit quadruple precision.
-@item @code{"oct"} @tab 256-bit octuple precision.
+@item @code{"half"} @tab 16-bit half-precision
+@item @code{"single"} @tab Basic 32-bit single precision
+@item @code{"double"} @tab Basic 64-bit double precision
+@item @code{"quad"} @tab Basic 128-bit quadruple precision
+@item @code{"oct"} @tab 256-bit octuple precision
@end multitable
@end float
@@ -30817,7 +30926,7 @@ differences among various ways to print a floating-point constant:
@example
$ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 0.1) @}'}
-@print{} 0.1000000000000000055511151
+@print{} 0.1000000000000000055511151
$ @kbd{gawk -M -v PREC=113 'BEGIN @{ printf("%0.25f\n", 0.1) @}'}
@print{} 0.1000000000000000000000000
$ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", "0.1") @}'}
@@ -30827,7 +30936,7 @@ $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 1/10) @}'}
@end example
@node Setting the rounding mode
-@subsection Setting The Rounding Mode
+@subsection Setting the Rounding Mode
The @code{ROUNDMODE} variable provides
program level control over the rounding mode.
@@ -30835,7 +30944,7 @@ The correspondence between @code{ROUNDMODE} and the IEEE
rounding modes is shown in @ref{table-gawk-rounding-modes}.
@float Table,table-gawk-rounding-modes
-@caption{@command{gawk} Rounding Modes}
+@caption{@command{gawk} rounding modes}
@multitable @columnfractions .45 .30 .25
@headitem Rounding Mode @tab IEEE Name @tab @code{ROUNDMODE}
@item Round to nearest, ties to even @tab @code{roundTiesToEven} @tab @code{"N"} or @code{"n"}
@@ -30850,7 +30959,7 @@ rounding modes is shown in @ref{table-gawk-rounding-modes}.
selects the IEEE 754 rounding mode @code{roundTiesToEven}.
In @ref{table-gawk-rounding-modes}, the value @code{"A"} selects
@code{roundTiesToAway}. This is only available if your version of the
-MPFR library supports it; otherwise setting @code{ROUNDMODE} to @code{"A"}
+MPFR library supports it; otherwise, setting @code{ROUNDMODE} to @code{"A"}
has no effect.
The default mode @code{roundTiesToEven} is the most preferred,
@@ -30921,14 +31030,14 @@ accumulation of round-off error, look for a significant difference in
output when you change the rounding mode to be sure.
@node Arbitrary Precision Integers
-@section Arbitrary Precision Integer Arithmetic with @command{gawk}
+@section Arbitrary-Precision Integer Arithmetic with @command{gawk}
@cindex integers, arbitrary precision
@cindex arbitrary precision integers
When given the @option{-M} option,
-@command{gawk} performs all integer arithmetic using GMP arbitrary
-precision integers. Any number that looks like an integer in a source
-or @value{DF} is stored as an arbitrary precision integer. The size
+@command{gawk} performs all integer arithmetic using GMP arbitrary-precision
+integers. Any number that looks like an integer in a source
+or @value{DF} is stored as an arbitrary-precision integer. The size
of the integer is limited only by the available memory. For example,
the following computes
@iftex
@@ -30943,7 +31052,7 @@ the following computes
5<superscript>4<superscript>3<superscript>2</superscript></superscript></superscript>, @c
@end docbook
the result of which is beyond the
-limits of ordinary hardware double precision floating point values:
+limits of ordinary hardware double-precision floating-point values:
@example
$ @kbd{gawk -M 'BEGIN @{}
@@ -30955,7 +31064,7 @@ $ @kbd{gawk -M 'BEGIN @{}
@print{} 62060698786608744707 ... 92256259918212890625
@end example
-If instead you were to compute the same value using arbitrary precision
+If instead you were to compute the same value using arbitrary-precision
floating-point values, the precision needed for correct output (using
the formula
@iftex
@@ -31000,10 +31109,10 @@ floating-point results exactly. You can either increase the precision
@samp{2.0} with an integer, to perform all computations using integer
arithmetic to get the correct output.
-Sometimes @command{gawk} must implicitly convert an arbitrary precision
-integer into an arbitrary precision floating-point value. This is
+Sometimes @command{gawk} must implicitly convert an arbitrary-precision
+integer into an arbitrary-precision floating-point value. This is
primarily because the MPFR library does not always provide the relevant
-interface to process arbitrary precision integers or mixed-mode numbers
+interface to process arbitrary-precision integers or mixed-mode numbers
as needed by an operation or function. In such a case, the precision is
set to the minimum value necessary for exact conversion, and the working
precision is not used for this purpose. If this is not what you need or
@@ -31021,7 +31130,7 @@ to begin with:
gawk -M 'BEGIN @{ n = 13.0; print n % 2.0 @}'
@end example
-Note that for the particular example above, it is likely best
+Note that for this particular example, it is likely best
to just use the following:
@example
@@ -31043,13 +31152,13 @@ should support additional features. These features are:
@itemize @value{BULLET}
@item
-Interpretation of floating point data values specified in hexadecimal
+Interpretation of floating-point data values specified in hexadecimal
notation (e.g., @code{0xDEADBEEF}). (Note: data values, @emph{not}
source code constants.)
@item
-Support for the special IEEE 754 floating point values ``Not A Number''
-(NaN), positive Infinity (``inf'') and negative Infinity (``@minus{}inf'').
+Support for the special IEEE 754 floating-point values ``Not A Number''
+(NaN), positive Infinity (``inf''), and negative Infinity (``@minus{}inf'').
In particular, the format for these values is as specified by the ISO 1999
C standard, which ignores case and can allow implementation-dependent additional
characters after the @samp{nan} and allow either @samp{inf} or @samp{infinity}.
@@ -31060,8 +31169,8 @@ practice:
@itemize @value{BULLET}
@item
-The @command{gawk} maintainer feels that supporting hexadecimal floating
-point values, in particular, is ugly, and was never intended by the
+The @command{gawk} maintainer feels that supporting hexadecimal
+floating-point values, in particular, is ugly, and was never intended by the
original designers to be part of the language.
@item
@@ -31075,10 +31184,10 @@ interpretation of the standard, which requires a certain amount of
intended by the standard developers. In other words, ``we see how you
got where you are, but we don't think that that's where you want to be.''
-Recognizing the above issues, but attempting to provide compatibility
+Recognizing these issues, but attempting to provide compatibility
with the earlier versions of the standard,
the 2008 POSIX standard added explicit wording to allow, but not require,
-that @command{awk} support hexadecimal floating point values and
+that @command{awk} support hexadecimal floating-point values and
special values for ``Not A Number'' and infinity.
Although the @command{gawk} maintainer continues to feel that
@@ -31135,12 +31244,12 @@ Thus @samp{+nan} and @samp{+NaN} are the same.
@itemize @value{BULLET}
@item
Most computer arithmetic is done using either integers or floating-point
-values. Standard @command{awk} uses double precision
+values. Standard @command{awk} uses double-precision
floating-point values.
@item
-In the early 1990's, Barbie mistakenly said ``Math class is tough!''
-While math isn't tough, floating-point arithmetic isn't the same
+In the early 1990s, Barbie mistakenly said ``Math class is tough!''
+Although math isn't tough, floating-point arithmetic isn't the same
as pencil and paper math, and care must be taken:
@c nested list
@@ -31173,7 +31282,7 @@ arithmetic. Use @code{PREC} to set the precision in bits, and
@item
With @option{-M}, @command{gawk} performs
-arbitrary precision integer arithmetic using the GMP library.
+arbitrary-precision integer arithmetic using the GMP library.
This is faster and more space efficient than using MPFR for
the same calculations.
@@ -31186,7 +31295,7 @@ It pays to be aware of them.
Overall, there is no need to be unduly suspicious about the results from
floating-point arithmetic. The lesson to remember is that floating-point
arithmetic is always more complex than arithmetic using pencil and
-paper. In order to take advantage of the power of computer floating-point,
+paper. In order to take advantage of the power of computer floating point,
you need to know its limitations and work within them. For most casual
use of floating-point arithmetic, you will often get the expected result
if you simply round the display of your final results to the correct number
@@ -31250,8 +31359,8 @@ C library routines that could be of use. As with most software,
``the sky is the limit;'' if you can imagine something that you might
want to do and can write in C or C++, you can write an extension to do it!
-Extensions are written in C or C++, using the @dfn{Application Programming
-Interface} (API) defined for this purpose by the @command{gawk}
+Extensions are written in C or C++, using the @dfn{application programming
+interface} (API) defined for this purpose by the @command{gawk}
developers. The rest of this @value{CHAPTER} explains
the facilities that the API provides and how to use
them, and presents a small example extension. In addition, it documents
@@ -31288,7 +31397,7 @@ int plugin_is_GPL_compatible;
@end example
@node Extension Mechanism Outline
-@section At A High Level How It Works
+@section How It Works at a High Level
Communication between
@command{gawk} and an extension is two-way. First, when an extension
@@ -31303,22 +31412,22 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-load-extension"/>}.
@ifnotdocbook
@float Figure,figure-load-extension
-@caption{Loading The Extension}
+@caption{Loading the extension}
@c FIXME: One day, it should not be necessary to have two cases,
@c but rather just the one without the "txt" final argument.
@c This applies to the other figures as well.
@ifinfo
-@center @image{api-figure1, , , Loading The Extension, txt}
+@center @image{api-figure1, , , Loading the extension, txt}
@end ifinfo
@ifnotinfo
-@center @image{api-figure1, , , Loading The Extension}
+@center @image{api-figure1, , , Loading the extension}
@end ifnotinfo
@end float
@end ifnotdocbook
@docbook
<figure id="figure-load-extension" float="0">
-<title>Loading The Extension</title>
+<title>Loading the extension</title>
<mediaobject>
<imageobject role="web"><imagedata fileref="api-figure1.png" format="PNG"/></imageobject>
</mediaobject>
@@ -31338,19 +31447,19 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-register-new-function
@ifnotdocbook
@float Figure,figure-register-new-function
-@caption{Registering A New Function}
+@caption{Registering a new function}
@ifinfo
-@center @image{api-figure2, , , Registering A New Function, txt}
+@center @image{api-figure2, , , Registering a new Function, txt}
@end ifinfo
@ifnotinfo
-@center @image{api-figure2, , , Registering A New Function}
+@center @image{api-figure2, , , Registering a new Function}
@end ifnotinfo
@end float
@end ifnotdocbook
@docbook
<figure id="figure-register-new-function" float="0">
-<title>Registering A New Function</title>
+<title>Registering a new function</title>
<mediaobject>
<imageobject role="web"><imagedata fileref="api-figure2.png" format="PNG"/></imageobject>
</mediaobject>
@@ -31371,7 +31480,7 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-call-new-function"/>}
@ifnotdocbook
@float Figure,figure-call-new-function
-@caption{Calling The New Function}
+@caption{Calling the new function}
@ifinfo
@center @image{api-figure3, , , Calling the new function, txt}
@end ifinfo
@@ -31383,7 +31492,7 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-call-new-function"/>}
@docbook
<figure id="figure-call-new-function" float="0">
-<title>Calling The New Function</title>
+<title>Calling the new function</title>
<mediaobject>
<imageobject role="web"><imagedata fileref="api-figure3.png" format="PNG"/></imageobject>
</mediaobject>
@@ -31419,10 +31528,9 @@ The API also provides major and minor version numbers, so that an
extension can check if the @command{gawk} it is loaded with supports the
facilities it was compiled with. (Version mismatches ``shouldn't''
happen, but we all know how @emph{that} goes.)
-@xref{Extension Versioning}, for details.
+@DBXREF{Extension Versioning} for details.
@end itemize
-
@node Extension API Description
@section API Description
@cindex extension API
@@ -31464,20 +31572,23 @@ Allocating, reallocating, and releasing memory.
@item
Registration functions. You may register:
+
+@c nested list
@itemize @value{MINUS}
@item
-extension functions,
+Extension functions
@item
-exit callbacks,
+Exit callbacks
@item
-a version string,
+A version string
@item
-input parsers,
+Input parsers
@item
-output wrappers,
+Output wrappers
@item
-and two-way processors.
+Two-way processors
@end itemize
+
All of these are discussed in detail, later in this @value{CHAPTER}.
@item
@@ -31524,7 +31635,7 @@ Some points about using the API:
@itemize @value{BULLET}
@item
-The following types and/or macros and/or functions are referenced
+The following types, macros, and/or functions are referenced
in @file{gawkapi.h}. For correct use, you must therefore include the
corresponding standard header file @emph{before} including @file{gawkapi.h}:
@@ -31538,7 +31649,7 @@ corresponding standard header file @emph{before} including @file{gawkapi.h}:
@item @code{memset()} @tab @code{<string.h>}
@item @code{size_t} @tab @code{<sys/types.h>}
@item @code{struct stat} @tab @code{<sys/stat.h>}
-@end multitable
+@end multitable
Due to portability concerns, especially to systems that are not
fully standards-compliant, it is your responsibility
@@ -31570,7 +31681,7 @@ and is managed by @command{gawk} from then on.
The API defines several simple @code{struct}s that map values as seen
from @command{awk}. A value can be a @code{double}, a string, or an
array (as in multidimensional arrays, or when creating a new array).
-String values maintain both pointer and length since embedded @sc{nul}
+String values maintain both pointer and length, because embedded @sc{nul}
characters are allowed.
@quotation NOTE
@@ -31595,14 +31706,14 @@ so that the extension can, e.g., print an error message
@c The table there should be presented here
@end itemize
-While you may call the API functions by using the function pointers
-directly, the interface is not so pretty. To make extension code look
+You may call the API functions by using the function pointers
+directly, but the interface is not so pretty. To make extension code look
more like regular code, the @file{gawkapi.h} header file defines several
macros that you should use in your code. This @value{SECTION} presents
the macros as if they were functions.
@node General Data Types
-@subsection General Purpose Data Types
+@subsection General-Purpose Data Types
@cindex Robbins, Arnold
@cindex Ramey, Chet
@@ -31617,9 +31728,10 @@ can accommodate both love and hate.}
@author Chet Ramey
@end quotation
-The extension API defines a number of simple types and structures for general
-purpose use. Additional, more specialized, data structures are introduced
-in subsequent @value{SECTION}s, together with the functions that use them.
+The extension API defines a number of simple types and structures for
+general-purpose use. Additional, more specialized, data structures are
+introduced in subsequent @value{SECTION}s, together with the functions
+that use them.
@table @code
@item typedef void *awk_ext_id_t;
@@ -31646,8 +31758,9 @@ A simple boolean type.
This represents a mutable string. @command{gawk}
owns the memory pointed to if it supplied
the value. Otherwise, it takes ownership of the memory pointed to.
-@strong{Such memory must come from calling one of the
-@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()} functions!}
+@emph{Such memory must come from calling one of the
+@code{gawk_malloc()}, @code{gawk_calloc()}, or
+@code{gawk_realloc()} functions!}
As mentioned earlier, strings are maintained using the current
multibyte encoding.
@@ -31673,7 +31786,7 @@ It is used in the following @code{struct}.
@itemx @ @ @ @ @ @ @ @ awk_value_cookie_t@ vc;
@itemx @ @ @ @ @} u;
@itemx @} awk_value_t;
-An ``@command{awk} value.''
+An ``@command{awk} value.''
The @code{val_type} member indicates what kind of value the
@code{union} holds, and each member is of the appropriate type.
@@ -31686,13 +31799,14 @@ These macros make accessing the fields of the @code{awk_value_t} more
readable.
@item typedef void *awk_scalar_t;
-Scalars can be represented as an opaque type. These values are obtained from
-@command{gawk} and then passed back into it. This is discussed in a general fashion below,
-and in more detail in @ref{Symbol table by cookie}.
+Scalars can be represented as an opaque type. These values are obtained
+from @command{gawk} and then passed back into it. This is discussed
+in a general fashion in the text following this list, and in more detail in
+@ref{Symbol table by cookie}.
@item typedef void *awk_value_cookie_t;
A ``value cookie'' is an opaque type representing a cached value.
-This is also discussed in a general fashion below,
+This is also discussed in a general fashion in the text following this list,
and in more detail in @ref{Cached values}.
@end table
@@ -31702,7 +31816,7 @@ Scalar values in @command{awk} are either numbers or strings. The
indicates what is in the @code{union}.
Representing numbers is easy---the API uses a C @code{double}. Strings
-require more work. Since @command{gawk} allows embedded @sc{nul} bytes
+require more work. Because @command{gawk} allows embedded @sc{nul} bytes
in string values, a string must be represented as a pair containing a
data-pointer and length. This is the @code{awk_string_t} type.
@@ -31715,13 +31829,13 @@ itself be an array. Discussion of arrays is delayed until
The various macros listed earlier make it easier to use the elements
of the @code{union} as if they were fields in a @code{struct}; this
is a common coding practice in C. Such code is easier to write and to
-read, however it remains @emph{your} responsibility to make sure that
+read, but it remains @emph{your} responsibility to make sure that
the @code{val_type} member correctly reflects the type of the value in
the @code{awk_value_t}.
Conceptually, the first three members of the @code{union} (number, string,
and array) are all that is needed for working with @command{awk} values.
-However, since the API provides routines for accessing and changing
+However, because the API provides routines for accessing and changing
the value of global scalar variables only by using the variable's name,
there is a performance penalty: @command{gawk} must find the variable
each time it is accessed and changed. This turns out to be a real issue,
@@ -31761,7 +31875,7 @@ The API provides a number of @dfn{memory allocation} functions for
allocating memory that can be passed to @command{gawk}, as well as a number of
convenience macros.
This @value{SUBSECTION} presents them all as function prototypes, in
-the way that extension code would use them.
+the way that extension code would use them:
@table @code
@item void *gawk_malloc(size_t size);
@@ -31806,7 +31920,8 @@ The arguments to this macro are as follows:
The pointer variable to point at the allocated storage.
@item type
-The type of the pointer variable, used to create a cast for the call to @code{gawk_malloc()}.
+The type of the pointer variable. This is used to create a cast for
+the call to @code{gawk_malloc()}.
@item size
The total number of bytes to be allocated.
@@ -31841,7 +31956,7 @@ The arguments are the same as for the @code{emalloc()} macro.
The API provides a number of @dfn{constructor} functions for creating
string and numeric values, as well as a number of convenience macros.
This @value{SUBSECTION} presents them all as function prototypes, in
-the way that extension code would use them.
+the way that extension code would use them:
@table @code
@item static inline awk_value_t *
@@ -31920,8 +32035,8 @@ This is a pointer to the C function that provides the extension's
functionality.
The function must fill in @code{*result} with either a number
or a string. @command{gawk} takes ownership of any string memory.
-As mentioned earlier, string memory @strong{must} come from one of @code{gawk_malloc()},
-@code{gawk_calloc()} or @code{gawk_realloc()}.
+As mentioned earlier, string memory @strong{must} come from one of
+@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}.
The @code{num_actual_args} argument tells the C function how many
actual parameters were passed from the calling @command{awk} code.
@@ -31956,7 +32071,7 @@ Such functions are useful if you have general ``cleanup'' tasks
that should be performed in your extension (such as closing database
connections or other resource deallocations).
You can register such
-a function with @command{gawk} using the following function.
+a function with @command{gawk} using the following function:
@table @code
@item void awk_atexit(void (*funcp)(void *data, int exit_status),
@@ -31977,8 +32092,9 @@ the function pointed to by @code{funcp}.
@end table
@end table
-Exit callback functions are called in Last-In-First-Out (LIFO) order---that is, in
-the reverse order in which they are registered with @command{gawk}.
+Exit callback functions are called in last-in-first-out (LIFO)
+order---that is, in the reverse order in which they are registered with
+@command{gawk}.
@node Extension Version String
@subsubsection Registering An Extension Version String
@@ -31989,7 +32105,7 @@ version of your extension, with @command{gawk}, as follows:
@table @code
@item void register_ext_version(const char *version);
Register the string pointed to by @code{version} with @command{gawk}.
-@command{gawk} does @emph{not} copy the @code{version} string, so
+Note that @command{gawk} does @emph{not} copy the @code{version} string, so
it should not be changed.
@end table
@@ -32071,7 +32187,7 @@ appropriately.
@item
When your extension is loaded, register your input parser with
@command{gawk} using the @code{register_input_parser()} API function
-(described below).
+(described next).
@end enumerate
An @code{awk_input_buf_t} looks like this:
@@ -32101,7 +32217,7 @@ The name of the file.
@item int fd;
A file descriptor for the file. If @command{gawk} was able to
-open the file, then @code{fd} will @emph{not} be equal to
+open the file, then @code{fd} will @emph{not} be equal to
@code{INVALID_HANDLE}. Otherwise, it will.
@item struct stat sbuf;
@@ -32115,15 +32231,15 @@ The decision can be made based upon @command{gawk} state (the value
of a variable defined previously by the extension and set by
@command{awk} code), the name of the
file, whether or not the file descriptor is valid, the information
-in the @code{struct stat}, or any combination of the above.
+in the @code{struct stat}, or any combination of these factors.
Once @code{@var{XXX}_can_take_file()} has returned true, and
@command{gawk} has decided to use your input parser, it calls
@code{@var{XXX}_take_control_of()}. That function then fills one of
either the @code{get_record} field or the @code{read_func} field in
the @code{awk_input_buf_t}. It must also ensure that @code{fd} is @emph{not}
-set to @code{INVALID_HANDLE}. All of the fields that may be filled by
-@code{@var{XXX}_take_control_of()} are as follows:
+set to @code{INVALID_HANDLE}. The following list describes the fields that
+may be filled by @code{@var{XXX}_take_control_of()}:
@table @code
@item void *opaque;
@@ -32138,13 +32254,13 @@ is not required to use this pointer.
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len);
This function pointer should point to a function that creates the input
records. Said function is the core of the input parser. Its behavior
-is described below.
+is described in the text following this list.
@item ssize_t (*read_func)();
This function pointer should point to function that has the
same behavior as the standard POSIX @code{read()} system call.
It is an alternative to the @code{get_record} pointer. Its behavior
-is also described below.
+is also described in the text following this list.
@item void (*close_func)(struct awk_input *iobuf);
This function pointer should point to a function that does
@@ -32282,7 +32398,7 @@ values, etc.) within @command{gawk}.
The function pointed to by this field is called when @command{gawk}
decides to let the output wrapper take control of the file. It should
fill in appropriate members of the @code{awk_output_buf_t} structure,
-as described below, and return true if successful, false otherwise.
+as described next, and return true if successful, false otherwise.
@item awk_const struct output_wrapper *awk_const next;
This is for use by @command{gawk};
@@ -32425,9 +32541,9 @@ Register the two-way processor pointed to by @code{two_way_processor} with
@cindex messages from extensions
You can print different kinds of warning messages from your
-extension, as described below. Note that for these functions,
+extension, as described here. Note that for these functions,
you must pass in the extension id received from @command{gawk}
-when the extension was loaded.@footnote{Because the API uses only ISO C 90
+when the extension was loaded:@footnote{Because the API uses only ISO C 90
features, it cannot make use of the ISO C 99 variadic macro feature to hide
that parameter. More's the pity.}
@@ -32484,7 +32600,7 @@ value type, as appropriate. This behavior is summarized in
@ref{table-value-types-returned}.
@float Table,table-value-types-returned
-@caption{API Value Types Returned}
+@caption{API value types returned}
@docbook
<informaltable>
<tgroup cols="6">
@@ -32496,7 +32612,7 @@ value type, as appropriate. This behavior is summarized in
<colspec colwidth="16.6*" colname="c6"/>
<spanspec spanname="hspan" namest="c3" nameend="c6" align="center"/>
<thead>
- <row><entry></entry><entry spanname="hspan"><para>Type of Actual Value:</para></entry></row>
+ <row><entry></entry><entry spanname="hspan"><para>Type of Actual Value</para></entry></row>
<row>
<entry></entry>
<entry></entry>
@@ -32532,7 +32648,7 @@ value type, as appropriate. This behavior is summarized in
<entry><para>false</para></entry>
</row>
<row>
- <entry><para><emphasis role="bold">Requested:</emphasis></para></entry>
+ <entry><para><emphasis role="bold">Requested</emphasis></para></entry>
<entry><para><emphasis role="bold">Scalar</emphasis></para></entry>
<entry><para>Scalar</para></entry>
<entry><para>Scalar</para></entry>
@@ -32563,7 +32679,7 @@ value type, as appropriate. This behavior is summarized in
@ifnotplaintext
@ifnotdocbook
@multitable @columnfractions .50 .50
-@headitem @tab Type of Actual Value:
+@headitem @tab Type of Actual Value
@end multitable
@c 10/2014: Thanks to Karl Berry for this bit to reduce the space:
@tex
@@ -32574,7 +32690,7 @@ value type, as appropriate. This behavior is summarized in
@item @tab @b{String} @tab String @tab String @tab false @tab false
@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false
@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false
-@item @b{Requested:} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false
+@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false
@item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined
@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false
@end multitable
@@ -32628,7 +32744,7 @@ indicates the type of value expected.
@item awk_bool_t set_argument(size_t count, awk_array_t array);
Convert a parameter that was undefined into an array; this provides
call-by-reference for arrays. Return false if @code{count} is too big,
-or if the argument's type is not undefined. @xref{Array Manipulation},
+or if the argument's type is not undefined. @DBXREF{Array Manipulation}
for more information on creating arrays.
@end table
@@ -32683,7 +32799,7 @@ cannot change any of those variables.
@quotation CAUTION
It is possible for the lookup of @code{PROCINFO} to fail. This happens if
the @command{awk} program being run does not reference @code{PROCINFO};
-in this case @command{gawk} doesn't bother to create the array and
+in this case, @command{gawk} doesn't bother to create the array and
populate it.
@end quotation
@@ -32693,9 +32809,9 @@ populate it.
A @dfn{scalar cookie} is an opaque handle that provides access
to a global variable or array. It is an optimization that
avoids looking up variables in @command{gawk}'s symbol table every time
-access is needed. This was discussed earlier, in @ref{General Data Types}.
+access is needed. This was discussed earlier in @ref{General Data Types}.
-The following functions let you work with scalar cookies.
+The following functions let you work with scalar cookies:
@table @code
@item awk_bool_t sym_lookup_scalar(awk_scalar_t cookie,
@@ -32740,18 +32856,21 @@ do_magic(int nargs, awk_value_t *result)
@noindent
This code looks (and is) simple and straightforward. So what's the problem?
-Consider what happens if @command{awk}-level code associated with your
-extension calls the @code{magic()} function (implemented in C by @code{do_magic()}),
-once per record, while processing hundreds of thousands or millions of records.
-The @code{MAGIC_VAR} variable is looked up in the symbol table once or twice per function call!
+Well, consider what happens if @command{awk}-level code associated
+with your extension calls the @code{magic()} function (implemented in
+C by @code{do_magic()}), once per record, while processing hundreds
+of thousands or millions of records. The @code{MAGIC_VAR} variable is
+looked up in the symbol table once or twice per function call!
-The symbol table lookup is really pure overhead; it is considerably more efficient
-to get a cookie that represents the variable, and use that to get the variable's
-value and update it as needed.@footnote{The difference is measurable and quite real. Trust us.}
+The symbol table lookup is really pure overhead; it is considerably
+more efficient to get a cookie that represents the variable, and use
+that to get the variable's value and update it as needed.@footnote{The
+difference is measurable and quite real. Trust us.}
-Thus, the way to use cookies is as follows. First, install your extension's variable
-in @command{gawk}'s symbol table using @code{sym_update()}, as usual. Then get a
-scalar cookie for the variable using @code{sym_lookup()}:
+Thus, the way to use cookies is as follows. First, install
+your extension's variable in @command{gawk}'s symbol table using
+@code{sym_update()}, as usual. Then get a scalar cookie for the variable
+using @code{sym_lookup()}:
@example
static awk_scalar_t magic_var_cookie; /* cookie for MAGIC_VAR */
@@ -32814,7 +32933,7 @@ or @code{sym_update_scalar()}, as you like.
However, you can understand the point of cached values if you remember that
@emph{every} string value's storage @emph{must} come from @code{gawk_malloc()},
-@code{gawk_calloc()} or @code{gawk_realloc()}.
+@code{gawk_calloc()}, or @code{gawk_realloc()}.
If you have 20 variables, all of which have the same string value, you
must create 20 identical copies of the string.@footnote{Numeric values
are clearly less problematic, requiring only a C @code{double} to store.}
@@ -32825,11 +32944,11 @@ is what the routines in this section let you do. The functions are as follows:
@table @code
@item awk_bool_t create_value(awk_value_t *value, awk_value_cookie_t *result);
-Create a cached string or numeric value from @code{value} for efficient later
-assignment.
-Only values of type @code{AWK_NUMBER} and @code{AWK_STRING} are allowed. Any other type
-is rejected. While @code{AWK_UNDEFINED} could be allowed, doing so would
-result in inferior performance.
+Create a cached string or numeric value from @code{value} for
+efficient later assignment. Only values of type @code{AWK_NUMBER}
+and @code{AWK_STRING} are allowed. Any other type is rejected.
+@code{AWK_UNDEFINED} could be allowed, but doing so would result in
+inferior performance.
@item awk_bool_t release_value(awk_value_cookie_t vc);
Release the memory associated with a value cookie obtained
@@ -32850,7 +32969,7 @@ my_extension_init()
size_t long_string_len;
/* code from earlier */
- @dots{}
+ @dots{}
/* @dots{} fill in long_string and long_string_len @dots{} */
make_malloced_string(long_string, long_string_len, & value);
create_value(& value, & answer_cookie); /* create cookie */
@@ -32880,7 +32999,7 @@ do_magic(int nargs, awk_value_t *result)
@end example
@noindent
-Using value cookies in this way saves considerable storage, since all of
+Using value cookies in this way saves considerable storage, as all of
@code{VAR1} through @code{VAR100} share the same value.
You might be wondering, ``Is this sharing problematic?
@@ -32902,7 +33021,7 @@ you should release any cached values that you created, using
@subsection Array Manipulation
@cindex array manipulation in extensions
-The primary data structure@footnote{Okay, the only data structure.} in @command{awk}
+The primary data structure@footnote{OK, the only data structure.} in @command{awk}
is the associative array (@pxref{Arrays}).
Extensions need to be able to manipulate @command{awk} arrays.
The API provides a number of data structures for working with arrays,
@@ -32923,7 +33042,7 @@ both work with and create true arrays of arrays (@pxref{General Data Types}).
@node Array Data Types
@subsubsection Array Data Types
-The data types associated with arrays are listed below.
+The data types associated with arrays are as follows:
@table @code
@item typedef void *awk_array_t;
@@ -33042,7 +33161,7 @@ The following functions relate to arrays as a whole:
@table @code
@item awk_array_t create_array(void);
Create a new array to which elements may be added.
-@xref{Creating Arrays}, for a discussion of how to
+@DBXREF{Creating Arrays} for a discussion of how to
create a new array and add elements to it.
@item awk_bool_t clear_array(awk_array_t a_cookie);
@@ -33077,7 +33196,7 @@ The function returns true upon success, false otherwise.
@node Flattening Arrays
@subsubsection Working With All The Elements of an Array
-To @dfn{flatten} an array is create a structure that
+To @dfn{flatten} an array is to create a structure that
represents the full array in a fashion that makes it easy
for C code to traverse the entire array. Test code
in @file{extension/testext.c} does this, and also serves
@@ -33245,7 +33364,7 @@ code) once you have called @code{release_flattened_array()}:
@}
@end example
-Finally, since everything was successful, the function sets the
+Finally, because everything was successful, the function sets the
return value to success, and returns:
@example
@@ -33280,7 +33399,7 @@ code can access them and manipulate them.
There are two important points about creating arrays from extension code:
-@enumerate 1
+@itemize @value{BULLET}
@item
You must install a new array into @command{gawk}'s symbol
table immediately upon creating it. Once you have done so,
@@ -33322,7 +33441,7 @@ new_array = val.array_cookie; /* YOU MUST DO THIS */
If installing an array as a subarray, you must also retrieve the value
of the array cookie after the call to @code{set_element()}.
-@end enumerate
+@end itemize
The following C code is a simple test extension to create an array
with two regular elements and with a subarray. The leading @code{#include}
@@ -33441,7 +33560,7 @@ dl_load_func(func_table, testarray, "")
@end ignore
@end example
-Here is sample script that loads the extension
+Here is a sample script that loads the extension
and then dumps the array:
@example
@@ -33471,7 +33590,7 @@ $ @kbd{AWKLIBPATH=$PWD ./gawk -f subarray.awk}
@end example
@noindent
-(@xref{Finding Extensions}, for more information on the
+(@DBXREF{Finding Extensions} for more information on the
@env{AWKLIBPATH} environment variable.)
@node Extension API Variables
@@ -33583,8 +33702,8 @@ The others should not change during execution.
As mentioned earlier (@pxref{Extension Mechanism Outline}), the function
definitions as presented are really macros. To use these macros, your
extension must provide a small amount of boilerplate code (variables and
-functions) towards the top of your source file, using pre-defined names
-as described below. The boilerplate needed is also provided in comments
+functions) toward the top of your source file, using predefined names
+as described here. The boilerplate needed is also provided in comments
in the @file{gawkapi.h} header file:
@example
@@ -33672,7 +33791,7 @@ This macro expands to a @code{dl_load()} function that performs
all the necessary initializations.
@end table
-The point of the all the variables and arrays is to let the
+The point of all the variables and arrays is to let the
@code{dl_load()} function (from the @code{dl_load_func()}
macro) do all the standard work. It does the following:
@@ -33707,7 +33826,7 @@ Compiled extensions have to be installed in a directory where
built in the default fashion, the directory in which to find
extensions is @file{/usr/local/lib/gawk}. You can also specify a search
path with a list of directories to search for compiled extensions.
-@xref{AWKLIBPATH Variable}, for more information.
+@DBXREF{AWKLIBPATH Variable} for more information.
@node Extension Example
@section Example: Some File Functions
@@ -33715,7 +33834,7 @@ path with a list of directories to search for compiled extensions.
@quotation
@i{No matter where you go, there you are.}
-@author Buckaroo Bonzai
+@author Buckaroo Banzai
@end quotation
@c It's enough to show chdir and stat, no need for fts
@@ -33888,9 +34007,9 @@ in the @command{gawk} distribution for the complete version.}
The file includes a number of standard header files, and then includes
the @file{gawkapi.h} header file which provides the API definitions.
-Those are followed by the necessary variable declarations
+Those are followed by the necessary variable declarations
to make use of the API macros and boilerplate code
-(@pxref{Extension API Boilerplate}).
+(@pxref{Extension API Boilerplate}):
@example
#ifdef HAVE_CONFIG_H
@@ -33931,7 +34050,7 @@ that implements it is called @code{do_foo()}. The function should have
two arguments: the first is an @code{int} usually called @code{nargs},
that represents the number of actual arguments for the function.
The second is a pointer to an @code{awk_value_t}, usually named
-@code{result}.
+@code{result}:
@example
/* do_chdir --- provide dynamically loaded chdir() function for gawk */
@@ -33951,13 +34070,13 @@ do_chdir(int nargs, awk_value_t *result)
@end example
The @code{newdir}
-variable represents the new directory to change to, retrieved
+variable represents the new directory to change to, which is retrieved
with @code{get_argument()}. Note that the first argument is
numbered zero.
If the argument is retrieved successfully, the function calls the
@code{chdir()} system call. If the @code{chdir()} fails, @code{ERRNO}
-is updated.
+is updated:
@example
if (get_argument(0, AWK_STRING, & newdir)) @{
@@ -34158,7 +34277,7 @@ of @code{stat()}) to get the file information, in case the file is a
symbolic link. However, if there were three arguments, @code{statfunc}
is set point to @code{stat()}, instead.
-Here is the @code{do_stat()} function. It starts with
+Here is the @code{do_stat()} function, which starts with
variable declarations and argument checking:
@ignore
@@ -34273,7 +34392,7 @@ dl_load_func(func_table, filefuncs, "")
And that's it!
@node Using Internal File Ops
-@subsection Integrating The Extensions
+@subsection Integrating the Extensions
@cindex @command{gawk}, interpreter@comma{} adding code to
Now that the code is written, it must be possible to add it at
@@ -34282,9 +34401,9 @@ code must be compiled. Assuming that the functions are in
a file named @file{filefuncs.c}, and @var{idir} is the location
of the @file{gawkapi.h} header file,
the following steps@footnote{In practice, you would probably want to
-use the GNU Autotools---Automake, Autoconf, Libtool, and @command{gettext}---to
+use the GNU Autotools (Automake, Autoconf, Libtool, and @command{gettext}) to
configure and build your libraries. Instructions for doing so are beyond
-the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for Internet links to
+the scope of this @value{DOCUMENT}. @DBXREF{gawkextlib} for Internet links to
the tools.} create a GNU/Linux shared library:
@example
@@ -34292,7 +34411,7 @@ $ @kbd{gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g -I@var{idir} filefuncs.c}
$ @kbd{gcc -o filefuncs.so -shared filefuncs.o}
@end example
-Once the library exists, it is loaded by using the @code{@@load} keyword.
+Once the library exists, it is loaded by using the @code{@@load} keyword:
@example
# file testff.awk
@@ -34356,13 +34475,14 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk}
@end example
@node Extension Samples
-@section The Sample Extensions In The @command{gawk} Distribution
+@section The Sample Extensions in the @command{gawk} Distribution
@cindex extensions distributed with @command{gawk}
This @value{SECTION} provides brief overviews of the sample extensions
that come in the @command{gawk} distribution. Some of them are intended
-for production use, such the @code{filefuncs}, @code{readdir} and @code{inplace} extensions.
-Others mainly provide example code that shows how to use the extension API.
+for production use (e.g., the @code{filefuncs}, @code{readdir} and
+@code{inplace} extensions). Others mainly provide example code that
+shows how to use the extension API.
@menu
* Extension Sample File Functions:: The file functions sample.
@@ -34383,9 +34503,9 @@ Others mainly provide example code that shows how to use the extension API.
@end menu
@node Extension Sample File Functions
-@subsection File Related Functions
+@subsection File-Related Functions
-The @code{filefuncs} extension provides three different functions, as follows:
+The @code{filefuncs} extension provides three different functions, as follows.
The usage is:
@table @asis
@@ -34396,7 +34516,7 @@ This is how you load the extension.
@item @code{result = chdir("/some/directory")}
The @code{chdir()} function is a direct hook to the @code{chdir()}
system call to change the current directory. It returns zero
-upon success or less than zero upon error. In the latter case it updates
+upon success or less than zero upon error. In the latter case, it updates
@code{ERRNO}.
@cindex @code{stat()} extension function
@@ -34404,7 +34524,7 @@ upon success or less than zero upon error. In the latter case it updates
The @code{stat()} function provides a hook into the
@code{stat()} system call.
It returns zero upon success or less than zero upon error.
-In the latter case it updates @code{ERRNO}.
+In the latter case, it updates @code{ERRNO}.
By default, it uses the @code{lstat()} system call. However, if passed
a third argument, it uses @code{stat()} instead.
@@ -34451,8 +34571,8 @@ Not all systems support all file types. @tab All
@item @code{flags = or(FTS_PHYSICAL, ...)}
@itemx @code{result = fts(pathlist, flags, filedata)}
Walk the file trees provided in @code{pathlist} and fill in the
-@code{filedata} array as described below. @code{flags} is the bitwise
-OR of several predefined values, also described below.
+@code{filedata} array as described next. @code{flags} is the bitwise
+OR of several predefined values, also described in a moment.
Return zero if there were no errors, otherwise return @minus{}1.
@end table
@@ -34500,7 +34620,7 @@ whether or not @code{FTS_LOGICAL} is set.
By default, the C library @code{fts()} routines do not return entries for
@file{.} (dot) and @file{..} (dot-dot). This option causes entries for
dot-dot to also be included. (The extension always includes an entry
-for dot, see below.)
+for dot; more on this in a moment.)
@item FTS_XDEV
During a traversal, do not cross onto a different mounted filesystem.
@@ -34510,7 +34630,7 @@ During a traversal, do not cross onto a different mounted filesystem.
The @code{filedata} array is first cleared. Then, @code{fts()} creates
an element in @code{filedata} for every element in @code{pathlist}.
The index is the name of the directory or file given in @code{pathlist}.
-The element for this index is itself an array. There are two cases.
+The element for this index is itself an array. There are two cases:
@c nested table
@table @emph
@@ -34536,8 +34656,8 @@ contain an element named @code{"error"}, which is a string describing the error.
@item The path is a directory
In this case, the array contains one element for each entry in the
-directory. If an entry is a file, that element is as for files, just
-described. If the entry is a directory, that element is (recursively),
+directory. If an entry is a file, that element is the same as for files, just
+described. If the entry is a directory, that element is (recursively)
an array describing the subdirectory. If @code{FTS_SEEDOT} was provided
in the flags, then there will also be an element named @code{".."}. This
element will be an array containing the data as provided by @code{stat()}.
@@ -34556,8 +34676,8 @@ The @code{fts()} extension does not exactly mimic the
interface of the C library @code{fts()} routines, choosing instead to
provide an interface that is based on associative arrays, which is
more comfortable to use from an @command{awk} program. This includes the
-lack of a comparison function, since @command{gawk} already provides
-powerful array sorting facilities. While an @code{fts_read()}-like
+lack of a comparison function, because @command{gawk} already provides
+powerful array sorting facilities. Although an @code{fts_read()}-like
interface could have been provided, this felt less natural than simply
creating a multidimensional array to represent the file hierarchy and
its information.
@@ -34567,7 +34687,7 @@ See @file{test/fts.awk} in the @command{gawk} distribution for an example
use of the @code{fts()} extension function.
@node Extension Sample Fnmatch
-@subsection Interface To @code{fnmatch()}
+@subsection Interface to @code{fnmatch()}
This extension provides an interface to the C library
@code{fnmatch()} function. The usage is:
@@ -34580,10 +34700,10 @@ This is how you load the extension.
@item result = fnmatch(pattern, string, flags)
The return value is zero on success, @code{FNM_NOMATCH}
if the string did not match the pattern, or
-a different non-zero value if an error occurred.
+a different nonzero value if an error occurred.
@end table
-Besides the @code{fnmatch()} function, the @code{fnmatch} extension
+In addition to the @code{fnmatch()} function, the @code{fnmatch} extension
adds one constant (@code{FNM_NOMATCH}), and an array of flag values
named @code{FNM}.
@@ -34601,7 +34721,7 @@ Either zero, or the bitwise OR of one or more of the
flags in the @code{FNM} array.
@end table
-The flags are follows:
+The flags are as follows:
@multitable @columnfractions .25 .75
@headitem Array element @tab Corresponding flag defined by @code{fnmatch()}
@@ -34624,9 +34744,9 @@ if (fnmatch("*.a", "foo.c", flags) == FNM_NOMATCH)
@end example
@node Extension Sample Fork
-@subsection Interface To @code{fork()}, @code{wait()} and @code{waitpid()}
+@subsection Interface to @code{fork()}, @code{wait()}, and @code{waitpid()}
-The @code{fork} extension adds three functions, as follows.
+The @code{fork} extension adds three functions, as follows:
@table @code
@item @@load "fork"
@@ -34724,7 +34844,7 @@ $ @kbd{gawk -i inplace -v INPLACE_SUFFIX=.bak '@{ gsub(/foo/, "bar") @}}
@subsection Character and Numeric values: @code{ord()} and @code{chr()}
The @code{ordchr} extension adds two functions, named
-@code{ord()} and @code{chr()}, as follows.
+@code{ord()} and @code{chr()}, as follows:
@table @code
@item @@load "ordchr"
@@ -34772,7 +34892,7 @@ indicating the type of the file. The letters and their corresponding file
types are shown in @ref{table-readdir-file-types}.
@float Table,table-readdir-file-types
-@caption{File Types Returned By The @code{readdir} Extension}
+@caption{File types returned by the @code{readdir} extension}
@multitable @columnfractions .1 .9
@headitem Letter @tab File Type
@item @code{b} @tab Block device
@@ -34809,7 +34929,7 @@ BEGIN @{ FS = "/" @}
@subsection Reversing Output
The @code{revoutput} extension adds a simple output wrapper that reverses
-the characters in each output line. It's main purpose is to show how to
+the characters in each output line. Its main purpose is to show how to
write an output wrapper, although it may be mildly amusing for the unwary.
Here is an example:
@@ -34831,7 +34951,7 @@ The output from this program is:
The @code{revtwoway} extension adds a simple two-way processor that
reverses the characters in each line sent to it for reading back by
-the @command{awk} program. It's main purpose is to show how to write
+the @command{awk} program. Its main purpose is to show how to write
a two-way processor, although it may also be mildly amusing.
The following example shows how to use it:
@@ -34858,7 +34978,7 @@ is:
@samp{cinap t'nod}.
@node Extension Sample Read write array
-@subsection Dumping and Restoring An Array
+@subsection Dumping and Restoring an Array
The @code{rwarray} extension adds two functions,
named @code{writea()} and @code{reada()}, as follows:
@@ -34884,7 +35004,7 @@ Here too, the return value is one on success and zero upon failure.
The array created by @code{reada()} is identical to that written by
@code{writea()} in the sense that the contents are the same. However,
-due to implementation issues, the array traversal order of the recreated
+due to implementation issues, the array traversal order of the re-created
array is likely to be different from that of the original array. As array
traversal order in @command{awk} is by default undefined, this is (technically)
not a problem. If you need to guarantee a particular traversal
@@ -34892,7 +35012,7 @@ order, use the array sorting features in @command{gawk} to do so
(@pxref{Array Sorting}).
The file contains binary data. All integral values are written in network
-byte order. However, double precision floating-point values are written
+byte order. However, double-precision floating-point values are written
as native binary data. Thus, arrays containing only string data can
theoretically be dumped on systems with one byte order and restored on
systems with a different one, but this has not been tried.
@@ -34908,7 +35028,7 @@ ret = reada("arraydump.bin", array)
@end example
@node Extension Sample Readfile
-@subsection Reading An Entire File
+@subsection Reading an Entire File
The @code{readfile} extension adds a single function
named @code{readfile()}, and an input parser:
@@ -34955,7 +35075,7 @@ This is how you load the extension.
@cindex @code{gettimeofday()} extension function
@item the_time = gettimeofday()
Return the time in seconds that has elapsed since 1970-01-01 UTC as a
-floating point value. If the time is unavailable on this platform, return
+floating-point value. If the time is unavailable on this platform, return
@minus{}1 and set @code{ERRNO}. The returned time should have sub-second
precision, but the actual precision may vary based on the platform.
If the standard C @code{gettimeofday()} system call is available on this
@@ -34998,22 +35118,22 @@ As of this writing, there are five extensions:
@itemize @value{BULLET}
@item
-GD graphics library extension.
+GD graphics library extension
@item
-PDF extension.
+PDF extension
@item
-PostgreSQL extension.
+PostgreSQL extension
@item
-MPFR library extension.
-This provides access to a number of MPFR functions which @command{gawk}'s
-native MPFR support does not.
+MPFR library extension
+(this provides access to a number of MPFR functions which @command{gawk}'s
+native MPFR support does not)
@item
XML parser extension, using the @uref{http://expat.sourceforge.net, Expat}
-XML parsing library.
+XML parsing library
@end itemize
@cindex @command{git} utility
@@ -35064,9 +35184,9 @@ to install both @command{gawk} and @code{gawkextlib}, depending upon
how your system works.
If you write an extension that you wish to share with other
-@command{gawk} users, please consider doing so through the
+@command{gawk} users, consider doing so through the
@code{gawkextlib} project.
-See the project's web site for more information.
+See the project's website for more information.
@node Extension summary
@section Summary
@@ -35074,7 +35194,7 @@ See the project's web site for more information.
@itemize @value{BULLET}
@item
You can write extensions (sometimes called plug-ins) for @command{gawk}
-in C or C++ using the Application Programming Interface (API) defined
+in C or C++ using the application programming interface (API) defined
by the @command{gawk} developers.
@item
@@ -35105,44 +35225,44 @@ API function pointers are provided for the following kinds of operations:
@itemize @value{BULLET}
@item
-Allocating, reallocating, and releasing memory.
+Allocating, reallocating, and releasing memory
@item
-Registration functions. You may register
+Registration functions (you may register
extension functions,
exit callbacks,
a version string,
input parsers,
output wrappers,
-and two-way processors.
+and two-way processors)
@item
-Printing fatal, warning, and ``lint'' warning messages.
+Printing fatal, warning, and ``lint'' warning messages
@item
-Updating @code{ERRNO}, or unsetting it.
+Updating @code{ERRNO}, or unsetting it
@item
Accessing parameters, including converting an undefined parameter into
-an array.
+an array
@item
-Symbol table access: retrieving a global variable, creating one,
-or changing one.
+Symbol table access (retrieving a global variable, creating one,
+or changing one)
@item
Creating and releasing cached values; this provides an
efficient way to use values for multiple variables and
-can be a big performance win.
+can be a big performance win
@item
-Manipulating arrays:
-retrieving, adding, deleting, and modifying elements;
+Manipulating arrays
+(retrieving, adding, deleting, and modifying elements;
getting the count of elements in an array;
creating a new array;
clearing an array;
and
-flattening an array for easy C style looping over all its indices and elements.
+flattening an array for easy C style looping over all its indices and elements)
@end itemize
@item
@@ -35221,34 +35341,34 @@ and the Glossary:
@end ifclear
@ifset FOR_PRINT
-Part IV contains two appendices and the license that
+Part IV contains three appendices, the last of which is the license that
covers the @command{gawk} source code:
@end ifset
@itemize @value{BULLET}
@item
-@ref{Language History}.
+@ref{Language History}
@item
-@ref{Installation}.
+@ref{Installation}
@ifclear FOR_PRINT
@item
-@ref{Notes}.
+@ref{Notes}
@item
-@ref{Basic Concepts}.
+@ref{Basic Concepts}
@item
-@ref{Glossary}.
+@ref{Glossary}
@end ifclear
@item
-@ref{Copying}.
+@ref{Copying}
@ifclear FOR_PRINT
@item
-@ref{GNU Free Documentation License}.
+@ref{GNU Free Documentation License}
@end ifclear
@end itemize
@end ifdocbook
@@ -35257,7 +35377,7 @@ covers the @command{gawk} source code:
@appendix The Evolution of the @command{awk} Language
This @value{DOCUMENT} describes the GNU implementation of @command{awk},
-which follows the POSIX specification. Many long-time @command{awk}
+which follows the POSIX specification. Many longtime @command{awk}
users learned @command{awk} programming with the original @command{awk}
implementation in Version 7 Unix. (This implementation was the basis for
@command{awk} in Berkeley Unix, through 4.3-Reno. Subsequent versions
@@ -35492,7 +35612,7 @@ The ability to delete all of an array at once with @samp{delete @var{array}}
@end itemize
-@xref{Common Extensions}, for a list of common extensions
+@DBXREF{Common Extensions} for a list of common extensions
not permitted by the POSIX standard.
The 2008 POSIX standard can be found online at
@@ -35512,7 +35632,7 @@ has made his version available via his home page
(@pxref{Other Versions}).
This @value{SECTION} describes common extensions that
-originally appeared in his version of @command{awk}.
+originally appeared in his version of @command{awk}:
@itemize @value{BULLET}
@item
@@ -35538,7 +35658,7 @@ or array elements through it.
@end ignore
@end itemize
-@xref{Common Extensions}, for a full list of the extensions
+@DBXREF{Common Extensions} for a full list of the extensions
available in his @command{awk}.
@node POSIX/GNU
@@ -35594,7 +35714,7 @@ The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and
@item
The @file{/inet}, @file{/inet4}, and @samp{/inet6} special files for
TCP/IP networking using @samp{|&} to specify which version of the
-IP protocol to use.
+IP protocol to use
(@pxref{TCP/IP Networking}).
@end itemize
@@ -35642,7 +35762,7 @@ New keywords:
@itemize @value{MINUS}
@item
-The @code{BEGINFILE} and @code{ENDFILE} special patterns.
+The @code{BEGINFILE} and @code{ENDFILE} special patterns
(@pxref{BEGINFILE/ENDFILE}).
@item
@@ -35679,7 +35799,7 @@ making translations easier
@item
The @code{split()} function's additional optional fourth
-argument which is an array to hold the text of the field separators.
+argument which is an array to hold the text of the field separators
(@pxref{String Functions}).
@end itemize
@@ -36442,7 +36562,7 @@ load @command{awk} library files.
@item
The @option{-l} and @option{--load} options load compiled dynamic extensions.
-@item
+@item
The @option{-M} and @option{--bignum} options enable MPFR.
@item
@@ -36481,7 +36601,7 @@ The dynamic extension interface was completely redone
@cindex extensions, @command{mawk}
The following table summarizes the common extensions supported
by @command{gawk}, Brian Kernighan's @command{awk}, and @command{mawk},
-the three most widely-used freely available versions of @command{awk}
+the three most widely used freely available versions of @command{awk}
(@pxref{Other Versions}).
@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} {Now standard}
@@ -36499,7 +36619,7 @@ the three most widely-used freely available versions of @command{awk}
@item @code{func} keyword @tab X @tab @tab X @tab
@item @code{BINMODE} variable @tab @tab X @tab X @tab
@item @code{RS} as regexp @tab @tab X @tab X @tab
-@item Time related functions @tab @tab X @tab X @tab
+@item Time-related functions @tab @tab X @tab X @tab
@end multitable
@node Ranges and Locales
@@ -36515,7 +36635,7 @@ the first character in the range and the last character in the range,
inclusive. Ordering was based on the numeric value of each character
in the machine's native character set. Thus, on ASCII-based systems,
@samp{[a-z]} matched all the lowercase letters, and only the lowercase
-letters, since the numeric values for the letters from @samp{a} through
+letters, as the numeric values for the letters from @samp{a} through
@samp{z} were contiguous. (On an EBCDIC system, the range @samp{[a-z]}
includes additional, non-alphabetic characters as well.)
@@ -36526,8 +36646,8 @@ that @samp{[A-Z]} was the ``correct'' way to match uppercase letters.
And indeed, this was true.@footnote{And Life was good.}
The 1992 POSIX standard introduced the idea of locales (@pxref{Locales}).
-Since many locales include other letters besides the plain twenty-six
-letters of the American English alphabet, the POSIX standard added
+Because many locales include other letters besides the plain 26
+letters of the English alphabet, the POSIX standard added
character classes (@pxref{Bracket Expressions}) as a way to match
different kinds of characters besides the traditional ones in the ASCII
character set.
@@ -36544,7 +36664,7 @@ In other words, these locales sort characters in dictionary order,
and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
instead it might be equivalent to @samp{[ABCXYabcdxyz]}, for example.
-This point needs to be emphasized: Much literature teaches that you should
+This point needs to be emphasized: much literature teaches that you should
use @samp{[a-z]} to match a lowercase character. But on systems with
non-ASCII locales, this also matches all of the uppercase characters
except @samp{A} or @samp{Z}! This was a continuous cause of confusion, even well
@@ -36560,7 +36680,7 @@ $ @kbd{echo something1234abc | gawk-3.1.8 '@{ sub("[A-Z]*$", ""); print @}'}
@end example
@noindent
-This output is unexpected, since the @samp{bc} at the end of
+This output is unexpected, as the @samp{bc} at the end of
@samp{something1234abc} should not normally match @samp{[A-Z]*}.
This result is due to the locale setting (and thus you may not see
it on your system).
@@ -36582,7 +36702,7 @@ like ``why does @samp{[A-Z]} match lowercase letters?!?''
@cindex Berry, Karl
This situation existed for close to 10 years, if not more, and
the @command{gawk} maintainer grew weary of trying to explain that
-@command{gawk} was being nicely standards-compliant, and that the issue
+@command{gawk} was being nicely standards compliant, and that the issue
was in the user's locale. During the development of @value{PVERSION} 4.0,
he modified @command{gawk} to always treat ranges in the original,
pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).@footnote{And
@@ -36795,7 +36915,7 @@ Michael Benzinger contributed the initial code for @code{switch} statements.
@cindex McPhee, Patrick
Patrick T.J.@: McPhee contributed the code for dynamic loading in Windows32
environments.
-(This is no longer supported)
+(This is no longer supported.)
@item
@cindex Wallin, Anders
@@ -36819,7 +36939,7 @@ into a byte-code interpreter, including the debugger.
The addition of true arrays of arrays.
@item
-The additional modifications for support of arbitrary precision arithmetic.
+The additional modifications for support of arbitrary-precision arithmetic.
@item
The initial text of
@@ -36875,7 +36995,7 @@ helping David Trueman, and as the primary maintainer since around 1994.
@itemize @value{BULLET}
@item
The @command{awk} language has evolved over time. The first release
-was with V7 Unix circa 1978. In 1987 for System V Release 3.1,
+was with V7 Unix circa 1978. In 1987, for System V Release 3.1,
major additions, including user-defined functions, were made to the language.
Additional changes were made for System V Release 4, in 1989.
Since then, further minor changes happen under the auspices of the
@@ -36917,8 +37037,8 @@ This appendix provides instructions for installing @command{gawk} on the
various platforms that are supported by the developers. The primary
developer supports GNU/Linux (and Unix), whereas the other ports are
contributed.
-@xref{Bugs},
-for the electronic mail addresses of the people who maintain
+@DBXREF{Bugs}
+for the email addresses of the people who maintain
the respective ports.
@menu
@@ -36972,7 +37092,7 @@ wget http://ftp.gnu.org/gnu/gawk/gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz
The GNU software archive is mirrored around the world.
The up-to-date list of mirror sites is available from
-@uref{http://www.gnu.org/order/ftp.html, the main FSF web site}.
+@uref{http://www.gnu.org/order/ftp.html, the main FSF website}.
Try to use one of the mirrors; they
will be less busy, and you can usually find one closer to your site.
@@ -36983,7 +37103,7 @@ different compression programs: @command{gzip}, @command{bzip2},
and @command{xz}. For simplicity, the rest of these instructions assume
you are using the one compressed with the GNU Zip program, @code{gzip}.
-Once you have the distribution (for example,
+Once you have the distribution (e.g.,
@file{gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz}),
use @code{gzip} to expand the
file and then use @code{tar} to extract it. You can use the following
@@ -37076,7 +37196,7 @@ as a list of things that the POSIX standard should describe but does not.
@item doc/awkforai.txt
Pointers to the original draft of
a short article describing why @command{gawk} is a good language for
-Artificial Intelligence (AI) programming.
+artificial intelligence (AI) programming.
@item doc/bc_notes
A brief description of @command{gawk}'s ``byte code'' internals.
@@ -37182,7 +37302,7 @@ source file for this @value{DOCUMENT}. It also contains a @file{Makefile.in} fil
The library functions from
@ref{Library Functions},
and the @command{igawk} program from
-@ref{Igawk Program},
+@DBREF{Igawk Program}
are included as ready-to-use files in the @command{gawk} distribution.
They are installed as part of the installation process.
The rest of the programs in this @value{DOCUMENT} are available in appropriate
@@ -37201,11 +37321,11 @@ Files needed for building @command{gawk} under MS-Windows
@ifclear FOR_PRINT
and OS/2
@end ifclear
-(@pxref{PC Installation}, for details).
+(@DBPXREF{PC Installation} for details).
@item vms/*
Files needed for building @command{gawk} under Vax/VMS and OpenVMS
-(@pxref{VMS Installation}, for details).
+(@DBPXREF{VMS Installation} for details).
@item test/*
A test suite for
@@ -37217,7 +37337,7 @@ be confident of a successful port.
@c ENDOFRANGE gawdis
@node Unix Installation
-@appendixsec Compiling and Installing @command{gawk} on Unix-like Systems
+@appendixsec Compiling and Installing @command{gawk} on Unix-Like Systems
Usually, you can compile and install @command{gawk} by typing only two
commands. However, if you use an unusual system, you may need
@@ -37230,7 +37350,7 @@ to configure @command{gawk} for your system yourself.
@end menu
@node Quick Installation
-@appendixsubsec Compiling @command{gawk} for Unix-like Systems
+@appendixsubsec Compiling @command{gawk} for Unix-Like Systems
The normal installation steps should work on all modern commercial
Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin
@@ -37247,7 +37367,7 @@ described fully in
@cite{Autoconf---Generating Automatic Configuration Scripts},
which can be found online at
@uref{http://www.gnu.org/software/autoconf/manual/index.html,
-the Free Software Foundation's web site}.)
+the Free Software Foundation's website}.)
@end ifnotinfo
@ifinfo
(The Autoconf software is described fully starting with
@@ -37294,7 +37414,7 @@ run @samp{make check}. All of the tests should succeed.
If these steps do not work, or if any of the tests fail,
check the files in the @file{README_d} directory to see if you've
found a known problem. If the failure is not described there,
-please send in a bug report (@pxref{Bugs}).
+send in a bug report (@pxref{Bugs}).
Of course, once you've built @command{gawk}, it is likely that you will
wish to install it. To do so, you need to run the command @samp{make
@@ -37358,7 +37478,7 @@ function for deficient systems.
@end table
Use the command @samp{./configure --help} to see the full list of
-options that @command{configure} supplies.
+options supplied by @command{configure}.
@node Configuration Philosophy
@appendixsubsec The Configuration Process
@@ -37392,19 +37512,19 @@ facts about your operating system. For example, there may not be an
@cindex @code{custom.h} file
It is possible for your C compiler to lie to @command{configure}. It may
do so by not exiting with an error when a library function is not
-available. To get around this, edit the file @file{custom.h}.
+available. To get around this, edit the @file{custom.h} file.
Use an @samp{#ifdef} that is appropriate for your system, and either
@code{#define} any constants that @command{configure} should have defined but
didn't, or @code{#undef} any constants that @command{configure} defined and
-should not have. @file{custom.h} is automatically included by
-@file{config.h}.
+should not have. The @file{custom.h} file is automatically included by
+the @file{config.h} file.
It is also possible that the @command{configure} program generated by
Autoconf will not work on your system in some other fashion.
-If you do have a problem, the file @file{configure.ac} is the input for
+If you do have a problem, the @file{configure.ac} file is the input for
Autoconf. You may be able to change this file and generate a
new version of @command{configure} that works on your system
-(@pxref{Bugs},
+(@DBPXREF{Bugs}
for information on how to report problems in configuring @command{gawk}).
The same mechanism may be used to send in updates to @file{configure.ac}
and/or @file{custom.h}.
@@ -37444,7 +37564,7 @@ The limitations of MS-DOS (and MS-DOS shells under the other operating
systems) has meant that various ``DOS extenders'' are often used with
programs such as @command{gawk}. The varying capabilities of Microsoft
Windows 3.1 and Windows32 can add to the confusion. For an overview
-of the considerations, please refer to @file{README_d/README.pc} in
+of the considerations, refer to @file{README_d/README.pc} in
the distribution.
@menu
@@ -37607,7 +37727,7 @@ Ancient OS/2 ports of GNU @command{make} are not able to handle
the Makefiles of this package. If you encounter any problems with
@command{make}, try GNU Make 3.79.1 or later versions. You should
find the latest version on
-@uref{ftp://hobbes.nmsu.edu/pub/os2/}.@footnote{As of May, 2014,
+@uref{ftp://hobbes.nmsu.edu/pub/os2/}.@footnote{As of November 2014,
this site is still there, but the author could not find a package
for GNU Make.}
@end quotation
@@ -37817,7 +37937,7 @@ need to use the @code{BINMODE} variable.
This can cause problems with other Unix-like components that have
been ported to MS-Windows that expect @command{gawk} to do automatic
-translation of @code{"\r\n"}, since it won't.
+translation of @code{"\r\n"}, because it won't.
@node VMS Installation
@appendixsubsec Compiling and Installing @command{gawk} on Vax/VMS and OpenVMS
@@ -37881,14 +38001,14 @@ The most recent builds used HP C V7.3 on Alpha VMS 8.3 and both
Alpha and IA64 VMS 8.4 used HP C 7.3.@footnote{The IA64 architecture
is also known as ``Itanium.''}
-@xref{VMS GNV}, for information on building
+@DBXREF{VMS GNV} for information on building
@command{gawk} as a PCSI kit that is compatible with the GNV product.
@node VMS Dynamic Extensions
@appendixsubsubsec Compiling @command{gawk} Dynamic Extensions on VMS
The extensions that have been ported to VMS can be built using one of
-the following commands.
+the following commands:
@example
$ @kbd{MMS/DESCRIPTION=[.vms]descrip.mms extensions}
@@ -37905,7 +38025,7 @@ $ @kbd{MMK/DESCRIPTION=[.vms]descrip.mms extensions}
or a logical name to find the dynamic extensions.
Dynamic extensions need to be compiled with the same compiler options for
-floating point, pointer size, and symbol name handling as were used
+floating-point, pointer size, and symbol name handling as were used
to compile @command{gawk} itself.
Alpha and Itanium should use IEEE floating point. The pointer size is 32 bits,
and the symbol name handling should be exact case with CRC shortening for
@@ -38035,7 +38155,7 @@ Note that uppercase and mixed-case text must be quoted.
The VMS port of @command{gawk} includes a @code{DCL}-style interface in addition
to the original shell-style interface (see the help entry for details).
One side effect of dual command-line parsing is that if there is only a
-single parameter (as in the quoted string program above), the command
+single parameter (as in the quoted string program), the command
becomes ambiguous. To work around this, the normally optional @option{--}
flag is required to force Unix-style parsing rather than @code{DCL} parsing. If any
other dash-type options (or multiple parameters such as @value{DF}s to
@@ -38155,10 +38275,10 @@ recommend compiling and using the current version.
@node Bugs
@appendixsec Reporting Problems and Bugs
-@cindex archeologists
+@cindex archaeologists
@quotation
-@i{There is nothing more dangerous than a bored archeologist.}
-@author The Hitchhiker's Guide to the Galaxy
+@i{There is nothing more dangerous than a bored archaeologist.}
+@author Douglas Adams, @cite{The Hitchhiker's Guide to the Galaxy}
@end quotation
@c the radio show, not the book. :-)
@@ -38167,10 +38287,10 @@ recommend compiling and using the current version.
@c STARTOFRANGE tblgawb
@cindex troubleshooting, @command{gawk}, bug reports
If you have problems with @command{gawk} or think that you have found a bug,
-please report it to the developers; we cannot promise to do anything
+report it to the developers; we cannot promise to do anything
but we might well want to fix it.
-Before reporting a bug, please make sure you have really found a genuine bug.
+Before reporting a bug, make sure you have really found a genuine bug.
Carefully reread the documentation and see if it says you can do
what you're trying to do. If it's not clear whether you should be able
to do something or not, report that too; it's a bug in the documentation!
@@ -38183,7 +38303,7 @@ the compiler you used to compile @command{gawk}, and the exact results
@command{gawk} gave you. Also say what you expected to occur; this helps
us decide whether the problem is really in the documentation.
-Please include the version number of @command{gawk} you are using.
+Make sure to include the version number of @command{gawk} you are using.
You can get this information with the command @samp{gawk --version}.
@cindex @code{bug-gawk@@gnu.org} bug reporting address
@@ -38195,7 +38315,7 @@ Once you have a precise problem description, send email to
The @command{gawk} maintainers subscribe to this address and
thus they will receive your bug report.
Although you can send mail to the maintainers directly,
-the bug reporting address is preferred since the
+the bug reporting address is preferred because the
email list is archived at the GNU Project.
@emph{All email must be in English. This is the only language
understood in common by all the maintainers.}
@@ -38204,19 +38324,19 @@ understood in common by all the maintainers.}
@quotation CAUTION
Do @emph{not} try to report bugs in @command{gawk} by
posting to the Usenet/Internet newsgroup @code{comp.lang.awk}.
-While the @command{gawk} developers do occasionally read this newsgroup,
-there is no guarantee that we will see your posting. The steps described
-above are the only official recognized way for reporting bugs.
+The @command{gawk} developers do occasionally read this newsgroup,
+but there is no guarantee that we will see your posting. The steps described
+here are the only officially recognized way for reporting bugs.
Really.
@end quotation
@quotation NOTE
Many distributions of GNU/Linux and the various BSD-based operating systems
have their own bug reporting systems. If you report a bug using your distribution's
-bug reporting system, @emph{please} also send a copy to
+bug reporting system, you should also send a copy to
@EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}.
-This is for two reasons. First, while some distributions forward
+This is for two reasons. First, although some distributions forward
bug reports ``upstream'' to the GNU mailing list, many don't, so there is a good
chance that the @command{gawk} maintainers won't even see the bug report! Second,
mail to the GNU list is archived, and having everything at the GNU project
@@ -38227,8 +38347,8 @@ Non-bug suggestions are always welcome as well. If you have questions
about things that are unclear in the documentation or are just obscure
features, ask on the bug list; we will try to help you out if we can.
-If you find bugs in one of the non-Unix ports of @command{gawk}, please
-send an electronic mail message to the bug list, with a copy to the
+If you find bugs in one of the non-Unix ports of @command{gawk},
+send an email to the bug list, with a copy to the
person who maintains that port. They are named in the following list,
as well as in the @file{README} file in the @command{gawk} distribution.
Information in the @file{README} file should be considered authoritative
@@ -38259,7 +38379,7 @@ The people maintaining the various @command{gawk} ports are:
@item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}.
@end multitable
-If your bug is also reproducible under Unix, please send a copy of your
+If your bug is also reproducible under Unix, send a copy of your
report to the @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org} email list as well.
@c ENDOFRANGE dbugg
@c ENDOFRANGE tblgawb
@@ -38303,7 +38423,7 @@ This @value{SECTION} briefly describes where to get them:
Brian Kernighan, one of the original designers of Unix @command{awk},
has made his implementation of
@command{awk} freely available.
-You can retrieve this version via the World Wide Web from
+You can retrieve this version via
@uref{http://www.cs.princeton.edu/~bwk, his home page}.
It is available in several archive formats:
@@ -38326,7 +38446,7 @@ git clone git://github.com/onetrueawk/awk bwkawk
@end example
@noindent
-The above command creates a copy of the @uref{http://www.git-scm.com, Git}
+This command creates a copy of the @uref{http://www.git-scm.com, Git}
repository in a directory named @file{bwkawk}. If you leave that argument
off the @command{git} command line, the repository copy is created in a
directory named @file{awk}.
@@ -38334,9 +38454,13 @@ directory named @file{awk}.
This version requires an ISO C (1990 standard) compiler; the C compiler
from GCC (the GNU Compiler Collection) works quite nicely.
-@xref{Common Extensions},
+@DBXREF{Common Extensions}
for a list of extensions in this @command{awk} that are not in POSIX @command{awk}.
+As a side note, Dan Bornstein has created a Git repository tracking
+all the versions of BWK @command{awk} that he could find. It's
+available at @uref{git://github.com/onetrueawk/awk}.
+
@cindex Brennan, Michael
@cindex @command{mawk} utility
@cindex source code, @command{mawk}
@@ -38366,7 +38490,7 @@ Once you have it,
is similar to @command{gawk}'s
(@pxref{Unix Installation}).
-@xref{Common Extensions},
+@DBXREF{Common Extensions}
for a list of extensions in @command{mawk} that are not in POSIX @command{awk}.
@cindex Sumner, Andrew
@@ -38428,8 +38552,8 @@ has not been done, at least to our knowledge.
@cindex Illumos
@cindex Illumos, POSIX-compliant @command{awk}
@cindex source code, Illumos @command{awk}
-The source code used to be available from the OpenSolaris web site.
-However, that project was ended and the web site shut down. Fortunately, the
+The source code used to be available from the OpenSolaris website.
+However, that project was ended and the website shut down. Fortunately, the
@uref{http://wiki.illumos.org/display/illumos/illumos+Home, Illumos project}
makes this implementation available. You can view the files one at a time from
@uref{https://github.com/joyent/illumos-joyent/blob/master/usr/src/cmd/awk_xpg4}.
@@ -38448,7 +38572,7 @@ from POSIX @command{awk}. More information is available on the
@cindex libmawk
@cindex source code, libmawk
This is an embeddable @command{awk} interpreter derived from
-@command{mawk}. For more information see
+@command{mawk}. For more information, see
@uref{http://repo.hu/projects/libmawk/}.
@item @code{pawk}
@@ -38462,7 +38586,7 @@ modified version of BWK @command{awk}, described earlier.)
@item @w{QSE Awk}
@cindex QSE Awk
@cindex source code, QSE Awk
-This is an embeddable @command{awk} interpreter. For more information
+This is an embeddable @command{awk} interpreter. For more information,
see @uref{http://code.google.com/p/qse/} and @uref{http://awk.info/?tools/qse}.
@item @command{QTawk}
@@ -38477,9 +38601,10 @@ including the manual and a download link.
The project may also be frozen; no new code changes have been made
since approximately 2008.
-@item Other Versions
-See also the @uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations,
-Wikipedia article}, for information on additional versions.
+@item Other versions
+See also the ``Versions and Implementations'' section of the
+@uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations,
+Wikipedia article} for information on additional versions.
@end table
@c ENDOFRANGE awkim
@@ -38681,7 +38806,7 @@ This document describes how GNU software should be written. If you haven't
read it, please do so, preferably @emph{before} starting to modify @command{gawk}.
(The @cite{GNU Coding Standards} are available from
the GNU Project's
-@uref{http://www.gnu.org/prep/standards_toc.html, web site}.
+@uref{http://www.gnu.org/prep/standards_toc.html, website}.
Texinfo, Info, and DVI versions are also available.)
@cindex @command{gawk}, coding style in
@@ -40547,7 +40672,7 @@ record or a string.
@end docbook
@c This file is intended to be included within another document,
-@c hence no sectioning command or @node.
+@c hence no sectioning command or @node.
@display
Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/}
@@ -40769,7 +40894,7 @@ terms of section 4, provided that you also meet all of these
conditions:
@enumerate a
-@item
+@item
The work must carry prominent notices stating that you modified it,
and giving a relevant date.
@@ -41219,7 +41344,7 @@ state the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.
@smallexample
-@var{one line to give the program's name and a brief idea of what it does.}
+@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) @var{year} @var{name of author}
This program is free software: you can redistribute it and/or modify
@@ -41242,7 +41367,7 @@ If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
@smallexample
-@var{program} Copyright (C) @var{year} @var{name of author}
+@var{program} Copyright (C) @var{year} @var{name of author}
This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
This is free software, and you are welcome to redistribute it
under certain conditions; type @samp{show c} for details.
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-04 23:29:41 +0000