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这是用户在终端里会实际查阅的信息因此属于man1User Programs而非开发者文档。二、手册页体系与格式总览2.1 手册页的物理组织根据 man(7)每份 SerenityOS 手册页都是一个 Markdown.md文件位于系统内/usr/share/man下对应仓库中的 Base/usr/share/man。主 section 以man1至man8子目录组织Section内容仓库目录示例1User Programs用户程序与工具man12System Calls系统调用接口man23Library FunctionsC 库函数man34Special Files虚拟文件系统伪文件man45File FormatsSerenityOS 特有文件格式man56Games游戏man67Miscellanea其他杂项man78Sysadmin Tools系统管理工具man8子 sectionSubsections当某个 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: Dont show the headerArgumentsuser: Only show information about the specified userSee alsowhoami(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] Keymapsen-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 → Synopsissh 代码块→ 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），仅供参考