refactor(rsync): make engines/rsync.yml readable, no behavior change

CLAUDE.md

@@ -19,11 +19,25 @@ Read that section before you write.
 
 - Do not read a call var in a global var. Task renders a global var that reads a different
   var one time. It uses the values of the root and of the command line, and not a call
-  var. Thus, `GPGCHECK` gets the fingerprint as an awk `-v` in each command that uses it. In
-  that command, the call var `TL_KEY` is available.
+  var. Thus, each program in the `programs` part of `vars:` in `engines/rsync.yml` gets its
+  inputs from awk `-v`, `ENVIRON` or an argument, in the command that uses it. For example,
+  each command that uses `GPGCHECK` gives it the fingerprint as an awk `-v`. In that
+  command, the call var `TL_KEY` is available.
 - Some vars have a different name and read a var that a mirror can set, for example
   `BATCHES_MAX` from `MAX_BATCHES`. Such a var also gets the value on the command line
-  (verified). Thus, write each default one time, inline.
+  (verified). A task var with a different name, for example `BATCH_SIZE` in `split`, also
+  gets a call var (verified: `split-refuses` gives `BATCH_GB` as a call var). A global var
+  does not get a call var. Thus, write each default one time, inline or in a task var.
+- A task `env:` gets the call vars, and the command gets each value with no change
+  (verified, 3.53.1). Thus, the text values of a mirror go to the commands in `env:`, and
+  a quotation mark or a `$` in a value does not change a command. The render shows
+  `"$FRESH_KEY"`, not the value. In awk, read such a value with `ENVIRON`. `awk -v`
+  changes each backslash escape in a value (`\n` becomes a newline), and `ENVIRON` does
+  not. `offline` gives `fresh` a `FRESH_KEY` with a `\n` in its name.
+- A var of the environment wins over a task `env:` with the same name, also an empty var
+  (verified, 3.53.1). Then `{{.FRESH_KEY}}` and `"$FRESH_KEY"` can give two different
+  values in one command. The container gets only the names in `PASS_ENV`, and none of
+  them is a var of the engine. Do not add a var of the engine to `PASS` or to `op.env`.
 - Do not put `dir:` on an engine verb. Task can read a flattened Taskfile of `includes:`
   from a path. In that condition, it adds each `dir:`, also an absolute one, to the
   directory of that Taskfile (verified, 3.53.1). Thus, `verify` starts each command with
@@ -75,9 +89,9 @@ Read that section before you write.
   no key without a slash. Thus, if the only changed directory of a run is the root, that
   awk sends no line to `xargs`.
 - A `>-` folded block keeps a newline if a line that continues the line before it starts
-  with more spaces than the lines around it. The awk programs of `pages` use this. Put a
-  backslash at the end of a shell line that must continue. `task check` shows how the block
-  renders.
+  with more spaces than the lines around it. The two-line awk programs in the commands of
+  `split` and `pages` use this. Put a backslash at the end of a shell line that must
+  continue. `task check` shows how the block renders.
 - On a macOS disk, two directory names that are different only in uppercase and lowercase
   letters are one directory. Thus, the pages that a laptop writes from a listing of
   upstream are not complete if upstream has two such directories. For example, CTAN has
@@ -113,12 +127,13 @@ Read that section before you write.
   encoded first is encoded two times (`a%20b` goes out as `a%2520b`), and the copy then
   reads a different key (verified with `aws --debug`, aws-cli 2.36.24).
 - Increase `PAGE_FORMAT` in `engines/rsync.yml` at each change to the HTML or the style of
-  a directory page. If you do not, each mirror keeps the pages of the directories that do
-  not change, and they show the old format. The stamp in `.state/indexed.txt.xz` includes
-  `PAGE_FORMAT`. A new value makes each mirror write all of its pages again, one time.
-- The page awk of `pages` writes each page directly to its two files. Do not make the page
-  with a string that gets a row at a time. That method copies the full string for each
-  row. The `archive/` directory of TeX Live has approximately 34k rows.
+  a directory page (`PAGE_HTML` and `PAGE_CSS`). If you do not, each mirror keeps the pages
+  of the directories that do not change, and they show the old format. The stamp in
+  `.state/indexed.txt.xz` includes `PAGE_FORMAT`. A new value makes each mirror write all
+  of its pages again, one time.
+- `PAGE_HTML`, the page awk of `pages`, writes each page directly to its two files. Do not
+  make the page with a string that gets a row at a time. That method copies the full string
+  for each row. The `archive/` directory of TeX Live has approximately 34k rows.
 - In a check that reads the output of a task with `grep`, find text that only the output
   has. go-task shows each command before it runs it, and that line also has the text of
   each `echo` in the command. For example, `offline` finds `not 08` in the output of

CONTRIBUTING.md

@@ -5,9 +5,11 @@ are applicable to this repository. This repository adds three rules:
 
 - **Do not put a `vars:` default in `toolbox.yml` or in an engine for a var that a mirror
   sets.** If a `vars:` block has a default, the run uses that default, not the root value
-  of the mirror. Put each default inline in the command: `{{.X | default N}}`. `IMAGE` is
-  different: each engine sets `IMAGE: '{{.IMAGE | default "..."}}'` in `vars:`. Thus, if
-  the toolbox entry of `includes:` gives `IMAGE`, the run uses that value.
+  of the mirror. Put each default inline in the command: `{{.X | default N}}`. If two
+  commands of a verb read the var, put the default in a task var with a different name
+  (`BATCH_SIZE: '{{.BATCH_GB | default 4}}'` in `split`). `IMAGE` is different: each
+  engine sets `IMAGE: '{{.IMAGE | default "..."}}'` in `vars:`. Thus, if the toolbox entry
+  of `includes:` gives `IMAGE`, the run uses that value.
 - **Do not change the name of a verb in `toolbox.yml` or in an engine.** A mirror includes
   these files with `flatten: true`. Then the host verbs and the verbs in the container use
   one namespace.

README.md

@@ -288,8 +288,9 @@ different verb. Thus, the pipeline of a mirror has the same verbs with each engi
 
 An engine reads the root vars of the mirror and the environment. It has no `vars:` default
 for a var that a mirror sets. With such a default, the run uses the default, not the value
-of the mirror. Each var that a mirror can set has its default inline:
-`{{.X | default N}}`.
+of the mirror. Each var that a mirror can set has its default in one location: inline, as
+`{{.X | default N}}`, or in a task var with a different name, for example `BATCH_SIZE` in
+`split`.
 
 `IMAGE` is different. The engine sets it in `vars:` as `{{.IMAGE | default "..."}}`. Thus,
 the run uses an `IMAGE` in the toolbox entry of `includes:`, not the default of the engine.
@@ -603,8 +604,8 @@ A control byte is not a NUL. Thus, a `.sty` file of CTAN with a `^Z` at its end
 
 #### The vars
 
-A mirror always sets `SOURCE`, `BUCKET` and `HOST` in its root vars. All other vars have an
-inline default, and a mirror sets only the vars that are different:
+A mirror always sets `SOURCE`, `BUCKET` and `HOST` in its root vars. All other vars have a
+default in the engine, and a mirror sets only the vars that are different:
 
 | Var | Default | Function |
 |---|---|---|
@@ -1327,7 +1328,9 @@ updates:
 
 Then run `task render-update` one time. Commit `render.txt`. After that, use
 `task check`. If a pull request changes the commands of the mirror, `render.txt` shows a
-diff, and that diff is the review.
+diff, and that diff is the review. The engine gives some text values of the mirror to a
+command in `env:`, for example `FRESH_KEY`. The render shows these values as names
+(`"$FRESH_KEY"`), and the root vars of the Taskfile give the values.
 
 ### Rules a mirror keeps
 
@@ -1386,7 +1389,20 @@ these rules:
 
 - A new hook is an empty task, with a `desc` that gives the mirror that fills it. The verb that runs the hook gives it the vars that it uses.
 - A new var that a mirror can set is an inline `{{.X | default N}}` in the command that
-  reads it. Write the default one time. Add a row to the table in [The vars](#the-vars).
+  reads it. If two commands of a verb read it, put the default in a task var with a
+  different name, for example `BATCH_SIZE` in `split`. Write the default one time. Add a
+  row to the table in [The vars](#the-vars).
+- Give a text value of a mirror, for example `FRESH_KEY`, to a command in `env:`, not in a
+  template. The shell reads `"$X"`, awk reads `ENVIRON["X"]`, and Python gets the value as
+  an argument. Do not give such a value to awk with `-v`, because `-v` changes each
+  backslash escape. The render then shows the name of the value, not the value. A var of
+  the environment with the same name wins over `env:`. Thus, do not pass such a name into
+  the container (`PASS`).
+- Put each awk or Python program of more than two lines in the `programs` part of `vars:`.
+  Write a comment above it that gives its function and its inputs. The command that runs
+  the program gives it each input with awk `-v`, `ENVIRON` or an argument. A program has
+  no template of a var that a caller can give, because task renders a global var without
+  the call vars.
 - A change to a verb is a change to `examples/<variant>/render.txt`. The diff of that file
   in the pull request is the review.