Проект OpenNet: MAN mdoc (7) Макропакеты и соглашения (FreeBSD и Linux)

Интерактивная система просмотра системных руководств (man-ов)

mdoc (7)

mdoc (7) ( FreeBSD man: Макропакеты и соглашения )

>> mdoc (7) ( Русские man: Макропакеты и соглашения )

mdoc (7) ( Linux man: Макропакеты и соглашения )

BSD mandoc
Linux

НАЗВАНИЕ

mdoc - - краткий обзор макропакета -mdoc

СИНТАКСИС

groff -m doc файлы ...

НАЗВАНИЕ

Пакет -mdoc представляет собой набор контекстнозависимых и доменнозависимых макросов, использующихся для форматирования страниц руководства. BSD Названия макросов и их значения вкратце описаны ниже; подробное описание пакета находится в примерах на странице mdoc.samples7.

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

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

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

Макросы заголовка

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

. Месяц день, год: Дата документа.
.: Заголовок текста, оформленный прописными буквами.
. ОПЕРАЦИОННАЯ_СИСТЕМА [версия/выпуск]: Операционная система (BSD )

Макросы форматирования

Заголовки секций, разделители параграфов, списки и внешний вид документа.

.

Заголовки разделов.

Возможные заголовки (в том порядке, в котором они появляются на странице):

НАЗВАНИЕ: Название раздела. Должно содержать макросы: `. ' (или `.Fn ) ' и `. -
СИНТАКСИС: ' Способ использования описываемого объекта.
ОПИСАНИЕ: Общее описание, которое должно содержать описание опций и параметров.
ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ: Значения, возвращаемые функциями разделов ##2 и 3.
ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ: Описание переменных окружения.
ФАЙЛЫ: Файлы, связанные с объектом.
ПРИМЕРЫ: Примеры использования объекта.
ДИАГНОСТИКА: Обычно используется для определения состояния интерфейса устройства, описываемого в разделе 4.
ОШИБКИ: Обработка ошибок и сигналов функций, описанных в разделах ##2 и 3.
СМ. ТАКЖЕ: Ссылки и цитаты.
СООТВЕТСТВИЕ: Соответствие объекта стандартам, если таковые существуют.
ИСТОРИЯ: Если не существует соответствующего стандарта, то в этом разделе необходимо привести историю объекта.
ЗАМЕЧАНИЯ: Недочеты, ошибки реализации объекта.
другие разделы: По усмотрению автора могут использоваться и другие заголовки разделов.

Li .Ss Заголовки подразделов. Li .Pp Разделитель параграфов. Вертикальный пропуск (одна строка). Li .D1 Вывести одну строку текста со сдвигом. Li .Dl Вывести одну строку текста, не нуждающегося в форматировании, со сдвигом. Li .Bd Начало блока. Опции вывода блока:

-ragged

Невыровненный (неровные границы).

-filled

Выровненный.

-literal

Текст или код, не требующий форматирования.

-file name

Прочитать содержимое заданного файла и вывести его на экран.

-offset строка

Сдвиг строк. Возможные значения строки:

left: Выровнять строки блока по левому краю (по умолчанию).
center: Выровнять строки блока по центру.
indent: Шесть пробелов постоянной ширины (табуляция).
indent-two: Две табуляции.
right: Выровнять блок по правому краю.
xx n: При этом, xx - это число от 4 n до 99 n
Aa При этом,: Aa - это название макроса, который можно вызвать.
строка: Сдвиг на ширину строки.

Li .Ed Конец блока (соответствует .Bd). Li .Bl Начало списка. Создает списки или колонки. Опции:

Типы списков

-bullet Ta Ненумерованый список с точками
-item Ta Ненумерованый список без названий
-enum Ta Нумерованый список
-tag Ta Список, отмеченный тэгами
-diag Ta Диагностический список
-hang Ta Список с висячим отступом
-ohang Ta Список с нависающим отступом
-inset Ta Вложенный или продолженный список

Параметры списков

-offset: (Все виды). См. `. ' выше.
-width: (только списки --tag и --hang ). См. `. '
-compact: (Все списки). Не выводит пустые строки.

Li .El Конец списка. Li .It Элемент списка.

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

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

.[-s файл ]: преобразуется в [-s файл ]

В этом примере обрабатывается макрос форматирования опции `.[,] ' который вызывает контекстнозависимый макрос `- ' с параметром `s' , а затем контекстнозависимый макрос `file ... ' с параметром `файл' Некоторые макросы могут быть вызываемыми, но необрабатываемыми и наоборот. Такие макросы отмечены в колонках Обрабатываемые и Вызываемые списка, приведенного ниже.

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

.параметр [ . , ; : ( ) [ ] параметр ...]

Примечание Открывающие и закрывающие знаки препинания распознаются только в том случае, если они указаны по одному. Последовательность символов `),' не распознается как знак препинания и будет выведена с ведущим пробелом тем шрифтом, который использует вызывающий макрос. Список параметров `]' ) , будет распознан как три последовательных знака препинания, и пробелы не будут выведены как до первого символа, так и между символами. Специальное значение знака препинания может быть отменено экранирующей последовательностью `\&' Например, строка

.файл1 , файл2 , файл3 ) .: выведется как файл1 , файл2 , файл3 )

Страничные доменные макросы

Назв. Обраб. Вызыв. Описание
Ta Да Ta Да Ta Адрес. (Этот макрос может работать неправильно.)
An Ta Да Ta Да Ta Автор.
Ta Да Ta Да Ta Параметр командной строки.
Ta Нет Ta Нет Ta Объявление конфигурации (только раздел 4).
Ta Да Ta Да Ta Модификатор аргумента командной строки.
Ta Да Ta Да Ta Заданная (определенная) переменная (исходный текст).
Er Ta Да Ta Да Ta Номер ошибки (исходный текст).
Ta Да Ta Да Ta Переменная окружения.
Fa Ta Да Ta Да Ta Аргумент функции.
Fd Ta Да Ta Да Ta Объявление функции.
Fn Ta Да Ta Да Ta Вызов функции (также .Fo и .Fc).
Ta Да Ta Да Ta Интерактивная команда.
Ta Да Ta Да Ta Неформатируемый текст.
Ta Да Ta Да Ta Название команды.
[Ta Да Ta Да Ta Опция (также .[и .Oc). ]
Ot Ta Да Ta Да Ta Функция старого типа (только Фортран).
Ta Да Ta Да Ta Путь или имя файла.
St Ta Да Ta Да Ta Стандарты (-p1003.2, -p1003.1 или -ansiC)
Ta Да Ta Да Ta Название переменной.
Vt Ta Да Ta Да Ta Тип переменной (только Фортран).
TaДаTaДаTaСсылканастраницуруководства.

Общие текстовые доменные макросы

Назв. Обраб. Вызыв. Описание
%A Ta Да Ta Нет Ta Ссылка на автора.
%B Ta Да Ta Да Ta Ссылка на название книги.
%C Ta Нет Ta Нет Ta Ссылка на место публикации (город).
%D Ta Нет Ta Нет Ta Ссылка на дату публикации.
%J Ta Да Ta Да Ta Ссылка на название журнала.
%N Ta Нет Ta Нет Ta Ссылка на номер выпуска.
%O Ta Нет Ta Нет Ta Ссылка на дополнительную информацию.
%P Ta Нет Ta Нет Ta Ссылка на номер(а) страницы.
%R Ta Нет Ta Нет Ta Ссылка на название.
%T Ta Да Ta Да Ta Ссылка на название статьи.
%V Ta Нет Ta Нет Ta Ссылка на том.
Ac Ta Да Ta Да Ta Закрывающая угловая скобка.
Ao Ta Да Ta Да Ta Открывающая угловая скобка.
Ap Ta Да Ta Да Ta Апостроф.
Aq Ta Да Ta Да Ta Текст в угловых кавычках.
AT&T System Ta Нет Ta Нет Ta AT&T UNIX
Bc Ta Да Ta Да Ta Закрывающая квадратная скобка.
Bf Ta Нет Ta Нет Ta Задать шрифтовой режим.
Bo Ta Да Ta Да Ta Открывающая квадратная скобка.
Bq Ta Да Ta Да Ta Текст в квадратных скобках.
BSD Ta Да Ta Да Ta BSD
Db Ta Нет Ta Нет Ta Отладка (по умолчанию \*qoff\*q - отключена)
Dc Ta Да Ta Да Ta Закрывающая двойная кавычка.
Do Ta Да Ta Да Ta Открывающая двойная кавычка.
``Ta Да Ta Да Ta Текст в двойных кавычках. ''
Ec Ta Да Ta Да Ta Закрывающая кавычка прилагаемой строки.
Ef Ta Нет Ta Нет Ta Отключить шрифтовой режим.
Ta Да Ta Да Ta Выделение текста (в англоязычном стиле).
Eo Ta Да Ta Да Ta Открывающая кавычка прилагаемой строки.
Fx Ta Нет Ta Нет Ta ОС FreeBSD
Нет Ta Да Ta Да Ta Обычный текст.
Ta Да Ta Да Ta Отмена пробела.
Pc Ta Да Ta Да Ta Закрывающая круглая скобка.
Ta Да Ta Нет Ta Строка-префикс.
Po Ta Да Ta Да Ta Открывающая круглая скобка.
(Ta Да Ta Да Ta Текст в круглых скобках. )
Qc Ta Да Ta Да Ta Закрывающая прямая двойная кавычка.
`Ta Да ': Ta Да Ta Выделенный неформатируемый текст.
Qo Ta Да Ta Да Ta Открывающая прямая двойная кавычка.
Qq Ta Да Ta Да Ta Текст в прямых двойных кавычках.

Li Rs Ta Нет Ta Нет Ta "Начало ссылки." Li Rv Ta Нет Ta Нет Ta "Возвращаемые значения (только разделы #2 и "3)." Li Sc Ta Да Ta Да Ta "Закрывающая одинарная кавычка." Li So Ta Да Ta Да Ta "Открывающая одинарная кавычка." Li Sq Ta Да Ta Да Ta "Текст в одинарных кавычках." Li Sm Ta Нет Ta Нет Ta "Режим пробелов (по умолчанию \*qon\*q - запущен)" Li Sx Ta Да Ta Да Ta "Ссылка на секцию." Li Sy Ta Да Ta Да Ta "Символьный формат (в англоязычном стиле)." Li Tn Ta Да Ta Да Ta "Торговая марка или название вида (уменьшенные прописные буквы)." Li Ux Ta Да Ta Да Ta Ux Li Xc Ta Да Ta Да Ta "Окончание списка расширенных параметров." Li Xo Ta Да Ta Да Ta "Начало списка расширенных параметров."

Макросы, название которых оканчивается на `q' , выделяют кавычками оставшиеся в строке параметры. Макросы, название которых оканчивается на `o' , начинают текст, выделенный кавычками. Этот текст может занимать более одной строки и должен оканчиваться макросом, имя которого завершается символом `c' Макросы выделения кавычками могут быть вложены, максимальная глубина вложения - 8 параметров.

Замечание: макросы списка расширенных параметров ( `. ' `. ' , а также макросы функций ( `.Fo , ' `.Fc ) ' не подчиняются этому правилу. Макросы списка расширенных параметров используются в том случае, если количество параметров макроса превышает лимит troff , равный девяти параметрам.

Также доступны макросы UR (начало гипертекстовой ссылки URI/URL), UE (ее окончание), и UN (идентификация цели ссылки). Более подробная информация приведена на странице man#7.