feat(docgen): man Examples 多行保留

man EXAMPLES 改用 .nf/.fi(no-fill)区块逐行输出, 不再用 cleanLine 折叠换行,
多行示例按原样保留。抽出 protectLeading/roffRawLine 辅助函数复用行首控制字符保护。
对比文档移除已解决的 man Examples 单行折叠差距项。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: inhere

docgen/docgen_test.go

@@ -28,7 +28,8 @@ func newTestApp() *gcli.App {
 		Name:     "demo",
 		Desc:     "this is a demo command for test",
 		Help:     "long help message for demo command",
-		Examples: "<cyan>{$fullCmd} --name tom arg0 arg1</> # run the demo",
+		Examples: "<cyan>{$fullCmd} --name tom arg0 arg1</> # run the demo\n" +
+			"<cyan>{$fullCmd} --name tom -v arg0</> # verbose run",
 		Subs:     []*gcli.Command{sub},
 		Config: func(c *gcli.Command) {
 			var name string
@@ -66,6 +67,8 @@ func TestCmdMarkdown(t *testing.T) {
 	assert.NotContains(t, md, "<cyan>")
 	assert.NotContains(t, md, "{$fullCmd}")
 	assert.StrContains(t, md, "demo --name tom arg0 arg1")
+	// Examples: 多行保留(代码块内两行示例均在)
+	assert.StrContains(t, md, "demo --name tom -v arg0")
 	assert.StrContains(t, md, "## SubCommands")
 	// 子命令链接文件名应与 tree 命名规则一致
 	assert.StrContains(t, md, "demo_child.md")
@@ -100,6 +103,11 @@ func TestCmdMan(t *testing.T) {
 	assert.StrContains(t, man, ".SH EXAMPLES")
 	// --name 需被转义为 \-\-name
 	assert.StrContains(t, man, "\\-\\-name")
+	// Examples 多行保留: 用 .nf/.fi 区块逐行输出, 两行示例均在且未被折叠成一行
+	assert.StrContains(t, man, ".nf")
+	assert.StrContains(t, man, ".fi")
+	assert.StrContains(t, man, "demo \\-\\-name tom arg0 arg1 # run the demo")
+	assert.StrContains(t, man, "demo \\-\\-name tom \\-v arg0 # verbose run")
 }
 
 func TestManTree(t *testing.T) {

docgen/manpage.go

@@ -17,16 +17,25 @@ func escapeRoff(s string) string {
 	return s
 }
 
-// roffLine 转义并输出一行文本。
-// roff 中行首的 `.` 与 `'` 是控制字符, 需用 `\&` 零宽前缀保护。
-func roffLine(s string) string {
-	s = escapeRoff(cleanLine(s))
+// protectLeading 保护行首控制字符: roff 中行首的 `.` 与 `'` 是控制字符,
+// 需用 `\&` 零宽前缀保护, 否则该行会被当作宏调用。
+func protectLeading(s string) string {
 	if s != "" && (s[0] == '.' || s[0] == '\'') {
-		s = "\\&" + s
+		return "\\&" + s
 	}
 	return s
 }
 
+// roffLine 转义并输出一行文本(折叠内部换行为空格, 用于单行场景)。
+func roffLine(s string) string {
+	return protectLeading(escapeRoff(cleanLine(s)))
+}
+
+// roffRawLine 转义单行文本但不折叠换行, 用于 .nf/.fi 区块内逐行输出以保留原始换行。
+func roffRawLine(s string) string {
+	return protectLeading(escapeRoff(strings.TrimRight(s, "\r")))
+}
+
 // CmdMan 渲染单个命令为 man page(roff 格式)。
 func CmdMan(c *gcli.Command) string {
 	var buf strings.Builder
@@ -79,10 +88,14 @@ func CmdMan(c *gcli.Command) string {
 		}
 	}
 
-	// EXAMPLES
+	// EXAMPLES(用 .nf/.fi 关闭填充并逐行输出, 保留多行原样)
 	if c.Examples != "" {
 		buf.WriteString(".SH EXAMPLES\n")
-		buf.WriteString(roffLine(renderText(c, c.Examples)) + "\n")
+		buf.WriteString(".nf\n")
+		for _, line := range strings.Split(strings.Trim(renderText(c, c.Examples), "\n"), "\n") {
+			buf.WriteString(roffRawLine(line) + "\n")
+		}
+		buf.WriteString(".fi\n")
 	}
 
 	return buf.String()

docs/compare-with-others.zh-CN.md

@@ -77,7 +77,7 @@
 1. **采用度/生态**（主要差距）：cobra 体量碾压，插件、教程、招聘熟悉度都更高——这是短期难追的项。
 2. **POSIX 默认性**：cobra+pflag 的 GNU 行为「默认即标准」；gcli 不少 POSIX 特性是 opt-in（EnhanceShort）。
 3. **补全 shell 覆盖**：gcli 支持 bash/zsh/pwsh（含动态），暂无 fish（cobra/urfave 有）。
-4. **细节**：man 文档的 Examples 暂折叠为单行；kong 的自定义类型映射器机制更完备。
+4. **细节**：kong 的自定义类型映射器机制更完备。
 
 **不适合**：深度依赖社区生态/标准 POSIX 默认行为、或需要最大社区背书的项目 → cobra 更稳。强类型纯声明式解析（无需周边）→ kong 更轻。