MDOC(7)

ИМЯ
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-один) Сделать отступ при показе одной текстовой строки.
.Dl (D-эль) Сделать отступ при показе одной строки дословного текста.
.Bd Начало вывода блока. Параметры:
    -ragged
        Не выровненный по ширине (с рваными краями).
    -filled
        Выровненный по ширине.
    -literal
        Дословный текст или код.
    -file имя
        Прочитать из файла и вывести.
    -offset строка
        Сместить вывод. Значения строки:
        left
            Выравнивание блока по левому краю (по умолчанию).
        center
            Приблизительное центрирование.
        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’ просматривается и вызывается возможный для выполнения макрос ‘-’, который анализирует аргумент ‘s’ и затем вызывает возможный для выполнения макрос ‘file ...’, который анализирует аргумент ‘файл’. Некоторые макросы можно вызывать, но не анализировать и наоборот. Это отмечено ниже в колонках анализируемые и вызываемые.

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

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

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

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

  Макросы справочного домена
Имя | Просматривается | Вызываем | Описание
 | да | да | адрес (макрос может устареть)
 | да | да | имя автора
file ... | да | да | аргумент командной строки
 | нет | нет | объявление настроек (только раздел 4)
 | да | да | модификатор аргумента командной строки
 | да | да | определённые переменные (исходный код)
 | да | да | номер ошибки (исходный код)
 | да | да | переменная окружения
 | да | да | аргумент функции
Fd | да | да | объявление функции
 | да | да | вызов функции (также .Fo и .Fc).
 | да | да | интерактивная команда
 | да | да | дословный текст
mdoc | да | да | имя команды
[| да | да | параметр (также .Oo и .Oc).]
 | да | да | тип функции в старом стиле (только Fortran)
~ | да | да | путь или имя файла
 | да | да | стандарты (-p1003.2, -p1003.1 или -ansiC)
 | да | да | имя переменной
 | да | да | тип переменной (только Fortran)
 | да | да | перекрёстная ссылка на справочную страницу

  Макросы текстового домена
Имя | Просматривается | Вызываем | Описание
%A | да | нет | имя автора материала
%B | да | да | название книги
%C | нет | нет | место публикации материала (город).
%D | нет | нет | дата публикации материала
%J | да | да | название журнала
%N | нет | нет | номер выпуска материала
%O | нет | нет | дополнительная информация по материалу
%P | нет | нет | номер страницы в материале
%R | нет | нет | название доклада
%T | да | да | название статьи
%V | нет | нет | том материала
> | да | да | закрытие цитаты угловой скобкой
<| да | да | открытие цитаты угловой скобкой
'| да | да | Апостроф
<| да | да | цитата в скобках>
AT&T UNIX | нет | нет | AT&T UNIX
] | да | да | закрытие цитаты квадратной скобкой
Bf | нет | нет | начало режима шрифта
[| да | да | открытие цитаты квадратной скобкой
[| да | да | цитата в квадратных скобках]
BSD | да | да | BSD.
Db | нет | нет | отладка (по умолчанию выкл)
” | да | да | закрытие цитаты двойной кавычкой
“| да | да | открытие цитаты двойной кавычкой
“| да | да | цитата в двойных кавычках”
 | да | да | закрытие цитаты строкой
Ef | нет | нет | конец режима шрифта
 | да | да | выделение (обычное английское)
 | да | да | открытие цитаты строкой
FreeBSD | нет | нет | операционная система FreeBSD
 | да | да | обычный текст (ничего не применять)
 | нет | не | нет пробела
) | да | да | закрытие цитаты круглой кавычкой
 | да | нет | Строка-префикс
(| да | да | открытие цитаты круглой скобкой
(| да | да | цитата в круглых скобках)
" | да | да | закрытие цитаты прямой двойной кавычкой
‘| да | да | дословная цитата’
"| да | да | открытие цитаты прямой двойной кавычкой
"| да | да | цитата в прямых двойных кавычках"
Re | нет | нет | конец материала
Rs | нет | нет | начало материала
Rv | нет | нет | возвращаемые значения (только разделы 2 и 3)
’ | да | да | закрытие цитаты одинарной кавычкой
‘| да | да | открытие цитаты одинарной кавычкой
‘| да | да | цитата в одинарных кавычках’
Sm | нет | нет | режим пробелов (по умолчанию вкл)
 | да | да | ссылка на заголовок документа
 | да | да | символический (обычный английский)
 | да | да | имя вида или типа (малые прописные).
UNIX | да | да | UNIX
 | да | да | закрытие расширенного списка аргументов
 | да | да | открытие расширенного списка аргументов

Имена макросов, оканчивающихся на ‘q’, оставляют элементы в списке аргументов. Имена макросов, оканчивающихся на ‘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)