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).
Модификатор команды.
Определённые переменные.
Параметры.
Имена файлов.
Переменные.
Перекрёстные ссылки.

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) считать следующие
два символа именем макроса. Чтобы поместить ‘.’ (символ точки) в начало строки не
для вызова макроса поместите перед ‘.’ (точкой) экранирующую последовательность
‘\&’. Последовательность ‘\&’ преобразуется в пробел нулевой ширины и никак не
отображается в выводе.

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

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

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

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

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

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

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

Cd Объявление настроек (раздел 4 ОБЗОР)
Bl Начало списка (для задания ширины).
Em Выделение текста.
Fn Функции (раздел два и четыре).
It Элементы списка.
Li Неформатируемый текст.
Sy Символьный текст.
%B Названия книг.
%J Названия журналов.
%O Необязательное примечание к ссылке.
%R Название отчёта (в ссылке).
%T Название статьи в книге или журнале.

Ещё одним способом передачи строки с пробелами является использование «жёсткого»
(непереносимого) или не занимающего места пробельного символа ‘\ ’, то есть,
пробела, перед которым ставится символ экранирования ‘\’. Его можно использовать в
любом макросе, но есть побочный эффект — он влияет на расчёт длины текста в строке.
Troff считает жёсткий пробел обычным печатным символом и не может разделить строку
пробелом или символом новой строки , как того можно было ожидать. Данный способ
полезен для строк, которые влезают в одну строку. Пример:
Пример того, что случается когда список параметров заходит на границу новой строки,
смотрите в разделе ДЕФЕКТЫ.

Завершающие пробельные символы
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) сами по себе являются командами; общий синтаксис

Здесь filter — название команды, а заключенная в квадратные скобки строка -флаг —
передаваемый аргумент флаг, который может быть необязательным и указываться в
скобках. Согласно терминологии -mdoc, вх.файл и oвых.файл называются аргументами.
Макрос, который создал пример, показанный выше:

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

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

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

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

экранирующий ‘\&’. 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’ вызывается без аргументов, то предполагается ‘Ar’. Макрос ‘.Ar’
может вызываться из других макросов и просматривается.

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

Определённые переменные
Переменная, которая определена во включаемом файле, задаётся макросом ‘.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 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 include_file (or defined variable)

В разделе ОБЗОР вызов макроса ‘.Fd’ приводит к разрыву строки, если функция уже
Использование: .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 и поэтому может некорректно разбить строку. В ближайшем будущем это
будет исправлено.

Тип функции
Этот макрос предназначен для раздела ОБЗОР. Он может быть использован где угодно,
но его основной целью является представление типа функции в стандартной форме в
ОБЗОР для разделов два и три (он предусматривает разбиение строки, при котором,

Использование: .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’ используется для отображения путей или имён файлов.

Использование: .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 . 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’, что указывает на
.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 Ar ctype.h ) , ⟨ctype.h⟩),
.Bq []
.Bq Em греческий , французский .
[греческий, французский].
.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’ используется для слов в командной строке макросов, которые не должны
форматироваться и подчиняться синтаксису содержания макросов.

просматривается.

Перекрёстные ссылки между разделами
Макрос ‘.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 допускается только справочных страниц из раздела 2 и 3.

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

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

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

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

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

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’, который отделяет название предмета от его
описания.Описание, по возможности, должно быть как можно более кратким
ниже, могут понадобиться другие макросы:

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

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

.Nm cat
.Op Fl benstuv
.Op Fl
.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 СООТВЕТСТВИЕ СТАНДАРТАМ
Если команда, библиотечная функция или файл соответствуют определённому
стандарту, например IEEE Std 1003.2 (“POSIX.2”) или ANSI X3.159-1989
(“ANSI C89”), то должно быть указано в данном разделе. Если команда не
соответствует ни одному из стандартов, то её появление должно быть описано

.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.

-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),
.Sy Важное замечание Важное замечание

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

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

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

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

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

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

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

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

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

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

Результат:

.It
ещё пункт с точкой
.El

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

-tag
-diag
-hang
-ohang
-inset
Эти типы списков собирают аргументы, указанные при помощи макроса ‘.It’, и создают
ярлык (label), который может быть вставлен (inset) в последующий текст,
располагаться до (hanged) последующего текста, располагаться над (overhanged)
последующим текстом и без отступа или отмеченного (tagged). Этот список был построен
при помощи списочного типа ‘Fl 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

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

.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 Fl назначает ширину, равную ширине флага по умолчанию. Все
вызываемые макросы имеют ширину, указанную по умолчанию. В
данном случае установленная ширина ‘.Fl’ равняется десяти
символам постоянной ширины или приблизительно пяти шестым дюйма.

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

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

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

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

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

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

ДИАГНОСТИКА

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

Если в списке аргументов запроса имя регистра не будет экранировано, то последствия
непредсказуемы. Обычно, из-за этого некоторые части текста выводятся не там, где
ожидалось или исчезают маленькие строки, например списочные теги; это происходит в