[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[SCM] gawk branch, gawk-5.3-stable, updated. gawk-4.1.0-5537-ga3ab843b
|
From: |
Arnold Robbins |
|
Subject: |
[SCM] gawk branch, gawk-5.3-stable, updated. gawk-4.1.0-5537-ga3ab843b |
|
Date: |
Thu, 19 Sep 2024 11:15:10 -0400 (EDT) |
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, gawk-5.3-stable has been updated
via a3ab843bbe118e89e083b99b346fe1ce0a1e3ed4 (commit)
from ac764e2cd9e6740e77a9f8cda447d9f017a607a6 (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=a3ab843bbe118e89e083b99b346fe1ce0a1e3ed4
commit a3ab843bbe118e89e083b99b346fe1ce0a1e3ed4
Author: Arnold D. Robbins <arnold@skeeve.com>
Date: Thu Sep 19 18:14:49 2024 +0300
Update .info files. Oops.
diff --git a/doc/gawkworkflow.info b/doc/gawkworkflow.info
index 591ca0d6..aeba0028 100644
--- a/doc/gawkworkflow.info
+++ b/doc/gawkworkflow.info
@@ -1,4 +1,4 @@
-This is gawkworkflow.info, produced by makeinfo version 7.0.1 from
+This is gawkworkflow.info, produced by makeinfo version 7.1 from
gawkworkflow.texi.
Copyright © 2017, 2018, 2019, 2020, 2022, 2023 Free Software Foundation,
@@ -10,13 +10,13 @@ Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
-Invariant Sections being âGNU General Public Licenseâ, with the
-Front-Cover Texts being âA GNU Manualâ, and with the Back-Cover Texts as
+Invariant Sections being "GNU General Public License", with the
+Front-Cover Texts being "A GNU Manual", and with the Back-Cover Texts as
in (a) below. A copy of the license is included in the section entitled
-âGNU Free Documentation Licenseâ.
+"GNU Free Documentation License".
- a. The FSFâs Back-Cover Text is: âYou have the freedom to copy and
- modify this GNU manual.â
+ a. The FSF's Back-Cover Text is: "You have the freedom to copy and
+ modify this GNU manual."
INFO-DIR-SECTION Text creation and manipulation
START-INFO-DIR-ENTRY
* Gawk Work Flow: (gawkworkflow). Participating in âgawkâ
development.
@@ -45,13 +45,13 @@ Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
-Invariant Sections being âGNU General Public Licenseâ, with the
-Front-Cover Texts being âA GNU Manualâ, and with the Back-Cover Texts as
+Invariant Sections being "GNU General Public License", with the
+Front-Cover Texts being "A GNU Manual", and with the Back-Cover Texts as
in (a) below. A copy of the license is included in the section entitled
-âGNU Free Documentation Licenseâ.
+"GNU Free Documentation License".
- a. The FSFâs Back-Cover Text is: âYou have the freedom to copy and
- modify this GNU manual.â
+ a. The FSF's Back-Cover Text is: "You have the freedom to copy and
+ modify this GNU manual."
* Menu:
@@ -81,7 +81,7 @@ in (a) below. A copy of the license is included in the
section entitled
* Branches are state:: Branches represent development state.
* Repo State:: The different branch types in the repo.
* Local State:: Managing local branches.
-* Remotes:: What a âremoteâ is.
+* Remotes:: What a "remote" is.
* Cloning:: Cloning the repo the first time.
* Switching Branches:: Moving from one branch to another.
* Starting A New Branch:: Starting a new branch for development.
@@ -114,7 +114,7 @@ Preface
This Info file describes how to participate in development of GNU Awk
(âgawkâ). GNU Awk is a Free Software project belonging to the Free
-Software Foundationâs GNU project.
+Software Foundation's GNU project.
* Menu:
@@ -165,11 +165,11 @@ This Info file has the following chapters and appendices:
do before using Git seriously.
⢠*note Development without commit access:: gets into the meat of the
- development workflow, describing how to work if you donât have
+ development workflow, describing how to work if you don't have
commit access to the Savannah repository.
⢠*note Development with commit access:: continues the discussion,
- covering whatâs different when you can commit directly to the
+ covering what's different when you can commit directly to the
Savannah repository.
⢠*note General practices:: describes general development practices
@@ -182,7 +182,7 @@ This Info file has the following chapters and appendices:
should be familiar with in order to participate in âgawkâ
development and presents some tools that may make your work easier.
- ⢠*note Cheat Sheet:: provides a short âcheat sheetâ summarizing all
+ ⢠*note Cheat Sheet:: provides a short "cheat sheet" summarizing all
the Git commands referenced in this Info file.
⢠*note Resources:: provides a few pointers to Internet resources for
@@ -203,9 +203,9 @@ briefly documents the typographical conventions used in
Texinfo.
Examples you would type at the command line are preceded by the
common shell primary and secondary prompts, â$â and â>â. Input that
you
type is shown âlike thisâ. Output from the command is preceded by the
-glyph ââ£â. This typically represents the commandâs standard output.
-Error messages and other output on the commandâs standard error are
-preceded by the glyph âerrorââ. For example:
+glyph "â£". This typically represents the command's standard output.
+Error messages and other output on the command's standard error are
+preceded by the glyph "errorâ". For example:
$ echo hi on stdout
⣠hi on stdout
@@ -213,7 +213,7 @@ preceded by the glyph âerrorââ. For example:
errorâ hello on stderr
Characters that you type at the keyboard look âlike thisâ. In
-particular, there are special characters called âcontrol characters.â
+particular, there are special characters called "control characters."
These are characters that you type by holding down both the âCONTROLâ
key and another key, at the same time. For example, a âCtrl-dâ is typed
by first pressing and holding the âCONTROLâ key, next pressing the âdâ
@@ -255,12 +255,12 @@ File: gawkworkflow.info, Node: Contributing, Next:
Using Git, Prev: Preface,
1 How to Start Contributing
***************************
-âgawkâ development is distributed. Itâs done using electronic mail
+âgawkâ development is distributed. It's done using electronic mail
(âemailâ) and via branches in the Git repository (or ârepoâ) on
Savannah
-(http://savannah.gnu.org), the GNU projectâs source code management
+(http://savannah.gnu.org), the GNU project's source code management
site.
- In this major node we use some Git terminology. If youâre not at all
+ In this major node we use some Git terminology. If you're not at all
familiar with Git, then skim this major node and come back after reading
the rest of the Info file.
@@ -269,16 +269,16 @@ contributing, simply start! Take a look at the
âTODOâ file in the
distribution, see if there is something of interest to you, and ask on
the <bug-gawk@gnu.org> mailing list if anyone else is working on it. If
not, then go for it! (*Note Development Stuff:: for a discussion of
-some of the technical things youâll need to do. Here we describe the
+some of the technical things you'll need to do. Here we describe the
process in general.)
Your contribution can be almost anything that is relevant for âgawkâ,
such as code fixes, documentation fixes, and/or new features.
- NOTE: If possible, new features should be done using âgawkââs
+ NOTE: If possible, new features should be done using âgawkâ's
extension mechanism. If you want to add a user-visible language
- change to the âgawkâ core, youâre going to have to convince the
- maintainer and the other developers that itâs really worthwhile to
+ change to the âgawkâ core, you're going to have to convince the
+ maintainer and the other developers that it's really worthwhile to
do so.
Changes that improve performance or portability, or that fix bugs,
@@ -286,17 +286,17 @@ such as code fixes, documentation fixes, and/or new
features.
convincing, of course.
As you complete a task, submit patches for review to the
-<bug-gawk@gnu.org> mailing list, where youâll be given feedback about
+<bug-gawk@gnu.org> mailing list, where you'll be given feedback about
your work. Once your changes are acceptable, the maintainer will commit
them to the Git repository.
Over time, as the maintainer and development team gain confidence in
your ability to contribute, you may be asked to join the private âgawkâ
-developersâ mailing list, and/or be granted commit access to the Git
+developers' mailing list, and/or be granted commit access to the Git
repository on Savannah. This has happened to more than one person who
-just âcame out of the woodwork.â
+just "came out of the woodwork."
- Until that happens, or if you donât want to join the list, you should
+ Until that happens, or if you don't want to join the list, you should
continue to work with private branches and submission of patches to the
mailing list.
@@ -304,9 +304,9 @@ mailing list.
add a major feature, where the patch(es) would be very large, it has
become the practice to create a separate branch, based off of âmasterâ,
to host the feature. This way the maintainer can review it, and you can
-continue to improve it, until itâs ready for integration into âmasterâ.
+continue to improve it, until it's ready for integration into âmasterâ.
- NOTE: Because of the GNU projectâs requirements for signed
+ NOTE: Because of the GNU project's requirements for signed
paperwork for contributions, the âgawkâ project will *not* work
with pull requests from GitHub (http://github.com) or any other
Git-based software hosting service. You must submit patches to the
@@ -315,7 +315,7 @@ continue to improve it, until itâs ready for integration
into âmasterâ.
The <bug-gawk@gnu.org> mailing list is not private. Anyone may send
mail to it, and anyone may subscribe to it. To subscribe, go to the
-listâs web page (https://lists.gnu.org/mailman/listinfo/bug-gawk) and
+list's web page (https://lists.gnu.org/mailman/listinfo/bug-gawk) and
follow the instructions there. If you plan to be involved long-term
with âgawkâ development, then you probably should subscribe to the list.
@@ -329,7 +329,7 @@ This chapter provides an introduction to using Git. Our
point is _not_
to rave about how wonderful Git is, nor to go into painful detail about
how it works. Rather we want to give you enough background to
understand how to use Git effectively for bug fix and feature
-development and to interact (âplay nicelyâ) with the development team.
+development and to interact ("play nicely") with the development team.
* Menu:
@@ -341,11 +341,11 @@ development and to interact (âplay nicelyâ) with the
development team.
File: gawkworkflow.info, Node: Push Pull, Next: Repo Copies, Up: Using Git
-2.1 The âPush/Pullâ Model of Software Development
+2.1 The "Push/Pull" Model of Software Development
=================================================
Git is a powerful, distributed source code management system. However,
-the way itâs used for âgawkâ development purposely does not take
+the way it's used for âgawkâ development purposely does not take
advantage of all its features.
Instead, the model is rather simple, and in many ways much like more
@@ -353,7 +353,7 @@ traditional distributed systems such as the Concurrent
Versions System
(http://www.nongnu.org/cvs) (CVS) or Subversion
(http://subversion.apache.org) (SVN).
- The central idea can be termed âpush/pull.â You _pull_ updates down
+ The central idea can be termed "push/pull." You _pull_ updates down
from the central repository to your local copy, and if you have commit
rights, you _push_ your changes or updates up to the central repository.
@@ -385,15 +385,14 @@ represents the history of a collection of files and
directories (a file
directories added or deleted, and/or file contents changed) is termed a
âcommitâ.
- When you first create a local copy of a remote repository (âclone the
-repoâ), Git copies all of the original repositoryâs branches to your
+ When you first create a local copy of a remote repository ("clone the
+repo"), Git copies all of the original repository's branches to your
local system. The original remote repository is referred to as being
âupstreamâ, and your local repo is âdownstreamâ from it. Git
distinguishes branches from the upstream repo by prefixing their names
-with âorigin/â. Letâs draw some pictures. *note Figure 2.1:
+with âorigin/â. Let's draw some pictures. *note Figure 2.1:
savannah-repo. represents the state of the repo on Savannah:
-
+======================+
| Branches |
+======================+
@@ -411,7 +410,7 @@ savannah-repo. represents the state of the repo on Savannah:
Figure 2.1: The Savannah âgawkâ Repository
After you clone the repo, on your local system you will have a single
-branch named âmasterâ thatâs visible when you use âgit branchâ to see
+branch named âmasterâ that's visible when you use âgit branchâ to see
your branches.
$ git clone http://git.savannah.gnu.org/r/gawk.git Clone the repo
@@ -424,7 +423,6 @@ The current branch is always indicated with a leading
asterisk (â*â).
Pictorially, the local repo looks like *note Figure 2.2: your-repo.
(you can ignore the âTâ column for the moment):
-
+===+======================++=============================+
| T | Local Branches || Remote Branches |
+===+======================++=============================+
@@ -444,12 +442,12 @@ Figure 2.2: Your Local âgawkâ Repository
Note that what is simply âgawk-4.1-stableâ in the upstream repo is now
referred to as âorigin/gawk-4.1-stableâ. The âorigin/â branches are a
snapshot of the state of the upstream repo. This is how Git allows you
-to see what changes youâve made with respect to the upstream repo,
+to see what changes you've made with respect to the upstream repo,
without having to actually communicate with the upstream repo over the
Internet. (When files are identical, Git is smart enough to not have
two separate physical copies on your local disk.)
- If youâre working on a simple bug fix or change, you can do so
+ If you're working on a simple bug fix or change, you can do so
directly in your local âmasterâ branch. You can then commit your
changes, and if you have access rights, push them upstream to the
Savannah repo. (However, there is a process to follow. Please read the
@@ -465,7 +463,7 @@ File: gawkworkflow.info, Node: Local Branches, Next:
Branches are state, Prev
2.3 Local Branches
==================
-Letâs talk about local branches in more detail. (The terminology used
+Let's talk about local branches in more detail. (The terminology used
here is my own, not official Git jargon.) There are two kinds of local
branches:
@@ -496,12 +494,11 @@ branches:
and branches in *note Development without commit access::, later in this
Info file.
- Letâs say you have checked out a copy of âgawk-4.1-stableâ and have
+ Let's say you have checked out a copy of âgawk-4.1-stableâ and have
created a purely local branch named âbetter-randomâ. Then our picture
now looks like *note Figure 2.3: your-repo-2, where the âTâ column
indicates a tracking branch.
-
+===+======================++=============================+
| T | Local Branches || Remote Branches |
+===+======================++=============================+
@@ -542,7 +539,7 @@ branches.
* Repo State:: The different branch types in the repo.
* Local State:: Managing local branches.
-* Remotes:: What a âremoteâ is.
+* Remotes:: What a "remote" is.
File: gawkworkflow.info, Node: Repo State, Next: Local State, Up: Branches
are state
@@ -601,9 +598,9 @@ File: gawkworkflow.info, Node: Local State, Next:
Remotes, Prev: Repo State,
---------------------------------------
Purely local branches are where you do your own development. You may
-use purely local branches because you donât have commit rights to the
+use purely local branches because you don't have commit rights to the
Savannah repo. You may also use them if you are doing some work that
-isnât ready for sharing with the rest of the team, or cannot be
+isn't ready for sharing with the rest of the team, or cannot be
committed for some other reason.
For example, for around a nine-month period, the maintainer kept a
@@ -631,9 +628,9 @@ these branches with âgit branch -aâ:
⣠remotes/origin/feature/fix-comments
⣠...
- Youâll note that what weâve referred to as âorigin/â branches appear
+ You'll note that what we've referred to as âorigin/â branches appear
in the output with an additional prefix: âremotes/â. Up to this point,
-weâve treated Git as if it allowed only a single upstream repository.
+we've treated Git as if it allowed only a single upstream repository.
But in fact, you can configure it to use more than one. All the known
upstream repositories are grouped under the âremotes/â prefix, with
âremotes/originâ being the one from which you initially cloned your
@@ -650,7 +647,7 @@ File: gawkworkflow.info, Node: Configuring git, Next:
Development without comm
*************************************
Before starting to use Git, you should configure it with some important
-settings that wonât change as you use Git. You may configure options
+settings that won't change as you use Git. You may configure options
both globally, and on a per-repository basis. Here, we discuss only
global configuration settings.
@@ -663,7 +660,7 @@ relevant files with your favorite text editor.(1)
$ git config --global user.email jpdev@example.com Set email address
Setting these two items are an absolute requirement. *Note*: No
-aliases are allowed. If you canât supply your real name, you cannot
+aliases are allowed. If you can't supply your real name, you cannot
contribute to the project. Other options that the âgawkâ maintainer
recommends that you use are:
@@ -693,7 +690,7 @@ safest way to operate, and is the default in current Git
versions.
⣠user.email=jpdev@example.com
⣠push.default=simple
- Here are the âgawkâ maintainerâs settings:
+ Here are the âgawkâ maintainer's settings:
$ git config --global --list
⣠user.name=Arnold D. Robbins
@@ -705,13 +702,13 @@ safest way to operate, and is the default in current Git
versions.
⣠pager.status=true
⣠log.decorate=auto
- Additional, per-project (âlocalâ) settings are stored in each repoâs
+ Additional, per-project ("local") settings are stored in each repo's
â.git/configâ file.
---------- Footnotes ----------
(1) You are required to use either Vim or Emacs, other text editors
-are not allowed. Of course, reasonable developers wouldnât want to use
+are not allowed. Of course, reasonable developers wouldn't want to use
any other editor anyway.
@@ -772,7 +769,7 @@ your vacation in the Bahamas:
repo, do a âgit pullâ or checkout a different branch. (In the
latter case, do âmake distcleanâ first.) Otherwise things will get
messy very quickly. The âbootstrap.shâ script ensures that all of
- the file time stamps are up to date so that itâs not necessary to
+ the file time stamps are up to date so that it's not necessary to
run the various configuration tools.
---------- Footnotes ----------
@@ -785,8 +782,8 @@ File: gawkworkflow.info, Node: Switching Branches, Next:
Starting A New Branch
4.2 Switching Branches
======================
-So far, weâve been working in the default âmasterâ branch. Letâs check
-whatâs happening in the âgawk-4.1-stableâ branch:
+So far, we've been working in the default âmasterâ branch. Let's check
+what's happening in the âgawk-4.1-stableâ branch:
$ make distclean Clean up
$ git checkout gawk-4.1-stable Checkout a different branch
@@ -802,7 +799,7 @@ File: gawkworkflow.info, Node: Starting A New Branch,
Next: Undoing a change,
4.3 Starting A New Branch
=========================
-Letâs say you want to work on a new feature. For example, you might
+Let's say you want to work on a new feature. For example, you might
decide to add Python syntax support.(1) You should create a new branch
on which to work. First, switch back to âmasterâ:
@@ -819,8 +816,8 @@ on which to work. First, switch back to âmasterâ:
support. As you do each defined chunk of work, you update the
âChangeLogâ file with your changes before âcommittingâ them to the
repo.
- Letâs say youâve added a new file âpython.câ and updated several
-others. Use âgit statusâ to see whatâs changed:
+ Let's say you've added a new file âpython.câ and updated several
+others. Use âgit statusâ to see what's changed:
$ git status
⣠...
@@ -832,7 +829,7 @@ external âdiffâ command, such as âmeldâ on
GNU/Linux:
$ git diff Regular built-in tool for standard
diffs
$ git difftool --tool=meld GUI diff tool
- When youâre happy with the changes, use âgit addâ to tell Git which
+ When you're happy with the changes, use âgit addâ to tell Git which
of the changed and/or new files you wish to have ready to be committed:
$ git add ...
@@ -854,9 +851,9 @@ message will be visible via âgit logâ.
---------- Footnotes ----------
- (1) Just joking. Please donât attempt this for real.
+ (1) Just joking. Please don't attempt this for real.
- (2) Donât run âgit difftoolâ in the background; it works
+ (2) Don't run âgit difftoolâ in the background; it works
interactively.
@@ -882,10 +879,10 @@ File: gawkworkflow.info, Node: Saving Without
Committing, Next: Updating, Pre
========================
Sometimes, you may be in the middle of a set of changes that are not yet
-completed, when you need to stop what youâre doing and work on something
+completed, when you need to stop what you're doing and work on something
else. For example, you might be updating the documentation when a bug
-report comes in and you want to work on the bug. But you canât just
-switch branches, since you havenât finished your current changes.
+report comes in and you want to work on the bug. But you can't just
+switch branches, since you haven't finished your current changes.
The way to work around this problem is with âgit stashâ. This
command saves your changes in a special place within Git from which they
@@ -979,7 +976,7 @@ addâ and âgit commitâ:
$ git rebase --continue Continue the rebase
The âgit rebase --continueâ then continues the process of rebasing
-the current branch that we started in *note Rebasing::. Itâs not
+the current branch that we started in *note Rebasing::. It's not
necessary if you are using âgit mergeâ (*note Points to remember::).
@@ -988,10 +985,10 @@ File: gawkworkflow.info, Node: Submitting Changes,
Next: Removing Branches, P
4.7 Submitting Your Changes
===========================
-So now your feature is complete. Youâve added test cases for it to the
+So now your feature is complete. You've added test cases for it to the
test suite(1), you have âChangeLogâ entries that describe all the
changes(2), you have documented the new feature(3), and everything works
-great. Youâre ready to submit the changes for review, and with any
+great. You're ready to submit the changes for review, and with any
luck, inclusion into âgawkâ.
There are two ways to submit your changes for review.
@@ -1004,7 +1001,7 @@ _Generate a single large patch_
$ git diff master > /tmp/python.diff
Mail the âpython.diffâ file to the appropriate mailing list along
- with a description of what youâve changed and why.
+ with a description of what you've changed and why.
The patch file will likely contain changes to generated files, such
as âawkgram.câ or âMakefile.inâ. If you are comfortable manually
@@ -1017,10 +1014,10 @@ _Generate a set of patches that in toto comprise your
changes_
$ git checkout feature/python
$ git format-patch
- This creates a set of patch files, one per commit that isnât on the
+ This creates a set of patch files, one per commit that isn't on the
original branch. Mail these patches, either separately, or as a
set of attachments, to the appropriate mailing list along with a
- description of what youâve changed and why.
+ description of what you've changed and why.
Either way you choose to submit your changes, the âgawkâ maintainer
and development team will review your changes and provide feedback. If
@@ -1030,7 +1027,7 @@ changes.
Which list should you send mail to? If you are just starting to
contribute, use <bug-gawk@gnu.org>. After making enough contributions,
-you may be invited to join the private âgawkâ developersâ mailing list.
+you may be invited to join the private âgawkâ developers' mailing list.
If you do so, then submit your changes to that list.
If you make any substantial changes, you will need to assign
@@ -1040,11 +1037,11 @@ information.
---------- Footnotes ----------
- (1) You did do this, didnât you?
+ (1) You did do this, didn't you?
(2) You remembered this, right?
- (3) You wouldnât neglect this, would you?
+ (3) You wouldn't neglect this, would you?
File: gawkworkflow.info, Node: Removing Branches, Next: Points to remember,
Prev: Submitting Changes, Up: Development without commit access
@@ -1069,11 +1066,11 @@ File: gawkworkflow.info, Node: Points to remember,
Prev: Removing Branches, U
There are some important points to remember:
⢠Always do a âmake distcleanâ before switching between branches.
- Things will get really confused if you donât.
+ Things will get really confused if you don't.
⢠For upstream branches, _always_ work with tracking branches.
_Never_ use âgit checkout origin/WHATEVERâ. Git will happily let
- you do something like that, but itâs just plain asking for trouble.
+ you do something like that, but it's just plain asking for trouble.
⢠Make sure your tracking branches are up-to-date before doing
anything with them, particularly using them as the basis for a
@@ -1125,16 +1122,16 @@ File: gawkworkflow.info, Node: Initial setup, Next:
ssh clone, Up: Developmen
=================
Congratulations! After becoming a quality contributor to âgawkâ
-development, youâve been invited to join the private development list
+development, you've been invited to join the private development list
and to accept having commit access to the repo.
The first thing to do is to create an account on Savannah, choosing a
unique user name. To do so, go to the Savannah home page
-(http://savannah.gnu.org) and click on the âNew Userâ link. The setup
+(http://savannah.gnu.org) and click on the "New User" link. The setup
will include uploading of your âsshâ key, as per the instructions on the
Savannah web page.
- After youâve done all this, send email to the maintainer with your
+ After you've done all this, send email to the maintainer with your
Savannah user name, and he will add you to the list of users who have
commit access to the repo.
@@ -1178,8 +1175,8 @@ without commit access:
6. Iterate until the patch is ready to be committed.
However, now that you have commit access, you can commit the fix and
-push it up to the repo yourself! Letâs assume youâve made a bug fix
-directly on âmasterâ. Hereâs how to commit your changes:
+push it up to the repo yourself! Let's assume you've made a bug fix
+directly on âmasterâ. Here's how to commit your changes:
$ git diff Review the patch one more time
$ git add ... Add any files for committing
@@ -1187,7 +1184,7 @@ directly on âmasterâ. Hereâs how to commit your
changes:
$ git push Push the files up to the repo. Ta da!
The first three steps are the same described earlier (*note Starting
-A New Branch::). The âgit pushâ is whatâs new, and it updates the repo
+A New Branch::). The âgit pushâ is what's new, and it updates the repo
on Savannah. Congratulations!
As a courtesy, you should send a note to the mailing list indicating
@@ -1242,7 +1239,7 @@ File: gawkworkflow.info, Node: Developing fixes, Prev:
Developing new features
If you want to make a fix on âmasterâ or on the current stable branch,
you work the same way, by producing and discussing a diff on the mailing
-list. Once itâs approved, you can commit it yourself:
+list. Once it's approved, you can commit it yourself:
$ git checkout master Move to master
$ git pull Make sure we're up to date with the maintainer
@@ -1251,7 +1248,7 @@ list. Once itâs approved, you can commit it yourself:
$ git add ... Add any files for committing
$ git commit Commit the files with a commit message.
- When youâre ready to push your changes:
+ When you're ready to push your changes:
$ git pull Download latest version; Git will merge
$ gvim ... Resolve any merge conflicts with git add and
git commit
@@ -1271,14 +1268,14 @@ discussion here is mainly for developers with commit
access to the
Savannah repo.
âPropagating Fixesâ
- Usually, bug fixes should be made on the current âstableâ branch.
+ Usually, bug fixes should be made on the current "stable" branch.
Once a fix has been reviewed and approved, you can commit it and
push it yourself. Typically, the maintainer then takes care to
merge the fix to âmasterâ and from there to any other branches.
However, you are welcome to save him the time and do this yourself.
âDirectory ownershipâ
- Some developers âownâ certain parts of the tree, such as the âpcâ
+ Some developers "own" certain parts of the tree, such as the âpcâ
and âvmsâ directories. They are allowed to commit changes to those
directories without review by the mailing list, but changes that
also touch the mainline code should be submitted for review.
@@ -1286,12 +1283,12 @@ Savannah repo.
âNew feature developmentâ
Unless you can convince the maintainer (and the other developers!)
otherwise, you should _always_ start branches for new features from
- âmasterâ, and not from the current âstableâ branch.
+ âmasterâ, and not from the current "stable" branch.
Use âgit checkout -b feature/FEATURE_NAMEâ to create the initial
branch. You may then elect to keep it purely local, or to push it
up to Savannah for review, even if the feature is not yet totally
- âready for prime time.â
+ "ready for prime time."
During development of a new feature, you will most likely wish to
keep your feature branch up to date with respect to ongoing improvements
@@ -1326,11 +1323,11 @@ feature branch.
$ git merge master Merge from master
Here too, you may have to resolve any merge conflicts (*note Merge
- Conflicts::). Once thatâs done, you can push the changes up to
+ Conflicts::). Once that's done, you can push the changes up to
Savannah.
When the changes on your branch are complete, usually the maintainer
-merges the branch to âmasterâ. But thereâs really no magic involved,
+merges the branch to âmasterâ. But there's really no magic involved,
the merge is simply done in the other direction:
$ git checkout feature/python Checkout feature branch
@@ -1339,7 +1336,7 @@ the merge is simply done in the other direction:
$ git pull Bring it up to date
$ git merge feature/python Merge from feature/python into master
- If youâve been keeping âfeature/pythonâ in sync with âmasterâ,
then
+ If you've been keeping âfeature/pythonâ in sync with âmasterâ, then
there should be no merge conflicts to resolve, and you can push the
result to Savannah:
@@ -1356,8 +1353,8 @@ result to Savannah:
The âgit pushâ command deletes the âfeature/pythonâ branch from the
Savannah repo.
-Finally, you should send an email to developerâs list describing what
-youâve done so that everyone else can delete their copies of the branch
+Finally, you should send an email to developer's list describing what
+you've done so that everyone else can delete their copies of the branch
and do a âgit fetch --pruneâ (*note Repo Maintenance::).
To update the other remaining development branches with the latest
@@ -1379,7 +1376,7 @@ _Removing old branches_
on Savannah are deleted (as shown in *note General practices::).
However, your local copies of those branches (labelled with the
- âorigin/â prefix) remain in your local repo. If you donât need
+ âorigin/â prefix) remain in your local repo. If you don't need
them, then you can clean up your repo as follows.
First, remove any related tracking branch you may have:
@@ -1392,10 +1389,10 @@ _Removing old branches_
$ git fetch --prune Remove unneeded branches
_Removing cruft_
- As Git works, occasional âcruftâ collects in the repository. Git
- does occasionally clean this out on its own, but if youâre
+ As Git works, occasional "cruft" collects in the repository. Git
+ does occasionally clean this out on its own, but if you're
concerned about disk usage, you can do so yourself using âgit gcâ
- (short for âgarbage collectâ). For example:
+ (short for "garbage collect"). For example:
$ du -s . Check disk usage
⣠99188 . Almost 10 megabytes
@@ -1425,7 +1422,7 @@ _Renaming branches_
$ git push origin :feature/OLD-NAME feature/NEW-NAME
NOTE: It is the leading â:â in the first branch name that
- causes Git to delete the old name in the upstream repo. Donât
+ causes Git to delete the old name in the upstream repo. Don't
omit it!
Finally, reset the upstream branch for the local branch with the
@@ -1434,7 +1431,7 @@ _Renaming branches_
$ git push -u origin feature/NEW-NAME
You should also update the mailing list to let the other developers
- know whatâs happening.
+ know what's happening.
---------- Footnotes ----------
@@ -1448,7 +1445,7 @@ File: gawkworkflow.info, Node: Development Stuff, Next:
Cheat Sheet, Prev: Re
*******************
This major node discusses other things you need to know and/or do if
-youâre going to participate seriously in âgawkâ development.
+you're going to participate seriously in âgawkâ development.
* Menu:
@@ -1475,7 +1472,7 @@ respectively.
---------- Footnotes ----------
- (1) Changes that donât follow the coding style guidelines wonât be
+ (1) Changes that don't follow the coding style guidelines won't be
accepted. Period.
@@ -1571,9 +1568,9 @@ File: gawkworkflow.info, Node: Compilers, Prev: GNU
Tools, Up: Tools
The default compiler for âgawkâ development is GCC, the GNU Compiler
Collection (https://gcc.gnu.org). The default version of GCC is
-whatever is on the maintainerâs personal GNU/Linux system, although he
+whatever is on the maintainer's personal GNU/Linux system, although he
does try to build the latest released version if that is newer than
-whatâs on his system, and then occasionally test âgawkâ with it.
+what's on his system, and then occasionally test âgawkâ with it.
He also attempts to test occasionally with âclangâ
(https://clang.llvm.org/). However, he uses whatever is the default for
@@ -1596,8 +1593,8 @@ _The Tiny C Compiler, âtccâ_
GCC before doing any commits, in case âtccâ has missed
something.(1)
- See the projectâs home page (http://www.tinycc.org) for some
- information. More information can be found in the projectâs Git
+ See the project's home page (http://www.tinycc.org) for some
+ information. More information can be found in the project's Git
repository (http://repo.or.cz/tinycc.git). The maintainer builds
from the âmobâ branch for his work, but after updating it you
should check that this branch still works to compile âgawkâ before
@@ -1609,13 +1606,13 @@ _The (Revived) Portable C Compiler_
modern architectures. It produces better code than âtccâ but is
slower, although still much faster than GCC and âclangâ.
- See the projectâs home page (http://pcc.ludd.ltu.se) for more
+ See the project's home page (http://pcc.ludd.ltu.se) for more
information. See <http://pcc.ludd.ltu.se/supported-platforms> for
instructions about obtaining the code using CVS and building it.
- An alternative location for the source is the âgawkâ maintainerâs
+ An alternative location for the source is the âgawkâ maintainer's
Git mirror (https://github.com/arnoldrobbins/pcc-revived) of the
- code. If youâre using Ubuntu GNU/Linux 18.04 or later, you need to
+ code. If you're using Ubuntu GNU/Linux 18.04 or later, you need to
use the âubuntu-18â branch from this Git mirror.
---------- Footnotes ----------
@@ -1679,17 +1676,17 @@ given Git command.
Display and/or change global and/or local configuration settings.
âgit diffâ
- Show a unified-format diff of whatâs changed in the current
+ Show a unified-format diff of what's changed in the current
directory as of the last commit. It helps to have Git configured
to use its builtin pager for reviewing diffs (*note Configuring
git::).
âgit difftoolâ
- Use a âtoolâ (usually a GUI-based program) to view differences,
- instead of the standard textual diff as youâd get from âgit diffâ.
+ Use a "tool" (usually a GUI-based program) to view differences,
+ instead of the standard textual diff as you'd get from âgit diffâ.
âgit fetchâ
- Update your local copy of the upstreamâs branches. That is, update
+ Update your local copy of the upstream's branches. That is, update
the various âorigin/â branches. This leaves your local tracking
branches unchanged. With the â--pruneâ option, this removes any
copies of stale âorigin/â branches.
@@ -1699,15 +1696,15 @@ given Git command.
branch from which you started.
âgit gcâ
- Run a âgarbage collectionâ pass in the current repository. This
+ Run a "garbage collection" pass in the current repository. This
can often reduce the space used in a large repo. For âgawkâ it
does not make that much difference.
âgit helpâ
- Print a man-pageâstyle usage summary for a command.
+ Print a man-page-style usage summary for a command.
âgit logâ
- Show the current branchâs commit log. This includes who made the
+ Show the current branch's commit log. This includes who made the
commit, the date, and the commit message. Commits are shown from
newest to oldest.
@@ -1791,16 +1788,16 @@ Index
* bootstrap.sh script: Cloning. (line 30)
* branch, main: Repo State. (line 27)
* branch, master: Repo State. (line 27)
-* branches, origin/: Repo Copies. (line 70)
-* branches, local: Local Branches. (line 6)
-* branches, tracking: Local Branches. (line 11)
* branches, dead: Repo State. (line 8)
-* branches, stable: Repo State. (line 15)
* branches, feature: Repo State. (line 35)
+* branches, local: Local Branches. (line 6)
+* branches, origin/: Repo Copies. (line 68)
* branches, purely local: Local State. (line 6)
* branches, removing: Removing Branches. (line 6)
* branches, removing <1>: Repo Maintenance. (line 9)
* branches, renaming: Repo Maintenance. (line 44)
+* branches, stable: Repo State. (line 15)
+* branches, tracking: Local Branches. (line 11)
* ChangeLog file: Starting A New Branch.
(line 19)
* ChangeLog file <1>: Developing patches. (line 11)
@@ -1811,10 +1808,10 @@ Index
(line 19)
* compilers: Compilers. (line 6)
* compiling for debugging: Debugging. (line 6)
-* configuration setting, user.name: Configuring git. (line 16)
-* configuration setting, user.email: Configuring git. (line 16)
-* configuration setting, push.default: Configuring git. (line 24)
* configuration setting, pager.status: Configuring git. (line 24)
+* configuration setting, push.default: Configuring git. (line 24)
+* configuration setting, user.email: Configuring git. (line 16)
+* configuration setting, user.name: Configuring git. (line 16)
* configuration settings: Configuring git. (line 6)
* configuration settings, global: Configuring git. (line 6)
* configure.ac file: GNU Tools. (line 15)
@@ -1837,111 +1834,111 @@ Index
* generating multiple patches: Submitting Changes. (line 29)
* gettext: GNU Tools. (line 27)
* git branch command, -a option: Remotes. (line 6)
-* git command, git branch: Repo Copies. (line 39)
-* git command, git clone: Repo Copies. (line 43)
+* git command, --help option: Cheat Sheet. (line 10)
+* git command, git add: Starting A New Branch.
+ (line 36)
+* git command, git add <1>: Developing patches. (line 27)
+* git command, git add <2>: Developing new features.
+ (line 24)
+* git command, git add <3>: Developing new features.
+ (line 36)
+* git command, git add <4>: Developing fixes. (line 10)
+* git command, git branch: Repo Copies. (line 38)
+* git command, git branch <1>: Removing Branches. (line 9)
+* git command, git branch <2>: General practices. (line 87)
+* git command, git branch <3>: Repo Maintenance. (line 20)
* git command, git checkout: Local Branches. (line 11)
-* git command, git push: Local Branches. (line 16)
-* git command, git config: Configuring git. (line 11)
-* git command, git clone <1>: Cloning. (line 6)
-* git command, git pull: Cloning. (line 21)
* git command, git checkout <1>: Switching Branches. (line 9)
-* git command, git pull <1>: Switching Branches. (line 9)
* git command, git checkout <2>: Starting A New Branch.
(line 10)
-* git command, git status: Starting A New Branch.
- (line 23)
-* git command, git diff: Starting A New Branch.
- (line 29)
-* git command, git difftool: Starting A New Branch.
- (line 29)
-* git command, git add: Starting A New Branch.
- (line 36)
-* git command, git status <1>: Starting A New Branch.
- (line 41)
-* git command, git commit: Starting A New Branch.
- (line 49)
-* git command, git log: Starting A New Branch.
- (line 51)
* git command, git checkout <3>: Undoing a change. (line 10)
-* git command, git reset: Undoing a change. (line 12)
-* git command, git stash: Saving Without Committing.
- (line 12)
-* git command, git stash pop: Saving Without Committing.
- (line 12)
-* git command, git stash list: Saving Without Committing.
- (line 12)
-* git command, git rebase: Rebasing. (line 10)
* git command, git checkout <4>: Rebasing. (line 10)
-* git command, git pull <2>: Rebasing. (line 10)
* git command, git checkout <5>: Submitting Changes. (line 18)
-* git command, git diff <1>: Submitting Changes. (line 18)
-* git command, git format-patch: Submitting Changes. (line 29)
* git command, git checkout <6>: Submitting Changes. (line 32)
* git command, git checkout <7>: Removing Branches. (line 9)
-* git command, git pull <3>: Removing Branches. (line 9)
-* git command, git branch <1>: Removing Branches. (line 9)
* git command, git checkout <8>: Points to remember. (line 19)
-* git command, git pull <4>: Points to remember. (line 19)
-* git command, git rebase <1>: Points to remember. (line 25)
* git command, git checkout <9>: Points to remember. (line 32)
-* git command, git diff <2>: Points to remember. (line 32)
* git command, git checkout <10>: Points to remember. (line 37)
-* git command, git pull <5>: Points to remember. (line 37)
-* git command, git merge: Points to remember. (line 37)
-* git command, git clone <2>: ssh clone. (line 10)
-* git command, git diff <3>: Developing patches. (line 16)
-* git command, git diff <4>: Developing patches. (line 27)
-* git command, git add <1>: Developing patches. (line 27)
-* git command, git commit <1>: Developing patches. (line 27)
-* git command, git push <1>: Developing patches. (line 27)
* git command, git checkout <11>: Developing new features.
(line 9)
-* git command, git pull <6>: Developing new features.
- (line 9)
-* git command, git diff <5>: Developing new features.
- (line 24)
-* git command, git add <2>: Developing new features.
- (line 24)
+* git command, git checkout <12>: Developing fixes. (line 10)
+* git command, git checkout <13>: General practices. (line 43)
+* git command, git checkout <14>: General practices. (line 60)
+* git command, git checkout <15>: General practices. (line 73)
+* git command, git clone: Repo Copies. (line 42)
+* git command, git clone <1>: Cloning. (line 6)
+* git command, git clone <2>: ssh clone. (line 10)
+* git command, git commit: Starting A New Branch.
+ (line 49)
+* git command, git commit <1>: Developing patches. (line 27)
* git command, git commit <2>: Developing new features.
(line 24)
-* git command, git push <2>: Developing new features.
- (line 24)
-* git command, git diff <6>: Developing new features.
- (line 36)
-* git command, git add <3>: Developing new features.
- (line 36)
* git command, git commit <3>: Developing new features.
(line 36)
-* git command, git push <3>: Developing new features.
- (line 36)
-* git command, git checkout <12>: Developing fixes. (line 10)
-* git command, git pull <7>: Developing fixes. (line 10)
-* git command, git add <4>: Developing fixes. (line 10)
* git command, git commit <4>: Developing fixes. (line 10)
+* git command, git config: Configuring git. (line 11)
+* git command, git diff: Starting A New Branch.
+ (line 29)
+* git command, git diff <1>: Submitting Changes. (line 18)
+* git command, git diff <2>: Points to remember. (line 32)
+* git command, git diff <3>: Developing patches. (line 16)
+* git command, git diff <4>: Developing patches. (line 27)
+* git command, git diff <5>: Developing new features.
+ (line 24)
+* git command, git diff <6>: Developing new features.
+ (line 36)
* git command, git diff <7>: Developing fixes. (line 10)
+* git command, git difftool: Starting A New Branch.
+ (line 29)
+* git command, git fetch: General practices. (line 96)
+* git command, git fetch <1>: Repo Maintenance. (line 25)
+* git command, git format-patch: Submitting Changes. (line 29)
+* git command, git gc: Repo Maintenance. (line 33)
+* git command, git help: Cheat Sheet. (line 10)
+* git command, git log: Starting A New Branch.
+ (line 51)
+* git command, git merge: Points to remember. (line 37)
+* git command, git merge <1>: General practices. (line 60)
+* git command, git merge <2>: General practices. (line 73)
+* git command, git pull: Cloning. (line 21)
+* git command, git pull <1>: Switching Branches. (line 9)
+* git command, git pull <2>: Rebasing. (line 10)
+* git command, git pull <3>: Removing Branches. (line 9)
+* git command, git pull <4>: Points to remember. (line 19)
+* git command, git pull <5>: Points to remember. (line 37)
+* git command, git pull <6>: Developing new features.
+ (line 9)
+* git command, git pull <7>: Developing fixes. (line 10)
* git command, git pull <8>: Developing fixes. (line 19)
-* git command, git push <4>: Developing fixes. (line 19)
-* git command, git checkout <13>: General practices. (line 43)
* git command, git pull <9>: General practices. (line 43)
-* git command, git rebase <2>: General practices. (line 43)
-* git command, git checkout <14>: General practices. (line 60)
* git command, git pull <10>: General practices. (line 60)
-* git command, git merge <1>: General practices. (line 60)
-* git command, git checkout <15>: General practices. (line 73)
* git command, git pull <11>: General practices. (line 73)
-* git command, git merge <2>: General practices. (line 73)
+* git command, git pull <12>: Repo Maintenance. (line 20)
+* git command, git push: Local Branches. (line 16)
+* git command, git push <1>: Developing patches. (line 27)
+* git command, git push <2>: Developing new features.
+ (line 24)
+* git command, git push <3>: Developing new features.
+ (line 36)
+* git command, git push <4>: Developing fixes. (line 19)
* git command, git push <5>: General practices. (line 83)
-* git command, git branch <2>: General practices. (line 87)
* git command, git push <6>: General practices. (line 87)
-* git command, git fetch: General practices. (line 96)
-* git command, git pull <12>: Repo Maintenance. (line 20)
-* git command, git branch <3>: Repo Maintenance. (line 20)
-* git command, git fetch <1>: Repo Maintenance. (line 25)
-* git command, git gc: Repo Maintenance. (line 33)
-* git command, git help: Cheat Sheet. (line 10)
-* git command, --help option: Cheat Sheet. (line 10)
+* git command, git rebase: Rebasing. (line 10)
+* git command, git rebase <1>: Points to remember. (line 25)
+* git command, git rebase <2>: General practices. (line 43)
+* git command, git reset: Undoing a change. (line 12)
* git command, git reset, --hard option: Cheat Sheet. (line 93)
+* git command, git stash: Saving Without Committing.
+ (line 12)
* git command, git stash <1>: Cheat Sheet. (line 97)
+* git command, git stash list: Saving Without Committing.
+ (line 12)
+* git command, git stash pop: Saving Without Committing.
+ (line 12)
+* git command, git status: Starting A New Branch.
+ (line 23)
+* git command, git status <1>: Starting A New Branch.
+ (line 41)
* Git Project: Intended Audience. (line 18)
* GitHub: Contributing. (line 57)
* global configuration settings: Configuring git. (line 6)
@@ -1963,7 +1960,7 @@ Index
(line 29)
* merge conflicts: Merge Conflicts. (line 6)
* old branches, removing: Repo Maintenance. (line 9)
-* origin/ branches: Repo Copies. (line 70)
+* origin/ branches: Repo Copies. (line 68)
* ownership of directories: General practices. (line 17)
* pager.status configuration setting: Configuring git. (line 24)
* patch, single, generation of: Submitting Changes. (line 14)
@@ -1977,8 +1974,8 @@ Index
* push.default configuration setting: Configuring git. (line 24)
* rebasing: Rebasing. (line 6)
* removing, branches: Removing Branches. (line 6)
-* removing, old branches: Repo Maintenance. (line 9)
* removing, cruft: Repo Maintenance. (line 27)
+* removing, old branches: Repo Maintenance. (line 9)
* renaming branches: Repo Maintenance. (line 44)
* Repository, gawk, URL for: ssh clone. (line 10)
* review, changes you made: Submitting Changes. (line 12)
@@ -2001,69 +1998,69 @@ Index
Tag Table:
-Node: Top1168
-Node: Preface5315
-Node: Intended Audience5886
-Node: This Manual6768
-Node: Conventions8329
-Node: Acknowledgments9850
-Node: Reviewers10287
-Node: Contributing10608
-Node: Using Git14062
-Node: Push Pull14822
-Node: Repo Copies16388
-Ref: savannah-repo17403
-Ref: your-repo18460
-Ref: Repo Copies-Footnote-120179
-Node: Local Branches20236
-Ref: your-repo-222057
-Ref: Local Branches-Footnote-123143
-Node: Branches are state23201
-Node: Repo State23936
-Node: Local State26120
-Node: Remotes26788
-Node: Configuring git28145
-Ref: Configuring git-Footnote-130555
-Node: Development without commit access30726
-Node: Cloning31786
-Ref: Cloning-Footnote-133351
-Node: Switching Branches33418
-Node: Starting A New Branch34052
-Ref: Starting A New Branch-Footnote-136036
-Ref: Starting A New Branch-Footnote-236096
-Node: Undoing a change36178
-Node: Saving Without Committing36802
-Node: Updating38386
-Node: Rebasing38901
-Node: Merge Conflicts39523
-Node: Submitting Changes41800
-Ref: Submitting Changes-Footnote-144271
-Ref: Submitting Changes-Footnote-244310
-Ref: Submitting Changes-Footnote-344346
-Node: Removing Branches44394
-Node: Points to remember44930
-Node: Development with commit access46639
-Node: Initial setup47292
-Node: ssh clone48096
-Node: Developing patches48686
-Node: Developing new features50110
-Node: Developing fixes52022
-Node: General practices53113
-Node: Repo Maintenance57946
-Ref: Repo Maintenance-Footnote-160857
-Node: Development Stuff60993
-Node: Coding style61562
-Ref: Coding style-Footnote-162224
-Node: Doing paperwork62318
-Node: Tools63117
-Node: GNU Tools63707
-Node: Compilers65940
-Ref: Compilers-Footnote-168620
-Node: Debugging68658
-Node: Cheat Sheet69469
-Node: Resources73576
-Node: TODO74161
-Node: Index74383
+Node: Top1148
+Node: Preface5273
+Node: Intended Audience5842
+Node: This Manual6724
+Node: Conventions8277
+Node: Acknowledgments9782
+Node: Reviewers10219
+Node: Contributing10540
+Node: Using Git13964
+Node: Push Pull14720
+Node: Repo Copies16277
+Ref: savannah-repo17284
+Ref: your-repo18338
+Ref: Repo Copies-Footnote-120052
+Node: Local Branches20109
+Ref: your-repo-221926
+Ref: Local Branches-Footnote-123011
+Node: Branches are state23069
+Node: Repo State23800
+Node: Local State25984
+Node: Remotes26648
+Node: Configuring git27999
+Ref: Configuring git-Footnote-130397
+Node: Development without commit access30566
+Node: Cloning31626
+Ref: Cloning-Footnote-133189
+Node: Switching Branches33256
+Node: Starting A New Branch33884
+Ref: Starting A New Branch-Footnote-135858
+Ref: Starting A New Branch-Footnote-235916
+Node: Undoing a change35996
+Node: Saving Without Committing36620
+Node: Updating38198
+Node: Rebasing38713
+Node: Merge Conflicts39335
+Node: Submitting Changes41610
+Ref: Submitting Changes-Footnote-144069
+Ref: Submitting Changes-Footnote-244106
+Ref: Submitting Changes-Footnote-344142
+Node: Removing Branches44188
+Node: Points to remember44724
+Node: Development with commit access46429
+Node: Initial setup47082
+Node: ssh clone47878
+Node: Developing patches48468
+Node: Developing new features49884
+Node: Developing fixes51796
+Node: General practices52883
+Node: Repo Maintenance57690
+Ref: Repo Maintenance-Footnote-160585
+Node: Development Stuff60721
+Node: Coding style61288
+Ref: Coding style-Footnote-161950
+Node: Doing paperwork62040
+Node: Tools62839
+Node: GNU Tools63429
+Node: Compilers65662
+Ref: Compilers-Footnote-168328
+Node: Debugging68366
+Node: Cheat Sheet69177
+Node: Resources73266
+Node: TODO73851
+Node: Index74073
End Tag Table
diff --git a/doc/pm-gawk.info b/doc/pm-gawk.info
index fa186620..c08c5b46 100644
--- a/doc/pm-gawk.info
+++ b/doc/pm-gawk.info
@@ -1,4 +1,4 @@
-This is pm-gawk.info, produced by makeinfo version 7.0.1 from
+This is pm-gawk.info, produced by makeinfo version 7.1 from
pm-gawk.texi.
Copyright © 2022 Terence Kelly
@@ -11,7 +11,7 @@ Copyright © 2022 Terence Kelly
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
-Invariant Sections being âIntroductionâ and âHistoryâ, no Front-Cover
+Invariant Sections being "Introduction" and "History", no Front-Cover
Texts, and no Back-Cover Texts. A copy of the license is available at
<https://www.gnu.org/licenses/fdl-1.3.html>
INFO-DIR-SECTION Text creation and manipulation
@@ -25,7 +25,7 @@ File: pm-gawk.info, Node: Top, Next: Introduction, Up:
(dir)
General Introduction
********************
-âgawkâ 5.2 introduces a _persistent memory_ feature that can ârememberâ
+âgawkâ 5.2 introduces a _persistent memory_ feature that can "remember"
script-defined variables and functions across executions; pass variables
between unrelated scripts without serializing/parsing text files; and
handle data sets larger than available memory plus swap. This
@@ -42,7 +42,7 @@ Copyright © 2022 Terence Kelly
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
-Invariant Sections being âIntroductionâ and âHistoryâ, no Front-Cover
+Invariant Sections being "Introduction" and "History", no Front-Cover
Texts, and no Back-Cover Texts. A copy of the license is available at
<https://www.gnu.org/licenses/fdl-1.3.html>
@@ -67,10 +67,10 @@ File: pm-gawk.info, Node: Introduction, Next: Quick
Start, Prev: Top, Up: To
GNU AWK (âgawkâ) 5.2, expected in September 2022, introduces a new
_persistent memory_ feature that makes AWK scripting easier and
-sometimes improves performance. The new feature, called âpm-âgawkâ,â
-can ârememberâ script-defined variables and functions across executions
+sometimes improves performance. The new feature, called "pm-âgawkâ,"
+can "remember" script-defined variables and functions across executions
and can pass variables and functions between unrelated scripts without
-serializing/parsing text filesâall with near-zero fuss. pm-âgawkâ does
+serializing/parsing text files--all with near-zero fuss. pm-âgawkâ does
_not_ require non-volatile memory hardware nor any other exotic
infrastructure; it runs on the ordinary conventional computers and
operating systems that most of us have been using for decades.
@@ -79,7 +79,7 @@ operating systems that most of us have been using for decades.
The main âgawkâ documentation(1) covers the basics of the new
persistence feature. This supplementary manual provides additional
detail, tutorial examples, and a peek under the hood of pm-âgawkâ. If
-youâre familiar with âgawkâ and Unix-like environments, dive straight
+you're familiar with âgawkâ and Unix-like environments, dive straight
in:
⢠*note Quick Start:: hits the ground running with a few keystrokes.
@@ -91,11 +91,11 @@ in:
⢠*note Acknowledgments:: thanks those who made pm-âgawkâ happen.
⢠*note Installation:: shows where obtain pm-âgawkâ.
⢠*note Debugging:: explains how to handle suspected bugs.
- ⢠*note History:: traces pm-âgawkââs persistence technology.
+ ⢠*note History:: traces pm-âgawkâ's persistence technology.
-You can find the latest version of this manual, and also the âdirectorâs
-cut,â at the web site for the persistent memory allocator used in
+You can find the latest version of this manual, and also the "director's
+cut," at the web site for the persistent memory allocator used in
pm-âgawkâ:
<http://web.eecs.umich.edu/~tpkelly/pma/>
@@ -125,7 +125,7 @@ File: pm-gawk.info, Node: Quick Start, Next: Examples,
Prev: Introduction, U
2 Quick Start
*************
-Hereâs pm-âgawkâ in action at the âbashâ shell prompt (â$â):
+Here's pm-âgawkâ in action at the âbashâ shell prompt (â$â):
$ truncate -s 4096000 heap.pma
$ export GAWK_PERSIST_FILE=heap.pma
$ gawk 'BEGIN{myvar = 47}'
@@ -140,17 +140,17 @@ one-line AWK script that initializes variable
âmyvarâ, which will reside
in the heap file and thereby outlive the interpreter process that
initialized it. Finally, the fourth command invokes pm-âgawkâ on a
_different_ one-line script that increments and prints âmyvarâ. The
-output shows that pm-âgawkâ has indeed ârememberedâ âmyvarâ across
+output shows that pm-âgawkâ has indeed "remembered" âmyvarâ across
executions of unrelated scripts. (If the âgawkâ executable in your
search â$PATHâ lacks the persistence feature, the output in the above
example will be â7â instead of â54â. *Note Installation::.) To
disable
persistence until you want it again, prevent âgawkâ from finding the
-heap file via âunset GAWK_PERSIST_FILEâ. To permanently âforgetâ
script
+heap file via âunset GAWK_PERSIST_FILEâ. To permanently "forget" script
variables, delete the heap file.
- Toggling persistence by âexportâ-ing and âunsetâ-ing âambientâ
envars
+ Toggling persistence by âexportâ-ing and âunsetâ-ing "ambient"
envars
requires care: Forgetting to âunsetâ when you no longer want persistence
can cause confusing bugs. Fortunately, âbashâ allows you to pass envars
more deliberately, on a per-command basis:
@@ -186,7 +186,7 @@ File: pm-gawk.info, Node: Examples, Next: Performance,
Prev: Quick Start, Up
**********
Our first example uses pm-âgawkâ to streamline analysis of a prose
-corpus, Mark Twainâs âTom Sawyerâ and âHuckleberry Finnâ from
+corpus, Mark Twain's âTom Sawyerâ and âHuckleberry Finnâ from
<https://gutenberg.org/files/74/74-0.txt> and
<https://gutenberg.org/files/76/76-0.txt>. We first convert
non-alphabetic characters to newlines (so each line has at most one
@@ -194,10 +194,10 @@ word) and convert to lowercase:
$ tr -c a-zA-Z '\n' < 74-0.txt | tr A-Z a-z > sawyer.txt
$ tr -c a-zA-Z '\n' < 76-0.txt | tr A-Z a-z > finn.txt
- Itâs easy to count word frequencies with AWKâs associative arrays.
+ It's easy to count word frequencies with AWK's associative arrays.
pm-âgawkâ makes these arrays persistent, so we need not re-ingest the
-entire corpus every time we ask a new question (âread once, analyze
-happily ever afterâ):
+entire corpus every time we ask a new question ("read once, analyze
+happily ever after"):
$ truncate -s 100M twain.pma
$ export GAWK_PERSIST_FILE=twain.pma
$ gawk '{ts[$1]++}' sawyer.txt # ingest
@@ -207,46 +207,46 @@ happily ever afterâ):
2 27
The âtruncateâ command above creates a heap file large enough to store
all of the data it must eventually contain, with plenty of room to
-spare. (As weâll see in *note Sparse Heap Files::, this isnât
+spare. (As we'll see in *note Sparse Heap Files::, this isn't
wasteful.) The âexportâ command ensures that subsequent âgawkâ
invocations activate pm-âgawkâ. The first pm-âgawkâ command stores
âTom
-Sawyerââs word frequencies in associative array âts[]â. Because this
+Sawyerâ's word frequencies in associative array âts[]â. Because this
array is persistent, subsequent pm-âgawkâ commands can access it without
having to parse the input file again.
- Expanding our analysis to encompass a second book is easy. Letâs
+ Expanding our analysis to encompass a second book is easy. Let's
populate a new associative array âhf[]â with the word frequencies in
âHuckleberry Finnâ:
$ gawk '{hf[$1]++}' finn.txt
-Now we can freely intermix accesses to both booksâ data conveniently and
+Now we can freely intermix accesses to both books' data conveniently and
efficiently, without the overhead and coding fuss of repeated input
parsing:
$ gawk 'BEGIN{print ts["river"], hf["river"]}'
26 142
By making AWK more interactive, pm-âgawkâ invites casual
-conversations with data. If weâre curious what words in âFinnâ are
-absent from âSawyerâ, answers (including âflapdoodle,â
âyellocution,â
-and âsockdolagerâ) are easy to find:
+conversations with data. If we're curious what words in âFinnâ are
+absent from âSawyerâ, answers (including "flapdoodle," "yellocution,"
+and "sockdolager") are easy to find:
$ gawk 'BEGIN{for(w in hf) if (!(w in ts)) print w}'
- Rumors of Twainâs death may be exaggerated. If he publishes new
+ Rumors of Twain's death may be exaggerated. If he publishes new
books in the future, it will be easy to incorporate them into our
analysis incrementally. The performance benefits of incremental
processing for common AWK chores such as log file analysis are discussed
in <https://queue.acm.org/detail.cfm?id=3534855> and the companion paper
cited therein, and below in *note Performance::.
- Exercise: The âMarkovâ AWK script on page 79 of Kernighan & Pikeâs
+ Exercise: The "Markov" AWK script on page 79 of Kernighan & Pike's
âThe Practice of Programmingâ generates random text reminiscent of a
given corpus using a simple statistical modeling technique. This script
-consists of a âlearningâ or âtrainingâ phase followed by an
+consists of a "learning" or "training" phase followed by an
output-generation phase. Use pm-âgawkâ to de-couple the two phases and
to allow the statistical model to incrementally ingest additions to the
input corpus.
- Our second example considers another domain that plays to AWKâs
-strengths, data analysis. For simplicity weâll create two small input
+ Our second example considers another domain that plays to AWK's
+strengths, data analysis. For simplicity we'll create two small input
files of numeric data.
$ printf '1\n2\n3\n4\n5\n' > A.dat
$ printf '5\n6\n7\n8\n9\n' > B.dat
@@ -272,8 +272,8 @@ pm-âgawkâ requires changing the above script to ensure
that âminâ and
and _not_ every time the script runs. Furthermore, whereas
script-defined variables such as âminâ retain their values across
pm-âgawkâ executions, built-in AWK variables such as âNRâ are reset to
-zero every time pm-âgawkâ runs, so we canât use them in the same way.
-Hereâs a modified script for pm-âgawkâ:
+zero every time pm-âgawkâ runs, so we can't use them in the same way.
+Here's a modified script for pm-âgawkâ:
$ cat summary_persistent.awk
! init { min = max = $1; init = 1 }
min > $1 { min = $1 }
@@ -371,8 +371,9 @@ This chapter explains several performance advantages that
result from
the implementation of persistent memory in pm-âgawkâ, shows how tuning
the underlying operating system sometimes improves performance, and
presents experimental performance measurements. To make the discussion
-concrete, we use examples from a GNU/Linux systemâGNU utilities atop the
-Linux OSâbut the principles apply to other modern operating systems.
+concrete, we use examples from a GNU/Linux system--GNU utilities atop
+the Linux OS--but the principles apply to other modern operating
+systems.
* Menu:
@@ -392,11 +393,11 @@ File: pm-gawk.info, Node: Constant-Time Array Access,
Next: Virtual Memory and
pm-âgawkâ preserves the efficiency of data access when data structures
are created by one process and later re-used by a different process.
- Consider the associative arrays used to analyze Mark Twainâs books in
+ Consider the associative arrays used to analyze Mark Twain's books in
*note Examples::. We created arrays âts[]â and âhf[]â by reading files
âsawyer.txtâ and âfinn.txtâ. If N denotes the total volume of data in
these files, building the associative arrays typically requires time
-proportional to N, or âO(N) expected timeâ in the lingo of asymptotic
+proportional to N, or "O(N) expected time" in the lingo of asymptotic
analysis. If W is the number of unique words in the input files, the
size of the associative arrays will be proportional to W, or O(W).
Accessing individual array elements requires only _constant_ or O(1)
@@ -410,11 +411,11 @@ earlier in BEGIN{print ts["river"], hf["river"]}, still
requires only
O(1) time, which is asymptotically far superior to the alternatives.
Naïvely reconstructing arrays by re-ingesting all raw inputs in every
âgawkâ process that accesses the arrays would of course require O(N)
-timeâa profligate cost if the text corpus is large. Dumping arrays to
+time--a profligate cost if the text corpus is large. Dumping arrays to
files and re-loading them as needed would reduce the preparation time
for access to O(W). That can be a substantial improvement in practice; N
is roughly 19 times larger than W in our Twain corpus. Nonetheless O(W)
-remains far slower than pm-âgawkââs O(1). As weâll see in *note
+remains far slower than pm-âgawkâ's O(1). As we'll see in *note
Results::, the difference is not merely theoretical.
The persistent memory implementation beneath pm-âgawkâ enables it to
@@ -427,8 +428,8 @@ lookup on the corresponding hash table, which in turn
accesses memory on
the persistent heap. Modern operating systems implement memory-mapped
files in such a way that these memory accesses trigger the bare minimum
of data movement required: Only those parts of the heap file containing
-needed data are âpaged inâ to the memory of the pm-âgawkâ process. In
-the worst case, the heap file is not in the file systemâs in-memory
+needed data are "paged in" to the memory of the pm-âgawkâ process. In
+the worst case, the heap file is not in the file system's in-memory
cache, so the required pages must be faulted into memory from storage.
Our asymptotic analysis of efficiency applies regardless of whether the
heap file is cached or not. The entire heap file is _not_ accessed
@@ -448,7 +449,7 @@ File: pm-gawk.info, Node: Virtual Memory and Big Data,
Next: Sparse Heap Files
Small data sets seldom spoil the delights of AWK by causing performance
troubles, with or without persistence. As the size of the âgawkâ
-interpreterâs internal data structures approaches the capacity of
+interpreter's internal data structures approaches the capacity of
physical memory, however, acceptable performance requires understanding
modern operating systems and sometimes tuning them. Fortunately
pm-âgawkâ offers new degrees of control for performance-conscious users
@@ -458,18 +459,18 @@ perplexity.
Modern operating systems feature âvirtual memoryâ that strives to
appear both larger than installed DRAM (which is small) and faster than
-installed storage devices (which are slow). As a programâs memory
+installed storage devices (which are slow). As a program's memory
footprint approaches the capacity of DRAM, the virtual memory system
-transparently âpagesâ (moves) the programâs data between DRAM and a
+transparently âpagesâ (moves) the program's data between DRAM and a
âswap areaâ on a storage device. Paging can degrade performance mildly
-or severely, depending on the programâs memory access patterns. Random
+or severely, depending on the program's memory access patterns. Random
accesses to large data structures can trigger excessive paging and
-dramatic slowdown. Unfortunately, the hash tables beneath AWKâs
+dramatic slowdown. Unfortunately, the hash tables beneath AWK's
signature associative arrays inherently require random memory accesses,
so large associative arrays can be problematic.
Persistence changes the rules in our favor: The OS pages data to
-pm-âgawkââs _heap file_ instead of the swap area. This wonât help
+pm-âgawkâ's _heap file_ instead of the swap area. This won't help
performance much if the heap file resides in a conventional
storage-backed file system. On Unix-like systems, however, we may place
the heap file in a DRAM-backed file system such as â/dev/shm/â, which
@@ -478,18 +479,18 @@ the heap file in such a file system is a reasonable
expedient, with two
caveats: First, keep in mind that DRAM-backed file systems perish when
the machine reboots or crashes, so you must copy the heap file to a
conventional storage-backed file system when your computation is done.
-Second, pm-âgawkââs memory footprint canât exceed available DRAM if you
+Second, pm-âgawkâ's memory footprint can't exceed available DRAM if you
place the heap file in a DRAM-backed file system.
Tuning OS paging parameters may improve performance if you decide to
run pm-âgawkâ with a heap file in a conventional storage-backed file
system. Some OSes have unhelpful default habits regarding modified
-(âdirtyâ) memory backed by files. For example, the OS may write dirty
+("dirty") memory backed by files. For example, the OS may write dirty
memory pages to the heap file periodically and/or when the OS believes
-that âtoo muchâ memory is dirty. Such âeagerâ writeback can degrade
+that "too much" memory is dirty. Such "eager" writeback can degrade
performance noticeably and brings no benefit to pm-âgawkâ. Fortunately
some OSes allow paging defaults to be over-ridden so that writeback is
-âlazyâ rather than eager. For Linux see the discussion of the
âdirty_*â
+"lazy" rather than eager. For Linux see the discussion of the âdirty_*â
parameters at
<https://www.kernel.org/doc/html/latest/admin-guide/sysctl/vm.html>.
Changing these parameters can prevent wasteful eager paging:(1)
@@ -512,22 +513,22 @@ File: pm-gawk.info, Node: Sparse Heap Files, Next:
Persistence versus Durabili
4.3 Sparse Heap Files
=====================
-To be frugal with storage resources, pm-âgawkââs heap file should be
+To be frugal with storage resources, pm-âgawkâ's heap file should be
created as a âsparse fileâ: a file whose logical size is larger than its
storage resource footprint. Modern file systems support sparse files,
which are easy to create using the âtruncateâ tool shown in our
examples.
- Letâs first create a conventional _non_-sparse file using âechoâ:
+ Let's first create a conventional _non_-sparse file using âechoâ:
$ echo hi > dense
$ ls -l dense
-rw-rw-r--. 1 me me 3 Aug 5 23:08 dense
$ du -h dense
4.0K dense
The âlsâ utility reports that file âdenseâ is three bytes long (two for
-the letters in âhiâ plus one for the newline). The âduâ utility
reports
-that this file consumes 4 KiB of storageâone block of disk, as small as
-a non-sparse fileâs storage footprint can be. Now letâs use âtruncateâ
+the letters in "hi" plus one for the newline). The âduâ utility reports
+that this file consumes 4 KiB of storage--one block of disk, as small as
+a non-sparse file's storage footprint can be. Now let's use âtruncateâ
to create a logically enormous sparse file and check its physical size:
$ truncate -s 1T sparse
$ ls -l sparse
@@ -540,26 +541,26 @@ storage whatsoever. The file system will allocate
physical storage
resources beneath this file as data is written to it; reading unwritten
regions of the file yields zeros.
- The âpay as you goâ storage cost of sparse files offers both
+ The "pay as you go" storage cost of sparse files offers both
convenience and control for pm-âgawkâ users. If your file system
supports sparse files, go ahead and create lavishly capacious heap files
for pm-âgawkâ. Their logical size costs nothing and persistent memory
-allocation within pm-âgawkâ wonât fail until physical storage resources
+allocation within pm-âgawkâ won't fail until physical storage resources
beneath the file system are exhausted. But if instead you want to
_prevent_ a heap file from consuming too much storage, simply set its
-initial size to whatever bound you wish to enforce; it wonât eat more
+initial size to whatever bound you wish to enforce; it won't eat more
disk than that. Copying sparse files with GNU âcpâ creates sparse
copies by default.
File-system encryption can preclude sparse files: If the cleartext of
a byte offset range within a file is all zero bytes, the corresponding
-ciphertext probably shouldnât be all zeros! Encrypting at the storage
+ciphertext probably shouldn't be all zeros! Encrypting at the storage
layer instead of the file system layer may offer acceptable security
while still permitting file systems to implement sparse files.
Sometimes you might prefer a dense heap file backed by pre-allocated
storage resources, for example to increase the likelihood that
-pm-âgawkââs internal memory allocation will succeed until the persistent
+pm-âgawkâ's internal memory allocation will succeed until the persistent
heap occupies the entire heap file. The âfallocateâ utility will do the
trick:
$ fallocate -l 1M mibi
@@ -576,12 +577,12 @@ File: pm-gawk.info, Node: Persistence versus Durability,
Next: Experiments, P
=================================
Arguably the most important general guideline for good performance in
-computer systems is, âpay only for what you need.â(1) To apply this
+computer systems is, "pay only for what you need."(1) To apply this
maxim to pm-âgawkâ we must distinguish two concepts that are frequently
conflated: persistence and durability.(2) (A third logically distinct
concept is the subject of *note Data Integrity::.)
- âPersistentâ data outlive the processes that access them, but donât
+ âPersistentâ data outlive the processes that access them, but don't
necessarily last forever. For example, as explained in âman
mq_overviewâ, message queues are persistent because they exist until the
system shuts down. âDurableâ data reside on a physical medium that
@@ -599,7 +600,7 @@ systems such as â/dev/shm/â are persistent but not
durable.
performance-conscious pm-âgawkâ users pay the added premium for
durability only when persistence alone is not sufficient. Two ways to
avoid unwanted durability overheads were discussed in *note Virtual
-Memory and Big Data::: Place pm-âgawkââs heap file in a DRAM-backed file
+Memory and Big Data::: Place pm-âgawkâ's heap file in a DRAM-backed file
system, or disable eager writeback to the heap file. Expedients such as
these enable you to remove durability overheads from the critical path
of multi-stage data analyses even when you want heap files to eventually
@@ -614,14 +615,14 @@ AWK or C program to generate a stream of random text, or
just cobble
together a quick and dirty generator on the command line:
$ openssl rand --base64 1000000 | tr -c a-zA-Z '\n' > random.dat
Varying the size of random inputs can, for example, find where
-performance âfalls off the cliffâ as pm-âgawkââs memory footprint
+performance "falls off the cliff" as pm-âgawkâ's memory footprint
exceeds the capacity of DRAM and paging begins.
Experiments require careful methodology, especially when the heap
-file is in a storage-backed file system. Overlooking the file systemâs
+file is in a storage-backed file system. Overlooking the file system's
DRAM cache can easily misguide interpretation of results and foil
repeatability. Fortunately Linux allows us to invalidate the file
-system cache and thus mimic a âcold startâ condition resembling the
+system cache and thus mimic a "cold start" condition resembling the
immediate aftermath of a machine reboot. Accesses to ordinary files on
durable storage will then be served from the storage devices, not from
cache. Read about âsyncâ and â/proc/sys/vm/drop_cachesâ at
@@ -634,11 +635,11 @@ Certain well-known textbook algorithms continue to grind
away
fruitlessly long after having computed all of their output.
See <https://queue.acm.org/detail.cfm?id=3424304>.
- (2) In recent years the term âpersistent memoryâ has sometimes been
-used to denote novel byte-addressable non-volatile memory hardwareâan
+ (2) In recent years the term "persistent memory" has sometimes been
+used to denote novel byte-addressable non-volatile memory hardware--an
unfortunate practice that contradicts sensible long-standing convention
and causes needless confusion. NVM provides durability. Persistent
-memory is a software abstraction that doesnât require NVM. See
+memory is a software abstraction that doesn't require NVM. See
<https://queue.acm.org/detail.cfm?id=3358957>.
@@ -657,31 +658,31 @@ from <http://web.eecs.umich.edu/~tpkelly/pma/>.
word frequency queries over a text corpus: The naïve approach of reading
the corpus into an associative array for every query; manually dumping a
text representation of the word-frequency table and manually loading it
-prior to a query; using âgawkââs ârwarrayâ extension to dump and
load an
+prior to a query; using âgawkâ's ârwarrayâ extension to dump and load
an
associative array; and using pm-âgawkâ to maintain a persistent
associative array.
- Comments at the top explain prerequisites. Lines 8â10 set input
+ Comments at the top explain prerequisites. Lines 8-10 set input
parameters: the directory where tests are run and where files including
the heap file are held, the off-the-shelf timer used to measure run
times and other performance characteristics such as peak memory usage,
and the size of the input. The default input size results in pm-âgawkâ
memory footprints under 3 GiB, which is large enough for interesting
-results and small enough to fit in DRAM and avoid paging on todayâs
-computers. Lines 13â14 define a homebrew timer.
+results and small enough to fit in DRAM and avoid paging on today's
+computers. Lines 13-14 define a homebrew timer.
Two sections of the script are relevant if the default run directory
is changed from â/dev/shm/â to a directory in a conventional
-storage-backed file system: Lines 15â17 define the mechanism for
-clearing file data cached in DRAM; lines 23â30 set Linux kernel
+storage-backed file system: Lines 15-17 define the mechanism for
+clearing file data cached in DRAM; lines 23-30 set Linux kernel
parameters to discourage eager paging.
- Lines 37â70 spit out, compile, and run a little C program to generate
+ Lines 37-70 spit out, compile, and run a little C program to generate
a random text corpus. This program is fast, flexible, and
deterministic, generating the same random output given the same
parameters.
- Lines 71â100 run the four different AWK approaches on the same random
+ Lines 71-100 run the four different AWK approaches on the same random
input, reporting separately the time to build and to query the
associative array containing word frequencies.
@@ -807,7 +808,7 @@ results. Keep in mind that performance measurements are
often sensitive
to seemingly irrelevant factors. For example, the program that runs
first may have the advantage of a cooler CPU; later contestants may
start with a hot CPU and consequent clock throttling by a modern
-processorâs thermal regulation apparatus. Very generally, performance
+processor's thermal regulation apparatus. Very generally, performance
measurement is a notoriously tricky business. For scripting, whose main
motive is convenience rather than speed, the proper role for performance
measurements is to qualitatively test hypotheses such as those that
@@ -836,28 +837,28 @@ The âfreqtblâ and ârwarrayâ approaches build an
associative array of
word frequencies, serialize it to an intermediate file, and then read
the entire intermediate file prior to serving queries; the former does
this manually and the latter uses a âgawkâ extension. Both can serve
-queries in roughly ten seconds, not four minutes. As weâd expect from
+queries in roughly ten seconds, not four minutes. As we'd expect from
the asymptotic analysis, performing work proportional to the number of
words is preferable to work proportional to the size of the raw input
-corpus: O(W) time is faster than O(N). And as weâd expect, pm-âgawkââs
+corpus: O(W) time is faster than O(N). And as we'd expect, pm-âgawkâ's
constant-time queries are faster still, by roughly two orders of
magnitude. For the computations considered here, pm-âgawkâ makes the
difference between blink-of-an-eye interactive queries and response
-times long enough for the userâs mind to wander.
+times long enough for the user's mind to wander.
Whereas âfreqtblâ and ârwarrayâ reconstruct an associative array
prior to accessing an individual element, pm-âgawkâ stores a ready-made
-associative array in persistent memory. Thatâs why its intermediate
+associative array in persistent memory. That's why its intermediate
file (the heap file) is much larger than the other two intermediate
-files, why the heap file is nearly as large as pm-âgawkââs peak memory
+files, why the heap file is nearly as large as pm-âgawkâ's peak memory
footprint while building the persistent array, and why its memory
footprint is very small while serving a query that accesses a single
array element. The upside of the large heap file is O(1) access instead
-of O(W)âa classic time-space tradeoff. If storage is a scarce resource,
-all three intermediate files can be compressed, âfreqtblâ by a factor of
-roughly 2.7, ârwarrayâ by roughly 5.6x, and pm-âgawkâ by roughly 11x
-using âxzâ. Compression is CPU-intensive and slow, another time-space
-tradeoff.
+of O(W)--a classic time-space tradeoff. If storage is a scarce
+resource, all three intermediate files can be compressed, âfreqtblâ by a
+factor of roughly 2.7, ârwarrayâ by roughly 5.6x, and pm-âgawkâ by
+roughly 11x using âxzâ. Compression is CPU-intensive and slow, another
+time-space tradeoff.
File: pm-gawk.info, Node: Data Integrity, Next: Acknowledgments, Prev:
Performance, Up: Top
@@ -870,7 +871,7 @@ command-line typos can harm your data, but precautions can
mitigate
these risks. In scripting scenarios it usually suffices to create safe
backups of important files at appropriate times. As simple as this
sounds, care is needed to achieve genuine protection and to reduce the
-costs of backups. Hereâs a prudent yet frugal way to back up a heap
+costs of backups. Here's a prudent yet frugal way to back up a heap
file between uses:
$ backup_base=heap_bk_`date +%s`
$ cp --reflink=always heap.pma $backup_base.pma
@@ -887,30 +888,30 @@ Timestamps in backup filenames make it easy to find the
most recent copy
if the heap file is damaged, even if last-mod metadata are inadvertently
altered.
- The âcpâ commandâs â--reflinkâ option reduces both the storage
+ The âcpâ command's â--reflinkâ option reduces both the storage
footprint of the copy and the time required to make it. Just as sparse
-files provide âpay as you goâ storage footprints, reflink copying offers
-âpay as you _change_â storage costs.(1) A reflink copy shares storage
+files provide "pay as you go" storage footprints, reflink copying offers
+"pay as you _change_" storage costs.(1) A reflink copy shares storage
with the original file. The file system ensures that subsequent changes
-to either file donât affect the other. Reflink copying is not available
+to either file don't affect the other. Reflink copying is not available
on all file systems; XFS, BtrFS, and OCFS2 currently support it.(2)
Fortunately you can install, say, an XFS file system _inside an ordinary
file_ on some other file system, such as âext4â.(3)
After creating a backup copy of the heap file we use âsyncâ to force
it down to durable media. Otherwise the copy may reside only in
-volatile DRAM memoryâthe file systemâs cacheâwhere an OS crash or power
-failure could corrupt it.(4) After âsyncâ-ing the backup we create and
-âsyncâ a âsuccess indicatorâ file with extension â.doneâ to
address a
-nasty corner case: Power may fail _while_ a backup is being copied from
-the primary heap file, leaving either file, or both, corrupt on
-storageâa particularly worrisome possibility for jobs that run
+volatile DRAM memory--the file system's cache--where an OS crash or
+power failure could corrupt it.(4) After âsyncâ-ing the backup we
+create and âsyncâ a "success indicator" file with extension â.doneâ to
+address a nasty corner case: Power may fail _while_ a backup is being
+copied from the primary heap file, leaving either file, or both, corrupt
+on storage--a particularly worrisome possibility for jobs that run
unattended. Upon reboot, each â.doneâ file attests that the
corresponding backup succeeded, making it easy to identify the most
recent successful backup.
- Finally, if youâre serious about tolerating failures you must âtrain
-as you would fightâ by testing your hardware/software stack against
+ Finally, if you're serious about tolerating failures you must "train
+as you would fight" by testing your hardware/software stack against
realistic failures. For realistic power-failure testing, see
<https://queue.acm.org/detail.cfm?id=3400902>.
@@ -929,7 +930,7 @@ If reflink copying is not available, â--sparse=alwaysâ
should be used.
âsyncâ returns only after all file system data are flushed down to
durable storage. If your âsyncâ is unreliable, write a little C program
that calls âfsync()â to flush a file. To be safe, also call âfsync()â
-on every enclosing directory on the fileâs ârealpath()â up to the root.
+on every enclosing directory on the file's ârealpath()â up to the root.
File: pm-gawk.info, Node: Acknowledgments, Next: Installation, Prev: Data
Integrity, Up: Top
@@ -948,7 +949,7 @@ Cygwin. Nelson H. F. Beebe provided access to Solaris
machines for
testing. Robbins, Volos, Li, Tan, Jon Bentley, and Hans Boehm reviewed
drafts of this user manual and provided useful feedback. Bentley
suggested the min/max/mean example in *note Examples::, and also the
-exercise of making Kernighan & Pikeâs âMarkovâ script persistent. Volos
+exercise of making Kernighan & Pike's "Markov" script persistent. Volos
provided and tested the advice on tuning OS parameters in *note Virtual
Memory and Big Data::. Stan Park provided insights about virtual
memory, file systems, and utilities.
@@ -980,11 +981,11 @@ For bugs unrelated to persistence, see the âgawkâ
documentation, e.g.,
âGAWK: Effective AWK Programmingâ, available at
<https://www.gnu.org/software/gawk/manual/>.
- If pm-âgawkâ doesnât behave as you expect, first consider whether
-youâre using the heap file that you intend; using the wrong heap file is
+ If pm-âgawkâ doesn't behave as you expect, first consider whether
+you're using the heap file that you intend; using the wrong heap file is
a common mistake. Other fertile sources of bugs for newcomers are the
fact that a âBEGINâ block is executed every time pm-âgawkâ runs, which
-isnât always what you really want, and the fact that built-in AWK
+isn't always what you really want, and the fact that built-in AWK
variables such as âNRâ are always reset to zero every time the
interpreter runs. See the discussion of initialization surrounding the
min/max/mean script in *note Examples::.
@@ -1001,7 +1002,7 @@ will trigger extensive integrity checks within âpmaâ.
Ensure that
integrity checks can be very slow. If assertions fail, that likely
indicates bugs somewhere in pm-âgawkâ. Report such bugs to me (Terence
Kelly) and also following the procedures in the main âgawkâ
-documentation. Specify what version of âgawkâ youâre using, and try to
+documentation. Specify what version of âgawkâ you're using, and try to
provide a small and simple script that reliably reproduces the bug.
@@ -1026,24 +1027,24 @@ began to connect the dots that make persistent
scripting possible, and a
further decade would pass before pm-âgawkâ came together.
Circa 2011 while working at HP Labs I developed a fault-tolerant
-distributed computing platform called âKen,â which contained a
+distributed computing platform called "Ken," which contained a
persistent memory allocator that resembles a simplified âpmaâ: It
presented a âmalloc()â-like C interface and it allocated memory from a
file-backed memory mapping. Experience with Ken convinced me that the
software abstraction of persistent memory offers important attractions
compared with the alternatives for managing persistent data (e.g.,
-relational databases and key-value stores). Unfortunately, Kenâs
-allocator is so deeply intertwined with the rest of Ken that itâs
-essentially inseparable; to enjoy the benefits of Kenâs persistent
-memory, one must âbuy inâ to a larger and more complicated value
-proposition. Whatever its other virtues might be, Ken isnât ideal for
+relational databases and key-value stores). Unfortunately, Ken's
+allocator is so deeply intertwined with the rest of Ken that it's
+essentially inseparable; to enjoy the benefits of Ken's persistent
+memory, one must "buy in" to a larger and more complicated value
+proposition. Whatever its other virtues might be, Ken isn't ideal for
showcasing the benefits of persistent memory in isolation.
Another entangled aspect of Ken was a crash-tolerance mechanism that,
in retrospect, can be viewed as a user-space implementation of
failure-atomic âmsync()â. The first post-Ken disentanglement effort
isolated the crash-tolerance mechanism and implemented it in the Linux
-kernel, calling the result âfailure-atomic âmsync()ââ (FAMS). FAMS
+kernel, calling the result "failure-atomic âmsync()â" (FAMS). FAMS
strengthens the semantics of ordinary standard âmsync()â by guaranteeing
that the durable state of a memory-mapped file always reflects the most
recent successful âmsync()â call, even in the presence of failures such
@@ -1060,17 +1061,17 @@ ubiquitous GNU âdbmâ (âgdbmâ) database
In recent years my attention has returned to the advantages of
persistent memory programming, lately a hot topic thanks to the
commercial availability of byte-addressable non-volatile memory hardware
-(which, confusingly, is nowadays marketed as âpersistent memoryâ). The
+(which, confusingly, is nowadays marketed as "persistent memory"). The
software abstraction of persistent memory and the corresponding
programming style, however, are perfectly compatible with _conventional_
-computersâmachines with neither non-volatile memory nor any other
+computers--machines with neither non-volatile memory nor any other
special hardware or software. I wrote a few papers making this point,
for example <https://queue.acm.org/detail.cfm?id=3358957>.
In early 2022 I wrote a new stand-alone persistent memory allocator,
âpmaâ, to make persistent memory programming easy on conventional
hardware. The âpmaâ interface is compatible with âmalloc()â and,
unlike
-Kenâs allocator, âpmaâ is not coupled to a particular crash-tolerance
+Ken's allocator, âpmaâ is not coupled to a particular crash-tolerance
mechanism. Using âpmaâ is easy and, at least to some, enjoyable.
Ken had been integrated into prototype forks of both the V8
@@ -1095,43 +1096,43 @@ of the prototype, including performance measurements,
is available at
- I enjoy several aspects of pm-âgawkâ. Itâs unobtrusive; as you gain
+ I enjoy several aspects of pm-âgawkâ. It's unobtrusive; as you gain
familiarity and experience, it fades into the background of your
-scripting. Itâs simple in both concept and implementation, and more
+scripting. It's simple in both concept and implementation, and more
importantly it simplifies your scripts; much of its value is measured
not in the code it enables you to write but rather in the code it lets
-you discard. Itâs all that I needed for my dissertation research twenty
+you discard. It's all that I needed for my dissertation research twenty
years ago, and more. Anecdotally, it appears to inspire creativity in
-early adopters, who have devised uses that pm-âgawkââs designers never
-anticipated. Iâm curious to see what new purposes you find for it.
+early adopters, who have devised uses that pm-âgawkâ's designers never
+anticipated. I'm curious to see what new purposes you find for it.
Tag Table:
-Node: Top815
-Node: Introduction2036
-Ref: Introduction-Footnote-14464
-Node: Quick Start4568
-Node: Examples7485
-Node: Performance16627
-Node: Constant-Time Array Access17337
-Node: Virtual Memory and Big Data20704
-Ref: Virtual Memory and Big Data-Footnote-124341
-Node: Sparse Heap Files24481
-Node: Persistence versus Durability27580
-Ref: Persistence versus Durability-Footnote-131060
-Ref: Persistence versus Durability-Footnote-231306
-Node: Experiments31707
-Node: Results43458
-Node: Data Integrity47097
-Ref: Data Integrity-Footnote-149964
-Ref: Data Integrity-Footnote-250061
-Ref: Data Integrity-Footnote-350213
-Ref: Data Integrity-Footnote-450307
-Node: Acknowledgments50688
-Node: Installation51888
-Node: Debugging52718
-Node: History54467
+Node: Top805
+Node: Introduction2014
+Ref: Introduction-Footnote-14423
+Node: Quick Start4527
+Node: Examples7430
+Node: Performance16514
+Node: Constant-Time Array Access17222
+Node: Virtual Memory and Big Data20572
+Ref: Virtual Memory and Big Data-Footnote-124175
+Node: Sparse Heap Files24315
+Node: Persistence versus Durability27389
+Ref: Persistence versus Durability-Footnote-130850
+Ref: Persistence versus Durability-Footnote-231096
+Node: Experiments31490
+Node: Results43225
+Node: Data Integrity46849
+Ref: Data Integrity-Footnote-149687
+Ref: Data Integrity-Footnote-249784
+Ref: Data Integrity-Footnote-349936
+Ref: Data Integrity-Footnote-450030
+Node: Acknowledgments50409
+Node: Installation51603
+Node: Debugging52433
+Node: History54174
End Tag Table
-----------------------------------------------------------------------
Summary of changes:
doc/gawkworkflow.info | 537 +++++++++++++++++++++++++-------------------------
doc/pm-gawk.info | 295 +++++++++++++--------------
2 files changed, 415 insertions(+), 417 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [SCM] gawk branch, gawk-5.3-stable, updated. gawk-4.1.0-5537-ga3ab843b,
Arnold Robbins <=