From ef19e72b75debe96b8292ef7af9ea3544df32bea Mon Sep 17 00:00:00 2001
From: Sola <taka9819@gmail.com>
Date: Wed, 24 Dec 2025 00:05:56 +0900
Subject: [PATCH 1/2] doc: improve option anchor generation

---
 crates/core/flags/doc/man.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/crates/core/flags/doc/man.rs b/crates/core/flags/doc/man.rs
index c89a6d3ac6..10fcf40e9b 100644
--- a/crates/core/flags/doc/man.rs
+++ b/crates/core/flags/doc/man.rs
@@ -44,6 +44,7 @@ pub(crate) fn generate() -> String {
 
 /// Writes `roff` formatted documentation for `flag` to `out`.
 fn generate_flag(flag: &'static dyn Flag, out: &mut String) {
+    writeln!(out, ".TP 12");
     if let Some(byte) = flag.name_short() {
         let name = char::from(byte);
         write!(out, r"\fB\-{name}\fP");

From 1d4f6e6cd30e64484b92dbfa874510b5d06478e1 Mon Sep 17 00:00:00 2001
From: Sola <taka9819@gmail.com>
Date: Wed, 24 Dec 2025 22:21:12 +0900
Subject: [PATCH 2/2] man: improve option anchor generation

---
 crates/core/flags/doc/man.rs | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)

diff --git a/crates/core/flags/doc/man.rs b/crates/core/flags/doc/man.rs
index 10fcf40e9b..0e0a2b6b98 100644
--- a/crates/core/flags/doc/man.rs
+++ b/crates/core/flags/doc/man.rs
@@ -45,19 +45,34 @@ pub(crate) fn generate() -> String {
 /// Writes `roff` formatted documentation for `flag` to `out`.
 fn generate_flag(flag: &'static dyn Flag, out: &mut String) {
     writeln!(out, ".TP 12");
-    if let Some(byte) = flag.name_short() {
-        let name = char::from(byte);
-        write!(out, r"\fB\-{name}\fP");
+    let short = flag.name_short().map(char::from);
+    let name = flag.name_long().replace("-", r"\-");
+
+    if short.map(|c| c.is_ascii_alphanumeric()).unwrap_or(false) {
+        let short = short.unwrap();
+        write!(out, r"\fB\-{short}\fP");
         if let Some(var) = flag.doc_variable() {
             write!(out, r" \fI{var}\fP");
         }
         write!(out, r", ");
-    }
 
-    let name = flag.name_long().replace("-", r"\-");
-    write!(out, r"\fB\-\-{name}\fP");
-    if let Some(var) = flag.doc_variable() {
-        write!(out, r"=\fI{var}\fP");
+        write!(out, r"\fB\-\-{name}\fP");
+        if let Some(var) = flag.doc_variable() {
+            write!(out, r"=\fI{var}\fP");
+        }
+    } else {
+        write!(out, r"\fB\-\-{name}\fP");
+        if let Some(var) = flag.doc_variable() {
+            write!(out, r"=\fI{var}\fP");
+        }
+
+        if let Some(short) = short {
+            write!(out, r", ");
+            write!(out, r"\fB\-{short}\fP");
+            if let Some(var) = flag.doc_variable() {
+                write!(out, r" \fI{var}\fP");
+            }
+        }
     }
     write!(out, "\n");