From 903ef3aacc3d98d32d51b65aaf4bfbdc20d90bc5 Mon Sep 17 00:00:00 2001
From: Jake Wallin <jakewallin42@gmail.com>
Date: Fri, 16 Oct 2026 16:44:47 +0000
Subject: [PATCH] uudoc: prefer Linux tldr pages over common pages

---
 src/bin/uudoc.rs | 58 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 50 insertions(+), 8 deletions(-)

diff --git a/src/bin/uudoc.rs b/src/bin/uudoc.rs
index 992526b2e1..14adcb5088 100644
--- a/src/bin/uudoc.rs
+++ b/src/bin/uudoc.rs
@@ -666,16 +666,22 @@ fn write_zip_examples(
     name: &str,
     output_markdown: bool,
 ) -> io::Result<String> {
-    let content = if let Some(f) = get_zip_content(archive, &format!("pages/common/{name}.md")) {
-        f
-    } else if let Some(f) = get_zip_content(archive, &format!("pages/linux/{name}.md")) {
-        f
+    // Linux pages for these utilities can describe other implementations or shell builtins.
+    let platforms = if matches!(name, "hostname" | "kill" | "more" | "uptime") {
+        ["common", "linux"]
     } else {
-        return Err(io::Error::new(
-            io::ErrorKind::NotFound,
-            format!("Could not find tldr examples for {name}"),
-        ));
+        // Prefer GNU-specific examples over generic POSIX examples.
+        ["linux", "common"]
     };
+    let content = platforms
+        .into_iter()
+        .find_map(|platform| get_zip_content(archive, &format!("pages/{platform}/{name}.md")))
+        .ok_or_else(|| {
+            io::Error::new(
+                io::ErrorKind::NotFound,
+                format!("Could not find tldr examples for {name}"),
+            )
+        })?;
 
     match format_examples(content, output_markdown) {
         Err(e) => Err(io::Error::other(format!(
@@ -719,6 +725,42 @@ fn format_examples(content: String, output_markdown: bool) -> Result<String, std
 mod tests {
     use super::*;
 
+    #[rstest::rstest]
+    #[case("head", &["common", "linux"], "linux")]
+    #[case("head", &["linux"], "linux")]
+    #[case("head", &["common"], "common")]
+    #[case("hostname", &["common", "linux"], "common")]
+    #[case("kill", &["common", "linux"], "common")]
+    #[case("more", &["common", "linux"], "common")]
+    #[case("uptime", &["common", "linux"], "common")]
+    #[case("uptime", &["linux"], "linux")]
+    #[case("uptime", &["common"], "common")]
+    fn test_tldr_page_selection(
+        #[case] name: &str,
+        #[case] platforms: &[&str],
+        #[case] expected: &str,
+        #[values(false, true)] markdown: bool,
+    ) {
+        let mut zip = zip::ZipWriter::new(io::Cursor::new(Vec::new()));
+        for platform in platforms {
+            zip.start_file(
+                format!("pages/{platform}/{name}.md"),
+                zip::write::SimpleFileOptions::default(),
+            )
+            .unwrap();
+            writeln!(zip, "- {platform} example:\n\n`{name} file`").unwrap();
+        }
+        let mut archive = ZipArchive::new(zip.finish().unwrap()).unwrap();
+        let output = write_zip_examples(&mut archive, name, markdown).unwrap();
+        assert!(output.contains(&format!("{expected} example:")), "{output}");
+        let other = if expected == "linux" {
+            "common"
+        } else {
+            "linux"
+        };
+        assert!(!output.contains(&format!("{other} example:")), "{output}");
+    }
+
     #[test]
     fn test_post_process_manpage_fixes_th_header() {
         // Test that command names are uppercased and date is removed