mandoc.1
MANDOC(1)
MANDOC(1)
FreeBSD General Commands Manual
MANDOC(1)
mandoc —
格式化手册页
mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options] [-T output] [-W level] [file ...]
mandoc 实用程序格式化手册页以供显示。
默认情况下， mandoc 从标准输入读取 mdoc(7) 或 man(7) 文本并生成 -T locale 输出。
选项如下：
如果标准输出是终端设备并且未指定 -c ，则使用 more(1) 对输出进行分页，就像 man(1) 一样。
将格式化的手册页复制到标准输出，而不使用 more(1) 对其进行分页。这是默认设置。可以指定覆盖 -a -。
-I os=name
覆盖 mdoc(7) Os 操作系统和 man(7) TH 宏的默认操作系统 name 。
-K encoding
指定输入编码。支持的 encoding 参数是 us-ascii, iso-8859-1 和 utf-8 。如果未指定，自动检测将使用以下列表中的第一个匹配项：
如果输入文件的前三个字节是 UTF-8 字节顺序标记（BOM，0xefbbbf），输入被解释为
utf-8 。如果输入文件的第一行或第二行匹配 emacs 模式行格式
.\" -*- [...;] coding: encoding; -*-
然后根据 encoding 解释输入。
如果文件中的第一个非 ASCII 字节引入了有效的 UTF-8 序列，则输入被解释为
utf-8 。否则，输入被解释为
iso-8859-1 。
使用 -mdoc, 所有输入文件都被解释为 mdoc(7) 。 使用 -man, 所有输入文件都被解释为 man(7) 。 默认情况下，自动检测每个文件的输入语言：如果第一个宏是 Dd 或 Dt, 则使用 mdoc(7) 解析器；否则，使用 man(7) 解析器。对于其他参数， -m 会被静默忽略。
-O options
逗号分隔的输出选项。有关支持的 options ，请参阅各个输出格式的描述。
-T output
选择输出格式。 output 参数支持的值为 ascii 、 html 、 locale 的默认值、 man, markdown, pdf 、 ps 、 tree 和 utf8 的默认值。
特殊的 -T lint 模式只解析输入并且不产生输出。它暗示 -W all 并将解析器消息（通常出现在标准错误输出中）重定向到标准输出。
-W level
指定要在标准错误输出上报告并影响退出状态的最小消息 level 。 level 可以是 base, style, warning, error, 或 unsupp 。 base 级别自动从 Os 宏的内容、 -Ios 命令行选项或 uname(3) 返回值派生操作系统。 openbsd 和 netbsd 级别是 base 的变体，它们绕过自动检测并请求验证特定操作系统的基本系统约定。 级别 all 是 base 的别名。默认情况下， mandoc 是静默的。有关详细信息，请参阅 退出状态 和 诊断 。
特殊选项 -W stop 告诉 mandoc 在解析导致至少为请求级别的警告或错误的文件后退出。该文件不会产生格式化的输出。 如果同时请求 level 和 stop ，则可以用逗号连接它们，例如 -W error,stop 。
file
从给定的输入文件中读取。如果指定了多个文件，则按给定顺序处理它们。如果未指定， mandoc 从标准输入读取。
选项 -fhklw 也受支持，并记录在 man(1). 中。在 -f 和 -k 模式下， mandoc 还支持 apropos(1) 手册中描述的选项 -CMmOSs 。选项 -fkl 是互斥的并且相互覆盖。
使用 -T ascii 强制以 ascii(7) 手册页中记录的 7 位 ASCII 字符编码输出文本，忽略环境中设置的 locale(1) 。
字体样式通过使用退格编码来应用，这样带下划线的字符 ‘c’ 被渲染为 ‘_\[bs]c’, 其中 ‘\[bs]’ 是退格字符编号 8。 渲染加粗字符作为 ‘c\[bs]c 。’ 该标记通常由寻呼机或 ul(1) 转换为适当的终端序列。要删除标记，请将输出通过管道传递给 col(1) -b 。
mandoc_char(7) 中记录的特殊字符将尽最大努力以 ASCII 等效形式呈现。特别是，打开和关闭 ‘single quotes’ 分别表示为字符编号 0x60 和 0x27，这符合从 1965 年到最新版本 (2012) 的所有 ASCII 标准，并且与 roff(7) 格式化程序表示的传统方式相匹配ASCII 输出中的单引号。这种正确的 ASCII 渲染对于现代 Unicode 兼容字体可能看起来很奇怪，因为与 ASCII 相反，Unicode 仅将代码点 U+0060 用于重音，从不用于开头引号。
接受以下 -O 参数：
indent=indent
普通文本的左边距设置为 indent 空白字符，而不是 mdoc(7) 的默认值 5 和 man(7) 的默认值 7。 不建议增加此值；它可能会导致格式降级，例如过满的行或难看的换行符。当输出到小于 66 列宽的终端上的寻呼机时，默认值减少到三列。
以 mdoc(7) 输出样式格式化 man(7) 输入文件。具体来说，这会抑制每页顶部和底部附近的两个额外空行，这意味着 -O indent=5 。一个有用的应用程序是检查 -T man 输出格式是否与生成它的 mdoc(7) 源相同。
tag[=term]
如果格式化的手册页是在寻呼机中打开的，请转到 term 的定义，而不是从头开始显示手册页。如果未指定 term ，重用第一个不是 section 号的命令行参数。 如果该参数采用 apropos(1) key=val 格式，则仅使用 val 而不是整个参数。这对于诸如 ‘man -akO tag Ic=ulimit’ 之类的命令来搜索关键字并直接跳转到匹配手册页中的定义非常有用。
width=width
输出宽度设置为 width 而不是默认值 78。当输出到小于 79 列宽的终端上的寻呼机时，默认值减小到比终端宽度小一。在任何情况下，以文字模式输出的行都不会被换行，并且可能超出输出宽度。
-T html 产生的输出使用可选的自闭合标签符合 HTML5。默认样式仅使用 CSS1。从 eqn(7) 块渲染的方程使用 MathML。
文件 /usr/share/misc/mandoc.css 记录可用于自定义输出的样式表类。如果未使用 -O style 指定样式表，则 -T html 默认为在任何图形或基于文本的 Web 浏览器中可读的简单输出（通过嵌入式样式表）。
非 ASCII 字符呈现为十六进制 Unicode 字符引用。
接受以下 -O 参数：
省略 声明和 、 和 元素，只发出 元素下方的子树。 style 参数将被忽略。这在将手动内容嵌入现有文档时很有用。
includes=fmt
字符串 fmt ，例如 ../src/%I.html ，用作链接头文件的模板（通常通过 In 宏）。 ‘%I’ 的实例被替换为包含文件名。默认不显示超链接。
man=fmt[;fmt]
字符串 fmt ，例如 ../html%S/%N.%S.html ，用作链接手册的模板（通常通过 Xr 宏）。 ‘%N’ 和 ‘%S’ 的实例分别替换为链接手册的名称和章节。如果不包括任何部分，则假定为第 1 部分。默认不显示超链接。如果给出了两种格式并且当前目录中存在文件 %N.%S ，则使用第一种格式；否则，使用第二种格式。
style=style.css
文件 style.css 用于外部样式表。这必须是有效的绝对或相对 URI。
如果输入文件包含至少两个非标准部分，则在输出开头附近打印目录。
默认情况下， mandoc 根据当前的 locale(1) 自动选择 UTF-8 或 ASCII 输出。如果设置任何环境变量 LC_ALL 、 LC_CTYPE 或 LANG ，并且设置的第一个选择 UTF-8 字符编码，它会产生 UTF-8 输出; 否则，它会退回到 ASCII 输出。 也可以使用 -T locale 显式选择此输出模式。
使用 -T man 将 mdoc(7) 输入转换为 man(7) 输出格式。这对于将手动资源分发到缺少 mdoc(7) 格式化程序的遗留系统很有用。
如果文件的输入格式是 man(7), 则输入被复制到输出，扩展任何 roff(7) so 请求。 解析器也会运行，并且像往常一样， -W 级别控制在将输入复制到输出之前显示哪些 DIAGNOSTICS 。
使用 -T markdown 将 mdoc(7) 输入转换为符合 "John Gruber's 2004 specification" 的 markdown 格式: 。 输出也几乎符合 CommonMark: 规范。
用于 markdown 输出的字符集是 ASCII。非 ASCII 字符被编码为 HTML 实体。由于这在文字字体上下文中是不可能的，因为它们在 markdown 输出中呈现为代码跨度和代码块，因此非 ASCII 字符在这些上下文中被音译为 ASCII 近似值。
Markdown 是一种非常弱的标记语言，因此所有语义标记都会丢失，甚至可能会丢失部分表示性标记。不要将此作为转换为 HTML 的中间步骤；相反，直接使用 -T html 。
-T markdown 输出模式不支持 man(7) 、 tbl(7) 和 eqn(7) 输入语言。
PDF-1.1 输出可能由 -T pdf 生成。请参阅 PostScript 输出 以了解 -O 参数和默认值。
PostScript “Adobe-3.0” Level-2 页面可以由 -T ps 生成。输出页面默认为字母大小，并以 Times 字体系列呈现，11 磅。边距计算为页面长度和宽度的 1/9。线高为1.4m。
特殊字符在 ASCII 输出 中呈现。
接受以下 -O 参数：
paper=name
纸张尺寸 name 可以是 a3 、 a4 、 a5 、 legal 或 letter 之一。您也可以手动将尺寸指定为 NNxNN, 宽乘高（以毫米为单位）。如果遇到未知值，则使用 letter 。
使用 -T utf8 强制以 UTF-8 多字节字符编码输出文本，忽略环境中的 locale(1) 设置。关于字体样式和 -O 参数，请参见 ASCII 输出 。
在缺乏区域设置或宽字符支持的操作系统上，以及内部字符表示不是 UCS-4 的操作系统上， mandoc 总是回退到 ASCII 输出 。
使用 -T tree 显示语法树的人类可读表示。它对于调试手册页的源代码很有用。确切的格式可能会发生变化，所以不要为它编写解析器。
第一段显示在 mdoc(7) 序言中找到的元数据，在 man(7) TH 行，或使用的后备。
在树转储中，每个输出行显示一个语法树节点。子节点相对于其父节点缩进。这些列是：
对于宏节点，宏名称；对于 text 和 tbl(7) 节点，内容。 eqn(7) 节点有一种特殊的格式。
节点类型 (text、 elem、 block、 head、 body、 body-end、 tail、 tbl、 eqn)。
标志：
如果节点是左分隔符，则为左括号。
如果节点开始新的输入行，则为星号。
输入行号（从一开始）。
一个冒号。
输入列号（从一开始）。
如果节点是右分隔符，则右括号。
如果节点结束一个句子，则为句号。
BROKEN 如果节点是被另一个块破坏的块。
如果节点不在输入文件中，而是从宏自动生成，则为 NOSRC。
如果节点不应该为任何输出格式生成输出，则为 NOPRT。
接受以下 -O 参数：
跳过验证并显示未经验证的语法树。这可以帮助找出给定的行为是由解析器还是由验证器引起的。在这种情况下，元数据不可用。
字符编码 locale(1) 。选择 Locale Output 时，它会决定是否使用 ASCII 或 UTF-8 输出格式。它从不影响输入文件的解释。
使用环境变量 MANPAGER 的任何非空值代替标准分页程序， more(1); 有关详细信息，请参见 man(1) 。仅在指定 -a 或 -l 时使用。
指定未定义 MANPAGER 时要使用的分页程序。如果 PAGER 和 MANPAGER 均未定义，则使用 more(1) -s 。仅在指定 -a 或 -l 时使用。
mandoc 实用程序以下列值之一退出，由与 -W 选项关联的消息 level 控制：
0
没有发生基本系统约定违规、样式建议、警告或错误，或者那些因为低于请求的 level 而被忽略的错误。
1
至少发生一次基本系统约定违规或样式建议，但没有警告或错误，并且指定 -W base 或 -W style 。
2
至少发生一个警告，但没有错误，并且请求 -W warning 或更低 level 的警告。
3
至少发生一个解析错误，但没有遇到不受支持的功能，并且请求 -W error 错误或更低 level 。
4
至少发生一个不受支持的功能，并且请求 -W unsupp 或更低 level 。
5
指定无效的命令行参数。未读取任何输入文件。
6
发生操作系统错误，例如内存、文件描述符或进程表条目耗尽。此类错误可能会导致 mandoc 立即退出，可能是在解析或格式化文件的过程中。
请注意，选择 -T lint 输出模式意味着 -W all 。
要将手册翻页到终端：
$ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
使用 /usr/share/misc/mandoc.css 作为样式表生成 HTML 手册：
$ mandoc -T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html
要查看大量手册：
$ mandoc -T lint `find /usr/src -name \*\.[1-9]`
制作一系列 PostScript A4 手册：
$ mandoc -T ps -O paper=a4 mdoc.7 man.7 > manuals.ps
将现代 mdoc(7) 手册转换为较旧的 man(7) 格式，以便在缺少 mdoc(7) 解析器的系统上使用：
$ mandoc -T man foo.mdoc > foo.man
mandoc 显示的消息遵循以下格式：
mandoc: file:line:column: level: message: macro arguments (os)
前三个字段标识触发消息的输入文件的 file 名、 line 号和 column 号。行号和列号从 1 开始。对于将输入文件作为一个整体引用的消息，两者都被省略。 下面解释所有 level 和 message 字符串。触发消息的 macro 名称及其 arguments 在无意义的地方被省略。对于与所有操作系统相关的消息，省略 os 操作系统说明符。有关无效命令行参数或操作系统错误的致命消息（例如内存耗尽时）也可能会省略 file 和 level 字段。
消息级别具有以下含义：
发生操作系统错误。输入文件不一定有任何问题。输出可能同样缺失或不完整。
指定无效的命令行参数。没有读取输入文件，也没有产生输出。
输入文件使用不受支持的低级 roff(7) 功能。输出可能不完整和/或格式错误，因此使用 GNU troff 而不是 mandoc 来处理文件可能更可取。
表示存在信息丢失或严重格式错误的风险，在大多数情况下是由严重的语法错误引起的。
表示所显示的信息或其格式可能与作者的意图略有不符的风险。此外，语法错误至少被归类为警告，即使它们通常不会导致格式错误。
输入文件使用可疑或不鼓励的样式。这不是对语法的抱怨，而且格式和可移植性可能都没有危险。虽然在较高的消息级别上非常注意避免误报，但 style 级别会尝试降低问题被忽视的可能性，因此它可能偶尔会发出虚假建议。 请使用良好判断，以决定是否任何特定的 style 建议需要对输入文件进行更改。
不遵守特定操作系统的基本系统中使用的约定。这些不是标记错误，格式质量和可移植性都没有危险。 base 级别的消息使用更直观的 style level 标记打印。
隐藏 base 、 style 、 warning 、 error 和 unsupp 级别的消息，除非使用 -W 选项或 -T lint 输出模式请求它们的级别或更低级别。
如下所示，仅当特定操作系统名称出现在 -W 命令行选项、 Os 宏、 -Ios 命令行选项的参数中，或者两者都不存在时，才会执行所有 base 和某些 style 检查, 在 uname(3) 函数的返回值中。
Mdocdate found
(mdoc, NetBSD) Dd 宏使用 CVS Mdocdate 键字替换， NetBSD 基本系统不支持这种替换。 考虑改用传统的 “Month dd, yyyy” 格式。
Mdocdate missing
(mdoc, OpenBSD)
Dd 宏不使用 CVS Mdocdate 关键字替换，但是在 OpenBSD 基本系统中通常会使用它。
unknown architecture
(mdoc, OpenBSD, NetBSD) Dt 宏的第三个参数与运行此操作系统的任何体系结构都不匹配。
operating system explicitly specified
(mdoc, OpenBSD, NetBSD) Os 宏有一个参数。在基本系统中，它通常是空白的。
RCS id missing
(OpenBSD, NetBSD) 手册页缺少注释行，其中包含由 CVS OpenBSD 或 NetBSD 关键字替换生成的 RCS 标识符，这些操作系统中通常使用这些标识符。
referenced manual not found
(mdoc) Xr 宏引用了在基本系统中找不到的手册页。查找基本系统手册的路径可在编译时配置，默认为 /usr/share/man: /usr/X11R6/man.
遗留 man(7) 日期格式
(mdoc) Dd 宏使用旧版 man(7) 日期格式 “yyyy-dd-mm 。” 考虑改用传统的 mdoc(7) 日期格式 “Month dd, yyyy” 。
日期格式标准化为: ...
(mdoc, man) Dd 或 TH 宏提供缩写的月份名称或带有前导零的日期编号。在格式化的输出中，完整地写出月份名称，并且省略前导零。
文档标题中的小写字符
(mdoc, man) 标题仍然按照 Dt 或 TH 宏中给出的方式使用。
重复的 RCS id
单个手册页包含同一操作系统的 RCS 标识符的两个副本。考虑删除后面的实例并将第一个实例移到页面顶部。
部分名称中可能存在拼写错误
(mdoc) 模糊字符串匹配显示 Sh 宏的参数与标准节名称相似，但不完全相同。
未终止的引用参数
(roff) 宏参数可以用双引号字符括起来，这样引号参数中包含的空格字符和宏名称就不需要转义。宏的最后一个参数的右引号可以省略。但是，不建议省略它，因为它会使代码更难阅读。
没用的宏
(mdoc) 找到 Bt 、 Tn 或 Ud 宏。只需删除它：它没有任何用处。
考虑使用 OS 宏
(mdoc) 在纯文本或可以使用 Ox 、 Nx 、 Fx 或 Dx 表示的 Bx 宏中找到一个字符串。
errnos 出故障
(mdoc, NetBSD) Bl 列表中的 Er 项目不是按字母顺序排列的。
重复错误
(mdoc, NetBSD) Bl 列表包含两个连续的 It 条目，描述相同的 Er 编号。
尾随分隔符
(mdoc) Ex 、 Fo 、 Nd 、 Nm 、 Os 、 Sh 、 Ss 、 St 或 Sx 宏的最后一个参数以尾随分隔符结尾。这通常是不好的风格，并且通常表示拼写错误。最有可能的是，可以删除分隔符。
尾随分隔符前没有空格
(mdoc) 支持尾随分隔符参数的宏的最后一个参数长于一个字节，并以尾随分隔符结束。考虑插入一个空格，使分隔符成为一个单独的参数，从而将其移出宏的范围。
填充模式已启用，正在跳过
(man) 即使文档仍处于填充模式或已切换回填充模式，也会发生 fi 请求。它没有效果。
填充模式已禁用，正在跳过
(man) 即使文档已经切换到无填充模式并且尚未切换回填充模式，也会发生 nf 请求。它没有效果。
逐字 "--", 也许考虑使用 \(em
(mdoc) 即使 ASCII 输出设备将 em-dash 呈现为 “--”, 这也不是将其写入输入文件的好方法，因为它在所有其他输出设备上呈现不佳。
没有标记的函数名
(mdoc) 文本行上出现一个单词，后面跟着一对空括号。考虑使用 Fn 或 Xr 宏。
输入行末尾的空格
(mdoc, man, roff) 输入行末尾的空格几乎从不具有语义意义 — 但在可能的奇怪情况下，在查看和维护文档时会非常混乱。
不好的注释风格
(roff) 注释行以点、反斜杠和双引号字符开头。 mandoc 实用程序将该行视为注释行，即使没有反斜杠，但省略反斜杠可能不便于移植。
缺少手册标题，使用 UNTITLED
(mdoc) Dt 宏没有参数，或者在第一个非序言宏之前没有 Dt 宏。
缺少手册标题，使用 ""
(man) 没有 TH 宏，或者它没有参数。
缺少手册部分，使用 ""
(mdoc, man) Dt 或 TH 宏缺少必需的节参数。
未知的手册章节
(mdoc) Dt 行中的节号无效，但仍在使用。
缺少日期，使用今天的日期
(mdoc, man) 文档被解析为 mdoc(7) 并且它没有 Dd 宏，或者 Dd 宏没有参数或只有空参数；或者文档被解析为 man(7) 并且它没有 TH 宏，或者 TH 宏的参数少于三个或其第三个参数为空。
无法解析日期，逐字使用
(mdoc, man) Dd 或 TH 宏中给出的日期不遵循常规格式。
将来的日期，无论如何都要使用它
(mdoc, man) Dd 或 TH 宏中给出的日期比当前系统 time(3) 提前一天多。
缺少 Os 宏，使用 ""
(mdoc) 在这种情况下不显示默认或当前系统。
后期序言宏
(mdoc) Dd 或 Os 宏出现在某个非序言宏之后，但仍然生效。
序言宏乱序
(mdoc) 序言宏未按常规顺序 Dd 、 Dt 、 Os 给出。即使以其他顺序给出，也会使用所有三个宏。
.so 很脆弱，最好使用 ln(1)
(roff) 仅当解析器程序使用正确的当前工作目录运行时，才包含文件。
没有文件正文
(mdoc, man) 文档正文既不包含文本也不包含宏。显示一个空文档，仅包含页眉和页脚行。
第一部分标题之前的内容
(mdoc, man) 某些宏或文本位于第一个 Sh 或 SH 节标题之前。有问题的宏和文本被解析并添加到语法树的顶层，在任何节块之外。
第一部分不是 NAME
(mdoc) 第一个 Sh 宏的参数不是 ‘NAME’ 。这可能会混淆 makewhatis(8) 和 apropos(1) 。
在 Nd 之前没有 Nm 的 NAME 部分
(mdoc) NAME 部分在第一个 Nm 之前不包含任何 Nd 子宏。
NAME 部分没有描述
(mdoc) NAME 部分缺少强制的 Nd 子宏。
描述不在 NAME 的末尾
(mdoc) NAME 部分确实包含一个 Nd 宏，但后面有其他内容。
错误的 NAME 部分内容
(mdoc) NAME 部分包含纯文本或除 Nm 和 Nd 之外的宏。
NAME 前缺少逗号
(mdoc) NAME 部分包含一个 Nm 宏，它既不是第一个宏，也不是以逗号开头。
缺少描述行，使用 ""
(mdoc) Nd 宏缺少所需的参数。手册的标题行将在破折号之后结束。
NAME 部分外的描述行
(mdoc) Nd 宏出现在 NAME 部分之外。无论如何都会打印参数，并且以下文本用于 apropos(1) ，但这些行为都不是可移植的。
不合常规的部分
(mdoc) 一个标准部分出现在它通常之前的另一个部分之后。所有章节标题均按原样使用，章节顺序不变。
重复的部分标题
(mdoc) 相同的标准章节标题不止一次出现。
意想不到的部分
(mdoc) 标准章节标题出现在手册中通常没用的章节中。
交叉引用自我
(mdoc) Xr 宏是指与当前手册页的部分匹配的名称和部分，以及在 NAME 或 SYNOPSIS 部分中的 Nm 宏中或在 SYNOPSIS 中的 Fn 或 Fo 宏中提到的名称。考虑使用 Nm 或 Fn 代替 Xr 。
不寻常的 Xr 顺序
(mdoc) 在 SEE ALSO 部分中，具有较低节号的 Xr 宏跟在具有较高号的 Xr 宏之后，或者引用同一节的两个 Xr 宏不按字母顺序排列。
不寻常的 Xr 标点符号
(mdoc) 在 SEE ALSO 部分中，两个 Xr 宏之间的标点符号不同于单个逗号，或者在最后一个 Xr 宏之后有尾随标点符号。
没有宏的 AUTHORS 部分
(mdoc) AUTHORS 部分不包含 An 宏，或者只包含空宏。也许，有些作者的名字缺乏标记。
过时的宏
(mdoc) 请参阅 mdoc(7) 手册。
宏既不可调用也不转义
(mdoc) 不可调用的宏的名称出现在宏行上。它是逐字打印的。如果打算调用它，请将其移动到自己的输入行；否则，通过添加 ‘\&’ 来转义它。
跳过段落宏
在 mdoc(7) 文档中，会发生这种情况
在章节和小节的开头和结尾
就在非紧凑列表和显示之前
在非列、非紧凑列表中的项目末尾
对于多个连续的段落宏。
在 man(7) 文档中，它发生
对于空的
P 、PP和LP宏对于既没有 head 也没有 body 参数的
IP宏在
SH或SS之后的br或sp
将段落宏移出列表
(mdoc) Bl 列表中的列表项包含尾随段落宏。段落宏移动到列表末尾之后。
跳过无空间宏
(mdoc) 输入行以 Ns 宏开头，或者 Ns 宏之后的下一个参数是独立的结束分隔符。宏被忽略。
严重嵌套的块
(mdoc) 如果两个块相交，一个应该完全包含另一个。否则，渲染的输出在任何输出格式中都可能看起来很奇怪，并且在基于 SGML 的输出格式中渲染可能是完全错误的，因为这些语言根本不支持严重嵌套的块。严重嵌套块的典型示例是 “Ao Bo Ac Bc” 和 “Ao Bq Ac 。” 在这些示例中， Ac 分别断开 Bo 和 Bq 。
嵌套显示不可移植
(mdoc) Bd 、 D1 或 Dl 显示嵌套在另一个 Bd 显示中。这适用于 mandoc, 但适用于大多数其他实现。
将内容移出列表
(mdoc) Bl 列表块在第一个 It 宏之前包含文本或宏。违规的子列表被移动到列表的开头之前。
行中的第一个宏
在 Bl -column 列表中， Ta 宏作为行上的第一个宏出现，这是不可移植的。
行范围损坏
(man) 在解析前一个宏的下一行作用域时，发现另一个宏过早地终止了前一个宏。从解析树中删除先前中断的宏。 与缺少参数有关的警告
跳过空请求
(roff, eqn) 宏定义请求中缺少宏名称，或者 eqn(7) 控制语句或操作关键字缺少所需的参数。
条件请求控制空范围
(roff) 条件请求仅在以下任何一项出现在同一逻辑输入行上时才有用：
‘\{’ 关键字打开多行范围。
请求或宏或一些文本，导致单行范围。
没有任何中间空格的逻辑行的直接结束，导致下一行范围。
在这里，条件请求后仅跟尾空格，其逻辑输入行上没有其他内容。请注意，是否使用 ‘\’ 行继续字符将逻辑输入行拆分为多个物理输入行并不重要。这是尾随空格在语法上很重要的罕见情况之一。条件请求只控制一个包含空格的范围，因此它不太可能产生重大影响，除了它可能控制后面的 el 子句。
跳过空宏
(mdoc) 指示的宏没有参数，因此没有效果。
空块
(mdoc, man) A Bd 、 Bk 、 Bl 、 D1 、 Dl 、 MT 、 RS 或 UR 块在其主体中不包含任何内容，并且不会产生任何输出。
空参数，使用 0n
(mdoc) Bd 或 Bl -offset 或 -width 后缺少所需的宽度。
缺少显示类型，使用 -ragged
(mdoc) 在没有所需显示类型的情况下调用 Bd 宏。
列表类型不是第一个参数
(mdoc) 在 Bl 宏中，至少一个其他参数位于类型参数之前。 mandoc 实用程序可以处理任何参数顺序，但其他一些 mdoc(7) 实现则不能。
-tag 列表中缺少 -width，使用 8n
(mdoc) 每个具有 -tag 参数的 Bl 宏也需要 -width -。
缺少实用程序名称，使用 ""
(mdoc) 在第一次使用参数调用 Nm 之前调用 Ex -std 宏而不使用参数。
缺少函数名，使用 ""
(mdoc) Fo 宏在没有参数的情况下被调用。不打印函数名称。
列表项中的空头
(mdoc) 在 Bl -diag -、 -hang -、 -inset -、 -ohang 或 -tag 列表中， It 宏缺少所需的参数。项目标题为空。
空列表项
(mdoc) 在 Bl -bullet -、 -dash -、 -enum 或 -hyphen 列表中， It 块为空。显示一个空列表项。
缺少参数，使用下一行
(mdoc) Bd -column 列表中的 It 宏没有参数。虽然 mandoc 对单元格使用下一行的文本或宏（如果有），但其他格式化程序可能会错误地格式化列表。
缺少字体类型，使用 \fR
(mdoc) Bf 宏没有参数。它切换到默认字体。
未知字体类型，使用 \fR
(mdoc) Bf 参数无效。而是使用默认字体。
前缀后面没有
(mdoc) Pf 宏没有参数，或者只有一个参数并且在同一输入行上没有宏。这违背它的目的；特别是，在下一个输入行之后的文本或宏之前不会抑制间距。
空参考块
(mdoc) An Rs 宏紧跟在下一个输入行上的 Re 宏。这样的空块不会产生任何输出。
缺少部分参数
(mdoc) Xr 宏缺少第二个节号参数。第一个参数，即名称，被打印出来，但没有后面的括号。
缺少 -std 参数，添加它
(mdoc) Ex 或 Rv 宏缺少所需的 -std 参数。 mandoc 实用程序假定 -std 即使未指定，但其他实现可能不会。
缺少选项字符串，使用 ""
(man) OP 宏在没有任何参数的情况下被调用。显示一对空的方括号。
缺少资源标识符，使用 ""
(man) MT 或 UR 宏在没有任何参数的情况下被调用。显示一对空的尖括号。
缺少 eqn 块，使用 ""
(eqn) 找到一个变音符号或一个二元运算符，但它的左边什么都没有。插入一个空框。
重复参数
(mdoc) Bd 或 Bl 宏具有多个 -compact -、 多个 -offset 或多个 -width 参数。除了这些参数的最后一个实例之外的所有实例都被忽略。
跳过重复参数
(mdoc) An 宏有多个 -split 或 -nosplit 参数。除了第一个参数外，所有参数都被忽略。
跳过重复的显示类型
(mdoc) Bd 宏有多个类型参数；使用第一个。
跳过重复列表类型
(mdoc) Bl 宏有多个类型参数；使用第一个。
跳过 -width 参数
(mdoc) Bl -column -、 -diag -、 -ohang -、 -inset 或 -item 列表具有 -width 参数。那没有效果。
错误的单元格数
在 Bl -column 列表的一行中，制表符或 Ta 宏的数量小于列表标题行的预期数量或超过预期数量一个以上。缺失的单元格保持为空，所有超过列数的单元格都连接到一个单元格中。
未知的 AT&T UNIX 版本
(mdoc) At 宏的参数无效。它是逐字使用的，前缀为 “AT&T UNIX ” 。
函数参数中的逗号
(mdoc) Fa 或 Fn 宏的参数包含逗号；它可能应该分为两个论点。
函数名中的括号
(mdoc) Fc 或 Fn 宏的第一个参数包含左括号或右括号；这可能是错误的，括号是自动添加的。
未知的库名称
(mdoc, 不在 OpenBSD 上) Lb 宏有一个未知的名称参数，将呈现为 “library “name 。””
Rs 块中的无效内容
(mdoc) Rs 块包含纯文本或非-% 宏。伪造的内容留在语法树中。格式可能很差。
无效的布尔参数
(mdoc) Sm 宏具有除 on 或 off 以外的参数。无效的参数被移出宏，使宏为空，导致它切换间距模式。
参数包含两个字体转义
(roff) char 请求的第二个参数包含多个字体转义序列。使用字符后，错误的字体可能会保持活动状态。
未知字体，跳过请求
(man, tbl) roff(7) ft 请求或 tbl(7) f 布局修饰符具有未知的 font 参数。
请求中的奇数个字符
(roff) tr 请求包含奇数个字符。最后一个字符映射到空白字符。
填充模式下的空行，使用 .sp
(mdoc) 空白输入行的含义仅在非填充模式下明确定义：在填充模式下，文本输入行的换行符不应该是重要的。但是，为了与 groff 兼容，填充模式下的空行格式类似于 sp 请求。要请求分节符，请使用 Pp 而不是空行。
填充文本中的制表符
(mdoc, man) 制表符的含义仅在非填充模式下明确定义：在填充模式下，空格在文本输入行中不应该是重要的。作为依赖于实现的选择，在任何情况下，文本行上的制表符都会传递给格式化程序。鉴于制表符之前的文本将被填充，因此很难预测制表符将前进到哪个制表位。
新句子，新行
(mdoc) 一个新句子从文本行的中间开始。在新的输入行上启动它以帮助格式化程序生成正确的间距。
无效的转义序列
(roff) 转义序列具有无效的开始参数定界符，缺少结束参数定界符，参数的形式无效，或者它是具有无效名称的字符转义序列。如果参数不完整， \* 和 扩展为空字符串， \B 扩展为数字 ‘0’ 和 \w 扩展为不完整参数的长度。所有其他无效的转义序列都将被忽略。
未定义的转义，字面打印
(roff) 在转义序列中，前导反斜杠之后的第一个字符无效。该字符按字面意思打印，相当于忽略反斜杠。
未定义的字符串，使用 ""
(roff) 如果一个字符串被使用而之前没有定义，它的值被隐式设置为空字符串。但是，在使用之前明确定义字符串可以使代码更具可读性。
tbl 行以 span 开头
(tbl) 表格布局规范的第一行请求水平跨度 (‘s’) 。为该单元格提供的数据将被忽略，单元格中不会打印任何内容。
tbl 列以 span 开头
(tbl) 表格布局规范的第一行要求一个垂直跨度 (‘^’) 。为该单元格提供的数据将被忽略，单元格中不会打印任何内容。
布局中跳过竖线
(tbl) 表格布局规范包含两个以上的连续垂直条。打印双条，所有额外的条都被丢弃。
选项中的非字母字符
(tbl) 表选项行包含一个字符，而不是字母、空格或逗号，其中需要选项名称的开头。该字符被忽略。
跳过未知的 tbl 选项
(tbl) 表选项行包含与任何已知选项名称都不匹配的字母字符串。该词被忽略。
缺少 tbl 选项参数
(tbl) 需要参数的表选项后面没有左括号，或者左括号后面紧跟右括号。该选项被忽略。
错误的 tbl 选项参数大小
(tbl) 表选项参数包含无效的字符数。选项和参数都被忽略。
空表布局
(tbl) 表格布局规范是完全空的，指定零行和零列。作为后备，使用单个左对齐列。
tbl 布局中的无效字符
(tbl) 表格布局规范包含一个既不能解释为布局键字符也不能解释为布局修饰符的字符，或者修饰符位于第一个键之前。无效字符被丢弃。
tbl 布局中不匹配的括号
(tbl) 表格布局规范包含一个左括号，但没有匹配的右括号。输入行的其余部分（从括号开始）无效。
没有任何数据单元格的 tbl
(tbl) 表格不包含任何数据单元格。它可能不会产生任何输出。
忽略跨越的 tbl 单元格中的数据
(tbl) 表格单元格在表格布局中被标记为水平跨度 (‘s’) 或垂直跨度 (‘^’) ，但它包含数据。数据被忽略。
忽略额外的 tbl 数据单元
(tbl) 一条数据线包含的单元比相应的布局线多。多余单元格中的数据将被忽略
数据块在 tbl 末尾打开
(tbl) 一个数据块用 T{, 打开，但永远不会用匹配的 T} 关闭。表格的剩余数据行全部放入一个单元格中，任何剩余的单元格保持空白。
重复的序幕宏
(mdoc) 序言宏之一出现不止一次。最后一个实例覆盖所有以前的实例。
跳过后期标题宏
(mdoc) Dt 宏出现在第一个非序言宏之后。传统格式化程序无法处理此问题，因为它们在解析文档正文之前编写页眉。尽管此技术限制不适用于 mandoc ，但仍保留了传统语义。后期宏被丢弃，包括它的参数。
i超出输入堆栈限制，无限循环？
(roff) 为以下功能实现了显式递归限制，以防止无限循环：
嵌套转义序列的扩展，包括字符串和数字寄存器的扩展，
嵌套用户定义宏的扩展，
文件包含
so。
当达到限制时，输出不正确，通常会丢失一些内容，但解析器可以继续。
跳过坏字符
(mdoc, man, roff) 输入文件包含一个不是可打印 ascii(7) 字符的字节。该消息提到字符编号。有问题的字节被替换为问号 (‘?’) 。考虑编辑输入文件以将字节替换为预期字符的 ASCII 音译。
跳过未知宏
(mdoc, man, roff) 请求或宏行上的第一个标识符既不能识别为 roff(7) 请求，也不能识别为用户定义的宏，也不能分别识别为 mdoc(7) 或 man(7) 宏。它可能输入错误或不受支持。请求或宏被丢弃，包括其参数。
跳过宏外的请求
(roff) shift 或 return 请求发生在任何宏定义之外并且没有效果。
跳过不安全的请求
(roff) 输入文件试图运行 shell 命令或读取或写入外部文件。出于安全原因，此类尝试被拒绝。
跳过列表外的项目
(mdoc, eqn) It 宏出现在任何 Bl 列表之外，或者 above 的 eqn(7) 分隔符出现在任何堆之外。它被丢弃，包括它的论点。
跳过列列表外的列
(mdoc) Ta 宏出现在任何 Bl -column 块之外。它被丢弃，包括它的论点。
跳过未打开的块的结尾
(mdoc, man, eqn, tbl, roff) 各种语法元素只能用于显式关闭之前打开的块。遇到 mdoc(7) 块关闭宏、 man(7) ME 、 RE 或 UE 宏、 eqn(7) 右分隔符或右大括号，或者遇到等式、表格或 roff(7) 条件请求的结尾但没有匹配的块是打开的。有问题的请求或宏将被丢弃。
更少的 RS 块打开，跳过
(man) 使用参数调用 RE 宏，但打开的 RS 块少于指定数量。 RE 宏被丢弃。
插入缺失的块尾
(mdoc, tbl) 各种 mdoc(7) 宏和表需要由专用宏显式关闭。一个不支持错误嵌套的块在其所有子项都正确关闭之前结束。打开的子节点隐式关闭。
追加缺少的块尾
(mdoc, man, eqn, tbl, roff) 在文档的末尾，显式 mdoc(7) 块、 man(7) 下一行范围或 MT 、 RS 或 UR 块、方程式、表格或 roff(7) 条件或忽略块仍然打开。打开的块被隐式关闭。
名称中不允许出现转义字符
(roff) 宏、字符串和寄存器标识符由可打印的非空白 ASCII 字符组成。转义序列以及用它们表示的字符和字符串不能构成名称的一部分。 am 、 as 、 de 、 ds 、 nr 或 rr 请求的第一个参数，或 rm 请求的任何参数，或正在调用的请求或用户定义的宏的名称，由转义序列终止。在 as 、 ds 和 nr 的情况下，请求完全没有效果。在 am 、 de 、 rr 和 rm 的情况下，到目前为止解析的内容被用作请求的参数，并且输入行的其余部分被丢弃，包括转义序列。 前面的字符用作请求或宏名，后面的字符用作请求或宏的参数。
在宏外使用宏参数
(roff) 转义序列 \$ 出现在任何宏定义之外并扩展为空字符串。
参数编号不是数字
(roff) 转义序列 \$ 的参数不是数字；转义序列扩展为空字符串。
未实现：bd 文件
(mdoc) 出于安全原因， Bd 宏不支持 -file 参数。通过请求包含敏感文件，恶意文档可能会诱使特权用户无意中在屏幕上显示文件，从而将文件内容泄露给旁观者。该参数被忽略，包括它后面的文件名。
不带参数跳过显示
(mdoc) Bd 块宏没有任何参数。该块被丢弃，并且块内容以该块之前处于活动状态的任何模式显示。
缺少列表类型，使用 -item
(mdoc) Bl 宏未能指定列表类型。
参数不是数字，使用 1
(roff) ce 请求的参数不是数字。
参数不是字符
(roff) char 请求的第一个参数既不是单个 ASCII 字符也不是单个字符转义序列。该请求被忽略，包括其所有参数。
缺少手册名称，使用 ""
(mdoc) 对 Nm 的第一次调用，或 NAME 部分中的任何调用，都缺少必需的参数。
uname(3) 系统调用失败，使用 UNKNOWN
(mdoc) Os 宏在没有参数的情况下被调用，并且 uname(3) 系统调用失败。作为一种解决方法，可以使用 -D``OSNAME="\"string\"" 编译 mandoc 。
未知的标准说明符
(mdoc) St 宏具有未知参数并被丢弃。
跳过没有数字参数的请求
(roff, eqn) it 请求或 eqn(7) size 或 gsize 语句具有非数字或负参数或根本没有参数。无效的请求或语句被忽略。
过度移位
(roff) shift 请求的参数大于当前正在执行的宏的参数数量。所有宏参数都被删除， \n(.$ 设置为零。
未实现: .so 使用绝对路径或 ".."
(roff) 出于安全原因， mandoc 只允许 so 文件包含请求使用相对路径且不升序到任何父目录。 通过请求包含敏感文件，恶意文档可能会诱使特权用户无意中在屏幕上显示文件，从而将文件内容泄露给旁观者。 mandoc 仅显示出现在 so 后面的路径。
.so 请求失败
(roff) 为 so 请求提供服务需要读取外部文件，但无法打开该文件。 mandoc 仅显示出现在 so 后面的路径。
跳过所有参数
(mdoc, man, eqn, roff) mdoc(7) Bt 、 Ed 、 Ef 、 Ek 、 El 、 Lp 、 Pp 、 Re 、 Rs 或 Ud 宏，列表中不支持项目标题的 It 宏， man(7) LP 、 P 或 PP 宏， eqn(7) EQ 或 EN 宏，或 roff(7) br 、 fi 或 nf 请求或 ‘..’ 块关闭请求至少调用一个论点。所有参数都被忽略。
跳过多余的参数
(mdoc, man, roff) 使用太多参数调用宏或请求：
具有多个参数的
Fo 、MT 、PD 、RS 、UR 、ft或sp在
-split或-nosplit之后带有另一个参数的带有多个参数或非整数参数的
REOP或带有两个以上参数的de家庭的请求Dt具有三个以上参数的TH具有五个以上参数的带有无效参数的
Bd 、Bk或Bl
多余的参数将被忽略。
输入太大
(mdoc, man) 目前， mandoc 无法处理大于其任意大小限制 2^31 字节（2 GB）的输入文件。由于有用的手册总是很小，这在实践中不是问题。一旦检测到条件，解析就会中止。
不支持的控制字符
(roff) 在输入文件中找到其他 roff(7) 实现支持但 mandoc 不支持的 ASCII 控制字符。它被一个问号代替。
不支持的转义序列
(roff) 输入文件包含 GNU troff 或 Heirloom troff 支持但 mandoc 不支持的转义序列，这很可能会导致信息丢失或严重的格式错误。
不支持的 roff 请求
(roff) 输入文件包含 GNU troff 或 Heirloom troff 支持但 mandoc 不支持的 roff(7) 请求，这很可能会导致信息丢失或严重的格式错误。
tbl 中的 eqn delim 选项
(eqn, tbl) 表格的选项行定义方程分隔符。表中包含的任何方程式源代码都将不带格式打印。
不受支持的表格布局修饰符
(tbl) 表格布局规范包含 ‘m’ 修饰符。修饰符被丢弃。
忽略表中的宏
(tbl, mdoc, man) 表包含对 mdoc(7) 或 man(7) 宏或未定义宏的调用。宏被忽略，它的参数被当作文本行处理。
错误的命令行参数
-IKMmOTW 命令行选项之一后面的参数无效，或者无法打开作为命令行参数给出的 file 。
重复的命令行参数
-I 命令行选项被指定两次
选项有多余的值
-O 选项的参数有一个值，但不接受一个值。
缺少选项值
-O 选项的参数没有参数但需要一个参数。
糟糕的选项值
-O indent 或 width 选项的参数值无效。
重复的选项值
多次指定相同的 -O 选项。
没有这样的标签
指定 -O tag 标记选项，但在任何显示的手册页中都找不到该标记。
apropos(1) 、 man(1) 、 eqn(7) 、 man(7) 、 mandoc_char(7) 、 mdoc(7) 、 roff(7) 、 tbl(7)
mandoc 实用程序首先出现在 OpenBSD 4.8 中。选项 -I 出现在 OpenBSD 5.2 中，而 -aCcfhKklMSsw 出现在 OpenBSD 5.7 中。
mandoc 实用程序由 Kristaps Dzonsons <kristaps@bsd.lv> 编写，并由 Ingo Schwarze <schwarze@openbsd.org> 维护。
July 10, 2019
FreeBSD 13.1-RELEASE
最后更新于