From 82d5ff77cf88c3e9e7ae6221e57ddf9e5642981a Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Wed, 21 Oct 2026 05:24:20 +0200 Subject: [PATCH] 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 | 5 +++-- scripts/generate_readme.py | 14 +++++++------- tests/test_audit_regressions.py | 2 +- tests/test_doc_surfaces.py | 30 ++++++++++++++++++++++++++++++ 4 files changed, 41 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 37696e62..d5eddb67 100644 --- a/README.md +++ b/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) | diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py index 52256e85..b720e70c 100644 --- a/scripts/generate_readme.py +++ b/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: diff --git a/tests/test_audit_regressions.py b/tests/test_audit_regressions.py index 2c500274..01257364 100644 --- a/tests/test_audit_regressions.py +++ b/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] diff --git a/tests/test_doc_surfaces.py b/tests/test_doc_surfaces.py index a2f69a2d..35737c3e 100644 --- a/tests/test_doc_surfaces.py +++ b/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."""