GAWK getopt documentation is incomplete and fragmented

[Matthew . Hall1]

N.B.: All citations are the book page numbers, not the PDF page numbers, and
refer to Edition 3 (June 2004) of the PDF, which appeared to be the most
current
version available right now.


I would like to suggest a change to the documentation of the GAWK getopt
function. The documentation leaves out an important implementation detail
that
caused a lot of heartache when I tried to make use of this feature.

Section 12.4 Processing Command Line Options [Page 196] omits the
explanation
that the ARGV array must be cleared of all processed options before the
BEGIN
block is completed. This is not mentioned until 13.2.1 [Page 212]:
    "Also, note that after getopt is through, we have to clear out all the
elements of ARGV from 1 to Optind, so that awk does not try to process the
command-line options as file names."

I propose that this awk-specific implementation detail be explained in the
same
section of the manual where GAWK getopt is introduced, so that a person who
is
attempting to use getopt without having to hunt through sample applications
in
a completely different section of the manual, and additionally who is
accustomed to getopt's C behavior, can decipher what it is that (s)he must
do
in order to get proper behavior in awk.

Thanks for considering this change to the documentation and thank you for
producing a high-quality program that saves me and my coworkers many hours
and a
great deal of stress.

Matt Hall
Verizon Wireless

P.S. I am working on a patch to GAWK that will allow it to see updates to
ENVIRON["TZ"] and other environment variables. I noticed this was on the
wish
list, and I might have something available for this soon if I can work out
some
problems with the patch.
___________________________________________________________________
The information contained in this message and any attachment may be
proprietary, confidential, and privileged or subject to the work
product doctrine and thus protected from disclosure.  If the reader
of this message is not the intended recipient, or an employee or
agent responsible for delivering this message to the intended
recipient, you are hereby notified that any dissemination,
distribution or copying of this communication is strictly prohibited.
If you have received this communication in error, please notify me
immediately by replying to this message and deleting it and all
copies and backups thereof.  Thank you.