From c5ba17d3dd2c2cc008c475fc4695cb3f1e41112f Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Fri, 23 Oct 2026 10:50:52 +0200 Subject: [PATCH] refactor: fit setup pages in 220 words The new answers are shortened and the safety list, shown in full on the home page, is linked from each setup page instead of repeated. The setup ceiling stays at 220. --- scripts/generate_site.py | 33 +++++++++++++++++---------------- tests/test_site_copy.py | 5 +---- tests/test_site_r3_entry.py | 18 ++++++++++++++---- 3 files changed, 32 insertions(+), 24 deletions(-) diff --git a/scripts/generate_site.py b/scripts/generate_site.py index 0902c30f..b620a626 100644 --- a/scripts/generate_site.py +++ b/scripts/generate_site.py @@ -660,8 +660,7 @@ def release_line(platform_name: str, record: dict) -> list[str]: # What a reader on another version of the setup does with the pack. Our data # says which list the pack was made from, not what an older list lacks. -OTHER_VERSION = ("Another version? After copying, `--check` names any file missing " - "or different.") +OTHER_VERSION = "Other version? Run `--check` after copying." def setup_version(platform_name: str, record: dict | None = None) -> str: @@ -686,7 +685,7 @@ def version_line(platform_name: str, record: dict, named: bool = False) -> str: made_from = setup_version(platform_name, record) if named or not made_from: return OTHER_VERSION - return f"Made from the BIOS list of {made_from}. {OTHER_VERSION}" + return f"Made for {made_from}. {OTHER_VERSION}" def _pack_buttons(platform_name: str, label: str = "Pack") -> str: @@ -2816,13 +2815,10 @@ def _check_sentence(display: str, mode: str, config: dict, no_list: bool) -> str return (f"{display} has no BIOS list, so it checks nothing itself. Each " "emulator looks for its own files when a game starts.") if config.get("hash_rule") == "size_and_any_hash": - return (f"{display} checks each file's size and fingerprint too. It " - "reports a file with the wrong size or contents.") + return f"{display} also checks each file's size and contents." if digest_algorithm(mode): - return (f"{display} checks each file's fingerprint too. It reports a file " - "with the wrong contents.") - return (f"{display} only checks that a file with the right name is there. " - "`--check` also checks what is inside.") + return f"{display} also checks each file's contents." + return f"{display} checks names only. `--check` also checks contents." def _folder_rows(rows: tuple[tuple[str, str], ...], indent: str = "") -> list[str]: @@ -2837,7 +2833,11 @@ def _folder_rows(rows: tuple[tuple[str, str], ...], indent: str = "") -> list[st # sample): the file is there and the setup still reports it missing. # `--check` lists every file whose hash is wrong by name (install.py, the # "wrong hash" lines of check_lines). -MISSING_IN_PLACE = "In place but reported missing? `--check` names a file with the wrong contents." +MISSING_IN_PLACE = "Reported missing anyway? `--check` names a wrong file." + +# Under every command of a setup page: the safety list is the one the home +# page shows in full, so the setup page links it. +SAFE_LINK = "[Is it safe?](../index.md#is-it-safe)" # Under "From your computer": a device with no network installs from the ZIP # (`--from-pack`). The id is the one wiki/installer.md gives its section. @@ -2899,7 +2899,7 @@ def _guide_download(name: str, display: str, guide: Guide, extract_to: str | Non made_from = setup_version(name) lines += [ f"No {display} ZIP yet. The command installs the same files" - + (f", from the BIOS list of {made_from}." if made_from else "."), + + (f", made for {made_from}." if made_from else "."), "", ] else: @@ -2911,7 +2911,7 @@ def only_some_consoles(name: str, prefix: str = "") -> list[str]: """The way to a smaller download, in the words Get your files uses.""" return [ f"Only some consoles? [Pick them]({prefix}which-pack.md?platform={name}" - "#only-some-consoles), or press **c** when the command asks.", + "#only-some-consoles), or press **c** in the command.", "", ] @@ -2921,8 +2921,7 @@ def _guide_install(name: str, guide: Guide, heading: str) -> list[str]: lines = [ heading, "", - "The command finds the folder, downloads what is missing, and checks " - "each file.", + "It finds the folder and checks each file.", "", ] if guide.on_card: @@ -2935,7 +2934,8 @@ def _guide_install(name: str, guide: Guide, heading: str) -> list[str]: return [ *lines, *terminal_tabs(guide.run, platform_args(name, guide), how={"device": device}), - *trust_box("../"), + SAFE_LINK, + "", ] @@ -2997,7 +2997,8 @@ def generate_handheld_guide(guide: HandheldGuide) -> str: "`--dest`, written as in the table.", "", *terminal_tabs(("windows", "macos", "linux"), args), - *trust_box("../"), + SAFE_LINK, + "", *_next_block([ f"[{display}]({guide.uses}.md): every folder and every file", "[When a game does not start](../wiki/troubleshooting.md)", diff --git a/tests/test_site_copy.py b/tests/test_site_copy.py index c4f7bd06..ebf80951 100644 --- a/tests/test_site_copy.py +++ b/tests/test_site_copy.py @@ -37,10 +37,7 @@ START_PAGES = { "wiki/glossary.md": 200, } # Level 1: the guide part of each setup page, above its Reference heading. -# 220 until each page also answered three asked questions in about 50 words: -# which setup version the ZIP was made from (7 % of the community sample), -# how to get only some consoles, and a file in place but reported missing (14 %). -SETUP_CEILING = 280 +SETUP_CEILING = 220 # The setup index is a card per setup, one sentence each. SETUP_INDEX_CEILING = 300 diff --git a/tests/test_site_r3_entry.py b/tests/test_site_r3_entry.py index a7fb1aca..7732956a 100644 --- a/tests/test_site_r3_entry.py +++ b/tests/test_site_r3_entry.py @@ -124,7 +124,7 @@ class PackNamesItsVersion(unittest.TestCase): self.skipTest("release.json has no Batocera pack") block = generate_site._pack_buttons("batocera") version = generate_site._pack_version(release_record.pack_name_for("batocera", record)) - self.assertIn(f"Made from the BIOS list of Batocera {version}. " + self.assertIn(f"Made for Batocera {version}. " + generate_site.OTHER_VERSION, block) def test_a_version_gap_is_said_once(self): @@ -142,7 +142,7 @@ class PackNamesItsVersion(unittest.TestCase): for key in REGISTRY: with self.subTest(platform=key): text = _guide_part(_page(f"platforms/{key}.md")) - self.assertRegex(text, r"(?:from the BIOS list of|This pack was built for) \S") + self.assertRegex(text, r"(?:[Mm]ade for|This pack was built for) \S") class SetupPagesOfferPartOfThePack(unittest.TestCase): @@ -151,7 +151,7 @@ class SetupPagesOfferPartOfThePack(unittest.TestCase): with self.subTest(platform=key): text = _guide_part(_page(f"platforms/{key}.md")) self.assertIn(f"/retrobios/which-pack/?platform={key}#only-some-consoles", text) - self.assertIn("or press **c** when the command asks.", text) + self.assertIn("or press **c** in the command.", text) def test_the_anchor_exists(self): self.assertIn("## Only some consoles?", _page("which-pack.md")) @@ -159,10 +159,20 @@ class SetupPagesOfferPartOfThePack(unittest.TestCase): def test_a_file_in_place_but_missing_is_answered(self): for key in REGISTRY: with self.subTest(platform=key): - self.assertIn("In place but reported missing?", + self.assertIn("Reported missing anyway?", _guide_part(_page(f"platforms/{key}.md"))) +class SafetyListIsLinked(unittest.TestCase): + def test_setup_pages_link_the_home_list(self): + for key in REGISTRY: + with self.subTest(platform=key): + text = _guide_part(_page(f"platforms/{key}.md")) + self.assertIn("[Is it safe?](/retrobios/#is-it-safe)", text) + self.assertNotIn("Is it safe?", text) + self.assertIn("## Is it safe? { #is-it-safe }", _page("index.md")) + + class OfflineLine(unittest.TestCase): def test_under_from_your_computer(self): text = _page("platforms/batocera.md")