Формат man файла

MAN(7) Linux Programmer's Manual MAN(7)



NAME
man - macros to format man pages

SYNOPSIS
groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title

DESCRIPTION
This manual page explains the groff an.tmac macro package (often called the man macro package). This macro package should be
used by developers when writing or porting man pages for Linux. It is fairly compatible with other versions of this macro pack‐
age, so porting man pages should not be a major problem (exceptions include the NET-2 BSD release, which uses a totally differ‐
ent macro package called mdoc; see mdoc(7)).

Note that NET-2 BSD mdoc man pages can be used with groff simply by specifying the -mdoc option instead of the -man option.
Using the -mandoc option is, however, recommended, since this will automatically detect which macro package is in use.

For conventions that should be employed when writing man pages for the Linux man-pages package, see man-pages(7).

Title line
The first command in a man page (after comment lines, that is, lines that start with .\") should be

.TH title section date source manual

For details of the arguments that should be supplied to the TH command, see man-pages(7).

Note that BSD mdoc-formatted pages begin with the Dd command, not the TH command.

Sections
Sections are started with .SH followed by the heading name.

The only mandatory heading is NAME, which should be the first section and be followed on the next line by a one line description
of the program:

.SH NAME

It is extremely important that this format is followed, and that there is a backslash before the single dash which follows the
command name. This syntax is used by the makewhatis(8) program to create a database of short command descriptions for the
whatis(1) and apropos(1) commands.

For a list of other sections that might appear in a manual page, see man-pages(7).

Fonts
The commands to select the type face are:

.B Bold

.BI Bold alternating with italics (especially useful for function specifications)

.BR Bold alternating with Roman (especially useful for referring to other manual pages)

.I Italics

.IB Italics alternating with bold

.IR Italics alternating with Roman

.RB Roman alternating with bold

.RI Roman alternating with italics

.SB Small alternating with bold

.SM Small (useful for acronyms)

Traditionally, each command can have up to six arguments, but the GNU implementation removes this limitation (you might still
want to limit yourself to 6 arguments for portability's sake). Arguments are delimited by spaces. Double quotes can be used to
specify an argument which contains spaces. All of the arguments will be printed next to each other without intervening spaces,
so that the .BR command can be used to specify a word in bold followed by a mark of punctuation in Roman. If no arguments are
given, the command is applied to the following line of text.

Other Macros and Strings
Below are other relevant macros and predefined strings. Unless noted otherwise, all macros cause a break (end the current line
of text). Many of these macros set or use the "prevailing indent." The "prevailing indent" value is set by any macro with the
parameter i below; macros may omit i in which case the current prevailing indent will be used. As a result, successive indented
paragraphs can use the same indent without respecifying the indent value. A normal (nonindented) paragraph resets the prevail‐
ing indent value to its default value (0.5 inches). By default a given indent is measured in ens; try to use ens or ems as
units for indents, since these will automatically adjust to font size changes. The other key macro definitions are:

Normal Paragraphs
.LP Same as .PP (begin a new paragraph).

.P Same as .PP (begin a new paragraph).

.PP Begin a new paragraph and reset prevailing indent.

Relative Margin Indent
.RS i Start relative margin indent: moves the left margin i to the right (if i is omitted, the prevailing indent value is
used). A new prevailing indent is set to 0.5 inches. As a result, all following paragraph(s) will be indented until
the corresponding .RE.

.RE End relative margin indent and restores the previous value of the prevailing indent.

Indented Paragraph Macros
.HP i Begin paragraph with a hanging indent (the first line of the paragraph is at the left margin of normal paragraphs, and
the rest of the paragraph's lines are indented).

.IP x i Indented paragraph with optional hanging tag. If the tag x is omitted, the entire following paragraph is indented by
i. If the tag x is provided, it is hung at the left margin before the following indented paragraph (this is just like
.TP except the tag is included with the command instead of being on the following line). If the tag is too long, the
text after the tag will be moved down to the next line (text will not be lost or garbled). For bulleted lists, use
this macro with \(bu (bullet) or \(em (em dash) as the tag, and for numbered lists, use the number or letter followed
by a period as the tag; this simplifies translation to other formats.

.TP i Begin paragraph with hanging tag. The tag is given on the next line, but its results are like those of the .IP com‐
mand.

Hypertext Link Macros
(Feature supported with groff only.) In order to use hypertext link macros, it is necessary to load the www.tmac macro package.
Use the request .mso www.tmac to do this.

.URL url link trailer
Inserts a hypertext link to the URI (URL) url, with link as the text of the link. The trailer will be printed immedi‐
ately afterward. When generating HTML this should translate into the HTML command <A HREF="url">link</A>trailer.

This and other related macros are new, and many tools won't do anything with them, but since many tools (including
troff) will simply ignore undefined macros (or at worst insert their text) these are safe to insert.

It can be useful to define your own URL macro in manual pages for the benefit of those viewing it with a roff viewer
other than groff. That way, the URL, link text, and trailer text (if any) are still visible.

Here's an example:
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH ...
(later in the page)
This software comes from the
.URL "http://www.gnu.org/" "GNU Project" " of the"
.URL "http://www.fsf.org/" "Free Software Foundation" .

In the above, if groff is being used, the www.tmac macro package's definition of the URL macro will supersede the
locally defined one.

A number of other link macros are available. See groff_www(7) for more details.

Miscellaneous Macros
.DT Reset tabs to default tab values (every 0.5 inches); does not cause a break.

.PD d Set inter-paragraph vertical distance to d (if omitted, d=0.4v); does not cause a break.

.SS t Subheading t (like .SH, but used for a subsection inside a section).

Predefined Strings
The man package has the following predefined strings:

\*R Registration Symbol: ®

\*S Change to default font size

\*(Tm Trademark Symbol: ™

\*(lq Left angled double quote: “

\*(rq Right angled double quote: ”

Safe Subset
Although technically man is a troff macro package, in reality a large number of other tools process man page files that don't
implement all of troff's abilities. Thus, it's best to avoid some of troff's more exotic abilities where possible to permit
these other tools to work correctly. Avoid using the various troff preprocessors (if you must, go ahead and use tbl(1), but try
to use the IP and TP commands instead for two-column tables). Avoid using computations; most other tools can't process them.
Use simple commands that are easy to translate to other formats. The following troff macros are believed to be safe (though in
many cases they will be ignored by translators): \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh,
ps, so, sp, ti, tr.

You may also use many troff escape sequences (those sequences beginning with \). When you need to include the backslash charac‐
ter as normal text, use \e. Other sequences you may use, where x or xx are any characters and N is any digit, include: \', \`,
\-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, and \f(xx. Avoid using the escape sequences for drawing graphics.

Do not use the optional parameter for bp (break page). Use only positive values for sp (vertical space). Don't define a macro
(de) with the same name as a macro in this or the mdoc macro package with a different meaning; it's likely that such redefini‐
tions will be ignored. Every positive indent (in) should be paired with a matching negative indent (although you should be
using the RS and RE macros instead). The condition test (if,ie) should only have 't' or 'n' as the condition. Only transla‐
tions (tr) that can be ignored should be used. Font changes (ft and the \f escape sequence) should only have the values 1, 2,
3, 4, R, I, B, P, or CW (the ft command may also have no parameters).

If you use capabilities beyond these, check the results carefully on several tools. Once you've confirmed that the additional
capability is safe, let the maintainer of this document know about the safe command or sequence that should be added to this
list.

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

NOTES
By all means include full URLs (or URIs) in the text itself; some tools such as man2html(1) can automatically turn them into
hypertext links. You can also use the new URL macro to identify links to related information. If you include URLs, use the
full URL (e.g., <http://www.kernelnotes.org>) to ensure that tools can automatically find the URLs.

Tools processing these files should open the file and examine the first nonwhitespace character. A period (.) or single quote
(') at the beginning of a line indicates a troff-based file (such as man or mdoc). A left angle bracket (<) indicates an
SGML/XML-based file (such as HTML or Docbook). Anything else suggests simple ASCII text (e.g., a "catman" result).

Many man pages begin with ´\" followed by a space and a list of characters, indicating how the page is to be preprocessed. For
portability's sake to non-troff translators we recommend that you avoid using anything other than tbl(1), and Linux can detect
that automatically. However, you might want to include this information so your man page can be handled by other (less capable)
systems. Here are the definitions of the preprocessors invoked by these characters:

e eqn(1)

g grap(1)

p pic(1)

r refer(1)

t tbl(1)

v vgrind(1)

BUGS
Most of the macros describe formatting (e.g., font type and spacing) instead of marking semantic content (e.g., this text is a
reference to another page), compared to formats like mdoc and DocBook (even HTML has more semantic markings). This situation
makes it harder to vary the man format for different media, to make the formatting consistent for a given media, and to automat‐
ically insert cross-references. By sticking to the safe subset described above, it should be easier to automate transitioning
to a different reference page format in the future.

The Sun macro TX is not implemented.

SEE ALSO
apropos(1), groff(1), man(1), man2html(1), whatis(1), groff_man(7), groff_www(7), man-pages(7), mdoc(7), mdoc.samples(7)

COLOPHON
This page is part of release 3.32 of the Linux man-pages project. A description of the project, and information about reporting
bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux 2007-05-30 MAN(7)

НАЗВАНИЕ
man - макросы форматирования страниц руководства
СИНТАКСИС
groff -Tascii -man файл ...

groff -Tps -man файл ...

man [секция] название
ОПИСАНИЕ
На этой странице описывается макропакет groff tmac.an (часто называемый макропакетом man) и соглашения по созданию страниц руководства (manual pages). Этот макропакет должен использоваться разработчиками при написании страниц руководства по Linux или переносе их с других систем. Вариант Linux практически полностью совместим с другими версиями этого макропакета, поэтому с переносом не должно возникнуть проблем (за исключением NET-2 BSD, использующего совсем другой пакет под названием mdoc; смотрите mdoc(7)).

Заметьте, что mdoc-страницы руководства по NET-2 BSD могут быть просмотрены при помощи groff путем указания опции -mdoc вместо -man. Однако, рекомендуется использование -mandoc, так как в этом случае формат будет распознан автоматически.
ПРЕАМБУЛА
Первой на странице руководства (после комментариев) должна быть команда

.TH заголовок раздел дата источник документация,

где:

заголовок
Заголовок страницы руководства (например, MAN).
раздел
Номер раздела, где должна находиться страница руководства (например, 7).
дата
Дата последнего изменения. Hе забывайте изменять эту дату каждый раз, так как это наиболее простой способ контролировать версии документа.
source
Источник.

Для задания команд надо использовать что-то вроде: GNU, NET-2, SLS Distribution, ASPLinux Distribution.

Для системных вызовов используйте версию ядра, с которой Вы работаете, например: Linux 0.99.11.

Для библиотечных вызовов используйте один из источников: GNU, BSD 4.3, Linux DLL 4.4.1.
документация
Название руководства (например, Linux Programmer's Manual).

Заметьте, что mdoc-страницы в BSD начинаются с команды Dd, а не с TH.

Разделы страниц руководства, обычно такие:

1 Команды
Команды, обычно запускаемые пользователем из оболочки.
2 Системные вызовы
Функции, исполняемые ядром.
3 Библиотечные вызовы
Обычно это функции libc, такие как qsort(3)
4 Специальные файлы
Файлы, находящиеся в /dev)
5 Форматы файлов и соглашения
Формат файла /etc/passwd и других, подобных ему, файлов настроек.
6 Игры
7 Макропакеты и соглашения
Описание стандартной "раскладки" файловой системы, сетевых протоколов, кодов ASCII и других таблиц, данная страница документации и др.
8 Команды управления системой
Команды типа mount(8), исполняемые обычно только суперпользователем root.
9 Процедуры ядра
Это устаревший раздел руководства. В свое время появилась идея держать документацию о ядре Linux в этом разделе. Однако, в то время документация о ядре была неполной, и по большей части устаревшей. Существуют гораздо более удобные источники информации для разработчиков ядра.


РАЗДЕЛЫ
Разделы страниц документации начинаются с команды .SH, за которой следует название раздела. Если название раздела содержит пробелы, то это название необходимо заключать в двойные кавычки. Рекомендуется использование стандартных названий секций: НАЗВАНИЕ, СИНТАКСИС, ОПИСАНИЕ, ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ, КОД ЗАВЕРШЕНИЯ, ОБРАБОТКА ОШИБОК, ОШИБКИ, ОПЦИИ, ИСПОЛЬЗОВАНИЕ, ПРИМЕРЫ, ФАЙЛЫ, ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ, СООБЩЕНИЯ ОБ ОШИБКАХ, БЕЗОПАСНОСТЬ, СООТВЕТСТВИЕ, ПРИМЕЧАНИЯ, ЗАМЕЧАНИЯ, АВТОРЫ и СМ.ТАКЖЕ. Пожалуйста, используйте стандартные заголовки там, где это возможно: подобная однозначность позволяет упростить понимание предоставленной информации. Однако, Вы можете использовать и свои заголовки, если считаете, что Ваше название раздела будет более понятным. Единственный обязательный раздел - НАЗВАНИЕ. Он должен быть первым, и за его заголовком должна следовать одна строка с описанием программы:

.SH НАЗВАНИЕ
man \- макросы форматирования страниц руководства

Очень важно следовать этому формату, включая обозначение обратного слэша перед тире, идущего после названия команды. Этот формат используется программой makewhatis(8) для создания базы данных кратких описаний программ. Эта база используется при помощи команд whatis(1) и apropos(1).

Остальные стандартные разделы должны содержать в себе следующее:

СИНТАКСИС
содержит краткое описание команды или интерфейса функции. В этой секции приводится синтаксис команды и ее параметры (включая опции); жирный шрифт используется для неизменяемого текста, а наклонный - для указания параметров, заменяемых конкретными значениями. Квадратные скобки ([]) указывают на необязательные параметры, символ | означает несколько возможных вариантов, а многоточие (...) - то, что параметр может повторяться. Функциям в этом разделе указываются все необходимые определения данных и/или директивы #include, за которыми следует определение самой функции.
ОПИСАНИЕ
объясняет, что делает команда, функция или формат. Описывается работа с файлами и стандартным потоком ввода и то, что попадает в стандартный поток вывода или в стандартный поток ошибок. В этом разделе можно не описывать детали внутреннего строения функции или команды и отличия в их реализации, если они не важны для понимания интерфейса. Кроме того, здесь можно привести пример вызова команды (функции). Для описания опций используйте секцию ОПЦИИ. Если имеется общая для всех описываемых команд часть или сложный набор подкоманд, то их лучше описывать в секции ИСПОЛЬЗОВАНИЕ (а в секции ОПИСАНИЕ привести лишь обзор действий).
ВОЗВРАЩЕМОЕ ЗНАЧЕНИЕ
содержит список значений, которые библиотечная функция возвращает вызвавшему процессу, а также условия возникновения тех или иных значений.
КОД ЗАВЕРШЕНИЯ
содержит список возможных кодов завершения программы и условия их возникновения.
ОПЦИИ
содержит список всех возможных опций программы и их влияние на работу программы.
ИСПОЛЬЗОВАНИЕ
содержит описание внутренней грамматики подъязыка программы.
ПРИМЕРЫ
содержит один или несколько примеров использования данной функции, файла или команды.
ФАЙЛЫ
содержит список файлов, с которыми работает программа или функция (файлы конфигурации, пакетные файлы, а также файлы, с которыми работает сама программа). Приводится полный путь к файлам, а процесс установки страницы должен изменять эти пути в соответствии с настройками системы. Многие программы по умолчанию устанавливаются в /usr/local, поэтому в исходной версии страницы должен указываться каталог /usr/local.
ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
содержит список переменных окружения, влияющих на работу программы или функции, а также суть этого влияния.
СООБЩЕНИЯ ОБ ОШИБКАХ
содержит описание возможных ошибок и способы их устранения. Нет необходимости описывать сообщения об ошибках системы или сигналы тревоги, которые могут возникнуть в процессе работы любой программы, если только они не влияют на работу Вашей программы.
БЕЗОПАСНОСТЬ
В этой главе рассматриваются вопросы безопасности и следствия некорректной работы программы. Описаны ситуации, которых следует избегать; команды, которые могут привести к серьезным проблемам в системе безопасности, в особенности, если они незаметны. Описание этих вопросов необязательно выносить в отдельный раздел: иногда проще поместить эту информацию в другие разделы, например, в ОПИСАНИЕ или ИСПОЛЬЗОВАНИЕ. Обязательно включите эту информацию в один из разделов!
СООТВЕТСТВИЕ
содержит ссылки на стандарты или соглашения, которым соответствует программа или функция.
ПРИМЕЧАНИЯ
содержит различные примечания.
ЗАМЕЧАНИЯ
содержит список ограничений, известных недочетов или несоответствий в описании и прочих погрешностей, которые могут возникнуть при работе с программой или функцией.
АВТОР
содержит список авторов документации или программы, чтобы Вы могли послать им отчет об ошибках в работе программы.
СМ. ТАКЖЕ
содержит список ссылок на другие страницы руководства, так или иначе связанные с текущей. Список составлен в алфавитном порядке; далее может следовать список другой документации, связанной с этой страницей. Обычно это последняя секция.


ШРИФТЫ
Несмотря на то, что в мире UNIX существует много разных соглашений по формату страниц руководства, наличие нескольких сотен страниц руководства по Linux привело к созданию некоторых стандартов использования шрифтов:

Параметры функций всегда пишутся курсивом, даже в секции СИНТАКСИС, а все остальное пишется жирным шрифтом:

int myfunction(int argc, char **argv);

Имена файлов всегда пишутся курсивом (например, /usr/include/stdio.h) за исключением секции СИНТАКСИС, в которой имена включаемых файлов пишутся жирным шрифтом (например, #include <stdio.h>).
Для специальных макросов, которые обычно пишутся прописными буквами, используется жирный шрифт (например, MAXINT).
Коды ошибок в списке пишутся жирным шрифтом (для списка обычно используется макрос .TP).
Ссылки на другие страницы руководства (или на объект описания текущей страницы) пишутся жирным шрифтом. Если приводится и номер раздела, то он пишется обычным (Roman) шрифтом без пробелов (например, man(7)).

Для выбора шрифта используются следующие команды:

.B
Утолщенный шрифт
.BI
Утолщенный и затем наклонный шрифт (удобно при описании функций)
.BR
Утолщенный и затем обычный шрифт (удобно при приведении ссылок на другие страницы)
.I
Наклонный шрифт
.IB
Наклонный и затем утолщенный шрифт
.IR
Наклонный и затем обычный шрифт
.RB
Обычный и затем утолщенный шрифт
.RI
Обычный и затем наклонный шрифт
.SB
Сжатый и затем утолщенный шрифт
.SM
Сжатый шрифт (удобен для акронимов)

Раньше у этих команд не могло быть более шести параметров, но реализация GNU сняла это ограничение (Вы можете сами ограничивать себя шестью параметрами для обеспечения совместимости). Параметры разделяются пробелами. Параметры, содержащие пробелы, заключаются в двойные кавычки. Все параметры этих команд будут напечатаны слитно, без пробелов, поэтому команду .BR можно использовать для вывода слова жирным шрифтом, за которым следует знак препинания, выводимый обычным шрифтом. Если параметров нет, то команда относится к следующей строке текста.
ДРУГИЕ МАКРОСЫ И СТРОКИ

Ниже приведен список других полезных макросов и строковых констант. Если не указано иное, все макросы вызывают перевод строки (конец текущей строки текста). Многие из этих макросов задают или используют "стандартный" отступ. Значение этого "стандартного отступа" может быть задано в любом макросе при помощи параметра, упоминаемого ниже как i; этот параметр может и не применяться. В этом случае используется текущее значение отступа. То есть вложенные параграфы с отступом могут использовать то же значение отступа без его повторного указания. Макросы обычного параграфа (без отступа) переводят значение отступа в стандартное значение (0.5 дюйма). По умолчанию отступ измеряется в энах (ens); в качестве единиц можно использовать эны (n) и эмы (m), так как это позволяет автоматически подстраиваться под изменение размера шрифта. (Эм - печатная единица измерения, равная ширине равностороннего символа (М). Эн - печатная единица измерения, равная ширине символа, вдвое меньшей высоты(Н)). Другие ключевые макроопределения:
Обычные параграфы

.LP
То же, что и .PP (начало нового параграфа).
.P
То же, что и .PP (начало нового параграфа).
.PP
Начинает новый параграф и "сбрасывает" значение стандартного отступа.


Относительный сдвиг границы

.RS i
Начало относительного сдвига левой границы: отодвигает левую границу текста на i вправо (если i не упоминается, то используется стандартный отступ). Новый стандартный отступ устанавливается равным 0.5 дюйма. В результате выполнения этой команды левая граница всех последующих параграфов будет сдвинута вправо до появления соответствующей команды .RE.
.RE
Завершает относительный сдвиг левой границы и восстанавливает предыдущее значение стандартного отступа.


Макросы работы с отступами параграфов

.HP i
Начало параграфа с "висячим" отступом (первая строка параграфа находится на левой границе обычного параграфа, а остаток параграфа выводится с отступом).
.IP x i
Параграф с отступом и возможным "висячим" тэгом. Если тэг x опущен, то весь параграф будет выведен с отступом i. Если же тэг x задан, то он будет выведен на левой границе до параграфа (аналогично .TP, только тэг находится в самой команде, а не в следующей строке). Если тэг слишком длинный, то текст после тэга будет опущен на строку вниз (без потерь или искажений). В случае возникновения неупорядоченных списков используйте макрос \(be или \(em в качестве тэга), а в случае возникновения упорядоченных списков - цифру или букву, за которой следует точка: это упростит преобразование файла в другие форматы.
.TP i
Начало параграфа с "висячим" тэгом. Тэг задается в следующей строке, но результаты аналогичны команде .IP.


Макросы гипертекстовых ссылок

.UR u
Начало гипертекстовой ссылки на URI (URL) u; ее окончание указывается при помощи команды UE. При создании HTML это начало должно преобразоваться в HTML-тэг <A HREF="u">. Правда, есть исключение: если u равно специальному значению ":", то никакие гипертекстовые ссылки не будут создаваться в тексте до появления соответствующей закрывающей команды UE (это позволяет отключить ссылки во фразах типа LALR(1), когда формирование ссылок неприемлемо). Эти гипертекстовые макросы являются нововведением, и многие утилиты (включая и troff) ничего не делают с ними, но так как большинство из них просто игнорирует неопределенные макросы (в худшем случае, вставляет их в результат), поэтому такие макросы можно свободно вставлять в страницу.
.UE
Окончание гипертекстовой ссылки, заданной командой UR; При создании HTML эта команда должна преобразоваться в HTML-тэг </A>.
.UN u
Создает гипертекстовую ссылку на URL u; для этой команды соответствующей команды UE не требуется. При создании HTML эта команда должна преобразоваться в HTML-тэг <A NAME="u" id="u">&nbsp;</A> (&nbsp; указывать необязательно, если не нужна поддержка Mosaic).


Прочие Макросы

.DT
Перевести значения позиций табуляции в стандартные значения (по 0.5 дюйма каждое); эта команда не вызывает перевода строки.
.PD d
Установить расстояние между параграфами, равное d (по умолчанию d=40% высоты строки); эта команда не вызывает перевода строки.
.SS t
Подзаголовок t (то же самое, что и .SH, но используется в качестве заголовка подраздела внутри раздела).


Предопределенные строки
В пакете man предопределены следующие строки:

\*R
Символ регистрации: ®
\*S
Переход к стандартному размеру шрифта
\*(Tm
Символ торговой марки:
\*(lq
Левая угловая двойная кавычка: ``
\*(rq
Правая угловая двойная кавычка: ''


БЕЗОПАСНОСТЬ
Несмотря на то, что технически man - это макро-пакет, основанный на troff, на самом деле существует большое количество других утилит, работающих с файлами man-страниц, которые не включают в себя всех возможностей troff. Таким образом, лучше избегать всех экзотических возможностей troff везде, где это возможно. Избегайте использования различных препроцессоров troff (если необходимо, используйте tbl(1), но старайтесь использовать команды IP и TP для двухколоночных таблиц). Избегайте использования вычислений; многие утилиты не обрабатывают их. Используйте простые команды, которые легко преобразовывать в другие форматы. Следующие макросы troff считаются безопасными (во многих случаях они игнорируются преобразователями форматов): \ , ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.

Вы можете использовать и многие escape-последовательности troff, начинающиеся с \). Если Вы хотите проставить обратный слэш в тексте, то используйте \e. Вы можете использоть и другие последовательности, где x или xx - это любые символы, а N - это цифра, в том числе: \', \`, \-, \., \ , \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx и \f(xx. Избегайте использования экранирующих последовательностей для вывода графики.

Не используйте необязательный параметр команды bp (разрыв страницы). Используйте только положительные значения для задания sp (вертикального сдвига). Не определяйте макрос (de) с тем же именем в данном пакете или пакете mdoc, в котором этот макрос имеет другое значение; скорее всего, такие определения будут проигнорировани. Каждый положительный отступ (in) должен сочетаться с соответствующим отрицательным отступом (хотя лучше использовать вместо этого макросы RS и RE ). Условный оператор (if,ie) в качестве условий должен иметь только 't' или 'n'. Из преобразований (tr) должны использоваться только те, которые могут быть проигнорированы. Изменения шрифтов (ft и экранирующие последовательности \f) должны использоваться только со значениями 1, 2, 3, 4, R, I, B, P или CW (у команды ft может и не быть параметров).

Если Вы используете другие возможности troff, то аккуратно проверьте результаты на нескольких утилитах. После того, как Вы убедитесь в безопасности этой команды, дайте знать об этом администратору данного документа, чтобы он мог включить безопасную команду или экранирующую последовательность в этот список.
ЗАМЕЧАНИЯ

Любыми способами включайте полные URL (или URI) в сам текст; многие утилиты, такие, как man2html(1), могут автоматически преобразовывать их в ссылки. Вы также можете использовать новый макрос UR для создания ссылок на сопутствующую информацию. Если Вы используете URL, то используйте полную форму (например, <http://www.kernelnotes.org>) для того, чтобы утилиты могли их автоматически найти.

Утилиты, обрабатывающие подобные файлы, должны открыть файл и рассмотреть первый непустой символ. Точка (.) или апостроф (') в начале файла означают файл в формате troff (man или mdoc). Левая угловая скобка (<) означает файл в формате SGML/XMSL (например, HTML или Docbook). Все остальное должно считаться простым ASCII-текстом (например, результатом работы "catman").

Многие страницы начинаются с символов "\" , за которыми следуют пробелы и список символов, определяющих, как должна обрабатываться страница. Для совместимости с не-troff конверторами мы рекомендуем избегать использования препроцессоров, кроме tbl(1), который определяется Linux автоматически. Однако, Вы можете поместить в данный документ сходную информацию для того, чтобы Ваша страница могла обрабатываться другими системами (с меньшими возможностями). Ниже определены типы препроцессоров, запускаемые этими символами:

e
eqn(1)
g
grap(1)
p
pic(1)
r
refer(1)
t
tbl(1)
v
vgrind(1)


ФАЙЛЫ
/usr/share/groff/[*/]tmac/tmac.an
/usr/man/whatis
НАЙДЕННЫЕ ОШИБКИ

Многие макросы описывают форматирование (например, тип шрифта и расстояния) вместо разметки семантики содержания (например, этот текст является ссылкой на другую страницу) в отличие от других форматов типа mdoc и DocBook (даже в HTML больше семантических меток). По этой причине сложнее преобразовывать формат man в другой формат, сохраняя информационную насыщенность нового формата и автоматическую вставку ссылок. Если Вы будете задавать безопасные команды, описанные выше, то в будущем автоматически перейти в другой формат Вам будет гораздо легче.

Макрос TX из Sun не реализован.
АВТОРЫ

---
Джеймс Кларк (James Clark <jjc@jclark.com>) написал собственно макропакет.
---
Рикард Е. Фэйт (Rickard E. Faith <faith@cs.unc.edu>) написал исходную версию этой страницы.
---
Дженс Швейхардт (Jens Schweikhardt <schweikh@noc.fdn.de>) написал Linux Man-Page Mini-HOWTO (ставший исходным вариантом этой страницы руководства).
---
Дэвид А. Вилер (David A. Wheeler <dwheeler@ida.org>) внес серьезные изменения в эту страницу, добавив подробную информацию о разделах и макросах.


СМ. ТАКЖЕ
apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), whatis(1)