为什么字幕擦除不建议默认全屏，而更适合多区域？
2026/9/11 17:56:41
SerenityOS 手册页编写指南：WritingManPages 规范与 man(7) 体系详解
【免费下载链接】serenityThe Serenity Operating System 🐞项目地址: https://gitcode.com/GitHub_Trending/se/serenity
本文是 SerenityOS 官方《WritingManPages.md》手册页编写指南的完整技术解读，围绕"什么内容该写入手册页、手册页采用什么格式与结构、如何正确书写标题与链接"三大主线展开，并结合 Base/usr/share/man 目录下的真实手册页实例与 Meta/convert-markdown-links.lua 渲染转换脚本，给出可直接照搬的写作模板与可验证的源码级依据。读完本文，你将掌握编写一份符合 SerenityOS 规范、能通过 linter 检查并在man(1)与 Help 应用中正确显示的手册页的全部要点。
关联文档与配套资源导读
本指南对应的官方文档位于 Documentation/WritingManPages.md，它是 SerenityOS 手册页（manpages）的作者指南。理解这份指南需要配合以下仓库资源：
- man(7) 系统结构文档：手册页系统的主结构说明，定义了 section 划分、命名约定与访问方式，是撰写本文第 1、2 节内容的主要依据；
- 手册页目录：按 section 组织的全部真实手册页（
man1到man8共 8 个主 section），是格式模板的最佳实例来源； - convert-markdown-links.lua：构建时负责把
help://man/...伪协议链接转换为.html站内链接的脚本，直接佐证了"链接规范"一节所述规则的实现。
一、什么内容该写入手册页
指南开篇就划定了手册页与开发者文档的边界：
"The SerenityOS manpages are the primary documentation for SerenityOS itself."
手册页是 SerenityOS面向操作系统使用者的一等文档，与面向开发者的Documentation目录是互补关系。判断标准只有一个问题：
"Would this information be useful to view within the OS?"（这条信息在操作系统内查看是否有用？）
如果答案"是"，该信息就属于手册页；如果答案是"否"（例如面向内核开发者的构建流程、贡献规范），则属于 Documentation 目录下的开发者文档。这一分工在 man(7) 中也有呼应——手册页面向用户与开发者，"one of the two parts of the SerenityOS documentation"，而开发者文档则聚焦于搭建安装环境与贡献工作流。
一个典型的应用场景：w命令的手册页 w(1) 描述"Show information about currently logged-in users"，这是用户在终端里会实际查阅的信息，因此属于man1（User Programs）而非开发者文档。
二、手册页体系与格式总览
2.1 手册页的物理组织
根据 man(7)，每份 SerenityOS 手册页都是一个 Markdown（.md）文件，位于系统内/usr/share/man下，对应仓库中的 Base/usr/share/man。主 section 以man1至man8子目录组织：
| Section | 内容 | 仓库目录示例 |
|---|---|---|
| 1 | User Programs（用户程序与工具） | man1 |
| 2 | System Calls（系统调用接口） | man2 |
| 3 | Library Functions（C 库函数） | man3 |
| 4 | Special Files（虚拟文件系统伪文件） | man4 |
| 5 | File Formats（SerenityOS 特有文件格式） | man5 |
| 6 | Games（游戏） | man6 |
| 7 | Miscellanea（其他杂项） | man7 |
| 8 | Sysadmin Tools（系统管理工具） | man8 |
子 section（Subsections）：当某个 section 内页面过多或高度相关时，可建立子 section。子 section 本身必须有独立页面，至少说明其用途并列全其中包含的页面。例如 man5/GML 与 man1/Applications 都是典型的子 section 索引页。
命名约定（POSIX 风格）：页面名后以方括号跟 section 号，例如man(7)（系统主题）与man(1)（同名终端程序）；子 section 页面用斜杠目录记法，例如GML/Widget/Button(5)。命令行阅读时 section 单独作为参数：7 man、1 man或7 Mitigations。
2.2 格式：CommonMark Markdown
手册页一律使用CommonMark Markdown书写。指南明确：Serenity 的 markdown 工具链不支持的特性"允许使用，但不理想"——即优先使用工具链已支持的特性，避免为了花哨语法牺牲可渲染性。所有页面以.md后缀存放于 Base/usr/share/man 对应 section 目录下。
2.3 标题层级约束
手册页的最高标题级别是##（二级标题），不使用#。这一约束保证页面在 man 渲染器与 Help 应用中层级一致，且便于程序化解析页面结构。
三、链接规范：help 伪协议与资源引用
链接是手册页编写中最容易出错、也最受 linter 约束的部分，指南给出了三条明确规则：
3.1 手册页互链必须使用help://man/伪协议
链接到其他手册页必须使用如下格式：
help://man/section/page其中section是主 section 号，page是页面名（可含子 section 路径）。官方示例：
help://man/1/Applications/FontEditor help://man/7/boot_parameters这一格式由 manpage linter 强制检查。其实现可从 Meta/convert-markdown-links.lua 中得到源码级佐证：
el.target = string.gsub(el.target, "help://man/([^/]*)/(.*)", "/man%1/%2.html")即构建渲染阶段会把help://man/7/boot_parameters这类目标重写为/man7/boot_parameters.html站内链接。因此切勿在页面间互链时使用相对路径或绝对文件路径，否则要么无法通过 linter，要么构建后链接失效。
仓库中的真实用法示例（w(1)）：
## See also - `whoami`(1) - `utmpupdate`(1) - `usermod`(8)3.2 外部在线资源：允许直链
手册页允许链接外部在线资源。但注意本指南的输出规范：本文不输出外部网站链接，读者在仓库内即可找到全部所需信息。
3.3 本地资源：两种推荐方式
- 手册页专属资源（如应用截图）：建议放在手册页所在目录旁边，随页面一起维护；
- 系统级资源：作为 SerenityOS 基础文件（Base 的一部分），以绝对路径引用，例如
/res/graphics/map.png。
两种路径在发布到 man 站点时都会被自动转换以正确工作。这一点与本文所引用的仓库内部相对路径转换规则一致——文中所有仓库文件均以仓库根目录相对路径给出。
四、标题与语言风格
4.1 句子式大小写（Sentence Case）
页面标题必须使用句子式大小写（仅首字母及专有名词大写），而非书籍标题式大小写。这是项目整体的语言风格规范在手册页上的延伸。
4.2 Name 小节：一句话命名
每份手册页以## Name开头，其中最多一句话命名该页面。推荐使用破折号格式：
Short title - full name or single-sentence descriptor官方示例：
- 缩写展开型：
INI - generic config file format (.ini)（见真实页面 ini(5) 的## Name）； - 应用描述型：
w - Show information about currently logged-in users（见 w(1)）。
仅当使用完整句子而非破折号格式时才需要句号结尾。
带图标的应用：若页面描述的应用有图标，必须在文字名称前以行内方式链接 16x16 图标，alt 文本固定为 "Icon"，例如：
[](https://link.gitcode.com/i/bf82865b41d4da931c407c5be31e9dd2) Certificate Settings五、手册页最小结构：Name / Description / See also
所有手册页至少包含以下三个 section：
## Name The manpage name, in the style described above. ## Description Main text of the manpage. ## See also List of related pages.## See also的细节要求：
- 列出相关手册页，也可链接相关外部页面；
- 即使正文中已链过相关页，只要与整页主题相关，仍应在此列出；
- 互链原则：页面 A 链接页面 B 时，B 也应回链 A，双向互链便于在 man 系统内导航；
- 若确无相关页面，
See also可省略。
man(7) 自身的结尾即展示了 See also 的规范写法：
## See Also - `man`(1) To read manpages in the terminal - `Help`(1) To read manpages in a GUI六、命令行程序（section 1/8）的完整结构模板
对 section 1 与 section 8 中的程序，尤其是命令行工具，指南规定了更完整的固定结构，这也是编写新工具手册页时最实用的模板：
## Name program name - single-sentence descriptor of the program ## Synopsis Usage synopsis for invoking the program, within a `sh` code block. ## Description Prose description of the program. ## Options A list of optional arguments (flags) the program takes, with a brief description of each. More complex description, especially when options interact, should be part of the Description section. May be omitted if the program has no options. ## Arguments A list of (required) arguments the program takes, in the same format as the Options section. May be omitted if the program has no arguments. ## Examples Program invocation examples with resulting output. ## See also List of related pages.要点解读：
- Synopsis 必须用
sh代码块包裹调用语法，保证终端用户可复制； - Options 与 Arguments 分开：可选参数（flags）归 Options，必选参数归 Arguments，二者格式一致、均可按需省略（程序无选项/无参数时）；
- 复杂的、选项间交互行为的说明应放到 Description 而不是 Options 里；
- 其他描述性 section 可放在 Description 之下作为子 section，或紧跟其后。
实战实例：按模板落地的 w(1)
以仓库中 w(1) 为例，可看到该模板的完整落地：
## Name w - Show information about currently logged-in users ## Synopsis ```sh $ w [--no-header] [user]Options
-h,--no-header: Don't show the header
Arguments
user: Only show information about the specified user
See also
whoami(1)utmpupdate(1)usermod(8)
注意其写法细节：Options 与 Arguments 使用无序列表，每项以 `-` 开头、后跟反引号包裹的选项名与冒号分隔的简短说明；Synopsis 中的参数用方括号表示可选。程序无 Examples 时该 section 可省略（w(1) 即未包含 Examples）。 ### 实例对照：包含 Examples 与资源链接的 ini(5) 文件格式类页面（section 5）同样遵循 Name/Description/See also 骨架，并可扩展 Examples 等小节。[ini(5)](https://link.gitcode.com/i/54097333f21e18c995cdb5e3d92743e0) 展示了另一种重要写法——在正文中链接真实配置文件与源码佐证（其内部链接已按本指南要求转换为仓库根目录相对路径）： ```md ## Name INI - generic config file format (.ini) ## Description INI files serve as human-readable configuration files. They consist of key-value pairs separated by '=', optionally located under a unique group in square brackets. Additionally, [Userland/Libraries/LibCore/ConfigFile.cpp](https://link.gitcode.com/i/6bf7349b49a6ea9f1bcec46730811e97) supports comments: the characters '#' and ';' skip the entire line only if they appear at the beginning of the line. ## Examples [etc/Keyboard.ini](https://link.gitcode.com/i/ff150c07bb8bd0d2f808058d373b471d) ```ini [Mapping] Keymaps=en-us这印证了指南中"为描述的概念提供示例总是受欢迎的"这一要求，也演示了如何把实现细节（注释字符行为）与示例配置一并写入手册页。 ## 七、写作自检清单 综合指南全部要点，编写或评审一份手册页时可对照以下清单： 1. **归属判断**：这条信息在 OS 内查看是否有用？有用 → 手册页；开发者工作流 → [Documentation](https://link.gitcode.com/i/26ec1e5b0421653c6e68e9acdeeb9497)。 2. **目录选择**：按 [man(7)](https://link.gitcode.com/i/be229f197cc795a3b9cebf33dcb49aa4) 的 section 定义放入正确目录；页面过多则考虑子 section，并为子 section 建立索引页。 3. **格式**：CommonMark Markdown；最高标题为 `##`；句子式大小写标题。 4. **Name**：以 `## Name` 开头，一句话，优先 `短标题 - 一句话描述` 格式；有图标的应用先放 `Icon`。 5. **最小结构**：至少包含 `## Name`、`## Description`、`## See also`（无相关页时可省略）。 6. **命令行程序模板**：section 1/8 程序按 `Name → Synopsis（sh 代码块）→ Description → Options → Arguments → Examples → See also` 顺序组织，无对应内容的小节可省略。 7. **链接规范**：手册页互链一律用 `help://man/section/page` 伪协议（linter 强制，[转换脚本](https://link.gitcode.com/i/8d67dea3ef95747b647697d878855fbf)会将其重写为 `.html`）；系统资源用 `/res/...` 绝对路径；页面专属资源放手册页目录旁；`See also` 互链双向。 8. **示例**：对复杂概念尽量给出可运行示例与输出。 遵循以上规范写出的手册页，将被 [man(1)](https://link.gitcode.com/i/2923cd1e244c9abff7d55e17060b1c58) 终端工具、[Help](https://link.gitcode.com/i/31fc4b9e8bec61f28d11ae2e839528d5) 图形应用正常渲染，也能在手册页构建流程中通过 linter 检查并正确发布。【免费下载链接】serenityThe Serenity Operating System 🐞项目地址: https://gitcode.com/GitHub_Trending/se/serenity
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考