docs: sentence-case and split README paragraphs

Quick Install was the one Title Case heading left in the published
text. The Files sentence was glued to the paragraph above it, two
paragraphs before the table whose column it describes. It now names
the column and sits just above the table.

README.md

@@ -10,7 +10,7 @@ BIOS and firmware files for Batocera, BizHawk, EmuDeck, Lakka, MiSTer FPGA, ROCK
 
 A pack holds the files its emulators read, as their source code names them, and leaves out what the emulators install themselves.
 
-## Quick Install
+## Quick install
 
 Copy one command into your terminal:
 
@@ -33,7 +33,6 @@ The script auto-detects your platform, downloads only missing files, and verifie
 ## Download BIOS packs
 
 One pack per platform, and it holds everything the platform runs: its own BIOS list plus every file its emulator cores load. Pick your platform, download the ZIP, extract to the BIOS path. The installer above does the same file by file. At a terminal it asks whether to install everything or to choose systems, cores and regions, and `--system`, `--core`, `--region` and `--target` make the same choice without questions. For a bare minimum, build your own pack below.
-Files is how many the pack holds once extracted, the figure a file manager shows for the folder. It differs from one platform to the next because a pack carries only what that platform's emulators load. The size is what the files occupy once extracted, and the ZIP itself downloads smaller.
 
 A pack over 2 GB comes in several parts, and every part is needed. How to open them depends on their name:
 
@@ -42,6 +41,8 @@ A pack over 2 GB comes in several parts, and every part is needed. How to open t
 
 Every release ships `SHA256SUMS.txt` and a detached signature of it, checkable against `allowed_signers` in this repository: [verifying a release](https://abdess.github.io/retrobios/wiki/release-process/#verifying-a-release).
 
+The Files column counts what a pack holds once extracted, the figure a file manager shows for the folder. It differs from one platform to the next because a pack carries only what that platform's emulators load. The size is what the files occupy once extracted, and the ZIP itself downloads smaller.
+
 | Platform | Files | Extracted size | Extract to | Download |
 |----------|------:|---------------:|-----------|----------|
 | Batocera | 12,810 | 7.5 GB | `/userdata/bios/` | [Download](../../releases/latest) |

scripts/generate_readme.py

@@ -351,7 +351,7 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
         "A pack holds the files its emulators read, as their source code names"
         " them, and leaves out what the emulators install themselves.",
         "",
-        "## Quick Install",
+        "## Quick install",
         "",
         "Copy one command into your terminal:",
         "",
@@ -374,12 +374,6 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
         "## Download BIOS packs",
         "",
         "One pack per platform, and it holds everything the platform runs: its own BIOS list plus every file its emulator cores load. Pick your platform, download the ZIP, extract to the BIOS path. The installer above does the same file by file. At a terminal it asks whether to install everything or to choose systems, cores and regions, and `--system`, `--core`, `--region` and `--target` make the same choice without questions. For a bare minimum, build your own pack below.",
-        "Files is how many the pack holds once extracted, the figure a file"
-        " manager shows for the folder. It differs from one platform to the"
-        " next because a pack carries only what that platform's emulators"
-        " load."
-        " The size is what the files occupy once extracted, and the ZIP itself"
-        " downloads smaller.",
         "",
         "A pack over 2 GB comes in several parts, and every part is needed."
         " How to open them depends on their name:",
@@ -398,6 +392,12 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
         "(https://abdess.github.io/retrobios/wiki/release-process/"
         "#verifying-a-release).",
         "",
+        "The Files column counts what a pack holds once extracted, the figure a"
+        " file manager shows for the folder. It differs from one platform to"
+        " the next because a pack carries only what that platform's emulators"
+        " load. The size is what the files occupy once extracted, and the ZIP"
+        " itself downloads smaller.",
+        "",
     ]
 
     # Where the pack itself is extracted, which is not always the BIOS folder:

tests/test_audit_regressions.py

@@ -54,7 +54,7 @@ class ReadmeRegressions(unittest.TestCase):
 
     def _quick_install(self) -> str:
         readme = (ROOT / "README.md").read_text(encoding="utf-8")
-        return readme.split("## Quick Install", 1)[1].split(
+        return readme.split("## Quick install", 1)[1].split(
             "## Download BIOS packs", 1
         )[0]
 

tests/test_doc_surfaces.py

@@ -185,6 +185,36 @@ class ReleaseCommitCarriesTheManifests(unittest.TestCase):
         self.assertIn("install/*.json", add.split())
 
 
+class PublishedHeadings(unittest.TestCase):
+    """README.md kept '## Quick Install', the one Title Case heading left,
+    because the casing test read wiki/ only."""
+
+    def test_readme_and_contributing_use_sentence_case(self):
+        offenders = []
+        for page in (ROOT / "README.md", ROOT / "CONTRIBUTING.md"):
+            text = FENCED.sub("", page.read_text(encoding="utf-8"))
+            for title in re.findall(r"(?m)^#{1,4} (.+)$", text):
+                if _sentence_case(title) != title:
+                    offenders.append(f"{page.name}: {title}")
+        self.assertEqual(offenders, [], "\n".join(offenders))
+
+
+class FilesColumnParagraph(unittest.TestCase):
+    """'Files is how many the pack holds' was glued to the paragraph above
+    it, two paragraphs before the table whose column it described."""
+
+    def test_it_names_the_column_in_its_own_paragraph_before_the_table(self):
+        import generate_readme
+
+        source = inspect.getsource(generate_readme)
+        self.assertNotIn("Files is how many", source)
+        readme = (ROOT / "README.md").read_text(encoding="utf-8")
+        paragraph = next(p for p in readme.split("\n\n") if "The Files column" in p)
+        self.assertNotIn("\n", paragraph.strip())
+        after = readme.split(paragraph, 1)[1].lstrip("\n")
+        self.assertTrue(after.startswith("| Platform | Files |"))
+
+
 class PageOpenings(unittest.TestCase):
     """Four pages opened by announcing what they cover."""