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.

A patch to docs/how to run.md.

The new page docs/how to run.md has two sections, each with a command in a fenced block of sh.

uv run mdformat --check docs

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

@@ -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.

A patch to docs/how to run.md.

At the end of docs/how to run.md, the section "Only the most common words" runs uv run tally --top 10.

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

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

@@ -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.

A patch to docs/how to run.md.

At the end of docs/how to run.md, the section "A table" runs tally with --top 10 --table.

uv run mdformat --check docs

It prints nothing, so the page is still formatted.

@@ -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.

A patch to docs/tally.png.

The new file docs/tally.png is a picture of ten blue bars, one for each of the most common words.

file docs/tally.png

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

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.

A patch to docs/how to run.md.

In docs/how to run.md, the section "Only the most common words" shows tally.png, with words that say what it draws.

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

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

@@ -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.

A patch to README.md.

At the end of README.md, the section "Count from Python" counts the words of "the cat and the hat", and keeps the two most common.

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.

@@ -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.

A patch to README.md.

The last sentence of README.md links to the page docs/how to run.md, with %20 for each space.

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

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

@@ -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.

A patch to docs/tally.png.

docs/tally.png has the same ten bars, now 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.

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.

A patch to README.md.

The block of Python in README.md reads data/corpus.txt with Path, and prints the three most common words.

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.

@@ -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.

A patch to justfile.

At the end of the justfile, the recipe docs runs mdformat --check on README.md and on docs.

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.

@@ -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:

This change came from running uv run mdformat README.md.

In the section "Run it" of README.md, the two indented lines are now a fenced block.

just docs

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

@@ -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.

A patch to docs/how to run.md.

At the end of docs/how to run.md, the section "Check the docs" runs just docs, and says what it prints.

just docs

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

@@ -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.