LinuxDoc.Rumdoc - краткий обзор макропакета -mdoc
HАЗВАHИЕmdoc - краткий обзор макропакета -mdoc
СИHТАКСИС
groff -mdoc файлы ...
HАЗВАHИЕ
Пакет -mdoc представляет собой набор контекстнозависимых и
доменнозависимых макросов, использующихся для форматирования страниц
руководства. BSD Названия макросов и их значения вкратце описаны ниже;
подробное описание пакета находится в примерах на странице
mdoc.samples(7).
Заметьте, что этот пакет редко используется в Linux, хотя он и
применяется для документирования многих широко распространенных программ
(см. man(7) ).
Макросы разбиты на две группы. Первая включает в себя структурные макросы
и макросы форматирования страницы. Вторая содержит страничные и общие
текстовые доменные макросы, которые являются главным отличием пакета
-mdoc от других пакетов форматирования текста, основанных на troff.
СТРУКТУРА СТРАНИЦЫ
Макросы заголовка
Для создания правильной страницы документации необходимы следующие три
макроса, расположенные в следующем строгом порядке:
.Dd Месяц день, год Дата документа.
.Dt НАЗВАНИЕ_ДОКУМЕНТА [раздел] [том] Заголовок текста, оформленный
прописными буквами.
.Os ОПЕРАЦИОННАЯ_СИСТЕМА [версия/выпуск] Операционная система (BSD).
Макросы форматирования
Заголовки секций, разделители параграфов, списки и внешний вид документа.
.Sh Заголовки разделов. Возможные заголовки (в том порядке, в котором
они появляются на странице):
НАЗВАНИЕ Название раздела. Должно содержать макросы:
`.Nm' (или `.Fn' ) и `.Nd'
СИНТАКСИС Способ использования описываемого объекта.
ОПИСАНИЕ Общее описание, которое должно содержать
описание опций и параметров.
ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ Значения, возвращаемые функциями разделов
ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ Описание переменных окружения.
ФАЙЛЫ Файлы, связанные с объектом.
ПРИМЕРЫ Примеры использования объекта.
ДИАГНОСТИКА Обычно используется для определения
состояния интерфейса устройства,
описываемого в разделе 4.
ОШИБКИ Обработка ошибок и сигналов функций,
описанных в разделах ##2 и 3.
СМ. ТАКЖЕ Ссылки и цитаты.
СООТВЕТСТВИЕ Соответствие объекта стандартам, если
таковые существуют.
ИСТОРИЯ Если не существует соответствующего
стандарта, то в этом разделе необходимо
привести историю объекта.
ЗАМЕЧАНИЯ Недочеты, ошибки реализации объекта.
другие разделы По усмотрению автора могут использоваться и
другие заголовки разделов.
.Ss Заголовки подразделов.
.Pp Разделитель параграфов. Вертикальный пропуск (одна строка).
.D1 Вывести одну строку текста со сдвигом.
.Dl Вывести одну строку текста, не нуждающегося в форматировании, со
сдвигом.
.Bd Начало блока. Опции вывода блока:
-ragged Невыровненный (неровные границы).
-filled Выровненный.
-literal Текст или код, не требующий форматирования.
-file name Прочитать содержимое заданного файла и вывести его
на экран.
-offset строка Сдвиг строк. Возможные значения строки:
left Выровнять строки блока по левому краю
(по умолчанию).
center Выровнять строки блока по центру.
indent Шесть пробелов постоянной ширины
(табуляция).
indent-two Две табуляции.
right Выровнять блок по правому краю.
xxn При этом, xx - это число от 4n до 99n.
Aa При этом, Aa - это название макроса,
который можно вызвать.
строка Сдвиг на ширину строки.
.Ed Конец блока (соответствует .Bd).
.Bl Начало списка. Создает списки или колонки. Опции:
Типы списков
-bullet Ненумерованый список с точками
-item Ненумерованый список без названий
-enum Нумерованый список
-tag Список, отмеченный тэгами
-diag Диагностический список
-hang Список с висячим" отступом"
-ohang Список с нависающим" отступом"
-inset Вложенный или продолженный список
Параметры списков
-offset (Все виды). См. `.Bd' выше.
-width (только списки Fl-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).
Cm Да Да Модификатор аргумента командной строки.
Dv Да Да Заданная (определенная) переменная (исходный
текст).
Er Да Да Номер ошибки (исходный текст).
Ev Да Да Переменная окружения.
Fa Да Да Аргумент функции.
Fd Да Да Объявление функции.
Fn Да Да Вызов функции (также .Fo и .Fc).
Ic Да Да Интерактивная команда.
Li Да Да Неформатируемый текст.
Nm Да Да Название команды.
Op Да Да Опция (также .Oo и .Oc).
Ot Да Да Функция старого типа (только Фортран).
Pa Да Да Путь или имя файла.
St Да Да Стандарты (-p1003.2, -p1003.1 или -ansiC)
Va Да Да Название переменной.
Vt Да Да Тип переменной (только Фортран).
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 Нет Нет Отладка (по умолчанию "off" - отключена)
Dc Да Да Закрывающая двойная кавычка.
Do Да Да Открывающая двойная кавычка.
Dq Да Да Текст в двойных кавычках.
Ec Да Да Закрывающая кавычка прилагаемой строки.
Ef Нет Нет Отключить шрифтовой режим.
Em Да Да Выделение текста (в англоязычном стиле).
Eo Да Да Открывающая кавычка прилагаемой строки.
Fx Нет Нет ОС FreeBSD
Нет Да Да Обычный текст.
Ns Да Да Отмена пробела.
Pc Да Да Закрывающая круглая скобка.
Pf Да Нет Строка-префикс.
Po Да Да Открывающая круглая скобка.
Pq Да Да Текст в круглых скобках.
Qc Да Да Закрывающая прямая двойная кавычка.
Ql Да Да Выделенный неформатируемый текст.
Qo Да Да Открывающая прямая двойная кавычка.
Qq Да Да Текст в прямых двойных кавычках.
Re Нет Нет Окончание ссылки.
Rs Нет Нет Начало ссылки.
Rv Нет Нет Возвращаемые значения (только разделы #2 и
3)."
Sc Да Да Закрывающая одинарная кавычка.
So Да Да Открывающая одинарная кавычка.
Sq Да Да Текст в одинарных кавычках.
Sm Нет Нет Режим пробелов (по умолчанию "on" - запущен)
Sx Да Да Ссылка на секцию.
Sy Да Да Символьный формат (в англоязычном стиле).
Tn Да Да Торговая марка или название вида
(уменьшенные прописные буквы).
Ux Да Да UNIX
Xc Да Да Окончание списка расширенных параметров.
Xo Да Да Начало списка расширенных параметров.
Макросы, название которых оканчивается на `q', выделяют кавычками
оставшиеся в строке параметры. Макросы, название которых оканчивается на
`o', начинают текст, выделенный кавычками. Этот текст может занимать
более одной строки и должен оканчиваться макросом, имя которого
завершается символом `c'. Макросы выделения кавычками могут быть
вложены, максимальная глубина вложения - 8 параметров.
Замечание: макросы списка расширенных параметров (`.Xo', `.Xc'), а также
макросы функций (`.Fo', `.Fc') не подчиняются этому правилу. Макросы
списка расширенных параметров используются в том случае, если количество
параметров макроса превышает лимит troff , равный девяти параметрам.
Также доступны макросы UR (начало гипертекстовой ссылки URI/URL), UE (ее
окончание), и UN (идентификация цели ссылки). Более подробная информация
приведена на странице man(#7).
КОНФИГУРАЦИЯ
Более подробная информация о локальной настройке макропакета приведена в
файле /usr/src/share/tmac/README.
ФАЙЛЫ
tmac.doc Страничные и общие текстовые доменные макросы.
tmac.doc-common Общие структурные макросы и определения.
tmac.doc-nroff Зависимый от машины файл стиля nroff.
tmac.doc-ditroff Зависимый от машины файл стиля troff.
tmac.doc-syms Специальные определения (такие, как макросы
стандартов).