[SCM] gawk branch, master, updated. gawk-4.1.0-4858-gff1dc4bc

[Arnold Robbins]

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, master has been updated
       via  ff1dc4bc8a287eaeb4814bc9685277e37a03d97a (commit)
      from  f094ce6a53b9daac0b78c3db623de6f6b141ad16 (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=ff1dc4bc8a287eaeb4814bc9685277e37a03d97a

commit ff1dc4bc8a287eaeb4814bc9685277e37a03d97a
Author: Arnold D. Robbins <arnold@skeeve.com>
Date:   Fri Aug 12 10:00:36 2022 +0300

    Add pm-gawk.1 man page and related changes.

diff --git a/ChangeLog b/ChangeLog
index b9ba6a33..dec5fe56 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2022-08-12         Arnold D. Robbins     <arnold@skeeve.com>
+
+       * NEWS: Small update: mention pm-gawk.1 man page.
+
 2022-08-11         Arnold D. Robbins     <arnold@skeeve.com>
 
        * main.c (get_pma_version): Check strchr() return value for
diff --git a/NEWS b/NEWS
index f643e276..62c743e6 100644
--- a/NEWS
+++ b/NEWS
@@ -49,7 +49,8 @@ copy of the manual.
 10. Gawk now supports Terence Kelly's "persistent malloc" (pma),
 allowing gawk to preserve its variables, arrays and user-defined
 functions between runs. THIS IS AN EXPERIMENTAL FEATURE!
-For more information, see the manual.
+For more information, see the manual. A new pm-gawk.1 man page
+is included.
 
 11. Support for OS/2 has been removed. It was not being actively
 maintained.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index ce994d19..d719dee1 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2022-08-12         Arnold D. Robbins     <arnold@skeeve.com>
+
+       * pm-gawk.1: New file.
+       * Makefile.am: Add stuff to integrate the new man page into
+       all the stuff: Installation, spell check, ps and pdf generation.
+
 2022-08-11         Arnold D. Robbins     <arnold@skeeve.com>
 
        * gawktexi.in (Persistent Memory): Small typo fixes.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8830eeb8..39d9cdb7 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -27,7 +27,7 @@
 
 info_TEXINFOS = gawk.texi gawkinet.texi gawkworkflow.texi
 
-man_MANS = gawk.1 gawkbug.1
+man_MANS = gawk.1 gawkbug.1 pm-gawk.1
 
 EXTRA_DIST = ChangeLog ChangeLog.0 ChangeLog.1 \
        README.card ad.block setter.outline \
@@ -54,7 +54,7 @@ EXTRA_DIST = ChangeLog ChangeLog.0 ChangeLog.1 \
        bc_notes
 
 # Get rid of generated files when cleaning
-CLEANFILES = *.ps *.html *.dvi *~ awkcard.nc awkcard.tr gawk.pdf gawkinet.pdf 
gawkworkflow.pdf awkcard.pdf gawk.1.pdf gawkbug.1.pdf
+CLEANFILES = *.ps *.html *.dvi *~ awkcard.nc awkcard.tr gawk.pdf gawkinet.pdf 
gawkworkflow.pdf awkcard.pdf gawk.1.pdf gawkbug.1.pdf pm-gawk.1.pdf
 
 MAKEINFO = @MAKEINFO@ --no-split --force
 
@@ -80,9 +80,9 @@ AWKCARD = awkcard.ps
 gawk.texi: $(srcdir)/gawktexi.in $(srcdir)/sidebar.awk
        awk -f $(srcdir)/sidebar.awk < $(srcdir)/gawktexi.in > gawk.texi
 
-postscript: gawk.ps gawkinet.ps gawkworkflow.ps gawk.1.ps gawkbug.1.ps 
$(AWKCARD)
+postscript: gawk.ps gawkinet.ps gawkworkflow.ps gawk.1.ps gawkbug.1.ps 
pm-gawk.1.ps $(AWKCARD)
 
-pdf-local: postscript gawk.pdf gawkinet.pdf awkcard.pdf gawk.1.pdf 
gawkbug.1.pdf
+pdf-local: postscript gawk.pdf gawkinet.pdf awkcard.pdf gawk.1.pdf 
gawkbug.1.pdf pm-gawk.1.pdf
 
 gawk.ps: gawk.dvi
        TEXINPUTS=$(srcdir): dvips -o gawk.ps gawk.dvi
@@ -105,6 +105,12 @@ gawkbug.1.ps: gawkbug.1
 gawkbug.1.pdf: gawkbug.1.ps
        ps2pdf gawkbug.1.ps gawkbug.1.pdf
 
+pm-gawk.1.ps: pm-gawk.1
+       -groff -man $(srcdir)/pm-gawk.1 > pm-gawk.1.ps
+
+pm-gawk.1.pdf: pm-gawk.1.ps
+       ps2pdf pm-gawk.1.ps pm-gawk.1.pdf
+
 awkcard.tr: awkcard.in
        sed 's:SRCDIR:$(srcdir):' < $(srcdir)/awkcard.in > awkcard.tr
 
@@ -129,7 +135,7 @@ spellworkflow:
        export LC_ALL=C ; spell "$(srcdir)"/gawkworkflow.texi | \
        sort -u | comm -23 - "$(srcdir)"/wordlist2
 
-spellmanpage: spellgawkmanpage spellgawkbugmanpage
+spellmanpage: spellgawkmanpage spellgawkbugmanpage spellpmgawkmanpage
 
 spellgawkmanpage:
        @echo ==== gawk.1 ====
@@ -141,6 +147,11 @@ spellgawkbugmanpage:
        export LC_ALL=C ; spell "$(srcdir)"/gawkbug.1 | \
        sort -u | comm -23 - "$(srcdir)"/wordlist5
 
+spellpmgawkmanpage:
+       @echo ==== pm-gawk.1 ====
+       export LC_ALL=C ; spell "$(srcdir)"/pm-gawk.1 | \
+       sort -u | comm -23 - "$(srcdir)"/wordlist6
+
 spellinet:
        @echo ==== gawkinet.texi ====
        export LC_ALL=C ; spell "$(srcdir)"/gawkinet.texi | \
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 5ad7837f..1753ce45 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -366,7 +366,7 @@ top_build_prefix = @top_build_prefix@
 top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
 info_TEXINFOS = gawk.texi gawkinet.texi gawkworkflow.texi
-man_MANS = gawk.1 gawkbug.1
+man_MANS = gawk.1 gawkbug.1 pm-gawk.1
 EXTRA_DIST = ChangeLog ChangeLog.0 ChangeLog.1 \
        README.card ad.block setter.outline \
        awkcard.in awkforai.txt texinfo.tex cardfonts \
@@ -393,7 +393,7 @@ EXTRA_DIST = ChangeLog ChangeLog.0 ChangeLog.1 \
 
 
 # Get rid of generated files when cleaning
-CLEANFILES = *.ps *.html *.dvi *~ awkcard.nc awkcard.tr gawk.pdf gawkinet.pdf 
gawkworkflow.pdf awkcard.pdf gawk.1.pdf gawkbug.1.pdf
+CLEANFILES = *.ps *.html *.dvi *~ awkcard.nc awkcard.tr gawk.pdf gawkinet.pdf 
gawkworkflow.pdf awkcard.pdf gawk.1.pdf gawkbug.1.pdf pm-gawk.1.pdf
 TROFF = groff -t -Tps -U
 SEDME = sed -e "s/^level0 restore/level0 restore flashme 100 72 moveto 
(Copyright `date '+%m-%d-%y %T'`, FSF, Inc. (all)) show/" \
                -e "s/^\/level0 save def/\/level0 save def 30 -48 translate/"
@@ -906,9 +906,9 @@ uninstall-man: uninstall-man1
 gawk.texi: $(srcdir)/gawktexi.in $(srcdir)/sidebar.awk
        awk -f $(srcdir)/sidebar.awk < $(srcdir)/gawktexi.in > gawk.texi
 
-postscript: gawk.ps gawkinet.ps gawkworkflow.ps gawk.1.ps gawkbug.1.ps 
$(AWKCARD)
+postscript: gawk.ps gawkinet.ps gawkworkflow.ps gawk.1.ps gawkbug.1.ps 
pm-gawk.1.ps $(AWKCARD)
 
-pdf-local: postscript gawk.pdf gawkinet.pdf awkcard.pdf gawk.1.pdf 
gawkbug.1.pdf
+pdf-local: postscript gawk.pdf gawkinet.pdf awkcard.pdf gawk.1.pdf 
gawkbug.1.pdf pm-gawk.1.pdf
 
 gawk.ps: gawk.dvi
        TEXINPUTS=$(srcdir): dvips -o gawk.ps gawk.dvi
@@ -931,6 +931,12 @@ gawkbug.1.ps: gawkbug.1
 gawkbug.1.pdf: gawkbug.1.ps
        ps2pdf gawkbug.1.ps gawkbug.1.pdf
 
+pm-gawk.1.ps: pm-gawk.1
+       -groff -man $(srcdir)/pm-gawk.1 > pm-gawk.1.ps
+
+pm-gawk.1.pdf: pm-gawk.1.ps
+       ps2pdf pm-gawk.1.ps pm-gawk.1.pdf
+
 awkcard.tr: awkcard.in
        sed 's:SRCDIR:$(srcdir):' < $(srcdir)/awkcard.in > awkcard.tr
 
@@ -955,7 +961,7 @@ spellworkflow:
        export LC_ALL=C ; spell "$(srcdir)"/gawkworkflow.texi | \
        sort -u | comm -23 - "$(srcdir)"/wordlist2
 
-spellmanpage: spellgawkmanpage spellgawkbugmanpage
+spellmanpage: spellgawkmanpage spellgawkbugmanpage spellpmgawkmanpage
 
 spellgawkmanpage:
        @echo ==== gawk.1 ====
@@ -967,6 +973,11 @@ spellgawkbugmanpage:
        export LC_ALL=C ; spell "$(srcdir)"/gawkbug.1 | \
        sort -u | comm -23 - "$(srcdir)"/wordlist5
 
+spellpmgawkmanpage:
+       @echo ==== pm-gawk.1 ====
+       export LC_ALL=C ; spell "$(srcdir)"/pm-gawk.1 | \
+       sort -u | comm -23 - "$(srcdir)"/wordlist6
+
 spellinet:
        @echo ==== gawkinet.texi ====
        export LC_ALL=C ; spell "$(srcdir)"/gawkinet.texi | \
diff --git a/doc/pm-gawk.1 b/doc/pm-gawk.1
new file mode 100644
index 00000000..1c0259e5
--- /dev/null
+++ b/doc/pm-gawk.1
@@ -0,0 +1,187 @@
+.ds EP \fIGAWK: Effective AWK Programming\fP
+.ds PM \fIPersistent Memory gawk User Manual\fP
+.TH PM-GAWK 1 "Aug 11 2022" "Free Software Foundation" "Utility Commands"
+.SH NAME
+persistent memory gawk \- persistent data and functions
+.SH SYNOPSIS
+.ft CW
+.nf
+truncate -s \f(CIsize\fP heap.pma
+export GAWK_PERSIST_FILE=heap.pma
+gawk .\^.\^.
+.sp
+truncate -s \f(CIsize\fP heap.pma
+GAWK_PERSIST_FILE=heap.pma gawk .\^.\^.
+.sp
+truncate -s \f(CIsize\fP heap.pma
+alias pm='GAWK_PERSIST_FILE=heap.pma'
+pm gawk .\^.\^.                       # succinct
+.sp
+unset GAWK_PERSIST_FILE   # disable persistence
+.sp
+export GAWK_PERSIST_FILE=other_heap.pma  # change heap
+.sp
+rm heap.pma               # delete heap
+.fi
+.ft R
+.SH DESCRIPTION
+.PP
+.I Gawk
+5.2 and later supports a persistent memory feature that
+can store script-defined variables and functions in a
+file for later use.  The feature, called
+.IR pm-gawk ,
+is described in \*(EP and in \*(PM.
+.PP
+.I pm-gawk
+is activated by passing to
+.I gawk
+the name of an initially empty
+(all-zero-bytes)
+.IR "heap file" ,
+via the environment variable
+\f(CWGAWK_PERSIST_FILE\fP.
+.I pm-gawk
+retains script-defined variables and functions in the heap file for
+use in subsequent
+.I gawk
+invocations.
+.PP
+.I pm-gawk
+offers at least two advantages compared with the existing \f(CWrwarray\fP
+extension: it offers constant-time (``O(1) time'') access to individual
+elements of persistent associative arrays, and it can store script-defined
+functions in addition to variables.
+.SH EXAMPLES
+.PP
+Demonstrate persistent variables:
+.RS
+.nf
+.ft CW
+$ \f(CBtruncate -s 1G heap.pma\fP            # create heap file
+$ \f(CBexport GAWK_PERSIST_FILE=heap.pma\fP  # "ambient" env var
+$ \f(CBgawk 'BEGIN{print ++i}'\fP
+1
+$ \f(CBgawk 'BEGIN{print ++i}'\fP
+2
+$ \f(CBgawk 'BEGIN{print ++i}'\fP
+.ft R
+.fi
+.RE
+.PP
+To pass the environment variable on per-command basis:
+.RS
+.nf
+.ft CW
+$ \f(CBunset GAWK_PERSIST_FILE\fP
+$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN{print ++i}'\fP
+4
+$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN{print ++i}'\fP
+5
+$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN{print ++i}'\fP
+6
+.ft R
+.fi
+.RE
+.PP
+To reduce visual clutter of per-command environment variable passing:
+.RS
+.nf
+.ft CW
+$ \f(CBalias pm='GAWK_PERSIST_FILE=heap.pma'\fP
+$ \f(CBpm gawk 'BEGIN{print ++i}'\fP
+7
+$ \f(CBpm gawk 'BEGIN{print ++i}'\fP
+8
+.ft R
+.fi
+.RE
+.PP
+To refrain from activating persistence:
+.RS
+.nf
+.ft CW
+$ \f(CBunset GAWK_PERSIST_FILE\fP
+$ \f(CBgawk 'BEGIN{print ++i}'\fP
+1
+$ \f(CBgawk 'BEGIN{print ++i}'\fP
+1
+.ft R
+.fi
+.RE
+.PP
+To permanently ``forget'' the contents of the heap file:
+.RS
+.nf
+.ft CW
+$ \f(CBrm heap.pma\fP
+.ft R
+.fi
+.RE
+.PP
+.SH ENVIRONMENT VARIABLES
+.PP
+\f(CWGAWK_PERSIST_FILE\fP contains the name of a heap file where
+script-defined variables and functions are stored.  If this environment
+variable is not visible to
+.IR gawk ,
+the
+persistence feature is not activated and
+.I gawk
+behaves in
+its traditional manner.
+.SH VERSION INFORMATION
+.PP
+Persistent memory
+.I gawk
+was first released in
+.I gawk
+5.2.
+.SH AUTHORS
+Arnold Robbins, the maintainer of
+.IR gawk ,
+implemented 
+.I pm-gawk
+using a persistent memory allocator (pma) provided by
+Terence Kelly.  An earlier proof-of-concept prototype
+of persistent
+.I gawk
+was developed by Haris Volos, Zi Fan
+Tan, and Jianan Li using a fork of the official
+.I gawk
+sources.
+.SH BUG REPORTS
+Follow the procedures in \*(EP and in \*(PM.
+For suspected
+bugs related to persistence (as opposed to other
+non-persistence-related
+.I gawk
+bugs) please also send
+e-mail to Terence Kelly at one or more of these addresses:
+\f(CWtpkelly@acm.org\fP,
+\f(CWtpkelly@eecs.umich.edu\fP,
+or
+\f(CWtpkelly@cs.princeton.edu\fP.
+.SH COPYING PERMISSIONS
+Copyright \(co 2022
+Terence Kelly.
+.PP
+Permission is granted to make and distribute verbatim copies of
+this manual page provided the copyright notice and this permission
+notice are preserved on all copies.
+.ig
+Permission is granted to process this file through troff and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual page).
+..
+.PP
+Permission is granted to copy and distribute modified versions of this
+manual page under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+.PP
+Permission is granted to copy and distribute translations of this
+manual page into another language, under the above conditions for
+modified versions, except that this permission notice may be stated in
+a translation approved by the Foundation.
diff --git a/doc/wordlist6 b/doc/wordlist6
new file mode 100644
index 00000000..af667f09
--- /dev/null
+++ b/doc/wordlist6
@@ -0,0 +1,19 @@
+AWK
+CW
+Haris
+Jianan
+Volos
+Zi
+acm
+edu
+eecs
+env
+org
+pm
+pma
+princeton
+rm
+rwarray
+tpkelly
+umich
+var

-----------------------------------------------------------------------

Summary of changes:
 ChangeLog       |   4 ++
 NEWS            |   3 +-
 doc/ChangeLog   |   6 ++
 doc/Makefile.am |  21 +++++--
 doc/Makefile.in |  21 +++++--
 doc/pm-gawk.1   | 187 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/wordlist6   |  19 ++++++
 7 files changed, 250 insertions(+), 11 deletions(-)
 create mode 100644 doc/pm-gawk.1
 create mode 100644 doc/wordlist6


hooks/post-receive
-- 
gawk