Linux程序员手册 第7部分
更新日期： 2019-03-06

名称

man-格式化手册页的宏

语法

groff -Tascii -man文件...

groff -Tps -man文件...

人[节]标题

说明

本手册页介绍了groff an.tmac宏程序包(通常称为man宏程序包)。开发人员在编写或移植Linux手册页时应使用此宏包。它与该宏程序包的其他版本完全兼容，因此，移植手册页应该不是主要问题(NET-2 BSD发行版除外，该版本使用完全不同的名为mdoc的宏程序包；请参见mdoc(7))。

请注意，只需指定-mdoc选项而不是-man选项，即可将NET-2 BSD mdoc手册页与groff一起使用。但是，建议使用-mandoc选项，因为这将自动检测正在使用哪个宏程序包。

有关为Linux手册页包编写手册页时应采用的约定，请参见man-pages(7)。

Title line

手册页中的第一个命令(在注释行之后，即以。"开头的行)应为

.TH标题部分日期来源手册

有关应提供给TH命令的参数的详细信息，请参见man-pages(7)。

请注意，BSD mdoc格式的页面以Dd命令而不是TH命令开头。

Sections

各节以.SH开头，后跟标题名称。

唯一的强制性标题是NAME，它应该是第一部分，并在下一行后跟该程序的一行说明：

.SH名称 商品描述

遵循这种格式非常重要，并且在项目名称后的单破折号之前必须有一个反斜杠。 mandb(8)程序使用此语法来为whatis(1)和apropos(1)命令创建简短描述的数据库。 (有关NAME部分的语法的更多详细信息，请参见lexgrog(1)。)

有关手册页中可能出现的其他部分的列表，请参见手册页(7)。

Fonts

选择面部类型的命令是：

.B

胆大

.BI

粗体与斜体交替显示(特别适用于功能说明)

.BR

粗体与罗马字母交替出现(对参考其他手册页特别有用)

.I

斜体字

.IB

斜体与粗体交替

.IR

斜体与罗马交替

.RB

罗马与粗体交替

.RI

罗马与斜体交替

.SB

小轮流加粗

.SM

小(适用于首字母缩写词)

传统上，每个命令最多可以有六个参数，但是GNU实现消除了此限制(出于可移植性的考虑，您可能仍希望将自己限制为6个参数)。参数由空格分隔。双引号可用于指定包含空格的参数。所有参数将彼此相邻打印而不会插入空格，因此.BR命令可用于指定粗体字和罗马字母标点符号。如果未提供任何参数，则该命令将应用于以下文本行。

Other macros and strings

以下是其他相关的宏和预定义的字符串。除非另有说明，否则所有宏都会引起中断(在当前文本行的结尾)。这些宏中有许多设置或使用"普遍缩进"。 "普遍缩进"值由任何宏使用下面的参数i设置；宏可能会省略i，在这种情况下，将使用当前流行的缩进。结果，连续的缩进段落可以使用相同的缩进，而无需重新指定缩进值。普通(无缩进)段落会将当前的缩进值重置为其默认值(0.5英寸)。默认情况下，给定的缩进以ens为单位；请尝试使用ens或ems作为缩进单位，因为它们会自动适应字体大小的变化。其他关键宏定义是：

Normal paragraphs

.LP

与.PP相同(开始一个新段落)。

.P

与.PP相同(开始一个新段落)。

.PP

开始一个新的段落并重置当前的缩进。

Relative margin indent

.RSi

开始相对边距缩进：将左边距i向右移(如果省略i，则使用当前的缩进值)。新的现行缩进设置为0.5英寸。结果，以下所有段落都会缩进，直到相应的.RE。

.RE

终止相对边距缩进并恢复当前缩进的先前值。

Indented paragraph macros

.HPi

以悬挂式缩进开始段落(段落的第一行在普通段落的左边缘，其余段落的行都缩进)。

.IPx i

缩进的段落带有可选的吊牌。如果省略了标签x，则后面的整个段落都以i缩进。如果提供了标记x，则它将x悬挂在下一个缩进段落之前的左边距(这与.TP一样，只是该标记包含在命令中而不是位于下一行)。如果标签太长，标签后的文本将向下移动到下一行(文本不会丢失或乱码)。对于项目符号列表，请使用带有\(bu(项目符号)或\(em(破折号))作为标签的宏，对于编号列表，请使用数字或字母后跟一个句点作为标签；这可简化翻译为其他格式。

.TPi

以悬挂标签开始段落。标记在下一行给出，但其结果类似于.IP命令的结果。

Hypertext link macros

.URurl

插入一个超文本链接到URI(URL)url，所有文本直至以下.UE宏作为链接文本。

.UE

[预告片]终止前面的.UR宏的链接文本，并紧随其后的可选预告片(如果存在，通常是右括号和/或句子结尾标点符号)。对于非HTML输出设备(例如man -Tutf8)，链接文本后跟尖括号中的URL；如果没有链接文本，则将URL打印为自己的链接文本，并用尖括号将其包围。 (尖括号可能并非在所有输出设备上都可用。)对于HTML输出设备，链接文本被超链接到URL；否则，链接文本将被链接到URL。如果没有链接文本，则将URL打印为自己的链接文本。

自GNU Troff 1.20(2009-01-05)和Heirloom Doctools Troff自160217(2016-02-17)起已支持这些宏。

Miscellaneous macros

.DT

将标签重置为默认标签值(每0.5英寸)；不会造成中断。

.PDd

将段间垂直距离设置为d(如果省略，则d = 0.4v)；不会造成中断。

.SSt

子标题t(类似于.SH，但用于节中的子节)。

Predefined strings

man软件包具有以下预定义的字符串：

\*R

注册符号：®

\*S

更改为默认字体大小

\*(Tm

商标符号：

\*(lq

左斜双引号：``

\*(rq

直角双引号：''

Safe subset

尽管从技术上说man是troff宏程序包，但实际上，许多其他工具处理的手册页文件并未实现troff的全部功能。因此，最好避免使用troff的一些更奇特的功能，以允许其他工具正常工作。避免使用各种troff预处理器(如果必须，请继续使用tbl(1)，但尝试对两列表使用IP和TP命令)。避免使用计算；其他大多数工具都无法处理它们。使用易于转换为其他格式的简单命令。以下troff宏被认为是安全的(尽管在很多情况下，翻译器会忽略它们)：\，。，ad，bp，br，ce，de，ds，el，if，fi，ft，hy， ig，in，na，ne，nf，nh，ps，so，sp，ti，tr。

您也可以使用许多troff转义序列(以\开头的序列)。当您需要在普通文本中包含反斜杠字符时，请使用\ e。您可能使用的其他序列，其中x或xx是任何字符，N是任何数字，包括：\ aq，`，-，\。，\，\％，\ * x，\ *(xx，(xx ，\ $ N，\ nx，\ n(xx，\ fx和\ f(xx。避免使用转义序列绘制图形。

请勿对bp(中断页)使用可选参数。对于sp(垂直空间)只能使用正值。在此宏或mdoc宏程序包中，请勿使用与宏相同的名称定义具有不同含义的宏(de)；这样的重新定义很可能会被忽略。每个正缩进(in)应该与匹配的负缩进配对(尽管您应该改用RS和RE宏)。条件测试(if，ie)仅应将aqtaq或aqnaq作为条件。仅应使用可以忽略的翻译(tr)。字体更改(ft和\ f转义序列)应仅具有值1、2、3、4，R，I，B，P或CW(ft命令也可能没有参数)。

如果您使用这些功能以外的功能，请在几种工具上仔细检查结果。一旦确认附加功能是安全的，请让本文档的维护者知道应添加到此列表的安全命令或顺序。

文件

/usr/share/groff/[*/]tmac/an.tmac
/ usr / man / whatis

备注

务必在文本本身中包含完整的URL(或URI)；一些工具，例如man2html(1)可以自动将它们变成超文本链接。您还可以使用UR和UE宏来标识指向相关信息的链接。如果您包含网址，请使用完整的网址(例如，确保工具可以自动找到网址。

处理这些文件的工具应打开文件并检查第一个非空白字符。行开头的句点(。)或单引号(aq)表示基于troff的文件(例如man或mdoc)。左尖括号(

许多手册页都以aq "开头，后跟一个空格和一个字符列表，指示如何对该页面进行预处理。出于对非troff转换器的可移植性的考虑，我们建议您避免使用tbl(1)以外的任何东西，并且Linux可以自动检测到该错误，但是，您可能希望包括此信息，以便您的手册页可以由其他(功能较弱的)系统处理。以下是这些字符调用的预处理器的定义：

e

eqn(1)

g

抓图(1)

p

图片(1)

r

参考(1)

t

tbl(1)

v

vgrind(1)

BUGS

与mdoc和DocBook之类的格式(甚至HTML具有更多的语义标记)相比，大多数宏都描述格式(例如字体类型和间距)而不是标记语义内容(例如，此文本是对另一页的引用)。这种情况使更改不同介质的手册格式，使格式与给定介质保持一致以及自动插入交叉引用变得更加困难。通过坚持上述安全子集，将来应该更容易实现自动转换为其他参考页面格式。

未实现Sun宏TX。

另外参见

apropos(1)，groff(1)，lexgrog(1)，man(1)，man2html(1)，whatis(1)，groff_man(7)，groff_www(7)，手册页(7)，mdoc(7) )

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。