mdoc — краткий справочник по пакету макросов -mdoc

ОБЗОР

groff -mdoc файлы …

ОПИСАНИЕ

Пакет -mdoc — это набор макросов на основе содержимого и доменов, предназначен для
форматирования справочных страниц BSD. Для справки, далее приведены имена макросов
и их назначение; подробное описание по использованию пакета смотрите в справочной
странице groff_mdoc(7) и обучающие примеры mdoc.samples(7).

Заметим, что обычно данный пакет макросов не используется в документации Linux, хотя
и применяется в нескольких широко распространённых программах; смотрите man(7).

Описание макросов поделена на две части; в первой рассказывается о макросах
структурирования и физического размещения в в макете страницы. Во второй содержится
описание макросов справочного и текстового домена, которые отличают пакет -mdoc от
других пакетов форматирования troff.

ДОМЕН СТРУКТУРИРОВАНИЯ СТРАНИЦЫ

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

.Dd день, месяц, год Дата документа.
.Dt НАЗВАНИЕ ДОКУМЕНТА [номер раздела] [том]
Заголовок, в верхнем регистре
.Os ОПЕРАЦИОННАЯ СИСТЕМА [версия/выпуск] Операционная система (BSD).

Макросы макета страницы
Заголовки разделов, разделение на параграфы, списки и отображения.

.Sh Заголовки разделов. Допустимые заголовки, в порядке появления:
ИМЯ Название раздела, должно содержать макросы ‘.Nm’ или ‘.Fn’ и
‘.Nd’.
ОБЗОР Описывает использование.
ОПИСАНИЕ Основное описание, должно содержать параметры и значения.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Для функций из раздела два и три.
ОКРУЖЕНИЕ Описание переменных окружения.
ФАЙЛЫ Файлы, относящиеся к описываемому объекту.
ПРИМЕРЫ Примеры и способы использования.
ДИАГНОСТИКА Обычно, используется для диагностики интерфейсов устройств из
раздела четыре.
ОШИБКИ Обработка ошибок и сигналов, для разделов два и три.
СМОТРИТЕ ТАКЖЕ
Перекрёстные ссылки и цитаты.
СООТВЕТСТВИЕ СТАНДАРТАМ
Упоминание о соответствии стандартам, если есть.
ИСТОРИЯ Если в стандарте не описано, то нужно привести историю создания
объекта.
ДЕФЕКТЫ Предостережения и подводные камни.
другое Сюда могут быть добавлены дополнительные главы и темы на
усмотрение автора.
.Ss Заголовки подразделов
.Pp Новый параграф. Вертикальный отступ (одна строка).
.D1 (D-один) Сделать отступ при показе одной текстовой строки.
indent Шесть пробелов постоянной ширины (табуляция).
indent-two Две табуляции.
right Выровнять блок по левому краю, отступая от
правого 2 дюйма.
xxn Где xx — число от 4n до 99n.
Aa Где Aa имя вызываемого макроса.
строка Использовать ширину строки.
.Ed Конец выводимого блока (начатого .Bd).
.Bl Начало списка. Создаёт списки или колонки. Параметры:
Типы списков
-bullet список с элементами с точкой
-item список без меток
-enum список с перечислением
-tag список с метками
-diag список для диагностической информации
-hang список с навешиваемыми ярлыками
-ohang список со свисающими ярлыками
-inset список с выделенными ярлыками
Параметры списка
-offset (все списки) Смотрите про начало блока ‘.Bd’ выше.
-width (только для списков -tag и -hang) Смотрите ‘.Bd’.
-compact (все списки) Не показывать пустые строки.
.El Конец списка.
.It Элемент списка.

МАКРОСЫ СПРАВОЧНОГО И ТЕКСТОВОГО ДОМЕНОВ

Макросы справочного и текстового доменов отличаются от остальных тем, что
большинство из них просматривается для выполнения вызываемых макросов, например:

.Op Fl s Ar файл
Выводит [-s файл]

В этом примере параметр макроса выделения ‘.Op’ просматривается и вызывается
возможный для выполнения макрос ‘Fl’, который анализирует аргумент ‘s’ и затем
вызывает возможный для выполнения макрос ‘Ar’, который анализирует аргумент ‘файл’.
Некоторые макросы можно вызывать, но не анализировать и наоборот. Это отмечено ниже
в колонках анализируемые и вызываемые.

Если не указано обратное, макросы справочного домена имеют единый синтаксис:

.Va аргумент [ . , ; : ( ) [ ] аргумент … ]

Замечание: Открывающие и закрывающие знаки прерывания учитываются только, если
указываются по одному за раз. Набор ‘),’ не считается прерыванием и будет показан с
начальным пробелом и даже использоваться в вызывающем макросе шрифта. Список
аргументов ‘] ) ,’ считается за три последовательных закрывающих знака и начального
пробела между символами и предыдущим аргументом (если есть) не появится. Работа
символа прерывания может быть экранирована с помощью строки ‘\&’. Например, строка

.Ar файл1 , файл2 , файл3 ) . выводит файл1, файл2, файл3).

Макросы справочного домена
Имя Просматривается ВызываемОписание
Ad да да адрес (макрос может устареть)
An да да имя автора
Ar да да аргумент командной строки
Cd нет нет объявление настроек (только раздел 4)
Nm да да имя команды
Op да да параметр (также .Oo и .Oc).
Ot да да тип функции в старом стиле (только Fortran)
Pa да да путь или имя файла
St да да стандарты (-p1003.2, -p1003.1 или -ansiC)
Va да да имя переменной
Vt да да тип переменной (только Fortran)
Xr да да перекрёстная ссылка на справочную страницу

Макросы текстового домена
Имя Просматривается ВызываемОписание
%A да нет имя автора материала
%B да да название книги
%C нет нет место публикации материала (город).
%D нет нет дата публикации материала
%J да да название журнала
%N нет нет номер выпуска материала
%O нет нет дополнительная информация по материалу
%P нет нет номер страницы в материале
%R нет нет название доклада
%T да да название статьи
%V нет нет том материала
Ac да да закрытие цитаты угловой скобкой
Ao да да открытие цитаты угловой скобкой
Ap да да Апостроф
Aq да да цитата в скобках
At нет нет AT&T UNIX
Bc да да закрытие цитаты квадратной скобкой
Bf нет нет начало режима шрифта
Bo да да открытие цитаты квадратной скобкой
Bq да да цитата в квадратных скобках
Bx да да BSD.
Db нет нет отладка (по умолчанию "выкл")
Dc да да закрытие цитаты двойной кавычкой
Do да да открытие цитаты двойной кавычкой
Dq да да цитата в двойных кавычках
Ec да да закрытие цитаты строкой
Ef нет нет конец режима шрифта
Em да да выделение (обычное английское)
Eo да да открытие цитаты строкой
Fx нет нет операционная система FreeBSD
No да да обычный текст (ничего не применять)
Ns нет не нет пробела
Pc да да закрытие цитаты круглой кавычкой
Pf да нет Строка-префикс
Po да да открытие цитаты круглой скобкой
Pq да да цитата в круглых скобках
Qc да да закрытие цитаты прямой двойной кавычкой
Ql да да дословная цитата
Qo да да открытие цитаты прямой двойной кавычкой
Qq да да цитата в прямых двойных кавычках
Re нет нет конец материала
Rs нет нет начало материала
Rv нет нет возвращаемые значения (только разделы 2 и 3)
Sc да да закрытие цитаты одинарной кавычкой
So да да открытие цитаты одинарной кавычкой
Sq да да цитата в одинарных кавычках
макросов, оканчивающихся на ‘o’, начинают цитату, которая может занимать больше
одной входной строки и закрывают цитату совпадающим по имени макросом,
оканчивающимся на ‘c’. Макросы выделения могут быть вложенными и ограничены восемью
аргументами.

Замечание: макросы расширения списка аргументов (‘.Xo’, ‘.Xc’) и макросы выделения
функции (‘.Fo’, ‘.Fc’) нестандартны. Макросы расширения списка аргументов
используются, если количество аргументов макроса превысило бы ограничение troff в
девять аргументов.

Также доступны макросы UR (начинающие гипертекстовую ссылку URI/URL), UE
(завершающие её) и UN (определяет назначение ссылки). Их описание доступно в man(7).

ФАЙЛЫ

doc.tmac Макросы справочного и текстового доменов.
tmac/doc-common Часто используемые структурирующие макросы и определения.
tmac/doc-nroff Стилевой файл nroff, определённый на этой машине.
tmac/doc-ditroff Стилевой файл troff, определённый на этой машине.
tmac/doc-syms Специальные определения (например, стандартные макросы).

СМОТРИТЕ ТАКЖЕ

groff_mdoc(7), man(7), man-pages(7), mdoc.samples(7)