ИМЯ

man - макросы для форматирования справочных страниц

ОБЗОР

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

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

man [раздел] имя

ОПИСАНИЕ

В этой справочной странице описывается макет макросов groff an.tmac (часто
называемый макетом макросов man). Данный пакет макросов должен использоваться
разработчиками для написания или переноса справочных страниц в Linux. Он
относительно совместим с другими версиями этого пакета макросов, так что перенос
справочных страниц не должен быть большой проблемой (кроме выпуска NET-2 BSD, в
котором используется полностью другой пакет макросов mdoc; смотрите mdoc(7)).

Заметим, что справочные страницы NET-2 BSD mdoc можно использовать с groff просто
указав параметра -mdoc вместо -man. Однако рекомендуется использовать параметр
-mandoc, так как это включает автоматическое определение какой пакет макросов
использовать.

Соглашения, которые нужно соблюдать при написании справочных страниц для пакета
Linux man-pages смотрите в man-pages(7).

Заголовок
Первой командой в справочной странице (после комментариев, то есть строк, которые
начинаются с .\") должна быть

.TH заголовок раздел дата источник справочник

Описание аргументов команды TH смотрите в man-pages(7).

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

Разделы
Разделы начинаются с макроса .SH, за которым следует название заголовка.

Единственным обязательным заголовком является ИМЯ, оно должно быть первым разделом
и снабжаться однострочным описанием программы на следующей строке:

.SH ИМЯ
элемент \- описание

Чрезвычайно важно следовать этому формату, и ставить наклонную черту влево перед
одиночным минусом, который указывается после названия объекта. Этот синтаксис
используется программой mandb(8) при создании базы данных кратких описаний для
команд whatis(1) и apropos(1) (описание синтаксиса раздела ИМЯ смотрите в
lexgrog(1)).

Список разделов, которые могут присутствовать в справочной странице, смотрите в
man-pages(7).

Шрифты
Команды для выбора начертания шрифта:
.IB Курсив, чередующийся с полужирным

.IR Курсив, чередующийся с прямым

.RB Прямой, чередующийся с полужирным

.RI Прямой, чередующийся с курсивом

.SB Капитель, чередующаяся с полужирным

.SM Капитель (полезна для аббревиатур)

Традиционно, у каждой команды может быть до шести аргументов, но в реализации GNU
удалено это ограничение (вы могли бы ограничить себя 6 аргументами с целью
переносимости). Аргументы разделяются пробелами. Для указания аргумента с
пробелами можно использовать двойные кавычки. Все аргументы будут выведены друг за
другом без разделяющих пробелов, поэтому для выделения слова жирным и последующим
знаком пунктуации прямым можно использовать команду .BR Если аргументы не заданы,
то команда применяется к следующей строке текста.

Другие макросы и строки
Далее описываются другие сопутствующие макросы и предопределённые строки.
Если не указано обратного, все макросы выполняют разрыв (конец текста в текущей
строке). Многие из этих макросов изменяют или используют «преобладающий отступ».
Это значение изменяется любым макросом с параметром i ниже; в макросы можно не
указывать i и в этом случае будет использован текущий преобладающий отступ. Это
позволяет использовать единый отступ для рядом стоящих параграфов без указания
значения отступа. Обычный (без отступа) параграф сбрасывает значение
преобладающего отступа в значение по умолчанию (0.5 дюйма). По умолчанию,
задаваемый отступ измеряется в ens; старайтесь использовать для отступов единицы
измерения ens или ems, так как при этом автоматически выбирается правильный размер
шрифта. Другие основные макросы:

Обычные параграфы
.LP Тоже что и .PP (начало нового параграфа).

.P Тоже что и .PP (начало нового параграфа).

.PP Начинает новый параграф и сбрасывает преобладающий отступ.

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

.RE Завершает учёт относительной границы отступа и восстанавливает предыдущее
значение преобладающего отступа.

Макросы параграфа с отступом
.HP i Начинает параграф с висящим отступом (первая строка параграфа имеет левую
границу как у обычных параграфов, а остальные строки параграфа имеют
отступ).

.IP x i Параграф с отступом и необязательным весящим тегом. Если тег x не указан,
то весь последующий параграф имеет отступ i. Если тег x задан, то он
висит у левой границы перед последующим параграфом с отступом (как при

Макросы гиперссылок
.UR url
Вставляет гипертекстовую ссылку в URI (URL) url в виде текста ссылки,
окружая её текстом до следующего макроса .UE.

.UE [trailer] Завершает текст ссылки из макроса .UR необязательным trailer
(если есть, то это, обычно закрывающая круглая скобка и/или знак конца
элемента), указываем тут же. Для устройств, не выводящих HTML (например,
man -Tutf8), текст ссылки указывается после URL в угловых скобках; если
текста нет, то URL печатается как ссылка, окружённая в квадратных скобках
(угловые скобки могут отсутствовать на некоторых устройствах). Для
устройств выводящих HTML, текст ссылки ведёт на URL; если текста нет, то
печатается URL как ссылка.

Эти макросы поддерживаются в GNU Troff начиная с версии 1.20 (2009-01-05) и в
Heirloom Doctools Troff начиная с версии 160217 (2016-02-17).

Различные макросы
.DT Сбрасывает значение табуляций в умолчательное (каждые 0.5 дюйма); не
приводит к разрыву.

.PD d Устанавливает вертикальное расстояние между параграфами равным d (если не
указано, то d=0.4v); не приводит к разрыву.

.SS t Подзаголовок t (как .SH, но используется для подраздела внутри раздела).

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

\*R Символ регистрации прав: ®

\*S Изменяет размер шрифта по умолчанию

\*(Tm Товарный знак: ™

\*(lq Двойная кавычка с наклоном влево: “

\*(rq Двойная кавычка с наклоном вправо: "

Безопасный набор
Хотя технически man и является пакетом макросов troff, большое количество других
инструментов обработки файлов справочных страниц не реализуют все свойства 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.

Также вы можете использовать много экранированных последовательностей troff
(начинающихся с \). Если нужно включить обратную косую черту в текст используйте
\e. Можно использовать другие последовательности (здесь x или xx могут быть любыми
символами и N любой цифрой): \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx,
только 't' или 'n' в качестве условия. Должны использоваться только трансляции
(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. При добавлении
URL используйте полный URL (например, ⟨http://www.kernel.org⟩) , чтобы инструменты
могли автоматически найти URL.

Инструменты, обрабатывающие эти файлы, должны открыть файл и исследовать первый
непробельный символ. Считается, что точка (.) или одинарная кавычка (') в начале
строки указывает, что файл в формате troff (man или mdoc). Левая угловая скобка
(<) указывает, что файл в SGML/XML-подобном формате (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)

ДЕФЕКТЫ

Большинство макросов служат для форматирования (например, тип шрифта и интервал),
а не для маркировки семантического содержания (например, что текст — ссылка на
другую страницу), если сравнивать с форматами mdoc и DocBook (даже в HTML больше
семантической маркировки). Это усложняет создание формата man для разных
носителей, чтобы выдать непротиворечивый результат для определённого носителя и
автоматически вставить перекрестные ссылки. Использование безопасного
подмножества, описанного выше, должно упростить автоматизацию перехода между