幽冥大陆(六十三) roff 语言：核心用途与使用指南

roff（全称 Runoff）是一套经典的文本排版标记语言，起源于 Unix 早期（1970 年代由 Joe Ossanna 开发），核心包含troff（排版输出）、nroff（终端 / 纯文本输出）等工具，是 Unix/Linux 系统中手册页（man page）的默认排版引擎，至今仍在系统文档、技术手册、纯文本书籍排版中广泛使用。

一、roff 的核心用途

1. 系统文档排版（最核心）

Unix/Linux 下的man手册页（如man ls看到的内容）几乎全部由man宏包（基于 roff）编写，roff 负责将标记化的文本转换为终端可读的格式（nroff）或打印格式（troff）。

2. 纯文本 / 打印文档排版

生成技术手册、论文、书籍（支持分页、字体、缩进、列表、表格、数学公式等）；
输出格式灵活：可直接输出到终端、PostScript/PDF、打印机，或转换为 HTML/TeX 等。

3. 自动化文档生成

结合脚本（Shell/Python）批量生成标准化文档（如 API 手册、系统说明），适合需要 “文本源文件 + 排版规则” 分离的场景。

4. 小众但不可替代的场景

嵌入式系统 / 极简环境：仅依赖系统自带的 roff 工具（无需复杂排版软件）；
历史系统兼容：老 Unix 文档的维护与渲染。

二、roff 的基础使用

1. 核心工具与环境

roff 不是单一程序，而是工具链，核心组件：

工具	用途
`nroff`	终端 / 纯文本输出（如 man 手册）
`troff`	排版输出（打印、PostScript/PDF）
`groff`	GNU 实现的 roff（主流，Linux 默认）
`man`	基于 groff/nroff 的手册页渲染工具
宏包	简化排版（如`man`、`ms`、`me`、`mm`）

前置条件：Linux/macOS 自带 groff（如无则安装：sudo apt install groff/brew install groff）。

2. 基本语法规则

roff 文本由普通文本+控制命令组成，命令以.（点）开头（宏命令）或\（反斜杠）开头（转义命令），区分大小写。

核心概念：

宏（Macro）：预定义的排版指令（如.SH定义章节标题），不同宏包（man/ms）语法不同；
请求（Request）：基础排版指令（如.br换行、.sp空行）；
转义序列：行内格式控制（如\fB粗体、\fI斜体）。

3. 入门示例：编写简单的 roff 文档

示例 1：man 宏包（手册页风格）

创建文件demo.1：

roff

.TH MYTOOL 1 "2025-12-24" "V1.0" "User Commands" .SH NAME mytool - a demo tool for roff example .SH SYNOPSIS .B mytool [\-h] [\-v] <file> .SH DESCRIPTION This is a \fIdemo\fR of roff/man syntax: .RS - \fB\-h\fR: Show help message - \fB\-v\fR: Show version .RE .SH AUTHOR Your Name <your@email.com>

渲染与查看：

bash

运行

# 方式1：用 nroff 渲染为终端格式 nroff -man demo.1 | less # 方式2：生成 PostScript（可转 PDF） groff -man -Tps demo.1 > demo.ps ps2pdf demo.ps demo.pdf # 转 PDF（需安装 ghostscript） # 方式3：模拟 man 手册查看 man ./demo.1 # 直接以手册页形式打开

示例 2：ms 宏包（通用文档风格）

创建文件doc.ms：

roff

.TL Title of My Document .AU Author Name .AB Abstract: This is a simple roff document with ms macros. .AE .SH Introduction This is the first section. .PP A new paragraph with \fBbold\fR and \fIitalic\fR text. .SH Conclusion End of document.

渲染：

bash

运行

# 终端输出 nroff -ms doc.ms | less # 生成 PDF groff -ms -Tps doc.ms | ps2pdf - doc.pdf

4. 常用 roff 命令 / 转义序列（man 宏包）

命令 / 序列	用途	示例
`.TH`	定义手册页标题	`.TH MYTOOL 1 "2025" "V1.0"`
`.SH`	一级章节标题	`.SH DESCRIPTION`
`.SS`	二级章节标题	`.SS Options`
`.B`	粗体文本	`.B \-h`
`.I`	斜体文本	`.I filename`
`.RS/.RE`	缩进 / 结束缩进	用于列表
`.PP`	新段落
`\fB`	行内粗体开始	`\fBbold\fR`
`\fI`	行内斜体开始	`\fIitalic\fR`
`\fR`	恢复默认字体
`.br`	强制换行
`.sp`	空行（.sp 2 空 2 行）	`.sp 1`

三、进阶使用

1. 自定义宏

可在 roff 文档中定义自定义宏，简化重复排版：

roff

.de MYLIST # 定义名为 MYLIST 的宏 .IP \- 4 # 列表项缩进4个字符 .. # 结束宏定义 .MYLIST First item .MYLIST Second item

2. 数学公式（eqn）

roff 配合eqn工具支持数学公式排版：

roff

.EQ E = mc^2 .EN

渲染时需加-e参数：groff -ms -e -Tps doc.ms > doc.ps。

3. 表格（tbl）

配合tbl工具制作表格：

roff

.TS center,box; c c c; l l l. Header1 Header2 Header3 Row1 Col2 Col3 Row2 Col2 Col3 .TE

渲染时需加-t参数：groff -ms -t -Tps doc.ms > doc.ps。

四、学习资源与工具

官方手册：
- man groff：GNU roff 总览；
- man man-pages：man 手册页编写规范；
- man 7 groff_man：man 宏包详细说明。
在线教程：
- GNU Groff 手册：https://www.gnu.org/software/groff/manual/
- 《Unix Text Processing》（经典书籍，涵盖 roff/troff）。
工具：
- groff：核心排版工具；
- ps2pdf：PostScript 转 PDF；
- vim/emacs：编辑器（有 roff 语法高亮）。

阿雪技术观

让我们积极投身于技术共享的浪潮中，不仅仅是作为受益者，更要成为贡献者。无论是分享自己的代码、撰写技术博客，还是参与开源项目的维护和改进，每一个小小的举动都可能成为推动技术进步的巨大力量

Embrace open source and sharing, witness the miracle of technological progress, and enjoy the happy times of humanity! Let's actively join the wave of technology sharing. Not only as beneficiaries, but also as contributors. Whether sharing our own code, writing technical blogs, or participating in the maintenance and improvement of open source projects, every small action may become a huge force driving technological progrss.