Writing Criteria

Every guide in this repo is written to the same standard. If you're adding or editing a guide — human or AI — hold it to these.

1. Plain words, real ideas. Simple language, never dumbed-down concepts. Explain jargon on first use; collect terms in the glossary.
2. No hype. No marketing adjectives, no "revolutionary," no promises about what something will do for the reader.
3. Honest about limits. Say what the thing can't do. State uncertainty instead of smoothing it over. Validation notes include what remains unverified.
4. No invented numbers. Benchmarks, defaults, and specs are either measured or qualified with "depends on your setup." If it wasn't tested, say so.
5. Checkable. Commands are meant to be run, with "Check:" blocks showing what success looks like. Sources are linked, not asserted.
6. Respect the reader's setup. Call out Windows/Mac/Linux differences. Don't assume a GPU, a budget, or prior experience.
7. Safety isn't skipped. Real risks get stated plainly, not buried.
8. Scoped. Each guide says what it covers and points elsewhere for the rest. No guide pretends to be the whole subject.
9. Structure over prose. Tables, before/after examples, symptom → fix. Scannable beats essay.

Verification notes for this guide

Built and verified 2026-10-24 against GNU Parallel 20231122 (Ubuntu package 20231122+ds-1, extracted from the noble .deb; noble-updates carries the same upstream as +ds-4), with Perl, procps and sysstat as shipped in Ubuntu 24.04, on a 2-CPU, 7.9 GB sandbox machine running Ubuntu 24.04.

Primary sources read, not remembered: the shipped man parallel from the same package (searched in full for the citation behaviour — it contains no mention of it), the shipped program's own source where the citation machinery lives, and upstream's manual at gnu.org/software/parallel/parallel.html (the 20260722 edition) for the citation options and the remote-execution chapter.

The citation behaviour, verified at the source. Debian and Ubuntu ship the program with the citation machinery commented out: the option registration, the --citation handler and the citation_notice() call are all #-prefixed in the shipped script, though the subroutine itself remains. Consequences, all observed: a first run in a fresh home directory prints no notice and leaves standard error empty (t00a); --citation is answered with "Unknown option: citation" plus usage text (t00b); --no-notice is accepted and does nothing (t00b); the Debian man page never mentions citation. Upstream builds behave as upstream's manual describes: a notice on early runs, settled by parallel --citation. Chapter 3 presents both shapes and says which build each belongs to.

The sandbox, declared. The lab machine was a shared sandbox under heavy load from other work throughout (load average near 9 on 2 cores at one point). Two consequences are kept visible rather than cleaned away. The timing transcript (t03) shows eight one-second sleeps taking 47.6s at -j1, 26.2s at the default two slots and 15.7s at -j4: the ordering matches the slot counts exactly, and the chapters say plainly that the absolute values are job-start overhead on a busy machine, not a benchmark. And one early input-sources capture lost a job's output line under that load; the command was re-run five times cleanly and the transcript regenerated, which is why t05 carries no scar tissue. The --bar capture (t04b) likewise reached 100% with an elapsed figure that belongs to the loaded sandbox, annotated in place.

Ran for real (transcripts in gnu-parallel-lab/transcripts/):

• t00a — parallel --version → 20231122; a first run in a fresh home directory: jobs correct, standard error empty, no citation notice.
• t00b — --no-notice accepted, exit 0; --citation refused as an unknown option with usage text, exit 255.
• t01 — the loop-to-list step: ::: arguments, {} appended when the template has no replacement string, and a piped list on standard input.
• t02 — all five replacement strings over two inputs, including {.} on archive/backup.tar.gz removing only the last extension; positional {1}/{2} with cutting forms over a Cartesian product; and the accident the troubleshooting chapter is built on — a literal | in the template acting as a real shell pipe.
• t03 — eight sleep 1 jobs at -j1, default and -j4, timed (see the sandbox note above).
• t04 — twelve files checksummed from a pipe with a job log; the log's columns shown in full (sequence 7 recorded before 6 — completion order, kept as evidence); total job time 0.702s by awk over the log.
• t04b — --bar over twelve jobs under a pseudo-terminal, captured to 100% (annotation in the transcript).
• t05 — two ::: lists as a Cartesian product; --link pairing; :::: and --a reading the same argument file.
• t05b — a paired rename with :::+, dry-run first, then real.
• t05c — --pipe -N10 cutting a 25-line stream into blocks counted 10, 10, 5.
• t06 — --dry-run of a gzip batch, then the real run; sizes listed; the lab tidies its own .gz files away.
• t06b — --halt now,fail=1 stopping a run at its first failure and naming the failed job; --timeout 1 ending a five-second job at one second, warned and counted failed.
• t07 — derived files built from {/.} (upper-case copies, first lines shown) and wc -w over all twelve fixtures.
• t08 — staggered sleeps printing in finish order by default and in input order with -k, all jobs started together under -j3 so the contrast is the ordering, not the slots.
• t08b — --ungroup streaming two jobs' lines interleaved; the default grouping keeping each job's lines together.
• t09 — a three-job run with one failure: exit status 1, the failure visible in the job log, the cause fixed, --retry-failed re-running only that job to exit 0, the log gaining its second line. --resume was also run on the completed log and correctly ran nothing — chapter 9 keeps the two continuations distinct because the lab initially conflated them and the transcripts show why they differ.
• t09b — --results filing each job's stdout, stderr and seq under per-input paths, the input's slashes rewritten as +z.
• t10 — the remote probe: nothing listening on port 22, ssh localhost refused. The evidence for the item below.

Documented only, and labelled as such in the chapters: remote execution — --sshlogin, --transfer/--return/--cleanup and --trc, --workdir, host files — because the lab has no SSH server to run against (t10); env_parallel's function and alias capture (named in chapters 3 and 14); the {= … =} Perl expressions (chapter 5 points at the manual); --eta and --progress (chapter 9 describes them beside the verified --bar); --delay (chapter 6 describes it beside the verified --halt and --timeout); and converters used as recipe patterns, such as ImageMagick's convert (chapter 10 labels the pattern as the lab's and the converter as the reader's to supply).

Fixtures: everything the lab made up is small and generic — twelve short invented notes about sorting donated books for a sale, in two folders named north and south, generated by gnu-parallel-lab/make-files.sh so any reader can rebuild them. Nothing in the lab is modelled on any real person, organisation or event.