[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[SCM] gawk branch, feature/notes-doc, updated. gawk-4.1.0-5492-gb32fef82
From: |
Arnold Robbins |
Subject: |
[SCM] gawk branch, feature/notes-doc, updated. gawk-4.1.0-5492-gb32fef82 |
Date: |
Wed, 14 Feb 2024 14:11:51 -0500 (EST) |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, feature/notes-doc has been updated
via b32fef82ee1aa1e3ec05190790368a81ce55f7cf (commit)
from 08c2c8a77c509274aa70963392da71fd83410595 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=b32fef82ee1aa1e3ec05190790368a81ce55f7cf
commit b32fef82ee1aa1e3ec05190790368a81ce55f7cf
Author: Arnold D. Robbins <arnold@skeeve.com>
Date: Wed Feb 14 21:11:23 2024 +0200
Initial edits to notes.texi.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 2fe76360..234ca9c3 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2024-02-14 Arnold D. Robbins <arnold@skeeve.com>
+
+ * notes.texi: Lots of edits and general formatting improvements.
+
2024-02-12 Tim Rice <trice@posteo.net>
* gawk.texi (Extension Sample Inplace): Add a note that
diff --git a/doc/notes.texi b/doc/notes.texi
index 7f06677c..defa46fc 100644
--- a/doc/notes.texi
+++ b/doc/notes.texi
@@ -1,6 +1,11 @@
\input texinfo @c -*-texinfo-*-
@settitle GNU Awk Maintainer Notes
@syncodeindex pg cp
+
+@set UPDATE-MONTH February, 2004
+@set EDITION 0.5
+@set TITLE GNU Awk Maintainer Notes
+
@copying
@c For HTML, spell out email addresses, to avoid problems with
@c address harvesters for spammers.
@@ -19,6 +24,8 @@ This manual is for maintainers of GNU @command{awk}.
Copyright @copyright{} 2024 Arnold Robbins.
+This is Edition @value{EDITION} of @cite{@value{TITLE}}.
+
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -27,7 +34,9 @@ any later version published by the Free Software Foundation.
@end copying
@titlepage
-@title GNU Awk Maintainer Notes
+@title @value{TITLE}
+@subtitle Edition @value{EDITION}
+@subtitle @value{UPDATE-MONTH}
@author Arnold Robbins
@page
@vskip 0pt plus 1filll
@@ -51,31 +60,46 @@ This manual is for maintainers of GNU @command{awk}.
@end menu
@c first note
-@node GNU @command{Awk} Maintainership Background and Context
+@node GNU Awk Maintainership Background and Context
@chapter GNU @command{Awk} Background and Context
+The purpose of this document is to provide background on GNU @command{awk},
+(@command{gawk}), it's code and it's development. The idea is to have
+something new maintainers can read in order to help them come up to
+speed.
@section Goals
-Here are my personal goals for bringing y'all on board.
+Here are my personal goals for bringing new maintainers on board.
Over the next few years, I want to:
@itemize @bullet
-@item Do a thorough review of the manual, and get it published again.
-@item Bring you two up to speed to the point that each of you would be able to
-@itemize @bullet
-@item Fix bugs as reported on the bug list
-@item Make releases
-@item Make improvements in the code base
+@item
+Do a thorough review of the manual, and get it published again.
+
+@item
+Bring you two up to speed to the point that each of you would be able to:
+
+@itemize ---
+@item
+Fix bugs as reported on the bug list
+
+@item
+Make releases
+
+@item
+Make improvements in the code base
@end itemize
-@item This will allow me to become ``Maintainer Emeritus''.
- In that position I hope that I would still be contributing,
- but no longer bearing the main responsibility.
+
+@item
+This will allow me to become ``Maintainer Emeritus''.
+In that position I hope that I would still be contributing,
+but no longer bearing the main responsibility.
@end itemize
-As I said, this won't happen overnight.
+This won't happen overnight.
The code base is large and there's a lot to come up to speed on, and I don't
expect miracles, we all have lives and day jobs.
-Slow but steady will be the watch word.
+``Slow but steady'' will be the watch word.
@section Some History
@@ -103,7 +127,7 @@ occasionally, new features.
@cindex Kernighan, Brian
In October of 1987, I picked up a copy of the Aho, Kernighan and Weinberger
book on @command{awk}.
-Up until then, the doc on @command{awk} was so skimpy that I'd stayed away
+Up until then, the documentation on @command{awk} was so skimpy that I'd
stayed away
from it; the book made things much clearer, and also more exciting!
I wanted to give (new) @command{awk} a try.
@@ -125,7 +149,7 @@ At some point, I asked if there was a manual; a 90 page
Texinfo draft existed
@cindex Trueman, David
@cindex Robbins, Arnold
-David and I met a time or two in person at USENIX; I may even still have some
+David and I met a time or two in person at USENIX conferences; I may even
still have some
notes on our feature plans, most of which eventually made their way into
@command{gawk}.
@@ -159,7 +183,7 @@ execute the program.
@cindex Haque, John
At version 4.0, that changed, when an outside developer (John Haque) changed
@command{gawk} to generate and interpret ``byte codes'' representing the
-program. As part of that work, John also added an awk-level debugger, which is
+program. As part of that work, John also added an @command{awk}-level
debugger, which is
really useful.
This structure remains in place today.
@@ -168,7 +192,7 @@ John Haque left the project in December of 2012 over a
disagreement with me
as to how the project should be run.
He wanted to see things being done in a certain way, which I did not have the
cycles to do, but he himself did not want to help make those changes.
-(I offered to promote him to co-maintainer, but he declined).
+(I had offered to promote him to co-maintainer, but he declined).
Effectively, ``here is what you should do, but I'm not going to help.''
Since that didn't suit me, he left in a bit of huff, but that's life.
@@ -182,8 +206,9 @@ structure, data structures, and performance, which I no
longer have the
motivation to really tackle;
I'm hoping new blood will be able to do some of these things. :-)
-FWIW, as many versions as I could find are in the @command{git} repo and tagged
-appropriately, so it's possible to go back and see the earlier versions.
+For what it's worth, as many versions as I could find are in the
+@command{git} repository and tagged appropriately, so it's possible to
+go back and see the earlier versions.
@section First Steps
@@ -191,18 +216,23 @@ appropriately, so it's possible to go back and see the
earlier versions.
Here are some first steps for every new co-maintainer candidate:
@enumerate
-@item Start the process to sign paperwork to assign copyright in your changes
-to @command{gawk} and its doc to the Free Software Foundation.
+@item
+Start the process to sign paperwork to assign copyright in your changes
+to @command{gawk} and its documentation to the Free Software Foundation.
Please send an email to
@email{copyright-clerk@@fsf.org}
asking for paperwork to assign copyright in all current and future changes to
-@command{gawk} and its doc to the FSF.
+@command{gawk} and its documentation to the FSF.
You will have to do this before any patches can be integrated into the code
base.
-@item Check out the @command{gawk} documentation online at the GNU project.
+
+@item
+Check out the @command{gawk} documentation online at the GNU project.
In particular, look at the @command{gawk} workflow document for how things
will start out for your contributions.
-@item Also, if you haven't read the @command{gawk} manual, please do.
+
+@item
+Also, if you haven't read the @command{gawk} manual, please do.
You will probably know a lot of what's there, but maybe not everything.
There's a lot there.
The section on contributing code is most relevant in terms of how patches
@@ -213,11 +243,15 @@ need to be done, but you'll need to learn the language
itself as well.
@node General Maintainership Background
@chapter General Maintainership Background
+This chapter describes the processes and tools you shold
+be familiar with, with general pointers to specific
+documents to read. All of them can be found easily on
+the Internet, so specific URLs are not included.
@section Workflow and Tooling Outline
This section provides some background introductory material and pointers.
-You should be able to find some of these documents just by searching.
+@c You should be able to find some of these documents just by searching.
@subsection GNU Coding Standards
This document describes how to write code for the GNU Project.
@@ -231,7 +265,7 @@ style, instead using standard ``K & R'' code layout, with
tabs, not spaces. The
one exception is that function names in function definitions are placed at the
beginning of the line.
-These days the document lives in @code{gnulib}:
+These days the document lives in GNULIB:
@example
git clone https://git.savannah.gnu.org/git/gnulib.git
@@ -245,25 +279,27 @@ that after reading the coding standards.
@subsection maintain.texi
This document describes high level general stuff to know if you're going to
be a GNU maintainer.
-These days it also lives in @code{gnulib}:
+These days it also lives in GNULIB:
@example
cd gnulib/doc
texi2pdf maintain.texi
@end example
+@noindent
It's necessary, if not exciting, reading.
@subsection Savannah
-The GNU project has its own software hosting, mainly for Git and CVS:
-@uref{https://savannah.gnu.org, Savannah.gnu.org}.
-This is where the @command{gawk} Git repo is maintained.
+The GNU project has its own software hosting, mainly for Git and CVS,
+called
+@uref{https://savannah.gnu.org, Savannah}.
+This is where the @command{gawk} Git repository is maintained.
It's worth poking around there.
Eventually you'll want to create a user account so that you'll be able to
-commit directly to the repo, but this is not urgent at this point.
+commit directly to the repository, but this is not urgent at this point.
@subsection Mailing list or bug tracker
-@command{Gawk} has two mailing lists:
+@command{gawk} has two mailing lists:
@email{bug-gawk@@gnu.org}
for bug reports, and
@email{help-gawk@@gnu.org}
@@ -272,17 +308,17 @@ I sometimes skim the latter via the web archive but do
not receive it.
I leave it to other folks to answer questions there, or not, as it happens.
I don't really wish to change off of mailing list usage.
-OTOH, if one of you wants to set up and manage a bug tracker, then let's
+On the other hand, if one of you wants to set up and manage a bug tracker,
then let's
discuss.
@subsection Release management
-@command{Gawk} use X.Y.Z versioning.
+@command{gawk} use X.Y.Z versioning.
The X is the major version, currently 5.
It changes rarely.
The Y is the minor version, changing whenever there are enough new features
to make it worth doing a major release.
The Z is the patch level.
-Those releases happen 2-3 times a year.
+Those patch releases happen 2-3 times a year.
Releases used to be more frequent, but I have purposely slowed down, trying
to avoid adding new features or making major changes.
@@ -300,9 +336,9 @@ Here are some the technical skills you'll need as a
maintainer.
These all also apply pretty much across the board, not just to @command{gawk}.
@subsection Git skills
-@command{Gawk}, and just about all the other GNU projects, use Git for source
+@command{gawk}, and just about all the other GNU projects, use Git for source
code management.
-Using the @command{git} command line is @strong{STRONGLY} recommended.
+Using the @command{git} command line is @strong{strongly} recommended.
I have seen things messed up too often when relying on graphical Git tools.
The @command{gawk} workflow document provides an extremely basic introduction
@@ -312,7 +348,7 @@ what's presented there.
@subsection C (and maybe also C++)
I doubt this is an issue, but you should definitely have C skills.
-@command{Gawk} is a very large C program.
+@command{gawk} is a very large C program.
The code expects at least a C 99 capable compiler.
I try to avoid being bleeding edge in the use of C features in order to allow
@@ -326,8 +362,8 @@ features.
It's an interesting question as to whether knowing C++ is necessary.
Moving @command{gawk} to a simple subset of C++ in order to get away from its
use of unions might not be a bad idea.
-OTOH, it's a big chunk of work and I think that most of the rest of the
-@command{gawk} developers would NOT be happy working in C++.
+On the other hand, it's a big chunk of work and I think that most of the rest
of the
+@command{gawk} developers would @emph{not} be happy working in C++.
On the third hand, the parts of @command{gawk} they deal with are generally
both small and localized, and they could probably manage.
@@ -347,43 +383,50 @@ uses @command{m4} macros to create @command{configure};
you should have a basic
understanding of @command{m4} also, although @command{autoconf} hides most of
it from you.
+The files of interest are @file{configure.ac}, @file{extension/configure.ac},
+and files in the @file{m4} directory.
+
@subsection Texinfo
+
The various manuals are all written in Texinfo, the GNU Project's markup
language.
-Texinfo can be used to produce Info files, HTML and (with TeX) PDF.
+Texinfo can be used to produce Info files, HTML and (with @TeX{}) PDF.
I don't care for Info myself, but it's the GNU standard format, so the files
are created during build for inclusion in releases.
Texinfo has grown a lot over the years.
I don't use every last feature in it.
You may want to skim @file{doc/gawk.texi} to get a feel for it and then read
-some of the ``basics'' on Texinfo in the Texinfo doc.
+some of the ``basics'' on Texinfo in the Texinfo documentation.
Texinfo is important since, if you add a user-visible feature, you will have
to document it in the manual as well.
-@subsection @command{troff} -man --- semi-optional
+@subsection @command{troff} @option{-man} --- semi-optional
+
The man pages are written in @command{troff}.
-A basic knowledge of how to write man pages is helpful. I recently cut the
+A basic knowledge of how to write man pages is helpful.
+For the 5.3.0 release, I cut the
@file{gawk.1} man page down in size by a lot, but it's still very large.
The four-color reference card, @file{awkcard.pdf}, is written in
-@command{troff} and tbl. That's a much harder thing to deal with. I suspect
+@command{troff} and @command{tbl}. That's a much harder thing to deal with. I
suspect
that once I ``retire'' it can be dropped from the distribution, or marked as
unmaintained.
-@subsection GDB, valgrind, gprof
-Debugging and profiling skills.
-I've been using gdb for decades, to the point where I can't really use any
-other debugger.
-There is good integration of it for both Vim and Emacs.
+@subsection GDB, @command{valgrind}, and @command{gprof}
+
+Debugging and profiling skills. I've been using @command{gdb} for
+decades, to the point where I can't really use any other debugger.
+Both Vim and Emacs have excellent integration for @command{gdb}.
@command{valgrind} is invaluable for dealing with memory leak issues.
@command{gprof} is occasionally necessary if you think there's a performance
bottleneck somewhere.
-@subsection GCC compile farm
+@subsection The GCC Compile Farm
+
Google this, and get yourself an account on it.
It's a resource that I only recently started to leverage, but they have a
number of machines that it's unlikely that you will have.
@@ -400,24 +443,24 @@ architecture that they have, this is one way to go.
@cindex Levine, John
You should be generally familiar with the terminology and components of
-compilers and interpreters. Things like: parsing, scanning, symbol tables. In
+compilers and interpreters. Things like: parsing, scanning, and symbol tables.
In
particular, @command{gawk} uses a hand-written scanner and a @command{Bison}
-parser (LALR, based on @command{Yacc}). The @cite{Flex and Bison} book by John
+parser (LALR, based on YACC). The @cite{Flex and Bison} book by John
Levine is probably a good resource if you have no background in this.
As @command{gawk} parses a program, it builds up a linked list of so-called
-``byte codes'', representing the program to be run. This is "compiling"
-and "code generation" of a sort, but the instructions generated are
+``byte codes,'' representing the program to be run. This is ``compiling''
+and ``code generation'' of a sort, but the instructions generated are
simply structs representing operations defined by @command{gawk} itself, not
code for a real machine or for any standard virtual machine such
as the Java JVM or the .Net CLR.
-Once the progam is built, @command{gawk} then interprets the ``byte codes'', by
+Once the progam is built, @command{gawk} then interprets the byte codes, by
way of a loop around a gigantic switch statement on each type of
instruction.
-The bytes codes are the basis also for the debugger and pretty
-printer. The pretty printer interprets the ``byte codes'' to reconstitute
+The bytes codes are the basis also for the debugger and the pretty
+printer. The pretty printer interprets the byte codes to reconstitute
@command{awk} source code. The pretty printer also handles line count
profiling.
@@ -426,7 +469,6 @@ I can explain how it works off the top of my head. (This
is sad.)
Future notes will talk about some of these things in more detail.
-
@section Learn The Language
To maintain @command{gawk}, you have to know @command{awk}, as well as what
@@ -438,29 +480,32 @@ work.
@cindex Kernighan, Brian
@cindex Weinberger, Peter
@enumerate
-@item @cite{The AWK Programming Language} by Aho, Kernighan and Weinberger.
+@item
+@cite{The AWK Programming Language} by Aho, Kernighan and Weinberger.
The first edition of this book is the classic reference for @command{awk},
despite it being 35 years old.
The second edition came out in 2023, and it has been completely
rewritten to reflect the changes in BWK @command{awk}.
+It is compact, but very worthwhile.
-@item The @cite{GAWK: Effective AWK Programming} manual, by yours truly.
+@item
+The manual, @cite{GAWK: Effective AWK Programming}, by yours truly.
The manual has grown over the years, as @command{gawk} has
grown. I've done my best to make it both tutorial and reference for
both standard @command{awk} and for @command{gawk}'s capabilities.
-If you want to print it out,
+If you want to print it out, here are the steps:
@example
-cd /path/to/@command{gawk}/repo
+cd /path/to/gawk/repo
./bootstrap.sh && ./configure && make
cd doc
make pdf
@end example
-The @file{gawk.pdf} file will be the manual. You'll need all the right TeX
-and texinfo bits installed for this.
+@noindent
+The @file{gawk.pdf} file will be the manual. You'll need all the right @TeX{}
+and Texinfo bits installed for this.
Alternatively, you can find it online in various formats at
-
@uref{https://www.gnu.org/software/gawk/manual/}.
Eventually y'all will be maintaining this manual, so you should
@@ -468,12 +513,12 @@ become familiar with it in any case.
You should read the other Texinfo files too, at your leisure:
@file{gawkinet.pdf} for networking with @command{gawk}, and
-@file{gawkworkflow.pdf}. The workflow doc is most relevant for getting started
+@file{gawkworkflow.pdf}. The workflow document is most relevant for getting
started
working with the team.
-@item The POSIX standard for @command{awk}.
+@item
+The POSIX standard for @command{awk}.
This can be found online at:
-
@uref{https://pubs.opengroup.org/onlinepubs/9699919799/utilities/awk.html}.
It is the official standard for @command{awk}. It's written
@@ -491,11 +536,11 @@ follow the standard, since doing so makes it too painful
to use. See the
@section Test Suite Structure
-The test suite is fairly formalized. For each test FOO, there is at least a
-@command{FOO.awk} and a @file{FOO.ok} file. Optionally, there may be a
-@file{FOO.in} file, which is input data for @file{FOO.awk} to process.
-@file{FOO.ok} is the combined standard output and standard error from running
-@command{gawk} on @command{FOO.awk} (with @file{FOO.in}, if relevant).
+The test suite is fairly formalized. For each test @var{foo}, there is at
least a
+@command{@var{foo}.awk} and a @file{@var{foo}.ok} file. Optionally, there may
be a
+@file{@var{foo}.in} file, which is input data for @file{@var{foo}.awk} to
process.
+@file{@var{foo}.ok} is the combined standard output and standard error from
running
+@command{gawk} on @command{@var{foo}.awk} (with @file{@var{foo}.in}, if
relevant).
Adding new tests generally does not require actually writing the test stanzas.
Instead the @file{Makefile} process takes care of this, using an @command{awk}
@@ -508,35 +553,36 @@ the same versions as I do. In that case, the steps to
add a test involve
editing @file{Makefile.am}:
@enumerate
-@item In the list of files for EXTRA_DIST, add @file{FOO.awk} and
-@file{FOO.ok}. Add @file{FOO.in} also if relevant. Keep this list sorted
+@item
+In the list of files for @code{EXTRA_DIST}, add @file{@var{foo}.awk} and
+@file{@var{foo}.ok}. Add @file{@var{foo}.in} also if relevant. Keep this list
sorted
alphabetically.
-@item Add the new test name in the relevant list:
-
-@example
-BASIC_TESTS - Tests for standard @command{awk} functionality
-UNIX_TESTS - Tests that require *nix
-GAWK_EXT_TESTS - Tests of @command{gawk}-specific extensions
-ARRAYDEBUG_TESTS - Array debugging tests
-EXTRA_TESTS - Tests we don't usually run
- (I should rethink these, maybe)
-INET_TESTS - Networking facility tests
-MACHINE_TESTS - Tests that may vary based on machine
- architecture
-LOCALE_CHARSET_TESTS - Tests whose results depend on different
- locales
-SHLIB_TESTS - Tests of the extension facility
-@end example
-
-@item In addition, there are a number of NEED_xxx groups listing tests that
+@item
+Add the new test name in the relevant list:
+
+@multitable @columnfractions .30 .70
+@item @code{ARRAYDEBUG_TESTS} @tab Array debugging tests.
+@item @code{BASIC_TESTS} @tab Tests for standard @command{awk} functionality.
+@item @code{EXTRA_TESTS} @tab Tests we don't usually run. (I should rethink
these, maybe.)
+@item @code{GAWK_EXT_TESTS} @tab Tests of @command{gawk}-specific extensions.
+@item @code{INET_TESTS} @tab Networking facility tests.
+@item @code{LOCALE_CHARSET_TESTS} @tab Tests whose results depend on different
locales.
+@item @code{MACHINE_TESTS} @tab Tests that may vary based on machine
architecture.
+@item @code{SHLIB_TESTS} @tab Tests of the extension facility.
+@item @code{UNIX_TESTS} @tab Tests that require *nix.
+@end multitable
+
+@item
+In addition, there are a number of @code{NEED_@var{xxx}} groups listing tests
that
need additional @command{gawk} options, such as @option{--lint} or
@option{--debug}. The @file{Makefile} doesn't use them directly. Instead, the
@command{test/Gentests} script, which generates the test stanzas, reads
@file{Makefile.am} and processes these lists in order to generate the test
stanzas. I recommend reviewing the @command{test/Gentests} script as well.
-@item After saving @file{Makefile.am}, just run @command{make}, and everything
+@item
+After saving @file{Makefile.am}, just run @command{make}, and everything
will be regenerated. This should be done in the top level directory. This will
also update @file{pc/Makefile.tst}, which is used for running the tests on
MinGW.
@@ -545,87 +591,88 @@ MinGW.
@section Documentation
-The `doc' directory contains all of @command{gawk}'s documentation. This
+The @file{doc} directory contains all of @command{gawk}'s documentation. This
includes manuals in Texinfo as well as man pages, and a four-color
-reference card, written in tbl and @command{troff}.
+reference card, written in @command{tbl} and @command{troff}.
The various files are:
-@example
-ChangeLog*
- ChangeLog files tracking changes.
-
-Makefile.am
-Makefile.in
- Makefile stuff via the Autotools.
-
-README.card
-ad.block
-awkcard.in
-cardfonts
-colors
-macros
-no.colors
-setter.outline
- The files for making the reference card.
-
-api-figure*.fig
-api-figure*.*
-array-elements.fig
-array-elements.*
-general-program.fig
-general-program.*
-lflashlight-small.xpic
-lflashlight.*
-process-flow.fig
-process-flow.*
-rflashlight-small.xpic
-rflashlight.*
-statist.*
- Image files used in the manual, both the original
- from the drawing programs (.fig and .xpic) and the
- generated files.
-
-awkforai.txt
- A draft of an article for ACM SIGPLAN Notices on why
- @command{awk} is good for AI.
-
-bc_notes
-implementation-notes.txt
- Some implementation notes.
- (I should review these.)
-
-@command{gawk}.1
-@command{gawk}bug.1
-i@command{gawk}.1
-pm-@command{gawk}.1
- Manual pages. @command{igawk}.1 is no longer installed.
-
-@command{gawk}inet.texi
-@command{gawk}.texi
-@command{gawk}workflow.texi
-pm-@command{gawk}.texi
-texinfo.tex
- The Texinfo manuals.
-
-it/*
-@cindex Colombo, Antonio
- The Italian translation of the manual and of the
- man pages@footnote{The Italian translation is maintained by Antonio
Colombo @EMAIL{azc100@@gmail.com, azc100 at gmail dot com}. He has commit
access to the repo.}.
-wordlist*
- Lists of valid words that my spell(1) doesn't think are
- valid. Used for spell checking the various documentation
- files.
-@end example
+@table @code
+@item ChangeLog*
+ChangeLog files tracking changes.
+
+@item Makefile.am
+@itemx Makefile.in
+@file{Makefile} stuff via the Autotools.
+
+@item README.card
+@itemx ad.block
+@itemx awkcard.in
+@itemx cardfonts
+@itemx colors
+@itemx macros
+@itemx no.colors
+@itemx setter.outline
+The files for making the reference card.
+
+@item api-figure*.fig
+@itemx api-figure*.*
+@itemx array-elements.fig
+@itemx array-elements.*
+@itemx general-program.fig
+@itemx general-program.*
+@itemx lflashlight-small.xpic
+@itemx lflashlight.*
+@itemx process-flow.fig
+@itemx process-flow.*
+@itemx rflashlight-small.xpic
+@itemx rflashlight.*
+@itemx statist.*
+Image files used in the manual, both the original
+from the drawing programs (@file{.fig} and @file{.xpic}) and the
+generated files.
+
+@item awkforai.txt
+A draft of an article for ACM SIGPLAN Notices on why
+@command{awk} is good for AI.
+
+@item bc_notes
+@itemx implementation-notes.txt
+Some implementation notes.
+(I should review these.)
+
+@item gawk.1
+@itemx gawkbug.1
+@itemx igawk.1
+@itemx pm-gawk.1
+Manual pages. @file{igawk.1} is no longer installed.
+
+@item gawkinet.texi
+@itemx gawk.texi
+@itemx gawkworkflow.texi
+@itemx pm-gawk.texi
+@itemx texinfo.tex
+The Texinfo manuals.
+@cindex Colombo, Antonio
+@item it/*
+The Italian translation of the manual and of the man
+pages@footnote{The Italian translation is maintained by Antonio Colombo
+@EMAIL{azc100@@gmail.com, azc100 at gmail dot com}. He has commit access
+to the repository.}.
-@section Portability - POSIX and Non-POSIX
+@item wordlist*
+Lists of valid words that my @i{spell}(1) doesn't think are
+valid. Used for spell checking the various documentation files.
+@end table
+
+@section Portability: POSIX and Non-POSIX
There are places in @command{gawk} where it needs to find out OS-specific
information or do an OS-specific task. These are abstracted into the following
routines:
-@example
+@smallexample
os_arg_fixup(int *argcp, char ***argvp)
os_devopen(const char *name, int flag)
os_close_on_exec(int fd, const char *name, const char *what, const char *dir)
@@ -636,12 +683,12 @@ os_setbinmode(int fd, int mode)
os_restore_mode(int fd)
os_isatty(int fd)
os_maybe_set_errno(void)
-@end example
+@end smallexample
There are three different implementations of these routines, one for
OpenVMS, one for Windows with MinGW, and one for everything else (POSIX).
-In the top level directory, the @command{gawk}misc.c file includes a subsidiary
+In the top level directory, the @file{gawkmisc.c} file includes a subsidiary
file for each environment, depending upon the system where @command{gawk} is
being compiled.
@@ -653,32 +700,31 @@ On some of the systems, these routines return default or
error values, as
appropriate.
In this way, the mainline @command{gawk} code avoids lots of @code{#ifdef}
-statements, yet the "os_" prefix provides an indication that the operation
+statements, yet the @samp{os_} prefix provides an indication that the operation
being performed is OS-specific.
If you look at the files, you will see that they are very similar to each
other.
-@section Gnulib
+@section GNULIB
In the support directory are files that @command{gawk} uses as essentially
-"library" or support routines. For example, the regex and dfa matchers. (Why
+``library'' or support routines. For example, the @code{regex} and @code{dfa}
matchers. (Why
@command{gawk} has two regular expression matchers is another story.)
-Almost all these files come from Gnulib.
+Almost all these files come from GNULIB.
-Unlike most other projects that take files from Gnulib, all I do is take the
-source files. I don't use the Gnulib infrastructure (@code{gnulibtoolize}, or
+Unlike most other projects that take files from GNULIB, all I do is take the
+source files. I don't use the GNULIB infrastructure (@code{gnulibtoolize}, or
whatever it's called) to bring in all their @command{m4} files. The reason is
that they tend to pull in the transitive closure of everything any particular
item depends upon. Thus the supporting infrastructure ends up overwhelming the
actual code in the project. That's both silly and wasteful of CPU time, person
-time, and disk space. There are other things not to like about Gnulib, which
-aren't worth getting into at the moment.
+time, and disk space.
The script @file{helpers/update-support.sh} can be used to update the support
directory's files, although it assumes that the local @command{git} clone of
-the gnulib repo lives in a certain directory.
+the GNULIB repository lives in a certain directory.
I am the only one who runs it, although we can look into making it more
general going forward.
-----------------------------------------------------------------------
Summary of changes:
doc/ChangeLog | 4 +
doc/notes.texi | 400 ++++++++++++++++++++++++++++++++-------------------------
2 files changed, 227 insertions(+), 177 deletions(-)
hooks/post-receive
--
gawk
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [SCM] gawk branch, feature/notes-doc, updated. gawk-4.1.0-5492-gb32fef82,
Arnold Robbins <=