Заголовок¶

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

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

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

Разделы¶

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

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

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

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

Шрифты¶

Команды для выбора начертания шрифта:

.B

Полужирный

.BI

Полужирный курсив (часто применяется при описании функций)

.BR

Полужирный прямой (часто применяется для ссылок на другие справочные страницы)

.I

Курсив

.IB

Курсив, чередующийся с полужирным

.IR

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

.RB

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

.RI

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

.SB

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

.SM

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

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. For the macros that produce alternating type faces, 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.

Другие макросы и строки¶

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 prevailing 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:

Обычные параграфы¶

.LP

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

.P

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

.PP

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

Относительная граница отступа¶

.RS i

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

.RE

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

Макросы параграфа с отступом¶

.HP i

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

.IP x i

Параграф с отступом и необязательным весящим тегом. Если тег x не указан, то весь последующий параграф имеет отступ i. Если тег x задан, то он висит у левой границы перед последующим параграфом с отступом (как при .TP, то тег стоит рядом с командой, а не на следующей строке). Если тег слишком длинный, то текст после тега будет помещён вниз на следующую строку (текст не теряется или искажается). Для списков с маркером используйте этот макрос с \(bu (маркер) или \(em (тире) в качестве тега, а для нумерованных списков в качестве тега используйте цифру или букву с точкой; это упрощает трансляцию в другие форматы.

.TP i

Начинает параграф с висящим тегом. Тег задаётся на следующей строке, но результат будет подобен команде .IP.

Макросы гиперссылок¶

.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

Това́рный знак: (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, \n(xx, \fx и \f(xx. Не используйте экранированные последовательности для рисования графики.

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 redefinitions 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 translations (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).

Если кроме этих возможностей вы используете какие-то другие, то внимательно проверяйте результат на нескольких инструментах. После положительной проверки дополнительной возможности, напишите об этом сопровождающему этого документа о безопасной команде или последовательности, которая будет вставлена в этот список.