2 The docs

2.1 A page on how to run tally

A user who opens the folder docs wants one page on how to run tally. Its name has spaces in it, how to run.md, as the names of pages often do.

Apply the patch to docs/how to run.md, from the top of the project:

curl -fsSL https://github.com/rahuldave/tally/commit/17ec79e65166fe1f93c13f94b35e909ca1e36a3c.diff | git apply --include='docs/how to run.md'

The patch makes the file docs/how to run.md, with a heading and two sections, "Set up" and "Count the words of a file".

uv run mdformat --check docs

It prints nothing, because the page is formatted as mdformat formats it.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check 17ec79e65166

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source ec6a8aa7f9a8 --staged -- :/ && git restore --source 17ec79e65166 --staged --worktree -- :/

@@ -0,0 +1,19 @@
+# How to run tally
+
+tally counts the words of a text file.
+
+## Set up
+
+Run this once, and again after each change of the project:
+
+```sh
+just setup
+```
+
+## Count the words of a file
+
+```sh
+uv run tally data/corpus.txt
+```
+
+It prints each word with its count, one word to a line, in the order of the alphabet.

2.2 The most common words

The page does not say how to keep only the most common words. A section says it, with the option --top.

Apply the patch to docs/how to run.md, from the top of the project:

curl -fsSL https://github.com/rahuldave/tally/commit/4a4de50fdb3f29580f612015d62ca81b6c9afe07.diff | git apply --include='docs/how to run.md'

The patch adds the section "Only the most common words" at the end of docs/how to run.md.

uv run tally --top 10 data/corpus.txt

It prints the ten lines that the section promises, from 127 line down to 110 code.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check 4a4de50fdb3f

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source 17ec79e65166 --staged -- :/ && git restore --source 4a4de50fdb3f --staged --worktree -- :/

@@ -17,3 +17,11 @@ uv run tally data/corpus.txt
 ```
 
 It prints each word with its count, one word to a line, in the order of the alphabet.
+
+## Only the most common words
+
+```sh
+uv run tally --top 10 data/corpus.txt
+```
+
+It prints the ten most common words, the most common first.

2.3 The table

The option --table is new, and the page does not name it. A section names it.

Apply the patch to docs/how to run.md, from the top of the project:

curl -fsSL https://github.com/rahuldave/tally/commit/fea3c9b91e4687bfdd1d528ad230890d5b6df4c9.diff | git apply --include='docs/how to run.md'

The patch adds the section "A table" at the end of docs/how to run.md.

uv run mdformat --check docs

It prints nothing, so the page is still formatted.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check fea3c9b91e46

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source 4a4de50fdb3f --staged -- :/ && git restore --source fea3c9b91e46 --staged --worktree -- :/

@@ -25,3 +25,11 @@ uv run tally --top 10 data/corpus.txt
 ```
 
 It prints the ten most common words, the most common first.
+
+## A table
+
+```sh
+uv run tally --top 10 --table data/corpus.txt
+```
+
+It prints the same words as a table, with a header.

2.4 A picture of the most common words

A picture tells at a glance that the ten most common words have about the same count. A file docs/tally.png draws them as ten blue bars. The file is binary, so its patch has no lines to read.

docs/tally.png is a binary file, with no patch to apply. Take it from the project:

git restore --source 62a45097ffcb --worktree -- ':(top,literal)docs/tally.png'

The patch makes the file docs/tally.png, a picture of 60 by 30 pixels.

file docs/tally.png

It prints docs/tally.png: PNG image data, 60 x 30, 8-bit/color RGB, non-interlaced.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check 62a45097ffcb

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source fea3c9b91e46 --staged -- :/ && git restore --source 62a45097ffcb --staged --worktree -- :/

2.5 The page shows the picture

The picture is in the folder docs, but no page shows it. The section on the most common words shows it, under its command.

Apply the patch to docs/how to run.md, from the top of the project:

curl -fsSL https://github.com/rahuldave/tally/commit/3f033b6e57ab1b04706ab3efe288701b3a7848ef.diff | git apply --include='docs/how to run.md'

The patch adds a line with the picture under the sentence "It prints the ten most common words, the most common first."

grep -n 'tally.png' "docs/how to run.md"

It prints the line of the picture, with its number.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check 3f033b6e57ab

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source 62a45097ffcb --staged -- :/ && git restore --source 3f033b6e57ab --staged --worktree -- :/

@@ -26,6 +26,8 @@ uv run tally --top 10 data/corpus.txt
 
 It prints the ten most common words, the most common first.
 
+![The ten most common words of the corpus, as bars](tally.png)
+
 ## A table
 
 ```sh

2.6 Count from Python

tally is a library as well as a command. A user who writes Python wants to call count and top. A new section of the README shows how, in a fenced block of Python.

Apply the patch to README.md, from the top of the project:

curl -fsSL https://github.com/rahuldave/tally/commit/4cf104b7cd816370bd0a34efc7ff2d2be39f6abb.diff | git apply --include=README.md

The patch adds the section "Count from Python" at the end of README.md, with a block that counts a short text.

uv run python -c "from tally import count, top; print(top(count('the cat and the hat'), 2))"

It prints [('the', 2), ('and', 1)], as the README says.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check 4cf104b7cd81

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source 3f033b6e57ab --staged -- :/ && git restore --source 4cf104b7cd81 --staged --worktree -- :/

@@ -11,3 +11,16 @@ Make the environment, the corpus and the report first. Then count the words of a
 
 `uv run tally --top 10 data/corpus.txt` prints only the ten most common words. `just test` runs the tests, and
 `just report` writes the ten most common words of the corpus to `build/top.txt`.
+
+## Count from Python
+
+tally is a library too. `count` counts the words of a text, and `top` keeps the most common:
+
+```python
+from tally import count, top
+
+counts = count("the cat and the hat")
+print(top(counts, 2))
+```
+
+It prints `[('the', 2), ('and', 1)]`.

2.7 The README links to the page

A reader of the README does not know that the page exists. A link at the end of the README names it. The path has spaces, so the link writes each one as %20.

Apply the patch to README.md, from the top of the project:

curl -fsSL https://github.com/rahuldave/tally/commit/1fac49bff15eb93b2e294c28a89ad85c4ec196c1.diff | git apply --include=README.md

The patch adds one sentence at the end of README.md, with a link to docs/how%20to%20run.md.

grep -o 'docs/how%20to%20run.md' README.md

It prints the path of the link, docs/how%20to%20run.md.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check 1fac49bff15e

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source 4cf104b7cd81 --staged -- :/ && git restore --source 1fac49bff15e --staged --worktree -- :/

@@ -24,3 +24,5 @@ print(top(counts, 2))
 ```
 
 It prints `[('the', 2), ('and', 1)]`.
+
+The page [How to run tally](docs/how%20to%20run.md) says more, with a picture of the most common words.

2.8 The picture in green

The blue bars look like links on a page of blue links. Green bars stand apart. The patch replaces the picture.

docs/tally.png is a binary file, with no patch to apply. Take it from the project:

git restore --source 2476ccb77ac1 --worktree -- ':(top,literal)docs/tally.png'

The patch replaces docs/tally.png with the same bars in green.

file docs/tally.png

It prints docs/tally.png: PNG image data, 60 x 30, 8-bit/color RGB, non-interlaced, as before. Only the colour changed.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check 2476ccb77ac1

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source 1fac49bff15e --staged -- :/ && git restore --source 2476ccb77ac1 --staged --worktree -- :/

2.9 Count a file from Python

A short text in the README shows little. The block of Python now counts the corpus, and keeps the three most common words.

Apply the patch to README.md, from the top of the project:

curl -fsSL https://github.com/rahuldave/tally/commit/a0cde9c7cdd6520d1e82207d6ea78bfc3dba99eb.diff | git apply --include=README.md

In the block of Python of README.md, the patch adds from pathlib import Path, and counts the text of data/corpus.txt. The sentence under the block gives the new output.

This command takes the block of Python out of the README, and runs it:

sed -n '/^```python$/,/^```$/p' README.md | sed '1d;$d' | uv run python -

It prints [('line', 127), ('class', 126), ('word', 125)], as the README says.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check a0cde9c7cdd6

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source 2476ccb77ac1 --staged -- :/ && git restore --source a0cde9c7cdd6 --staged --worktree -- :/

@@ -17,12 +17,14 @@ Make the environment, the corpus and the report first. Then count the words of a
 tally is a library too. `count` counts the words of a text, and `top` keeps the most common:
 
 ```python
+from pathlib import Path
+
 from tally import count, top
 
-counts = count("the cat and the hat")
-print(top(counts, 2))
+counts = count(Path("data/corpus.txt").read_text())
+print(top(counts, 3))
 ```
 
-It prints `[('the', 2), ('and', 1)]`.
+It prints `[('line', 127), ('class', 126), ('word', 125)]`, the three most common words of the corpus.
 
 The page [How to run tally](docs/how%20to%20run.md) says more, with a picture of the most common words.

2.10 A recipe that checks the docs

Nobody remembers to run mdformat on each page. A recipe, just docs, checks the README and the folder docs in one command.

Apply the patch to justfile, from the top of the project:

curl -fsSL https://github.com/rahuldave/tally/commit/cdde9a53f40f29d93721cc8defb7717ea5fb4d93.diff | git apply --include=justfile

The patch adds the recipe docs at the end of the justfile.

just docs

It fails, with exit code 1. mdformat says that README.md is not formatted. The section "Run it" has a block of code indented by four spaces, and mdformat writes a fenced block.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check cdde9a53f40f

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source a0cde9c7cdd6 --staged -- :/ && git restore --source cdde9a53f40f --staged --worktree -- :/

@@ -20,3 +20,7 @@ test:
 report:
     mkdir -p build
     uv run tally --top 10 data/corpus.txt > build/top.txt
+
+# Check that the README and the docs are formatted as mdformat formats them
+docs:
+    uv run mdformat --check README.md docs

2.11 The README as mdformat writes it

The check fails on the README. mdformat without --check formats the file in place:

uv run mdformat README.md

just docs

It prints the command of the recipe, and mdformat prints nothing. The README and the page are formatted.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check b8347ac5868c

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source cdde9a53f40f --staged -- :/ && git restore --source b8347ac5868c --staged --worktree -- :/

@@ -6,8 +6,10 @@ Count the words in a text.
 
 Make the environment, the corpus and the report first. Then count the words of a file:
 
-    just setup
-    uv run tally data/corpus.txt
+```
+just setup
+uv run tally data/corpus.txt
+```
 
 `uv run tally --top 10 data/corpus.txt` prints only the ten most common words. `just test` runs the tests, and
 `just report` writes the ten most common words of the corpus to `build/top.txt`.

2.12 The page says how to check the docs

A writer of the docs needs to know that the recipe exists. A last section of the page names it.

Apply the patch to docs/how to run.md, from the top of the project:

curl -fsSL https://github.com/rahuldave/tally/commit/d6f47209c66d7bb88e4e389e2eb9bc495694df55.diff | git apply --include='docs/how to run.md'

The patch adds the section "Check the docs" at the end of docs/how to run.md.

just docs

mdformat prints nothing, so the new section is formatted too.

Check your files against this move. The command prints nothing when they match, and otherwise shows what differs:

git check d6f47209c66d

If you are stuck, this command puts the files of this move in place of yours. A file that you made yourself stays:

git restore --source b8347ac5868c --staged -- :/ && git restore --source d6f47209c66d --staged --worktree -- :/

@@ -35,3 +35,11 @@ uv run tally --top 10 --table data/corpus.txt
 ```
 
 It prints the same words as a table, with a header.
+
+## Check the docs
+
+```sh
+just docs
+```
+
+It prints nothing when every page of the docs is formatted as mdformat formats it.