ИМЯ

man-pages — правила написания справочных страниц Linux

ОБЗОР

man [раздел] имя

ОПИСАНИЕ

На этой странице описаны правила, которые необходимо применять при написании
справочных страниц для проекта man-pages Linux, который, в свою очередь,
документирует программный интерфейс пространства пользователя, предоставляемый
ядром Linux и библиотекой GNU C. Таким образом, проект отвечает за большинство
страниц из Раздела 2, за многие страницы из Разделов 3, 4, и 7, и за несколько
страниц из Разделов 1, 5 и 8 справочной системы Linux. Данные правила также могут
быть полезны при написании справочных страниц для других проектов.

Разделы справочных страниц
Традиционно они следующие:

1 Команды пользователя (Программы)
Команды, которые пользователь запустить из оболочки.

2 Системные вызовы
Функции, являющиеся оберткой операций, выполняемых ядром.

3 Библиотечные вызовы
Все библиотечные функции (в основном функции libc), за исключением
представленных в Разделе 2.

4 Специальные файлы (устройства)
Файлы из /dev, дающие доступ к устройствам через ядро.

5 Форматы файлов и конфигурационные фалы
Описывает различные подходящие для чтения форматы файлов и
конфигурационные файлы.

6 Игры Игры и забавные небольшие программы

7 Обзоры, соглашения и разное
Описания или обзоры, касающиеся различных тем, соглашений и протоколов,
а также наборов символов, стандартный шаблон файловой системы, разное.

8 Команды для системного администрирования
Команды подобные mount(8), большинство из которых могут запускаться
только суперпользователем.

Пакет макросов
Новые справочные страницы должны размечаться с помощью пакета groff an.tmac,
описанного в man(7). Данный выбор основан, в основном, на том, что большинство из
существующих страниц Linux размечены с помощью этих макросов.

Правила, касающиеся формата исходных файлов
Длина строки не должна превышать 75 символов. В некоторых почтовых клиентах это
помогает избежать переноса строк в заплатах, встроенные в письмо.

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


раздел Номер раздела для размещения страницы (например 7).

дата Дата последнего значительного изменения справочной страницы (в
проекте man-pages необходимые обновления временных отметок
выполняются автоматически при помощи сценариев, вручную
устанавливать её заплатой не нужно). Дата должна иметь вид
YYYY-MM-DD, т. е. год-месяц-день.

источник Источник команды, функции, системного вызова.

Для нескольких страниц man-pages в Разделах 1 и 8, можно написать
GNU.

Для системных вызовов — Linux. (Ранее, стандартной практикой было
писать версию ядра, используя которую был написана или проверена
страница. Это никогда не было общепринятым. Так что не делайте
этого).

Для библиотечных вызовов, являющихся частью glibc или других
библиотек GNU — GNU C Library, GNU, или пустую строку.

Для страниц из Раздела 4 — Linux.

Если возникают сомнения — Linux или GNU.

справочник
Название справочника (например для Разделов 2, 3 в пакете
man-pages — Linux Programmer's Manual).

Разделы внутри справочной страницы
Следующий список содержит общепринятые и рекомендуемые разделы. Большинство
справочных страниц должно включать в себя по крайней мере выделенные жирным
разделы. Соблюдайте очередность, как показано в списке.

ИМЯ
ОБЗОР
КОНФИГУРАЦИЯ [Как правило, только в разделе 4]
ОПИСАНИЕ
ПАРАМЕТРЫ [Как правило, только в разделах 1, 8]
КОД ВЫХОДА [Как правило, только в разделах 1, 8]
ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ [Как правило, только в разделах 2, 3]
ОШИБКИ [Обычно только в разделах 2, 3]
ОКРУЖЕНИЕ
ФАЙЛЫ
ВЕРСИИ [Как правило, только в разделах 2, 3]
АТРИБУТЫ [Как правило, только в разделах 2, 3]
СООТВЕТСТВИЕ СТАНДАРТАМ
ЗАМЕЧАНИЯ
ДЕФЕКТЫ
ПРИМЕРЫ
СМОТРИ ТАКЖЕ

Там, где обычно используются заголовки, используйте их; это правило может сделать
информацию более доступной для понимания. Если это необходимо, Вы можете создать
свои собственные заголовки, если они сделают текст более понятным (это может быть
особенно полезным для страниц в разделах 4 и 5). Тем не менее, прежде чем
в этой строке (в том числе идущие сразу после «\-») должны быть в
нижнем регистре, за исключением тех случаев, когда правилами языка,
на котором написана страница, или сложившейся практикой употребления
технических терминов определено иное.

ОБЗОР Краткое описание команды или интерфейса функции

Для команд здесь показываются синтаксис и аргументы (включая
параметры); полужирное начертание используется для неизменяемого
текста, а курсивом обозначаются меняющиеся аргументы. Квадратные
скобки ([]) показывают необязательные аргументы, вертикальная черта
(|) указывает на выбор одного из вариантов, многоточие (...)
означает возможное повторение. Для функций показываются все
необходимые объявления данных или #include директивы с последующим
объявлением функции.

Если для получения объявления функции (или переменной) из
заголовочного файла требуется определить макрос тестирования
свойств, то это указывается в ОБЗОРЕ согласно описанию из
feature_test_macros(7).

КОНФИГУРАЦИЯ Особенности настройки устройства

Этот раздел, как правило, присутствует только в разделе 4.

ОПИСАНИЕ Объяснение того, для чего предназначена программа, функция или
формат

Здесь описывается взаимодействие с файлами и стандартным вводом, и
что записывается в стандартный вывода вывод или ошибок; не
приводятся детали реализации, если они не критичны для понимания
интерфейса; показывается типичное использование; информация о
параметрах командной строки программы даётся в разделе OPTIONS.

Если описывается новое поведение или новые флаги системного вызова
или библиотечной функции, отметьте где введено изменение — версию
ядра или библиотеки С. Данную информацию целесообразно приводить в
виде части списка .TP в следующем виде (здесь показан новый флаг
системного вызова):

XYZ_FLAG (начиная с Linux 3.7)
Описание флагов…

Включает информацию о версии, что особенно востребовано
пользователями, которые вынуждены использовать старые версии ядра
или библиотеки C (что характерно, например, для встраиваемых
систем).

ПАРАМЕТРЫ Описание параметров командной строки и их влияния на поведение
программы.

Этот раздел как правило содержится только в разделах 1 и 8.

КОД ВЫХОДА Перечень возможных значений кода выхода программы и ситуаций, при
которых программа возвращает данное значение кода.

Этот раздел как правило содержится только в разделах 1 и 8.

Если ошибка возникает при нескольких различных условиях,
предпочтительней создавать отдельные записи списка (с повторением
имени ошибки) для каждого из условий. Такое разделение делает
условия более понятными, этот список проще читать и можно указывать
метаинформацию (например, номер версии ядра, в котором условие
начало действовать) на каждое условие.

Список ошибок должен быть в алфавитном порядке.

ОКРУЖЕНИЕ Перечень переменных окружения, влияющих на программу и оказываемый
ими эффект.

ФАЙЛЫ Список файлов, используемых программой или функцией, таких как
конфигурационные файлы, файлы запуска и файлы, с которыми
непосредственно работает программа.

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

АТРИБУТЫ Общая информация о различных атрибутах функции(функций), описанной
на этой странице. Смотри attributes(7) для получения дополнительных
сведений.

ВЕРСИИ Краткое описание ядра Linux или версии glibc, где впервые появился
системный вызов или функция библиотеки, либо существенно изменилось
их действие.

Как правило, описание каждого нового интерфейса должно включать
раздел ВЕРСИИ в справочной странице. К сожалению, в многих
справочных страницах эта информация отсутствует (когда они были
написаны, не было правила, предписывающего делать это). Заплаты,
исправляющие подобные недостатки, приветствуются, но, с точки зрения
программистов, пишущих новый код, эта информация, вероятно, имеет
значение только в том случае, если интерфейсы ядра были добавлены в
Linux 2.4 или позже (т. е., отличаются от ядра 2.2), а для
библиотечных функций, если изменения были добавлены начиная с glibc
версии 2.1 (т. е., отличаются от glibc 2.0).

Справочная страница syscalls(2) также содержит информацию о версиях
ядра, в которых были впервые реализованы различные системные вызовы.

СООТВЕТСТВИЕ СТАНДАРТАМ
Описание любых стандартов или соглашений, относящихся к функции или
команде, речь о которой идет на странице.

Предпочтительные обозначения для различных стандартов указаны в
качестве заголовков на странице standards(7).

Для страницы из раздела 2 или 3, данный раздел должен показывать
версию POSIX.1, которой соответствует вызов, а также есть ли вызов в
C99 (наличие в других стандартах, таких как SUS, SUSv2 и XPG, или
реализациях стандартов SVr4 и 4.xBSD, не важно; если вызов был в
этих стандартах, но отсутствует в текущей версии POSIX.1, то это
стоит упомянуть).

Для разделов 2 и 3 может быть полезным создание подразделов (SS),
озаглавленных Примечания для Linux и Примечания для Glibc.

В разделе 2 используйте заголовок Различия между ядром и библиотекой
С, чтобы отметить различия (если имеются) между системными вызовами
функций библиотеки и ядра.

ДЕФЕКТЫ Перечень известных ошибок, ограничений, недостатков причиняющих
неудобство а также других сомнительных свойств.

ПРИМЕРЫ Один или несколько примеров, демонстрирующих, каким образом данная
функция, команда или файл используются.

Для получения более подробной информации о написании примеров
программ смотри Примеры программ далее.

АВТОРЫ Список авторов документа или программы.

Использовать раздел АВТОРЫ настоятельно не рекомендуется. Лучше не
загромождать каждую страницу списком авторов (список со временем
увеличивается); если вы написали или значительно исправили страницу,
добавьте уведомление об авторском праве в виде комментария в
исходный файл. Если вы автор драйвера устройства и хотите включить
адрес для отправки сообщений об ошибках, то сделайте это в разделе
ДЕФЕКТЫ.

СМОТРИ ТАКЖЕ Разделённый запятыми список уместных справочных страниц, возможно,
ведущих на другие страницы или документы.

Список должен быть упорядочен по номеру раздела, а затем по
алфавиту. Не заканчивайте список точкой.

Если список СМОТРИТЕ ТАКЖЕ содержит много длинных имён справочных
страниц, то для улучшения визуального представления может быть
полезно воспользоваться командами .ad l (не выравнивать по правому
краю) и .nh (отключить перенос). Запретить перенос имён справочных
страниц можно с помощью указания перед словом строки «\%».

Учитывая распределённую, автономную природу проектов FOSS и их
документирование, иногда необходимо — и во многих случаях желательно
— включать в раздел СМОТРИТЕ ТАКЖЕ ссылки на справочные страницы из
других проектов.

РУКОВОДСТВО ПО СТИЛЮ ОФОРМЛЕНИЯ

В следующих абзацах представлен предпочтительный стиль написания страница в
проекте man-pages. Если что-то не описано подробно, то следует придерживаться
чикагского стилистического справочника (Chicago Manual of Style); также
постарайтесь поискать схожие примеры в исходном коде дерева проекта.

Использование гендерно-нейтральных выражений
Используйте гендерно-нейтральный язык в тексте справочных страниц насколько это
возможно. Приемлемо использовать местоимения «они» («им», «себя», «их»).

Соглашения о форматировании справочных страниц, описывающих команды
Для справочных страниц, описывающих команду (как правило в разделах 1 и 8),
аргументы всегда указываются с помощью курсива, даже в разделе ОБЗОР.

Имена переменных, как и имена параметров, должны быть оформлены курсивом.

Любая ссылка на тему текущей справочной страницы должна быть записана с именем
оформленным полужирным, включая пару круглых скобок, в прямом(нормальном) шрифте.
Например, на странице fcntl(2), ссылки на тему страницы были бы записаны как:
fcntl(). Рекомендуемый способ записи в исходном файле:

.BR fcntl ()

(используйте этот формат вместо б\fB...\fP ()» — такой подход упрощает создание
инструментов разбора исходных файлов справочных страниц)

Общие соглашения по оформлению
Имена файлов (также пути или ссылки на заголовочные файлы) всегда должны быть
оформлены курсивом (например, <stdio.h>), кроме раздела ОБЗОР, где включаемые
файлы должны быть полужирным (например, #include <stdio.h>). Тут ссылка на
стандартный заголовочный файл включает имя заголовочного файл, окружённого
угловыми скобками, это типично для C (например, <stdio.h>).

Специальные макросы, которые обычно находятся в верхнем регистре, оформляют
полужирным (например, MAXINT). Исключение: не делайте полужирным NULL.

В списке, при перечислении кодов ошибок, коды оформляют полужирным (в этом списке
обычно используют макрос .TP).

Составные команды, если они длинные, должны быть записаны с отступом по линии, как
самодостаточные, с пустой строкой перед и после команды, например

man 7 man-pages

Если команда короткая, то её можно включить прямо в текст как курсив, например man
7 man-pages. В этом случае может потребоваться использовать неразрывные пробелы
(«\ ») в соответствующих местах команды. Параметры команды также должны быть
выделены курсивом (например, -l).

Выражения, если не записаны на отдельной строке с отступом, должны выделяться
курсивом. Здесь также может потребоваться задавать неразрывные пробелы, если
выражение встроено в обычный текст.

При показе примера сеанса оболочки пользовательский ввод должен быть выделен
жирным, например

$ date
Thu Jul 7 13:01:27 CEST 2016

Все ссылки на другие справочные страницы должны выделяться жирным шрифтом, всегда
должен быть указан номер раздела шрифтом Roman (обычным) и без пробелов (например,
intro(2)). В исходном файле это лучше записывать так:

.BR intro (2)

(включение номера раздела в перекрёстных ссылках позволяет таким инструментам как
man2html(1) создавать правильные гиперссылки между страницами)

Управляющие знаки следует писать полужирным шрифтом, без кавычек, как в примере
^X.

«backward» (назад), «upward» (вверх), «toward» (к) и т. д., а в британском
варианте это «backwards», «upwards», «towards» и т. д.

Номера версий BSD
Классической схемой обозначения версий BSD является x.yBSD, где x.y - номер версии
(например, 4.2BSD). Избегайте написания в стиле BSD 4.3.

Печать заглавными буквами
В заголовках разделов («SS») начинайте первое слово заголовка с заглавной буквы, а
остальные буквы должны быть строчными, если обратного не требуют правила
английского языка (например, имён собственных) или языка программирования
(например, идентификаторы имён). Пример:

.SS Юникод в Linux

Отступ при определении структур, содержимого журналов сеансов оболочек и т. п.
При включении определений структур, журналов сеансов оболочек и т. п. в
выполняемый текст, нужно использовать отступ в 4 пробела (т. е., блок заключается
в .in +4n и .in), форматировать их с помощью макросов .EX и EE и окружить их
подходящими маркерами параграфа (.PP или .IP). Пример:

.PP
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
.PP

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

Термин (перевод) Не используйте Замечания
────────────────────────────────────────────────────────────────────────────────────────────────────

bit mask (маска битов) bitmask
built-in (встроенный) builtin
Epoch (эпоха) epoch Эпоха UNIX (00:00:00,
1 января 1970 UTC)
filename (имя файла) file name
filesystem (файловая система) file system
hostname (имя узла) host name
inode i-node
lowercase (строчные) lower case, lower-case
pathname (путь) path name
pseudoterminal (псевдо-терминал) pseudo-terminal
privileged port (привилегированный порт) reserved port, system
port
real-time (реальное время) realtime, real time
run time (время исполнения) runtime
saved set-group-ID (сохранённый set-group-ID) saved group ID, saved
timestamp (метка времени) time stamp
timezone (часовой пояс) time zone
uppercase (прописные) upper case, upper-case
usable (приемлемый) useable
user space (пространство пользователя) userspace
username (имя пользователя) user name
x86-64 x86_64 Кроме случая, когда
ссылаются на результат
«uname -m» или
подобных
zeros (нули) zeroes

Смотрите также Дефисы в составных терминах далее.

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

Не используйте Для использования Замечания
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

32bit 32-bit (32-битный) тоже для 8-bit,
16-bit, и т. д.
current process (текущий процесс) calling process (вызывающий процесс) Частая ошибка,
делаемая
программистами ядра
при написании
справочных страниц
manpage man page, manual page (справочная страница)
minus infinity (минус бесконечность) negative infinity (отрицательная бесконечность)
non-root unprivileged user (непривилегированный пользователь)
non-superuser unprivileged user (непривилегированный пользователь)
nonprivileged непривилегированный
OS operating system (операционная система)
plus infinity (плюс бесконечность) positive infinity (положительная бесконечность)
pty pseudoterminal (псевдо-терминал)
tty terminal (терминал)
Unices UNIX systems (системы UNIX)
Unixes UNIX systems (системы UNIX)

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

DG/UX
HP-UX
UNIX
UnixWare

NULL, NUL, указатель null и символ null
Указатель null — это указатель, который ни на что не указывает и, как правило,
имеет значение константы NULL. С другой стороны, NUL представляет собой байт
null, байт со значением 0, который в C представляется символьной константой '\0'.

Данный указатель лучше называть «указатель null» или просто «NULL»; не используйте
Для указания гиперссылок используйте пару макросов .UR/.UE (смотрите
groff_man(7)). Они создаёт корректные гиперссылки, которые можно использовать при
просмотре в браузере, например так:

BROWSER=firefox man -H имя_страницы

Использование сокращений e.g. (например), i.e. (т. е.), a.k.a. (также известно как) и
подобных
Обычно лучше не использовать сокращения вида «e.g.», «i.e.», «etc.», «a.k.a.», а
писать слова полностью («например», «то есть», «и так далее», «также известно
как»).

Единственным приемлемым местом для их использования является короткая сноска (как,
напр., эта).

Всегда указывайте точки в подобных аббревиатурах. Также после «напр.р» и «т.е.»
всегда ставится запятая.

Длинное тире
Для написания тире — символический знак, который появится в конце этой фразы—в
*roff используется макрос «\(em» (на терминалах с ASCII тире, обычно, отображается
в виде двух переносов, но в других типографских контекстах оно может выглядеть как
длинное тире). Тире должно записываться без окружающих его пробелов.

Дефисы в составных терминах
Составные термины пишутся через дефис при использовании в качестве определителя
(т. е., для уточнения последующего существительного). Примеры:

32-bit value (32-битное значение)
command-line argument (аргумент командной строки)
floating-point number (число с плавающей запятой)
run-time check (проверка во время выполнения)
user-space function (функция пространства пользователя)
wide-character string (строка широких символов)

Дефис с multi, non, pre, re, sub и т. п.
Общая тенденция на современном английском языке состоит в том, чтобы не ставить
дефисы после префиксов «multi», «non», «pre», «re», «sub» и т. д. В справочных
страницах, в основном, нужно следовать этому правилу, когда эти префиксы
используются в естественных английских конструкциях с простыми суффиксами. В
следующем списке приведены некоторые примеры правильного написания:

interprocess
multithreaded
multiprocess
nonblocking
nondefault
nonempty
noninteractive
nonnegative
nonportable
nonzero
preallocated
precreate
prerecorded
reestablished
reinitialize

non-ASCII
non-English
non-NULL
non-real-time

И напоследок заметим, что «re-create» и «recreate» — это два различных глагола и
первый, вероятно то, что нужно.

Символ математического минуса
Если требуется символ математического минуса (например, для чисел (-1) или при
записи параметров, у которых есть начальные тире, такие как в ls -l), используйте
следующую форму записи в справочной странице:

\-

Это правило применимо и в примерах кода.

Символьные константы
Чтобы получить одинарные кавычки, которые хорошо отображаются и в ASCII и в UTF-8,
используйте следующую форму записи символьных констант в справочной странице:

\(aqC\(aq

где C — символ в кавычках. Это правило применимо и в примерах кода.

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

* Примеры программ должны быть написаны на языке C.

* Примеры программ необходимы и полезны лишь в тех случаях, когда они
демонстрируют что-то сверх того, что может быть легко представлено в текстовом
описании командного интерфейса. Примеры программ, которые не показывают ничего
кроме вызова команды, как правило обладают незначительной полезностью.

* Примеры программ должны быть предельно короткими (желательно менее 100 строк; в
идеале менее 50 строк)

* В примерах программ должна быть реализована проверка ошибок после системных
вызовов и вызовов библиотечных функций.

* Примеры программ должны быть полными и компилироваться без предупреждений при
использовании cc -Wall.

* Там, где это возможно и целесообразно, примеры программ должны демонстрировать
эксперимент, изменяя свое поведение в зависимости от входных параметров (в
идеале от параметров командной строки или получаемых программой через
стандартный ввод).

* Примеры программ должны быть написаны в стиле Кернигана (Kernighan) и Ритчи
(Ritchie), с отступом, состоящим из 4 пробелов. (Избегайте использования
символа табуляции в исходном коде!) Следующие команды могут быть использованы
для форматирования исходного кода в что-то близкое к предпочтительному стилю:

indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
exit(0);
exit(1);
return n;

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

.SS Код программы

Всегда делайте это, если пояснительный текст включает примеры вывода в
терминал.

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

* Поместите лог терминала выше листинга кода программы.

* Обозначьте лог терминала четырьмя пробелами.

* Выделите полужирным вводимый пользователем текст, чтобы отличить его от вывода
системы.

Ознакомиться с тем, как должны выглядеть примеры программ Вы можете, прочитав
wait(2) и pipe(2).

ПРИМЕР

В качестве канонического примера того, как должны выглядеть страницы в пакете
man-pages, смотрите pipe(2) и fcntl(2).

СМОТРИТЕ ТАКЖЕ

man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)