| man-pages(7) | Miscellaneous Information Manual | man-pages(7) |
man-pages - правила написания справочных страниц Linux
man [раздел] имя
На этой странице описаны правила, которые необходимо применять при написании справочных страниц для проекта man-pages Linux, который, в свою очередь, документирует программный интерфейс пространства пользователя, предоставляемый ядром Linux и библиотекой GNU C. Таким образом, проект отвечает за большинство страниц из Раздела 2, за многие страницы из Разделов 3, 4, и 7, и за несколько страниц из Разделов 1, 5 и 8 справочной системы Linux. Данные правила также могут быть полезны при написании справочных страниц для других проектов. Примечание переводчика: эта страница прежде всего описывает правила для написания исходных, англоязычных версий справочных страниц, так что детали их русских переводов могут отличаться; там где страница рекомендует использование определённых терминов или формулировок, по возможности, приводятся как их англоязычные, так и русскоязычные версии; однако данная страница не является авторитетным источником информации о том, как должны выглядеть переведённые страницы руководства.
В качестве традиционных определены следующие Разделы руководства:
Новые справочные страницы должны размечаться с помощью пакета groff an.tmac, описанного в man(7). Данный выбор основан по большей части на том, что большинство из существующих страниц Linux размечены с помощью этих макросов.
Длина строки не должна превышать 75 символов. В некоторых почтовых клиентах это помогает избежать переноса строк в заплатах, встроенных в письма.
Первой должна быть команда TH:
Аргументы этой команды следующие:
Следующий список содержит общепринятые и рекомендуемые разделы. Большинство справочных страниц должно включать в себя по крайней мере те разделы, которые выделены полужирным. При создании новой справочной страницы размещайте разделы в порядке, указанном в списке.
| NAME | |
| БИБЛИОТЕКА | [Обычно только в Разделах 2 и 3] |
| ОБЗОР | |
| НАСТРОЙКА | [Обычно только в Разделе 4] |
| ОПИСАНИЕ | |
| ПАРАМЕТРЫ | [Обычно только в Разделах 1 и 8] |
| КОД ЗАВЕРШЕНИЯ | [Обычно только в Разделах 1 и 8] |
| ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ | [Обычно только в Разделах 2 и 3] |
| ОШИБКИ | [Обычно только в Разделах 2 и 3] |
| СРЕДА ОКРУЖЕНИЯ | |
| ФАЙЛЫ | |
| АТРИБУТЫ | [Обычно только в Разделах 2 и 3] |
| ВЕРСИИ | [Обычно только в Разделах 2 и 3] |
| СТАНДАРТЫ | |
| ИСТОРИЯ | |
| ПРИМЕЧАНИЯ | |
| ОГОВОРКИ | |
| ОШИБКИ | |
| ПРИМЕРЫ | |
| АВТОРЫ | [Не рекомендуется] |
| ИНФОРМАЦИЯ ОБ ОШИБКАХ | [Не используется в справочных страницах] |
| АВТОРСКИЕ ПРАВА | [Не используется в справочных страницах] |
| СМОТРИТЕ ТАКЖЕ |
Там, где применимы обычные заголовки, используйте их; последовательность в подобных вещах может сделать информацию более доступной для понимания. Но если это необходимо, вы можете создавать и свои собственные заголовки, если они сделают текст более простым для понимания (это может быть особенно полезным для страниц в Разделах 4 и 5). Тем не менее, прежде чем создавать их, подумайте, нельзя ли обойтись традиционными заголовками и просто создать свои собственные подразделы (.SS) в этих разделах.
В приведённом ниже списке объясняется назначение каждого из разделов.
Старые версии стандартов (например, SUS, SUSv2 и XPG или стандарты реализаций SVr4 и 4.xBSD) должны упоминаться здесь, а не в разделе СТАНДАРТЫ.
Следующие подразделы описывают некоторые детали соглашений, касающихся предпочтительных вариантов форматирования и формулировок в различных разделах справочных страниц проекта man-pages.
Оборачивайте прототипы функций в .nf/.fi, чтобы предотвратить переносы строк.
В общем случае, если в разделе ОБЗОР перечислено более одного прототипа функции, эти прототипы не должны разделяться пустыми строками. Однако пустые строки могут быть добавлены (с помощью .P) в следующих случаях:
В разделе ОБЗОР может потребоваться разделить длинные прототипы функций на несколько строк. В таком случае отступы в строках, перенесённых на следующую строку, расставляются по следующим правилам:
int tcsetattr(int fd, int optional_actions,
const struct termios *termios_p);
int getopt(int argc, char * const argv[],
const char *optstring);
int getopt_long(int argc, char * const argv[],
const char *optstring,
const struct option *longopts, int *longindex);
Предпочтительная формулировка для описания того, какое значение устанавливается в errno: «errno устанавливается в соответствующее значение» («errno is set to indicate the error») или аналогичная. Эта формулировка соответствует формулировке, используемой как в POSIX.1, так и во FreeBSD.
Также заметим следующее:
Для примеров всего вышеперечисленного см. исходный код различных страниц.
В следующих абзацах представлен предпочтительный стиль для страниц в проекте man-pages. Если что-то в данном разделе описано недостаточно подробно, то следует придерживаться рекомендаций Чикагского руководства по стилю (Chicago Manual of Style); также постарайтесь поискать примеры для схожих ситуаций в дереве исходных текстов проекта.
Используйте гендерно-нейтральный язык в тексте справочных страниц насколько это возможно. Приемлемо использовать местоимения «они», «им», «себя», «их» («they», «them», «themself», «their») в качестве гендерно-нейтральных местоимений единственного числа.
Для справочных страниц, описывающих команды (как правило, в Разделах 1 и 8), аргументы всегда указываются с помощью курсива, даже в разделе ОБЗОР.
Имя команды и её параметры всегда должны быть выделены полужирным.
В справочных страницах, которые описывают функции (обычно в Разделах 2 и 3), параметры всегда оформляются, используя курсив; даже в разделе ОБЗОР, где остальная часть функции оформляется полужирным:
int имя_функции(int argc, char **argv);
Имена переменных, как и имена параметров, должны быть оформлены курсивом.
Любая ссылка на предмет текущей справочной страницы должна быть оформлена в виде имени этой страницы в полужирном начертании, за которым следует пара круглых скобок в обычном начертании. Например, на странице fcntl(2) ссылки на её тему должны выглядеть как: fcntl(). Рекомендуемый способ записи этого в исходном файле:
.BR fcntl ()
(Использование такого формата записи вместо «\fB...\fP()» упрощает создание инструментов разбора исходных файлов справочных страниц.)
В исходном тексте справочной страницы новые предложения должны начинаться с новой строки, а длинные предложения должны разбиваться на строки в местах их деления на синтаксические части (запятыми, точками с запятой, двоеточиями и т. п.), а слишком длинные синтаксические части должны разбиваться на границах словосочетаний. Это соглашение, иногда называемое «семантическими переводами строк», облегчает просмотр внесённых заплат, которые зачастую вносят изменения только в отдельные предложения или их части.
Существуют разные виды списков:
Между символом начала пункта списка и самим его содержимым всегда должно быть ровно два пробела. За исключением «помеченных абзацев», которые используют стандартные правила расстановки отступов.
Параграфы должны разделяться соответствующими маркерами (обычно .P или .IP). Не разделяйте параграфы пустыми строками, так как это может привести к плохому отображению в некоторых выходных форматах (в частности, PostScript и PDF).
Имена файлов (а также пути или упоминания в тексте заголовочных файлов) всегда должны быть выделены курсивом (например, <stdio.h>), за исключением раздела ОБЗОР, где включаемые файлы должны быть выделены полужирным (например, #include <stdio.h>). Когда речь идёт о стандартных заголовочных файлах, используйте угловые скобки при их включении, как это обычно делается в Си (например, <stdio.h>).
Специальные макросы, которые обычно находятся в верхнем регистре, выделяются полужирным (например, MAXINT). Исключение: не выделяйте полужирным NULL.
В списке, при перечислении кодов ошибок, коды оформляют полужирным (в этом списке обычно используют макрос .TP).
Полные команды, если они длинные, должны записываться в виде отдельной строки с отступом и пустыми строками перед и после команды, например:
man 7 man-pages
Если команда короткая, то её можно включить прямо в текст, выделив курсивом, например: man 7 man-pages. В таком случае, вероятно, будет лучше, по необходимости, использовать неразрывные пробелы (\~). Параметры команд также должны выделяться курсивом (например, -l).
Выражения, если они не записаны отдельной строкой с отступом, должны выделяться курсивом. Для их записи также может быть уместно использовать неразрывные пробелы, когда эти выражения встроены в обычный текст.
В примерах, демонстрирующих сеанс оболочки, пользовательский ввод должен быть выделен полужирным, например:
$ date Thu Jul 7 13:01:27 CEST 2016
Все упоминания других справочных страниц должны выделяться полужирным, и после них всегда должен идти номер раздела в обычном начертании и без пробелов (например, intro(2)). В исходном файле это лучше записывать так:
.BR intro (2)
(включение номера раздела в перекрёстных ссылках позволяет таким инструментам, как man2html(1), создавать страницы с правильными гиперссылками)
Управляющие символы следует выделять полужирным, без кавычек; например: ^X.
Начиная с выпуска 2.59, проект man-pages следует американским правилам орфографии (ранее использовалась произвольная смесь британской и американской орфографии); при написании всех новых страниц, а также при правке существующих придерживайтесь этого соглашения.
Кроме известных различий в написании, есть несколько других тонкостей, которые следует учитывать:
Классической схемой обозначения версий BSD является x.yBSD, где x.y - номер версии (например, 4.2BSD). Избегайте написания в стиле BSD 4.3.
В заголовках разделов («SS») начинайте первое слово заголовка с заглавной буквы, а остальные буквы должны быть строчными, если обратного не требуют правила вашего языка (например, в именах собственных) или языка программирования (например, в именах идентификаторов). Например:
.SS Юникод в системе Linux
При включении определений структур, журналов сеансов оболочек и т. п. в основной текст, нужно использовать отступ в 4 пробела (т. е. заключить блок в .in +4n и .in), задать им формат с помощью макросов .EX и .EE и окружить их подходящими маркерами параграфа (.P или .IP). Например:
.P
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
.P
В следующей таблице перечислены некоторые предпочтительные термины, для использования в справочных страницах, главным образом, для непротиворечивости информации на страницах.
| Термин (перевод) | Не используйте | Примечания |
| 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 | |
| nonzero (ненулевой) | non-zero | |
| 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 set-GID | |
| saved set-user-ID (сохранённый set-user-ID) | saved user ID, saved set-UID | |
| set-group-ID | set-GID, setgid | |
| set-user-ID | set-UID, setuid | |
| superuser (суперпользователь) | super user, super-user | |
| superblock (суперблок) | super block, super-block | |
| symbolic link (символьная ссылка) | symlink | |
| 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 (не root) | unprivileged user (непривилегированный пользователь) | |
| non-superuser (не суперпользователь) | unprivileged user (непривилегированный пользователь) | |
| nonprivileged | unprivileged (непривилегированный) | |
| 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 или нулевой указатель (null pointer) — это указатель, который ни на что не указывает и, как правило, обозначается константой NULL. С другой стороны, NUL представляет собой байт null или нулевой байт (null byte), байт со значением 0, который в Си представляется символьной константой '\0'.
Данный указатель лучше называть «указатель null» (null pointer) или «нулевой указатель», или просто «NULL»; избегайте написания «указатель NULL» (NULL pointer).
Для описания байта используйте «байт null» (null byte). Избегайте написания «NUL», так как такое наименование слишком просто спутать с «NULL». Также избегайте терминов «байт ноль» («zero byte») и «нулевой символ» (null character). Байт, которым заканчиваются строки в Си, нужно описывать как «завершающий байт null» (terminating null byte); про строки можно сказать как «завершающиеся null» (null-terminated), но не используйте «завершающиеся NUL» (NUL-terminated).
Для указания гиперссылок используйте пару макросов .UR/.UE (смотрите groff_man(7)). Это создаст корректные гиперссылки, которые можно использовать при просмотре в браузере; например так:
BROWSER=firefox man -H имя-страницы
Обычно лучше не использовать такие сокращения, как «e.g.», «i.e.», «etc.», «cf.» и «a.k.a.», а писать слова полностью («for example» (например), «that is» (то есть), «and so on» (и так далее), «compare to» (в сравнении с), «also known as» (также известный как)).
Единственное местом, где подобные сокращения могут быть уместны — это короткие отступления в скобках (т. е. как вот это).
Всегда указывайте точки в подобных аббревиатурах. Также после «e.g.» и «i.e.» всегда ставится запятая. Примечание переводчика: в русскоязычных справочных страницах после каждой точки в «т. е.», «и т. д.» и т. п. ставится пробел; кроме того сокращение «напр.» для «например» не используется.
Добавлять в текст длинное тире — глиф, которым выделено данное уточнение, — в *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» и т. д. В справочных страницах, в основном, нужно следовать этому правилу, когда эти префиксы используются в естественных английских конструкциях с простыми суффиксами. В следующем списке приведены некоторые примеры правильного написания:
| interprocess (межпроцессный) |
| multithreaded (многопоточный) |
| multiprocess (многопроцессный) |
| nonblocking (неблокирующий) |
| nondefault (нестандартный) |
| nonempty (непустой) |
| noninteractive (неинтерактивный) |
| nonnegative (неотрицательный) |
| nonportable (непереносимый) |
| nonzero (ненулевой) |
| preallocated (предварительно выделенный) |
| precreate (предварительно создать) |
| prerecorded (предварительно записанный) |
| reestablished (восстановленный) |
| reinitialize (переинициализировать) |
| rearm (переустановить) |
| reread (перечитать) |
| subcomponent (подкомпонент) |
| subdirectory (подкаталог) |
| subsystem (подсистема) |
Дефисы должны быть сохранены после префиксов для нестандартных английских слов, торговых марок, имён собственных, акронимов или составных терминов. Несколько примеров:
| non-ASCII (не-ASCII) |
| non-English (неанглийский) |
| non-NULL (не-NULL) |
| non-real-time (не в реальном времени) |
И напоследок заметим, что в английском «re-create» (пересоздать) и «recreate» (развлекаться) — это два различных глагола и вы, вероятно, хотите использовать последний.
Если требуется настоящий символ математического минуса (например, для чисел (-1), перекрёстных ссылок на другие справочные страницы (utf-8(7)) или при записи параметров, которые начинаются с чёрточки (ls -l)), записывайте его в исходном коде справочных страниц следующим образом:
\-
Это правило применимо и для примеров кода.
Использование настоящего символа минуса служит следующим целям:
Чтобы получить одинарные кавычки, которые хорошо отображаются и в ASCII, и в UTF-8, используйте «\[aq]» («apostrophe quote», «апострофная кавычка»); например:
\[aq]C\[aq]
где C — символ в кавычках. Это правило применимо и для символьных констант в примерах кода.
Когда требуется правильно отображаемый символ карет (^), который будет хорошо смотреться как в терминале, так и в PDF, используйте «\[ha]». Это особенно важно в примерах кода, чтобы получить красивые символы циркумфлекса при выводе в PDF.
Использование голого символа тильды «~» приводит к плохому отображению в PDF. Вместо этого используйте «\[ti]». Это также особенно важно в примерах кода, чтобы получить красивые символы тильды при выводе в PDF.
Справочные страницы могут включать примеры программ, демонстрирующие использование системных вызовов или библиотечных функций. При этом нужно учитывать ряд условий:
indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
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)
Русский перевод этой страницы руководства разработал(и) aereiae <aereiae@gmail.com>, Alexey <a.chepugov@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitriy S. Seregin <dseregin@59.ru>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, ITriskTI <ITriskTI@gmail.com>, Max Is <ismax799@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com>, Малянов Евгений Викторович <maljanow@outlook.com>, Kirill Rekhov <krekhov.dev@gmail.com> и Alexander Golubev <fatzer2@gmail.com>
Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.
Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков.
| 15 июня 2024 г. | Справочные страницы Linux 6.9.1 |