mdoc.samples - примеры написания страниц руководства BSD при помощи -mdoc

НАЗВАНИЕ
mdoc.samples - - примеры написания страниц руководства BSD при помощи
-mdoc

СИНТАКСИС
man mdoc.samples

ОПИСАНИЕ
В данном файле приведены примеры написания страниц руководства BSD при
помощи макро-пакета -mdoc, который является зависимым от контекстаи
доменапакетом форматирования текста troff(1). Его предок, пакет -man(7),
задавал только расположение текста на странице, оставляя работу со
шрифтами на авторскую доработку. В -mdoc формат страницы определяется
структурным доменом страницы, состоящим из макросов для заголовков
текста, секций, блоков вывода и списков. Особенно это касается макросов,
определяющих физическое положение текста на отформатированной странице.
В дополнение к структурному домену страницы существуют еще два домена:
страничный домен и общий текстовый домен. Общий текстовый домен содержит
макросы, выполняющие задачи выделения текста. Страничный домен содержит
набор макросов, предоставляющих пользователю (в стандартной форме вывода)
команды, функции и соответствующие файлы BSD. Макросы в страничном
домене работают с названиями команд, их параметрами и опциями, названиями
и параметрами функций, именами файлов, переменными, ссылками на другие
страницы и т.п. Эти элементы доменов имеют большую ценность как для
автора документа, так и для будущего пользователя. Есть надежда, что
такая стандартизация всего набора страниц руководства обеспечит более
простое их преобразование для будущих утилит формирования документации.

ПРИСТУПАЕМ К РАБОТЕ
По той причине, что обычно учебные пособия, похожие на это, читают люди,
которым информация нужна немедленно, мы предполагаем, что пользователь
этого документа тоже нетерпелив. Материал, представленный в этом
документе, поделен на несколько частей:

1. ОГРАНИЧЕНИЯ TROFF
Использование макросов.
Передача пробелов в виде параметров.
Завершающие строку пробелы (предупреждение).
Escape-последовательности для вывода специальных
символов.

2. СТРОЕНИЕ СТРАНИЦЫ РУКОВОДСТВА
Шаблон страницы руководства.

3. МАКРОСЫ ЗАГОЛОВКА.

4. ВВЕДЕНИЕ В СТРАНИЧНЫЙ И ОБЩИЙ ТЕКСТОВЫЙ ДОМЕНЫ.
Что в имени тебе моем....
Общий синтаксис.

5. СТРАНИЧНЫЙ ДОМЕН
Адреса.
Автор.
Параметры.
Задание конфигурации (только раздел #4).
Модификатор команды.
Определенные переменные.
Коды ошибок (только раздел #2).
Переменные окружения.
Параметры функции.
Определение функции.
Флаги.
Функции (в т.ч. и библиотечные).
Типы функций.
Интерактивные команды.
Названия.
Опции.
Пути.
Переменные.
Ссылки.

6. ОБЩИЙ ТЕКСТОВЫЙ ДОМЕН
Макрос AT&T.
Макрос BSD.
Макрос FreeBSD.
Макррос UNIX.
Макросы выделения
Выделение угловыми скобками.
Выделение квадратными скобками.
Выделение двойными кавычками.
Выделение круглыми скобками.
Выделение одинарными кавычками.
Макрос префикса.
Макрос обычного текста.
Макрос отключения пробелов.
Ссылки на раздел.
Ссылки и цитаты.
Возвращаемые значения (только разделы #2 и #3)
Торговые марки (Акронимы и названия видов).
Расширенные параметры.

7. СТРУКТУРНЫЙ ДОМЕН СТРАНИЦЫ
Заголовки секций.
Параграфы и расстояние между строками.
Сохранение исходного формата.
Блоки вывода.
Режимы шрифтов (Выделение, Неформатируемый текст и
Символьный режим).
Списки и колонки.

8. ПРЕДОПРЕДЕЛЕННЫЕ СТРОКИ

9. ДИАГНОСТИКА

10. ФОРМАТИРОВАНИЕ ПРИ ПОМОЩИ GROFF, TROFF И NROFF

11. ОШИБКИ

ОГРАНИЧЕНИЯ TROFF
Пакет -mdoc ставит перед собой цель упростить процесс написания страниц
руководства. Теоретически автор не должен знать тонкостей troff(1) для
использования -mdoc; однако, существует несколько ограничений, которые
обойти невозможно, и лучше их не использовать. Надо добавить, что этот
пакет не работает быстро.

Использование макросов
Как и в troff(1), макрос может быть вызван указанием `.' (точки) в начале
строки, за которой следует двухсимвольное название макроса. За ним могут
следовать параметры макроса, разделенные пробелами. Именно точка в
начале строки заставляет troff(1) считать следующие два символа именем
макроса. Для того, чтобы поместить `.' (точку) в начало строки в ином,
отличном от запуска макроса контексте, укажите перед `.' (точкой)
escape-последовательность `\&'. Эта последовательность означает пробел с
нулевой шириной и никогда не выводится.

Вообще, макросы troff(1) могут иметь до 9-и параметров, остальные же
параметры игнорируются. Многие макросы в -mdoc также могут иметь до 9-и
параметров, и в некоторых случаях параметров может быть и больше (См.
секцию Расширенные параметры). Некоторые макросы обрабатывают параметры
в кавычках (см. ниже секцию Передача пробелов в виде параметров ).

Многие макросы из общего текстового или страничного доменов -mdoc
особенны тем, что их параметры могут представлять собой имена вызываемых
макросов. Это означает, что если один из параметров в списке
соответствует имени макроса из общего текстового или страничного доменов
и этот макрос является вызываемым, то этот макрос будет исполнен или
вызван при обработке. В этом случае перед параметром не ставится `.'
(точка), несмотря на то, что это имя макроса. Таким образом, макросы
могут быть вложенными; например, макрос необязательных параметров, `.Op',
может вызвать макросы флагов и параметров `Fl' и `Ar' для указания
необязательного флага с параметром:

[-s байтов] делается при помощи .Op Fl s Ar байтов

Для того, чтобы двухсимвольная строка не обрабатывалась в качестве имени
макроса, перед ней надо указать `\&':

[Fl s Ar bytes] делается при помощи .Op \&Fl s \&Ar bytes

Таким образом, в данном случае строки `Fl' и `Ar' не считаются именами
макросов. Макросы, чьи списки параметров проверяются на наличие в них
имен вызываемых макросов, называются "обрабатываемыми", а макросы,
которые могут быть вызваны из параметров, называются "вызываемыми". Это
не совсем корректно, с технической точки зрения, так как все макросы
обрабатываются и вызываются, но эта терминология используется лишь для
разделения двух понятий.

Передача пробелов в виде параметров
Иногда в качестве параметра макроса необходимо указать один или несколько
пробелов. Это бывает нужно для игнорирования лимита из девяти параметров
или для макросов, которым необходим строгий порядок расположения
параметров в строке. Например, макрос функции `.Fn' определяет, что
первый его параметр - название функции, а все остальные - ее параметры.
В ANSI C параметры функции указываются в списке, заключенном в скобки, и
каждый параметр бывает, как минимум, строкой из двух слов. Например, int
foo.

Существует два возможных способа передачи параметра, содержащего пробел.
Примечание по реализации К сожалению, наиболее простой и удобный способ
передачи пробелов внутри кавычек очень отражался на скорости работы и
объемах памяти, используемой AT&T troff. Этот способ не отражается на
работе groff, но для совместимости этот способ реализован только для тех
макросов, которым это было необходимо:

Cd Задание конфигурации (только секция СИНТАКСИС раздела 4).
Bl Начало списка (для подпараметра width).
Em Выделенный текст.
Fn Функции (разделы #2 и #3).
It Элементы списков.
Li Неформатируемый текст.
Sy Символьный текст.
%B Названия книг.
%J Названия журналов.
%O Дополнительная информация об упоминаемом тексте.
%R Название отчета (в упоминаемом тексте).
%T Название статьи в книге или журнале.

Одним из способов передачи строки, содержащей пробелы, является
использование "жесткого" (или непереносимого) пробела `\ ', то есть,
пробела, перед которым указан символ `\'. Этот метод может
использоваться в работе с любым макросом, но у него есть побочный эффект
- не совсем корректное выравнивание пробелов в строке. Troff
рассматривает "жесткий" пробел так, как любой другой печатный символ, и
не может разделить строку для форматирования, как того можно было
ожидать. Этот метод можно использовать в работе со строками, которые, в
принципе, не должны переноситься на новую строку. Например:

fetch(char *str) делается при помощи `.Fn fetch char\ *str'

fetch(char *str) можно сделать и так: `.Fn fetch "char *str"'

Если `\' или кавычки опустить, то макрос `.Fn' будет иметь три параметра,
а результат будет следующим:

fetch(char, *str)

Пример, в котором описано, что происходит, если список параметров
превышает длину строки, приведен в секции ЗАМЕЧАНИЯ.

Завершающие строку пробелы (предупреждение)
Troff может не распознать пробелы в конце строки. Неплохо удалять все
пробелы, находящиеся в конце строк. Если возникнет необходимость
поставить пробел в конце строки, то лучше это сделать при помощи
непереносимого пробела и escape-символа `\&'. (Например, `string\ \&' ).

Escape-последовательности для вывода специальных символов
Специальные символы, такие, как `\n', указываются при помощи замены
символа `\' на `\e' (например, `\en') для того, чтобы сохранить в тексте
обратный слэш.

СТРОЕНИЕ СТРАНИЦЫ РУКОВОДСТВА
"Тело" страницы руководства можно легко создать при помощи базового
шаблона, находящегося в файле /usr/share/misc/mdoc.template. Несколько
примеров страниц руководства можно найти в каталоге
/usr/share/examples/mdoc.

Шаблон страницы руководства

.\" Следующие макросы обязательны для всех страниц руководства
.Dd Месяц, день, год
.Os ОПЕРАЦИОННАЯ_СИСТЕМА [версия/релиз]
.Dt НАЗВАНИЕ_ДОКУМЕНТА [номер_раздела] [том]
.Sh НАЗВАНИЕ
.Nm название
.Nd одна строка с описанием названия
.Sh СИНТАКСИС
.Sh ОПИСАНИЕ
.\" Следующие макросы должны быть раскомментированы
.\" и использованы по необходимости. Эта сеция справедлива
.\" только для описания возвращаемых значений страниц руководства из секций #2 и #3.
.\" .Sh ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
.\" Эта секция необходима только для страниц разделов #1, #6, #7 и #8
.\" .Sh ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
.\" .Sh ФАЙЛЫ
.\" .Sh ПРИМЕРЫ
.\" Следующая секция нужна только для разделов #1, #6, #7 и #8
.\" (возвращаемые shell-значения команды и
.\" диагностика fprintf/stderr)
.\" .Sh ДИАГНОСТИКА
.\" Следующая секция есть только в разделах #2 и #3
.\" .Sh ОШИБКИ
.\" .Sh СМ.ТАКЖЕ
.\" .Sh СООТВЕТСТВИЕ
.\" .Sh ИСТОРИЯ
.\" .Sh АВТОРЫ
.\" .Sh ЗАМЕЧАНИЯ

Первыми в шаблоне находятся макросы: (.Dd, .Os, .Dt); дата документа,
операционная система страницы руководства или некоторый источник, для
которого разрабатывалась или модифицировалась страница, и заголовок
страницы, (в верхнем регистре) вместе с номером раздела, которому
принадлежит страница. Эти макросы однозначно идентифицируют страницу.
Они описаны ниже в секции МАКРОСЫ ЗАГОЛОВКА.

Все остальное в шаблоне - заголовки секций (.Sh), из которых НАЗВАНИЕ,
СИНТАКСИС и ОПИСАНИЕ являются обязательными. Заголовки секций описаны в
разделе СТРУКТУРНЫЙ ДОМЕН СТРАНИЦЫ после описания СТРАНИЧНОГО ДОМЕНА.
Некоторые контекстные макросы используются для демонстрации работы
макросов форматирования страницы; рекомендуется прочесть главу о
контекстных макросах до главы о макросах форматирования.

МАКРОСЫ ЗАГОЛОВКА
Макросы заголовка являются первой частью структурного домена страницы, но
описаны отдельно. Это сделано для тех, кто желает создавать страницы
руководства старого формата. Макросы заголовка существуют для указания
названия страницы или документа, операционной системы и даты его
создания. Эти макросы вызываются только один раз в самом начале
документа и используются только для создания верхнего и нижнего
колонтитулов страницы.

.Dt НАЗВАНИЕ_ДОКУМЕНТА номер_раздела [том]
Название документа сообщает о том, что данный документ описывает.
Оно должно быть написано ПРОПИСНЫМИ БУКВАМИ вследствие некоторых
ограничений troff. Номер секции может быть от 1-ого до 8-и, и,
если он задан, название тома можно опустить. Название тома может
быть произвольным или таким:

AMD UNIX Ancestral Manual Documents (Документы
предыдущих версий)
SMM UNIX System Manager's Manual (Документы системного
администратора)
URM UNIX Reference Manual (Справочное руководство)
PRM UNIX Programmer's Manual (Руководство программиста)

По умолчанию для секций #1,#6 и #7 принимается том URM, для
секции #8 - SMM, а для секций #2, #3, #4 и #5 - PRM.

.Os операционная_система номер_версии
Название операцинной системы должно быть общепринятым
сокращением, например, BSD, FreeBSD или ATT. Номер версии должен
быть указан в стандартном формате заданной версии системы,
например, 4.3, 4.3+Tahoe, V.3, V.4. Нераспознанные параметры
выводятся в нижнем колонтитуле страницы, "как есть". Например,
стандартный нижний колонтитул выглядит примерно так:

.Os BSD 4.3,

.Os FreeBSD 2.2

или (для местного набора страниц)

.Os Отдел КБ

По умолчанию `.Os' без параметров задан как BSD в машинозависимом
файле /usr/share/tmac/mdoc/doc-common. На самом деле, это должно
автоматически преобразовываться, как в случае с LOCAL. Заметьте,
что если макрос `.Os' не указан, то левый нижний угол страницы
будет выглядеть непривлекательно.

.Dd месяц день, год
Дата должна быть написана в стандартном (для англоязычных стран)
варианте:

Январь 25, 1989

ВВЕДЕНИЕ В СТРАНИЧНЫЙ И ОБЩИЙ ТЕКСТОВЫЙ ДОМЕНЫ
Что в имени тебе моем...
Названия макросов страничного домена появились из повседневного
информационного языка, используемого для описания команд, процедур и
сопутствующих файлов. Несколько различающиеся варианты этого языка
используются для описания трех аспектов написания страницы руководства:
во-первых, это описание использования макросов -mdoc, во-вторых -
описание команд UNIX при помощи -mdoc, и в-третьих, - описание команды
пользователю в обычном виде; то есть описание команды в виде текста на
странице руководства.

В первом случае макросы troff(1) сами по себе являются командами; общий
синтаксис команд troff:

.Va параметр1 параметр2 ... параметр9

`.Va' - это макрос, а все, что следует за ним, - его параметры. Во
втором случае при описании команды UNIX используются контекстные макросы;
командная строка в секции СИНТАКСИС обычно выглядит так:

filter [-флаг] вх.файл вых.файл

Здесь, filter - это название команды, заключенная в квадратные скобки
строка; -флаг - это необязательный (это указано квадратными скобками)
параметр-флаг. Согласно терминологии -mdoc вх.файл и вых.файл называются
параметрами. Создается этот формат при помощи следующих макросов:

.Nm filter
.Op Fl флаг
.Ar вх.файл вых.файл

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

make [-e -iknqrstv] [-D переменная] [-d флаги] [-f makefile]
[-I каталог] [-j максимальное_количество_задач]
[переменная=значение] [цель_сборки ...]

Далее Вы можете рассмотреть команду make и определить аргумент makefile
как аргумент флага -f, имея в виду, что операнд файла цель_сборки
является дополнительным. Такие детали могут предотвратить появление
путаницы. Так или иначе, пакет -mdoc не имеет макроса для аргумента к
флагу. Вместо этого аргумент макроса `Ar' используется для такого
операнда или аргумента файла, как цель_сборки, так же, как и для
аргумента к флагу, например, variable. Командная строка make состоит из:

.Nm make
.Op Fl eiknqrstv
.Op Fl D Ar переменная
.Op Fl d Ar флаги
.Op Fl f Ar makefile
.Op Fl I Ar каталог
.Op Fl j Ar максимальное_количество_задач
.Op Ar переменная=значение
.Bk -words
.Op Ar цель_сборки ...
.Ek

Макросы `.Bk' и `.Ek' рассматриваются в Keeps.

Общий синтаксис
Страничный домен макросов и общий текстовый домен макросов имеют
одинаковый синтаксис, но есть ряд небольших различий: `.Ar', `.Fl',
`.Nm', и `.Pa' различаются только, когда вызываются без аргументов; `.Fn'
и `.Xr' определяют порядок своих аргументов в списках, а макросы `.Op' и
`.Fn' имеют ограничения глубины вложенных вызовов макросов. Все макросы
содержания должны распознавать и поддерживать пунктуацию, оставляя пробел
перед знаком. Если запрос делается в такой форме:

.Li sptr, ptr),

то результат будет следующим:

sptr, ptr),

Пунктуация не была распознана, и вся информация выведена в обычном
текстовом режиме. Поэтому перед знаками следует сразу ставить пробелы:

.Li sptr , ptr ) ,

В этом случае результат будет следующим:

sptr, ptr),

Теперь пунктуация распознана и выведена в формате, отличном от
текстового.

Для того, чтобы убрать специальное значение символа, используйте `\&'.
Troff является языком макросов, и поэтому возникают проблемы при
написании строки, содержащей математические, логические или цитирующие
символы:

{+,-,/,*,%,,=,=,==,&,`,',"}

Проблема заключается в том, что troff может воспринять эти знаки как
составляющие команды. Для того, чтобы этого не произошло, рекомендуется
обособлять такие знаки при помощи `\&'. Типичный синтаксис показан в
макросе содержания, приведенном ниже `.Ad'.

СТРАНИЧНЫЙ ДОМЕН
Адреса
Макрос адреса определяет структуру адреса в форме addr1[,addr2[,addr3]].

Использование: .Ad адрес ...
.Ad addr1 addr1
.Ad addr1 . addr1.
.Ad addr1 , file2 addr1, file2
.Ad f1 , f2 , f3 : f1, f2, f3:
.Ad addr ) ) , addr)),

Вызов `.Ad' без аргументов будет ошибочным. Значение `.Ad' может быть
вызвано и обработано другими макросами.

Автор
Макрос `.An' используется для указания имени автора документа или
страницы руководства. Любые аргументы, стоящие после имени, считаются
пунктуационными знаками.

Использование: .An имя_автора
.An Joe Author Joe Author
.An Joe Author , Joe Author,
.An Joe Author Aq nobody@FreeBSD.ORG
Joe Author
.An Joe Author ) ) , Joe Author)),

Макрос `.An' может быть вызван и обработан. Вызов макроса `.An' без
аргумента приведет к ошибке.

Параметры
Аргумент макроса `.Ar' может быть использован, когда есть ссылка на
аргумент командной строки.

Использование: .Ar аргумент ...
.Ar file ...
.Ar file1 file1
.Ar file1 . file1.
.Ar file1 file2 file1 file2
.Ar f1 f2 f3 : f1 f2 f3:
.Ar file ) ) , file)),

Если производится вызов `.Ar' без аргумента, то читаемое значение равно
`file ...'. Макрос `.Ar' может быть вызван и обработан.

Задание конфигурации (только раздел #4)
Пример использования макроса `.Cd' можно найти в config(8) Этот макрос
использует двойные кавычки.

device le0 at scode? пишется в виде строки: `.Cd device le0 at
scode?'.

Модификатор команд
модификатор команд идентичен команде `.Fl' (флаг), за исключением того,
что макрос `.Cm' не требует тире перед каждым аргументом. Обычно флаги
отмечаются предшествующим им тире, но некоторые команды не используют
этот прием. Модификаторы команд можно описать и совместно с
интерактивными командами, такими, как команды редактирования. См.
Flags.

Определенные переменные
Переменная, которая задана во вложеном файле, определена макросом `.Dv'.

Использование: .Dv определенная_переменная ...
.Dv MAXHOSTNAMELEN MAXHOSTNAMELEN
.Dv TIOCGPGRP ) TIOCGPGRP)

Вызов `.Dv' без аргумента приведет к ошибке. `.Dv' может быть вызван и
обработан.

Коды ошибок (только раздел #2)
Макрос кодов ошибок `.Er' определяет коды возвращаемых ошибок для второго
раздела библиотечных функций. Во втором примере, приведенном ниже,
показано, как `.Er' используется совместно с `.Bq' макросом общего
текстового домена.

Использование: .Er КОД_ОШИБКИ ...
.Er ENOENT ENOENT
.Er ENOENT ) ; ENOENT);
.Bq Er ENOTDIR [ENOTDIR]

Вызов `.Er' без аргумента приведет к ошибке. Макрос `.Er' можно вызвать
и обработать.

Переменные окружения
Макрос `.Ev' задает переменные окружения.

Использование: .Ev аргумент ...
.Ev DISPLAY DISPLAY
.Ev PATH . PATH.
.Ev PRINTER ) ) , PRINTER)),

Вызов `.Ev' без аргумента вызовет ошибку. Макрос `.Ev' может быть вызван
и обработан.

Параметры функции
Макрос `.Fa' используется для ссылки на аргумент функции (параметр) вне
раздела СИНТАКСИС или если список параметров внутри раздела СИНТАКСИС
слишком длинный для обработки его макросом `.Fn' и вложенными в него
макросами `.Fo' и `.Fc'. `.Fa' может также использоваться для ссылок на
члены структуры.

Использование: .Fa аргумент_функции ...
.Fa d_namlen ) ) , d_namlen)),
.Fa iov_len iov_len

Вызов макроса `.Fa' без аргумента приведет к ошибке. `.Fa' может быть
вызван и обработан.

Определение функции
Макрос `.Fd' используется в разделе СИНТАКСИС с функциями из второго и
третьего разделов. Макрос `.Fd' не может вызвать другой макрос и не
может быть вызван другим макросом.

Использование: .Fd файл (или определенная функция)

В разделе СИНТАКСИС запрос `.Fd' вызывает разбиение строки в том случае,
если соответствующая функция задана, а разбиения строки все еще не
произошло. После этого остаются удобные для работы вертикальные пробелы
между предыдущим и последующим вызовом функций.

Флаги
Макрос `.Fl' поддерживает разбиение командной строки и требует указания
тире до флага `-'.

Использование: .Fl аргумент ...
.Fl -
.Fl cfv -cfv
.Fl cfv . -cfv.
.Fl s v t -s -v -t
.Fl - , --,
.Fl xyz ) , -xyz),

Макрос `.Fl' без аргументов возвратит тире, то есть, стандартный
stdin/stdout. Если поставить тире, то `.Fl' вернет два тире. Макрос
`.Fl' может быть вызван и обработан.

Функции (в том числе и библиотечные)
Макрос .Fn создан по правилам ANSI C.

Использование: .Fn [тип] функция [[тип] параметры ... ]
.Fn getchar getchar()
.Fn strlen ) , strlen()),
.Fn "int align" "const * char *sptrs", int align(const * char *sptrs),

Вызов макроса `.Fn' без параметров приведет к ошибке. Макрос `.Fn' может
быть вызван и обработан, но любой вызов другого макроса приведет к
завершению работы `.Fn'.

Для функций, которые имеют более восьми параметров (это бывает редко),
используются макросы: `.Fo' (для открытия функции), `.Fc' (для закрытия
функции) и `.Fa' (для указания на аргументы функции). Например:

.Fo "int res_mkquery"
.Fa "int op"
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "char *data"
.Fa "int datalen"
.Fa "struct rrec *newrr"
.Fa "char *buf"
.Fa "int buflen"
.Fc

В результате получается:

int res_mkquery(int op, char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf, int buflen)

Макросы `.Fo' и `.Fc' могут быть вызваны и обработаны. В разделе
СИНТАКСИС функции описываются с начала строки. Если в разделе СИНТАКСИС
представлено более одной функция и не задан тип функции, то произойдет
разбиение строки и останется место между названием текущей функции и
названием предыдущей. В настоящее время макрос `.Fn' не проверяет
границы слов по длине форматирования строки troff и поэтому может
некорректно разбить строку. В ближайшем будущем такой случай будет
доработан.

Типы функций
Этот макрос предназначен для раздела СИНТАКСИС. он может быть
использован где угодно, но его основной целью является представление типа
функции в стандартной форме для СИНТАКСИСА второго и третьего разделов
(он предусматривает разбиение строки, при котором, название функции
пишется с начала следующей строки).

Использование: .Ft тип ...
.Ft struct stat struct stat

Макрос `.Ft' можно вызвать при помощи других макросов.

Интерактивные команды
Макрос `.Ic' обозначает интерактивные или внутренние команды.

Использование: .Ic аргумент ...
.Ic :wq :wq
.Ic do while {...} do while {...}
.Ic setenv , unsetenv setenv, unsetenv

Вызов макроса `.Ic' без аргумента вызовет ошибку. Макрос `.Ic' может
быть вызван и обработан.

Названия
Макрос `.Nm' используется для заголовков или подзаголовков. Его
особенностью является запоминание первого аргумента, с которым он был
вызван, что обычно бывает названием страницы. При вызове макроса `.Nm'
без аргумента он возвращается с этим первоначальным значением, что
облегчает работу автора. Замечание: во втором и третьем разделах страниц
руководства имя функции в секции NAME пишется с использованием макроса
`.Nm', а в остальных секциях и других разделах страниц руководства
используется макрос `.Fn'. Для интерактивных команд, таких, как `while'
в csh(1), используется макрос `.Ic'. Макросы `.Ic' и `.Nm' почти
идентичны, их различает только описанная выше возможность `.Nm'
запоминать первый аргумент.

Использование: .Nm аргумент ...
.Nm mdoc.sample mdoc.sample
.Nm \-mdoc -mdoc.
.Nm foo ) ) , foo)),
.Nm mdoc.samples

Макрос `.Nm' может быть вызван и обработан.

Опции
Макрос `.Op' ставит квадратные скобки, указывающие на дополнительное
значение их содержимого (опции), и ставит пунктуационные знаки после
скобок. Макросы `.Oc' и `.Oo' могут использоваться несколько раз в одной
строке.

Использование: .Op опции ...
.Op []
.Op Fl k [-k]
.Op Fl k ) . [-k]).
.Op Fl k Ar kookfile [-k kookfile]
.Op Fl k Ar kookfile , [-k kookfile],
.Op Ar objfil Op Ar corfil [objfil [corfil]]
.Op Fl c Ar objfil Op Ar corfil , [-c objfil [corfil]],
.Op word1 word2 [word1 word2]

Макросы `.Oc' и `.Oo':

.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar interval
.Op Fl c Ar count
.Oc

,- выдают результат: [[-k kilobytes] [-i interval] [-c count]]

Макросы `.Op', `.Oc' и `.Oo' могут быть вызваны и обработаны.

Пути
Макрос `.Pa' форматирует пути или имена файлов.

Использование: .Pa путь
.Pa /usr/share /usr/share
.Pa /tmp/fooXXXXX ) . /tmp/fooXXXXX).

Макрос `.Pa' может быть вызван и обработан.

Переменные
Характерная ссылка на переменную выглядит так:

Использование: .Va переменная ...
.Va count count
.Va settimer, settimer,
.Va int *prt ) : int *prt):
.Va char s ] ) ) , char s])),

При вызове `.Va' без аргумента произойдет ошибка. Макрос `.Va' может
быть вызван и обработан.

Ссылки
Макрос `.Xr' определяет, что первый аргумент - это название страницы
руководства, второй (если он есть) -номер раздела страниц или знак
пунктуации. Все остальные аргументы будут рассматриваться как
пунктуационные знаки.

Использование: .Xr man_страничка [1,...,8]
.Xr mdoc mdoc
.Xr mdoc , mdoc,
.Xr mdoc 7 mdoc(7)
.Xr mdoc 7 ) ) , mdoc(7))),

Макрос `.Xr' может быть вызван и обработан. Вызов макроса `.Xr' без
аргумента приведет к ошибке.

ОБЩИЙ ТЕКСТОВЫЙ ДОМЕН
Макрос AT&T
Использование: .At [v6 | v7 | 32v | V.1 | V.4] ...
.At AT&T UNIX
.At v6 . Version 6 AT&T UNIX.

Макрос `.At' не вызывается и не обрабатывается. Обычно он использует
сразу два аргумента.

Макрос BSD
Использование: .Bx [версия/релиз] ...
.Bx BSD
.Bx 4.3 . 4.3BSD.

Макрос `.Bx' может быть вызван и обработан.

Макрос FreeBSD
Использование: .Fx версия.релиз ...
.Fx 2.2 . FreeBSD 2.2.

Макрос `.Fx' не вызывается и не обрабатывается. Обычно он использует два
аргумента.

Макрос UNIX
Использование: .Ux ...
.Ux UNIX

Макрос `.Ux' может быть вызван и обработан.

Макросы выделения
Принцип выделения идентичен принципу цитирования. Объект, подлежащий
выделению, помещается между двумя символами, такими, как кавычки. В этом
документе для цитирования и выделения используются почти одна и та же
пунктуация. Для указания на обособление используются макросы,
оканчивающиеся буквой `q'. А так как они могут использоваться на
протяжении текста, то в эту область может попасть и объект цитирования
(или наоборот, в объект цитирования попадет объект, подлежащий
выделению), поэтому внутри можно использовать макрос цитирования,
прописанный в одной строке. Поэтому для каждого объекта обособления
можно еще использовать два макроса: открывающий и закрывающий - они
оканчиваются строчными буквами `o' и `c' соответственно.

Обособ. Закрыв. Открыв. действие Результат
.Aq .Ac .Ao Обособление угловыми скобками
.Bq .Bc .Bo Обособление квадратными скобками [string]
.Dq .Dc .Do Обособление двумя единичными кавычками ``string''
.Ec .Eo Обособление значками XX XXstringXX
.Pq .Pc .Po Обособление круглыми скобками (string)
.Ql Литературное цитирование `st' or string
.Qq .Qc .Qo Обособление двойными кавычками "string"
.Sq .Sc .So Обособление кавычками `string'

Все макросы обособления, кроме приведенных ниже, могут быть вызваны и
обработаны. Все поддерживают пунктуацию, если она представлена одним
знаком и разделена пробелами. Макросы обособления проверяют открывающуюся
и закрывающуюся пунктуацию на расположение ее в области обособления. Это
делает возможным проведение компоновки.

.Ec, .Eo Эти макросы определяют первый аргумент как открывающий, а
второй как закрывающий.

.Ql Макрос литературного цитирования по-разному работает в troff и
nroff. Если он форматируется nroff, то он всегда обособлен.
Если форматируется в troff, то он обособляется только в том
случае, если состоит менее чем из трех символов. Это
выполняется для того, чтобы сделать короткие строки более
заметными. Макрос приставки

.Pf не может быть вызван, но может быть обработан. Если выполнить
команду строки

.Pf ( Fa name2,
то результат будет следующим: (name2.

Макрос `.Ns' (нет пробела) производит аналогичное действие.

Примеры обособления:
.Aq <>
.Aq Ar ctype.h ) , ),
.Bq []
.Bq Em Greek , French . [Greek, French].
.Dq ``''
.Dq string abc . ``string abc''.
.Dq ╢^[A-Z]╢ ``╢^[A-Z]╢''
.Ql man mdoc `man mdoc'
.Qq ""
.Qq string ) , "string"),
.Qq string Ns ), "string),"
.Sq `'
.Sq string `string'

Примером вложенного макроса может служить макрос опций `.Op'. Он был
создан на основе вышеперечисленных макросов. Макросы расширенного списка
аргументов `.Xo' и `.Xc' были также созданы на основе этих функций и
могут служить хорошим примером использования пакета макросов -mdoc

No-Op или макроса обычного текста.
Макрос `.No' используется в случае, когда командная строка не должна быть
форматирована и подчиняется синтаксису содержания макроса.

Макрос отключения пробелов
Макрос `.Ns' убирает ненужные пробелы между его запросами. Он обычно
используется в старых списках аргументов, где между флагом и аргументом
нет пробела:

.Op Fl I Ns Ar каталог в результате получается: [-Iкаталог]

Замечание: макрос `.Ns' всегда вызывает макрос `.No' после удаления
пробелов, если за ним не следует другой макрос. Макрос `.Ns' может быть
вызван и обработан.

Ссылки на раздел
Макрос `.Sx' определяет ссылку на заголовок раздела в этом документе.
Макрос может быть вызван и обработан.

.Sx ФАЙЛЫ ФАЙЛЫ

Ссылки и цитаты
Этот макрос ограниченно поддерживает ссылки. В лучшем случае, он
помогает составлять их вручную по определенному шаблону.

.Rs Начало ссылок. Вызывает разбиение строки, начинает список
ссылок и продолжает его до конца макроса.
.Re Конец ссылок. Ссылка печатается.
.%A Имя автора, одно на каждый вызов.
.%B Название книги.
.%C Город/издательство.
.%D Дата.
.%J Название журнала.
.%N Номер журнала.
.%O Дополнительная информация.
.%P Номер страницы.
.%R Название отчета.
.%T Заголовок статьи.
.%V Том(-а).

Макросы, начинающиеся с `%', не вызываются и обрабатываются только
макросом торговой марки для того, чтобы торговые марки правильно и
красиво печатались при выводе их с troff/ditroff.

Возвращаемые значения
Макрос `.Rv' форматирует текст для раздела ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ.

Применение: .Rv [-std функция]

`.Rv -std atexit' создаст текст:

The atexit() function returns the value 0 if successful; otherwise the
value -1 is returned and the global variable errno is set to indicate the
error.

Опция -std применима только для второго и третьего разделов страниц
руководства.

Торговые марки (акронимы и названия их видов)
Макрос "торговые марки" - это макрос для всех слов верхнего регистра
длиннее двух символов.

Использование: .Tn символ ...
.Tn DEC DEC
.Tn ASCII ASCII

Макрос `.Tn' может быть обработан и вызван другими макросами.

Расширенные параметры
Макросы `.Xo' и `.Xc' позволяют расширить список аргументов в пределах
макроса. Списки аргументов не могут быть быть расширены в макросах,
допускающих расположения всех аргументов только в одной строке, например:
`.Op'.

Далее приведен пример использования `.Xo' совместно с макросом отключения
пробела:

.Sm off
.It