MDOC.SAMPLES(7)

ИМЯ
mdoc.samples - обучающий образец для написания справочных страниц BSD с использованием -mdoc

ОБЗОР
man mdoc.samples

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

Во всех справочных страницах UNIX сами страницы называют man-страницами, независимо от их размера и не имея намерения дискриминации по половому признаку.

НАЧАЛО РАБОТЫ
Так как учебные пособия, обычно, читают когда хотят использовать полученные знания сразу же, здесь предполагается, что читатель данной страницы может быть также нетерпелив. Вот содержание документа:

1.  ОСОБЕННОСТИ TROFF
    Использование макросов.
    Передача символов пробела в аргументе.
    Завершающие пробельные символы (предупреждение).
    Экранирование специальных символов.

2.  СТРУКТУРА СПРАВОЧНОЙ СТРАНИЦЫ
    Шаблон справочной страницы.

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

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

5.  СПРАВОЧНЫЙ ДОМЕН
    Адреса.
    Имя автора.
    Аргументы.
    Объявление настроек (только раздел 4).
    Модификатор команды.
    Определённые переменные.
    Значения errno (только раздел 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) считать следующие два символа именем макроса. Чтобы поместить ‘’. (символ точки) в начало строки не для вызова макроса поместите перед ‘’. (точкой) экранирующую последовательность ‘\&’. Последовательность ‘\&’ преобразуется в пробел нулевой ширины и никак не отображается в выводе.

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

Большинство макросов -mdoc текстового и справочного домена отличаются от остальных тем, что их списки аргументов просматриваются в поиске имён вызываемых макросов. Это означает, что если аргумент из списка совпадает с именем макроса текстового или справочного домена и его можно вызвать, то он будет выполнен или вызван при обработке. В этом случае аргумент, хотя и является именем макроса, не начинается с ‘’. (точки). Таким способом макросы могут быть вложенными; например, макрос параметра ‘.Op’ может вызвать макросы флага и аргумента ‘-’ и ‘file ...’, чтобы задать необязательный флаг с аргументом:

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

Чтобы два символа строки не считались именем макроса начните строку с экранирующей последовательности ‘\&’:

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

Здесь строки ‘-’ и ‘file ...’ не обрабатываются как макросы. Во всём этом документе и сходном кратком справочнике mdoc(7) макросы, списки аргументов которых просматриваются на предмет вызываемых аргументов, называются просматриваемыми, а макросы, которые можно вызвать из списка аргументов называются вызываемыми. Но эта технически неверно, так как почти все макросы -mdoc просматриваются, но так как было бы громоздко постоянно указывать, что макрос является вызываемым и способен вызывать другие макросы, был использован термин «просматриваемый».

  Передача символов пробела в аргументе
Иногда нужно указать в аргументе строку с одним и более пробельным символом. Это может быть необходимо для преодоления ограничения в девять аргументов или для передачи аргументов в макросы, которые ожидают определённый порядок элементов в списке аргументов. Например, макрос функции ‘.Fn’ первый аргумент считает именем функции, а остальные аргументы её параметрами. Так как в ANSI C ставится условием объявление параметров функции в виде списка параметров в круглых скобках, то каждый параметр гарантированно будет состоять из минимум двух слов слов. Например, int foo.

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

    Объявление настроек (раздел 4 ОБЗОР)
Bl  Начало списка (для задания ширины).
    Выделение текста.
    Функции (раздел два и четыре).
It  Элементы списка.
    Неформатируемый текст.
    Символьный текст.
%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 можно запутать пробельными символами в конце строки. Лучше предварительно везде удалить все пустые пространства из символьных последовательностей <пустое пространство><конец строки>. Если необходим пробельный символ в конце строки, то его можно создать с помощью незаполняемого пространства и символа экранирования ‘\&’. Например, ‘string\ \&’.

  Экранирование специальных символов
Специальные символы, такие как символ новой строки ‘\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
    .\" (значения, возвращаемые командой (в оболочку), и
    .\"	  диагностика fprintf/stderr)
    .\" .Sh ДИАГНОСТИКА
    .\" Эта часть только работы над ошибками и обработки
    .\" сигналов из разделов 2 и 3.
    .\" .Sh ОШИБКИ
    .\" .Sh СМОТРИТЕ ТАКЖЕ
    .\" .Sh СООТВЕТСТВИЕ СТАНДАРТАМ
    .\" .Sh ИСТОРИЯ
    .\" .Sh АВТОРЫ
    .\" .Sh ДЕФЕКТЫ

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

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

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

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

    AMD | Документы предыдущих версий UNIX
    SMM | Руководство системного администратора UNIX
    URM | Справочное руководство UNIX
    PRM | Руководство программиста UNIX

    По умолчанию страницы разделов 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 4.3BSD

    или
        .Os FreeBSD 2.2

    или для добавленных пользователем страниц

        .Os Отдел КБ

    По умолчанию в Berkeley для макроса ‘.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, вх.файл и oвых.файл называются аргументами. Макрос, который создал пример, показанный выше:

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

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

make
    [-eiknqrstv] [-D переменная] [-d флаги] [-f makefile] [-I каталог] [-j max_jobs] [переменная=значение] [цель …]

Здесь можно было бы говорить о команде make и посчитать аргумент makefile аргументом флага -f или обсудить необязательный файловый операнд цель. В словесном контексте такие детали могут предотвратить появление путаницы, однако пакет -mdoc не имеет макроса аргумента для флага. Вместо этого операнд или файловый аргумент, например цель, указывается как аргумент макроса ‘file ...’, также как аргумент для флага, подобно переменная. Командная строка 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 max_jobs
    .Op Ar переменная=значение
    .Bk -words
    .Op Ar цель …
    .Ek

Макросы ‘.Bk’ и ‘.Ek’ описаны в Сохранение исходного формата.

  Основной синтаксис
Макросы справочного и текстового доменов имеют одинаковый синтаксис, но есть ряд небольших различий: ‘.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 , файл2
    addr1, файл2
.Ad f1 , f2 , f3 :
    f1, f2, f3:
.Ad addr ) ) ,
    addr) ),

Вызов ‘.Ad’ без аргументов считается ошибкой. Макрос ‘.Ad’ может вызываться из других макросов и просматривается.

  Имя автора
Макрос ‘.An’ используется для указания имени автора описываемого элемента и справочной страницы. Любые аргументы, стоящие после имени, считаются знаками пунктуации.

    Использование: .An имя автора [ .,:;()[]?! ]
.An Василий Иванов
    Василий Иванов
.An Василий Иванов ,
    Василий Иванов,
.An Василий Иванов Aq nobody@FreeBSD.ORG
    Василий Иванов <nobody@FreeBSD.ORG>
.An Василий Иванов ) ) ,
    Василий Иванов) ),

Макрос ‘.An’ просматривается и вызывается. Вызов ‘.An’ без аргументов считается ошибкой.

  Макрос аргумента
Макрос аргумента ‘.Ar’ можно использовать в любом месте для ссылки на аргумент командной строки.

    Использование: .Ar аргумент … [ .,:;()[]?! ]
.Ar file ...
.Ar файл1
    файл1
.Ar файл1 .
    файл1.
.Ar файл1 файл2
    файл1 файл2
.Ar f1 f2 f3 :
    f1 f2 f3:
.Ar файл ) ) ,
    файл) ),

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

  Объявление настроек (только раздел 4)
Макрос ‘.Cd’ можно найти в config(8), где он используется для объявления интерфейсных устройств из раздела четыре. В этом макросе можно использовать аргументы в двойных кавычках.

device le0 at scode?
    делается при помощи: ‘.Cd device le0 at scode?’.

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

  Определённые переменные
Переменная, которая определена во включаемом файле, задаётся макросом ‘.Dv’.

    Использование: .Dv определённая переменная … [ .,:;()[]?! ]
.Dv MAXHOSTNAMELEN
    MAXHOSTNAMELEN
.Dv TIOCGPGRP )
    TIOCGPGRP)

Вызов ‘.Dv’ без аргументов считается ошибкой. ‘.Dv’ может вызываться из других макросов и просматривается.

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

    Использование: .Er ERRNOTYPE … [ .,:;()[]?! ]
.Er ENOENT
    ENOENT
.Er ENOENT ) ;
    ENOENT);
.Bq 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 include_file (or defined variable)

В разделе ОБЗОР вызов макроса ‘.Fd’ приводит к разрыву строки, если функция уже задана, а разбиения строки пока не было. Это привод к появлению удобного вертикального пространства между объявлением предыдущей и последующей функции.

  Флаги
Макрос ‘.Fl’ служит для представления флагов командной строки. Он добавляет к флагу знак минуса, ‘-’. Для флагов интерактивной команды, которые не начинаются с минуса, нужно использовать макрос ‘.Cm’ (модификатор команды), который идентичен данному макросу, но не добавляет знак минуса.

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

Макрос ‘.Fl’ без аргументов возвратит тире, то есть, стандартный поток ввода/вывода. Заметим, что если ‘.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’ без аргументов он возвращается с этим первоначальным значением, что облегчает работу автора. Замечание: во втором и третьем разделах справочных страниц макрос ‘.Nm’ служит для описания имени функции в разделе ИМЯ, а ‘.Fn’ — в разделе ОБЗОР и во всех остальных. Для интерактивных команд, например команды-ключевого слова ‘while’, csh(1) должен быть использован макрос ‘.Ic’. Хотя ‘.Ic’ очень близок ‘.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 слово1 слово2
    [слово1 слово2]

Макросы ‘.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 справочная страница [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 .
    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 выделение квадратными скобками [строка] .Dq .Dc .Do выделение двойными кавычками ``строка'' .Ec .Eo выделение строкой (в XX) XXстрокаXX .Pq .Pc .Po выделение круглыми скобками (строка) .Ql литературное цитирование `st' или строка .Qq .Qc .Qo выделение прямыми двойными кавычками "строка" .Sq .Sc .So выделение одинарными кавычками `строка'

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

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

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

.Pf Макрос префикса не может вызываться из других макросов, но просматривается:

    .Pf ( Fa имя2
        станет (имя2.

    Макрос ‘.Ns’ (отключение пробелов) производит аналогичное действие для конца.

Примеры выделения:
.Aq <>
.Aq ctype.h ) ,
    <ctype.h>),
.Bq []
.Bq греческий, французский.
    [греческий, французский].
.Dq “”
.Dq строка abc .
    “строка abc”.
.Dq '^[A-Z]'
    “'^[A-Z]'”
.Ql man mdoc
    ‘man mdoc’
.Qq ""
.Qq строка ) ,
    "строка"),
.Qq строка Ns ),
    "строка),"
.Sq ‘’
.Sq строка
    ‘строка’

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

  Нет операции или макрос для обычного текста
Макрос ‘.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’ генерирует следующий текст:

Параметр -std допускается только справочных страниц из раздела 2 и 3.

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

    Использование: .Tn символ … [ .,:;()[]?! ]
.Tn DEC
    DEC
.Tn ASCII
    ASCII

Макрос ‘.Tn’ может вызываться из других макросов и просматривается.

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

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

    .Sm off
    .It Xo Sy I Ar операция
    .No \en Ar счётчик No \en
    .Xc
    .Sm on

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

Iоперация
    \nсчётчик\n

Ещё один пример:

    .Sm off
    .It Cm S No / Ar старый_шаблон Xo
    .No / Ar новый_шаблон
    .No / Op Cm g
    .Xc
    .Sm on

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

S/старый_шаблон
    /новый_шаблон /[g]

Ещё пример с ‘.Xo’ и макросами выделения: тест значения переменной.

    .It Xo
    .Ic .ifndef
    .Oo \&! Oc Ns Ar переменная
    .Op Ar оператор переменная …
    .Xc

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

    .ifndef [!]переменная [оператор переменная …]

Во всех примерах, показанных выше, использовался макрос ‘.Xo’ со списком аргументов макроса ‘.It’ (элемент списка). Расширенные макросы используются не очень часто и, обычно, для расширения списка аргументов список-элемент. К сожалению, использование расширенных макросов добавляет сложностей. В первых двух примерах были убраны пробелы; в третьем случае пробелы надо было убрать только в определённой части. Чтобы макросы сработали в этой ситуации, удостоверьтесь, что макросы ‘.Xo’ и ‘.Xc’ расположены именно так, как в третьем примере. Если макрос ‘.Xo’ не единственный в списке аргументов ‘.It’, то невозможно определить, как и откуда будут удалены пробелы. В этом случае макрос ‘.Ns’ (макрос отключения пробелов) не должен оказаться первым или последним макросом в строке. Из 900 справочных страниц (а в реальности — около 1500 страниц), представленных в BSD, только в пятнадцати используется макрос ‘.Xo’.

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

  Заголовки разделов
Первые три макроса заголовков разделов ‘.Sh’ приведённых ниже, требуются для каждой справочной страницы. Остальные заголовки разделов добавляются по усмотрению автора. Макрос ‘.Sh’ может иметь до девяти аргументов. Макрос просматривается, но его нельзя вызвать.

.Sh ИМЯ
    Макрос ‘.Sh ИМЯ’ обязателен. Если не указан, значения по умолчанию для заголовков, нижних колонтитулов и формата страницы не будут определены и всё будет выглядеть неаккуратно. Раздел ИМЯ состоит минимум из трёх частей. Первая — макрос имени страницы ‘.Nm’, который называет сам предмет, описанный в справочной странице. Далее следует макрос описания имени, ‘.Nd’, который отделяет название предмета от его описания.Описание, по возможности, должно быть как можно более кратким и ясным, так как на странице под него выделяется не так много места.

.Sh ОБЗОР
    Раздел ОБЗОР описывает типичное применение рассматриваемого предмета. Макросы, которые могут потребоваться: ‘.Nm’, ‘.Cd’, ‘.Fn’, (и, возможно, ‘.Fo’, ‘.Fc’, ‘.Fd’, ‘.Ft’). Макрос названия функции ‘.Fn’ должен присутствовать в справочной странице раздела 2 и 3, макрос команды и обычного названия ‘.Nm’ требуется для страниц разделов 1, 5, 6, 7, 8. Для раздела 4 требуется ‘.Nm’, ‘.Fd’ или макрос использования устройств ‘.Cd’. Для описания синтаксиса, как показано в примере ниже, могут понадобиться другие макросы:

cat [-benstuv] [-] file ...

Использовались следующие макросы:

    .Nm cat
    .Op -benstuv
    .Op -
    .Ar

Замечание: Макросы ‘.Op’, ‘.Fl’ и ‘.Ar’ распознают символ вертикальной черты ‘’, поэтому строка вида:

    .Op Fl a | Fl b

будет обработана. Troff обычно интерпретирует как специальный оператор. В разделе ПРЕДОПРЕДЕЛЁННЫЕ СТРОКИ описано как символ используется в других ситуациях.

.Sh ОПИСАНИЕ
    В большинстве случаев первое, что пишется в разделе ОПИСАНИЕ это краткое описание команды, функции или файла с последующим списком параметров и пояснений к ним. Для того, чтобы создать такой список, используются макрос начала списка ‘.Bl’, элемента списка ‘.It’ и ‘.El’ конца списка (смотрите Списки и колонки ниже).

Следующие макросы заголовков разделов ‘.Sh’ являются частью предпочтительного раскладки страницы и должны использоваться в соответствии с контекстом. Они приведены в том порядке, в котором должны находиться в тексте.

.Sh ОКРУЖЕНИЕ
    Раздел ОКРУЖЕНИЕ описывает все используемые переменные окружения, их поведение и/или использование.

.Sh ПРИМЕРЫ
    Есть несколько способов описания примеров. Подробности смотрите в разделе ПРИМЕРЫ ниже.

.Sh ФАЙЛЫ
    Файлы, используемые или созданные предметом описания справочной страницы, должны перечисляться при помощи макроса ‘.Pa’ в разделе ФАЙЛЫ.

.Sh СМОТРИТЕ ТАКЖЕ
    Ссылки на другие материалы по теме страницы и ссылки на другие страницы должны находиться в разделе СМОТРИТЕ ТАКЖЕ. Перекрестные ссылки указываются при помощи макроса ‘.Xr’. Перекрестные ссылки в разделе СМОТРИТЕ ТАКЖЕ должны быть отсортированы по номерам разделов, а затем в алфавитном порядке и разделены запятыми. Пример:

    ls(1), ps(1), group(5), passwd(5).

    При этом ссылки в стиле refer(1) не включаются.

.Sh СООТВЕТСТВИЕ СТАНДАРТАМ
    Если команда, библиотечная функция или файл соответствуют определённому стандарту, например p1003.2 или ansiC, то должно быть указано в данном разделе. Если команда не соответствует ни одному из стандартов, то её появление должно быть описано в разделе ИСТОРИЯ.

.Sh ИСТОРИЯ
    В этом разделе описываются цели создания команд, не соответствующих никаким стандартам.

.Sh АВТОРЫ
    В этом разделе должны быть указаны все авторы страницы и их помощники.

.Sh ДИАГНОСТИКА
    В данном разделе описана диагностика команды.

.Sh ОШИБКИ
    В этом разделе рассматривается работа с ошибками, особенно библиотечных функций (справочные разделы 2 и 3). Макрос ‘.Er’ используется для описания errno.

.Sh ДЕФЕКТЫ
    В этом разделе описываются все выявленные проблемы.

С помощью ‘.Sh’ автор может добавлять свои собственные разделы, например как этот раздел:

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

  Параграфы и интервал между строками.

.Pp Команда параграфа ‘.Pp’ может быть использована для выделения необходимого пространства. Этот макрос необязателен после макроса ‘.Sh’ или ‘.Ss’ или перед макросом ‘.Bl’ (макрос ‘.Bl’ задаёт вертикальное расстояние, если не указан флаг -compact).

  Сохранение исходного формата
На настоящий момент реализовано только сохранение слов. Для этого служат макросы ‘.Bk’ (начало сохранения) и ‘.Ek’ (конец сохранения). Единственный параметр, который учитывает ‘.Bk’ это -words; он применяется для того, чтобы избежать неправильных переносов. При задании параметров команды make (смотрите Что в имени тебе моем…) сохранение не позволило nroff разместить флаг и аргумент в разных строках (в действительности, для этого используется макрос параметра, но он был удалён из-за решения (религиозного) делать принудительное выравнивание по правому краю в troff через параметры, из-за чего скверно выглядят обычные строки. Над макросами сохранения ещё требуется много работы, нужно добавить параметр -строка).

  Примеры и блоки вывода
Существует пять типов вывода: вывод строки с отступом ‘.D1’, вывод строки, начинающейся с заглавной буквы ‘.Dl’, вывод неотформатированного блока (literal) вывод блока, отформатированного по двум границам (filled), а также вывод блока, отформатированного по левой границе (ragged) и использующего макросы ‘.Bd’ (начало вывода) и ‘.Ed’ (конец вывода).

.D1 (D-один) Выводит одну строку с отступом. Этот макрос просматривается, но не вызывается.

        -ldghfstru

    Описанное выше было сделано с помощью: .Dl -ldghfstru.

.Dl (D-эль) выводит строку с отступом дословного текста. Макрос примера ‘.Dl’ также используется в этом тексте. Он позволяет делать отступ одной строки текста. По умолчанию установленная ширина шрифта является постоянной. Этот макрос просматривается и распознается другими макросами, но не может быть вызван ими.

        % ls -ldg /usr/local/bin

    Описанное выше было сделано с помощью: .Dl % ls -ldg /usr/local/bin.

.Bd Начало вывода. Вывод ‘.Bd’ должен заканчиваться макросом ‘.Ed’. Вывод может располагаться внутри других выводов и списков. Макрос ‘.Bd’ имеет следующий синтаксис:

        .Bd вид-вывода [-offset значение-отступа] [-compact]

    Вид вывода должен быть одним из четырех следующих типов и может иметь указатель величины отступа: ‘.Bd’.

-ragged
    Дословно воспроизводить текст, не выравнивая правый (и левый) край.
-filled
    Воспроизводить заполненный (отформатированный) блок. Блок текста отформатирован (выравнивание по обеим границам).
-literal
    Дословно воспроизводить текст, не форматируя его. Используется для исходного кода или текста, отформатированного пробелами или табуляциями.
-file имя_файла
    Читается и воспроизводится файл с именем, указанным за флагом -file. Подразумевается дословный режим (literal) и устанавливается ширина табуляции в 8 символов, однако любая команда troff/-mdoc файла будет обработана.
-offset строка
    Если указан -offset с одной из следующих строка, то то по ней будут равняться и следующие строки блока:

    left
        Производится выравнивание по существующей левой границе текста, режим в ‘.Bd’ по умолчанию.
    center
        Производится выравнивание блока по предположительному центру. К сожалению на настоящий момент, блок просто выравнивается по левой границе, ориентируясь на воображаемый центр экрана.
    indent
        Делает один отступ значения отступа по умолчанию или величины табуляции. Значение этого отступа по умолчанию также используется для вывода ‘.D1’, так что оба типа вывода гарантировано будут на одной строке. Величина отступа, обычно, равна 6 или, приблизительно, двум третям дюйма (постоянная ширина шести символов).
    indent-two
        Делает отступ в два раза больше, чем установленный по умолчанию.
    right
        Макрос left выравнивает блок по двух дюймовой границе от правого края страницы. Данный макрос нуждается в доработке и, возможно, в troff его работа никогда не будет корректной.
.Ed Конец вывода.

  Режимы шрифтов
Существует пять макросов для изменения внешнего вида текста справочной страницы:

.Em На тексте можно заострить внимание или выделить с помощью макроса ‘.Em’. Обычно, шрифт для выделения является курсивным (italic).

        Использование: .Em аргумент … [ .,:;()[]?! ]
    .Em не является
        не является
    .Em превышает 1024 .
        превышает 1024.
    .Em смотрите ниже ) ) ,
        смотрите ниже) ),

    Макрос ‘.Em’ просматривается и вызывается. Вызов ‘.Em’ без аргументов считается ошибкой.

.Li Дословный макрос ‘.Li’ может быть использован для специальных символов, переменных, констант или того, что должно быть отображено так, как это набрано.

        Использование: .Li аргумент … [ .,:;()[]?! ]
    .Li \en
        \n
    .Li M1 M2 M3 ;
        M1 M2 M3;
    .Li cntrl-D ) ,
        cntrl-D),
    .Li 1024 …
        1024 …

    Макрос ‘.Li’ может вызываться из других макросов и просматривается.

.Sy Символьный макрос акцентирования служит, в основном, для написания текста жирным шрифтом для смыслового выделения или традиционного использования в английском.

        Использование: .Sy символ … [ .,:;()[]?! ]
    .Sy Важное замечание
        Важное замечание

        Макрос ‘.Sy’ может вызываться из других макросов и просматривается. Аргументы макроса ‘.Sy’ могут указываться в кавычках.

.Bf Начало режима шрифта. Макрос режима шрифта ‘.Bf’ должен заканчиваться макросом ‘.Ef’. Режимы шрифтов могут быть размещены внутри других макросов режимов шрифтов.Макрос ‘.Bf’ имеет следующий синтаксис:

        .Bf режим-шрифта

    Режимом-шрифта должен быть одним из трех следующих типов ‘.Bf’:

    | -emphasis
        Выглядит, как будто макрос ‘.Em’ применили ко всему блоку текста.
    | -literal
        Выглядит, как будто макрос ‘.Li’ применили ко всему блоку текста.
    | -symbolic
        Выглядит, как будто макрос ‘.Sy’ применили ко всему блоку текста.

.Ef Конец режима шрифта.

  Помеченные списки и колонки
Существует несколько типов списков, которые могут начинаться с макроса ‘.Bl’ (начало-списка). Пункты внутри списка указываются при помощи макроса ‘.It’, и каждый список должен заканчиваться макросом ‘.El’. Списки могут быть размещены внутри таких же списков или блоков вывода. Внутри списков могут быть использованы колонки, но списки внутри колонок ведут себя не всегда адекватно.

Также, могут задаваться некоторые атрибуты списков, такие как: ширина тега, отступ и компактность (определяет, вставляются ли пустые строки между пунктами списка). Большая часть этого документа была отформатирована при помощи тега стиля списка (-tag). Для создания ступеньки при показе типов списков использовался нависающий список (-ohang). Этот тип списка очень популярен среди пользователей TeX, но может выглядеть забавно после прочтения нескольких страниц с тегированными списками. Следующие типы списков обрабатываются макросом ‘.Bl’:

-bullet
-item
-enum
Эти три типа являются самыми простыми. После указания макроса ‘.Bl’ все пункты списка обозначаются строкой, состоящей из макроса ‘.It’. Например, исходный текст простого списка перечисления будет выглядеть следующим образом:

    .Bl -enum -compact
    .It
    Название первого пункта
    .It
    Здесь второй пункт
    .It
    И последний третий пункт
    .El

Результат:

1.  Название первого пункта.
2.  Здесь второй пункт
3.  И последний третий пункт

Простой список элементов, выделенных точками:

    .Bl -bullet -compact
    .It
    это пункт с точкой
    .It
    ещё пункт с точкой
    .El

В результате получается:
•   это пункт с точкой
•   ещё пункт с точкой

-tag
-diag
-hang
-ohang
-inset
Эти типы списков собирают аргументы, указанные при помощи макроса ‘.It’, и создают ярлык (label), который может быть вставлен (inset) в последующий текст, располагаться до (hanged) последующего текста, располагаться над (overhanged) последующим текстом и без отступа или отмеченного (tagged). Этот список был построен при помощи списочного типа ‘-ohang’. Макрос ‘.It’ обрабатывается только списочных типов inset, hang и tag и не может быть вызван. Далее следует пример блока, выделенного при помощи ярлыков inset:

Tag Список меток (также называемый отмеченным параграфом) это наиболее часто используемый тип списка в справочных страницах Berkeley.

Diag Списки diag создаёт раздел списка диагностики и подобен спискам inset, но игнорирует вызываемые макросы.

Hang Навешиваемые ярлыки, расположенные перед текстом, используются по желанию автора.

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

Inset Выделенные ярлыки полезны для управления блоками параграфов и удобны для конвертирования страниц -mdoc в другие форматы.

Далее следует исходный текст описанного выше:

    .Bl -inset -offset indent
    .It Em Tag
    Список меток (также называемый отмеченным параграфом).
    это наиболее часто используемый тип списка в справочных страницах Berkeley.
    .It Em Diag
    Списки diag создаёт раздел списка диагностики и подобен спискам inset,
    но игнорирует вызываемые макросы.
    .It Em Hang
    Навешиваемые ярлыки, расположенные перед текстом,
    используются по желанию автора.
    .It Em Ohang
    Свисающие ярлыки, расположенные над текстом, очень
    удобны, если свободного места в целом немного.
    .It Em Inset
    Выделенные ярлыки полезны для управления блоками параграфов и
    удобны для конвертирования страниц
    .Nm -mdoc
    в другие форматы.
    .El

Ниже приведён пример списка с двумя выделенными блоками, расположенными до текста:

Навешиваемые
    ярлыки похожи на списки tag в случае, если ярлык меньше выделенной для него ширины.

Более длинные навешиваемые ярлыки
    врезаются в параграф, чего не происходит со списками tag.

Ниже приведён исходный вариант этого текста:

    .Bl -hang -offset indent
    .It Em Навешиваемые
    ярлыки похожи на списки tag в случае, если ярлык
    меньше выделенной для него ширины.
    .It Em Более длинные навешиваемые ярлыки
    врезаются в параграф,
    чего не происходит со списками tag.
    .El

Помеченный список после которого задаётся дополнительный указатель для управления шириной тега.

SL  длительность режима ожидания процесса (количество секунд блокировки)
PAGEIN
    количество дисковых операций ввода-вывода, возникших из-за обращений процесса к страницам не из ядра
UID числовой идентификатор владельца процесса
PPID
    числовой идентификатор родителя процесса, имеющий приоритет процесса (отрицательный, если находится в режиме непрерываемого ожидания)

Неструктурированный текст:

    .Bl -tag -width "PAGEIN" -compact -offset indent
    .It SL
    длительность режима ожидания процесса (количество секунд блокировки)
    .It PAGEIN
    количество дисковых операций
    .Tn ввода-вывода Ns
    , возникших из-за
    обращений процесса к страницам не из ядра
    .It UID
    числовой идентификатор владельца процесса
    .It PPID
    числовой идентификатор родителя процесса, имеющий приоритет
    процесса (отрицательный, если находится в режиме непрерываемого ожидания)
    .El

Допустимые указатели ширины:

-width file ... -
    назначает ширину, равную ширине флага по умолчанию. Все вызываемые макросы имеют ширину, указанную по умолчанию. В данном случае установленная ширина ‘.Fl’ равняется десяти символам постоянной ширины или приблизительно пяти шестым дюйма.

-width 24n
    назначает ширину, равную 24-м символам постоянной ширины или приблизительно двум дюймам. Буква ‘n’ необходима для правильной работы масштабирования.

-width ENAMETOOLONG
    задаёт ширину, равную постоянной ширине указанной строки.

-width int mkfifo
    тоже задаёт ширину, равную постоянной ширине указанной строки.

Если ширина помеченного списка не задана, то при первом вызове макроса ‘.It’ делается попытка определения нужной ширины. Если первый аргумент ‘.It’ является вызываемым макросом, то будет использована ширина по умолчанию этого макроса, как если бы вместо имени макроса была задана ширина. Однако, если другой элемент списка указан в с другим именем вызываемого макроса, то создается новый вложенный список.

ПРЕДОПРЕДЕЛЁННЫЕ СТРОКИ
Следующие строки являются предопределёнными и могут использоваться в строках интерпретирующей последовательности troff ‘\*(xx’, где xx — имя предопределенной строки или ‘\*x’, где x — имя строки. Интерпретирующая последовательность может быть использована в любом месте текста.

Строка | Nroff | Troff
<= | <= |
>= | >= |
Rq | '' |
Lq | `` |
ua | ^ |
aa | ' |
ga | ` |
q | " |
Pi | pi |
Ne | != |
Le | <= |
Ge | >= |
Lt | < |
Gt | > |
Pm | +- |
If | infinity |
Na | NaN |
Ba | | |

Замечание: Строка под названием ‘q’ должна записываться в виде ‘\*q’, так как в её названии только один символ.

ДИАГНОСТИКА
Возможности отладки -mdoc ограничены, но могут помочь в нахождении довольно незаметных ошибок, таких как совпадение названия аргумента с названием внутреннего регистра или макроса. (Что?) Регистр — это метод хранения информации troff с именем, состоящим из одного или двух символов. Все внутренние регистры -mdoc в troff и ditroff имеют названия из двух символов в виде <верхний регистр><нижний регистр>, например ‘file ...’, <нижний регистр><верхний регистр>, например ‘aR’ или <большая или маленькая буква><цифра>, например ‘C1’. И, вдобавок ко всему, в troff есть свои собственные внутренние регистры, названия которых состоят из двух маленьких символов или из точки и буквы. В одном из примеров введения было показано, как предотвратить определение названия макроса при помощи экранирующей последовательности ‘\&’. Это актуально и для названий внутренних регистров.

Если в списке аргументов запроса имя регистра не будет экранировано, то последствия непредсказуемы. Обычно, из-за этого некоторые части текста выводятся не там, где ожидалось или исчезают маленькие строки, например списочные теги; это происходит в связи с непониманием типа аргумента в списке аргументов. Вашей маме никогда не придётся за вас помнить весь этот ужас: узнать, правильно ли указан тип аргумента, можно при помощи макроса отладки ‘.Db’ (debug), который выводит интерпретацию списка аргументов для большинства макросов. Такие макросы, как ‘.Pp’ (paragraph), не содержат информации для отладки. При вызове макросов всегда рекомендуется включать макрос ‘.Db’.

    Использование: .Db [on | off]

Далее следует пример, состоящий из части текста с макросом отладки, расположенным выше и ниже специально созданной ошибки (флаг аргумента указан как ‘aC’, вместо ‘\&aC’, что необходимо для корректной работы):

    .Db on
    .Op Fl aC Ar файл )
    .Db off

Результат вывода:

    DEBUGGING ON
    DEBUG(argv) MACRO: `.Op'  Line #: 2
    	Argc: 1  Argv: `Fl'  Length: 2
    	Space: `'  Class: Executable
    	Argc: 2  Argv: `aC'  Length: 2
    	Space: `'  Class: Executable
    	Argc: 3  Argv: `Ar'  Length: 2
    	Space: `'  Class: Executable
    	Argc: 4  Argv: `файл'  Length: 4
    	Space: ` '  Class: String
    	Argc: 5  Argv: `)'  Length: 1
    	Space: ` '  Class: Closing Punctuation or suffix
    	MACRO REQUEST: .Op Fl aC Ar файл )
    DEBUGGING OFF

В первой строке указывается название вызывающего макроса (в данном случае это ‘.Op’) и номер строки, в которой он находится. Если используется более одного файла (в особенности, если используется текст из другого файла), то номер строки может быть некорректным. Если используется один файл, то строка должна быть указана точно. Во второй строке показывается счётчик аргументов, аргумент (‘-’) его длина. Если длина аргумента равна двум символам, то проверяется, выполняется ли он (к сожалению, любой регистр, имеющий ненулевое значение, тоже выполним). В третьей строке выводится пространство, зарезервированное для класса, и тип класса. Ошибка в том, что аргумент aC не должен быть выполнимым. Существует четыре типа класса: строковый, выполнения, открывающий и закрывающий пунктуационные знаки. В последней строке указывается полный список аргументов, каким он был прочитан. В следующем примере ‘aC’ будет экранировано:

    .Db on
    .Em An экранированный \&aC
    .Db off

    DEBUGGING ON
    DEBUG(fargv) MACRO: `.Em'  Line #: 2
    	Argc: 1  Argv: `An'  Length: 2
    	Space: ` '  Class: String
    	Argc: 2  Argv: `экранированный'  Length: 7
    	Space: ` '  Class: String
    	Argc: 3  Argv: `aC'  Length: 2
    	Space: ` '  Class: String
    	MACRO REQUEST: .Em An экранированный &aC
    DEBUGGING OFF

Аргумент ‘\&aC’ имеет ту же длину, равную 2-м, так как последовательность ‘\&’ имеет нулевую ширину, но регистр с названием ‘\&aC’ не был найден и тип был классифицирован как строка.

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

GROFF, TROFF И NROFF
Пакет -mdoc не нуждается в режиме совместимости с groff.

Для удобства чтения в режиме on-line пакет не выполняет разбивку на страницы, верхние и нижние колонтитулы, формируемые в таких случаях nroff. При вызове groff с параметров -Tascii вставляется счётчик страниц. Свойство nroff не выполнять разбивку на страницы делает неудобным распечатку созданным им документов. Чтобы включить старое поведение можно присвоить регистру ‘cR’ в файле /usr/src/share/tmac/doc-nroff значение нуля.

ФАЙЛЫ
/usr/share/tmac/doc.tmac
    пакет макросов справочника
/usr/share/misc/mdoc.template
    шаблон для написания справочной страницы
/usr/share/examples/mdoc/*
    несколько примеров справочных страниц

ДЕФЕКТЫ
Пока не решён вопрос с нежелательным автоматическим переносом на месте дефиса флага аргумента, который возникает в разделе ОПИСАНИЕ (перенос строки на месте дефиса).

Предопределенные строки не описаны в документации.

Раздел 3f не добавлен в процедуры заголовка.

Шрифт ‘.Nm’ нужно изменять в разделе ИМЯ.

‘.Fn’ нужно проверять для предотвращения разбиения очень короткой строки. Иногда он переносит последнюю скобку и выглядит нелепо, если строка находится в режиме заполнения.

Метод предотвращения разделения страницы в колонтитулах (кроме первого и последнего), используемые в nroff, иногда помещает некрасивую частично заполненную строку (пустую), как если бы это был конец страницы.

Макросы списков и вывода не всегда делают сохранения когда должны.

СМОТРИТЕ ТАКЖЕ
man(1), troff(1), groff_mdoc(7), mdoc(7)