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:
The arguments of the command are as follows:
Следующий список содержит общепринятые и рекомендуемые разделы. Большинство справочных страниц должно включать в себя по крайней мере выделенные жирным разделы. Соблюдайте очередность, как показано в списке.
NAME | |
LIBRARY | [Normally only in Sections 2, 3] |
ОБЗОР | |
НАСТРОЙКА | [Normally only in Section 4] |
ОПИСАНИЕ | |
ПАРАМЕТРЫ | [Normally only in Sections 1, 8] |
КОД РЕЗУЛЬТАТА | [Normally only in Sections 1, 8] |
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ | [Normally only in Sections 2, 3] |
ОШИБКИ | [Typically only in Sections 2, 3] |
ОКРУЖЕНИЕ | |
ФАЙЛЫ | |
ВЕРСИИ | [Normally only in Sections 2, 3] |
АТРИБУТЫ | [Normally only in Sections 2, 3] |
СТАНДАРТЫ | |
ЗАМЕЧАНИЯ | |
CAVEATS | |
ДЕФЕКТЫ | |
ПРИМЕРЫ | |
АВТОРЫ | [Discouraged] |
ИНФОРМАЦИЯ ОБ ОШИБКАХ | [Not used in man-pages] |
АВТОРСКИЕ ПРАВА | [Not used in man-pages] |
СМОТРИ ТАКЖЕ |
Там, где обычно используются заголовки, используйте их; это правило может сделать информацию более доступной для понимания. Если это необходимо, Вы можете создать свои собственные заголовки, если они сделают текст более понятным (это может быть особенно полезным для страниц в разделах 4 и 5). Тем не менее, прежде чем создавать их, подумайте, можно ли обойтись традиционными заголовками с созданием своих собственных подразделов (.SS) в пределах стандартных разделов.
В приведённом ниже списке объясняется назначение каждого из разделов.
The following subsections note some details for preferred formatting and wording conventions in various sections of the pages in the man-pages project.
Wrap the function prototype(s) in a .nf/.fi pair to prevent filling.
In general, where more than one function prototype is shown in the SYNOPSIS, the prototypes should not be separated by blank lines. However, blank lines (achieved using .PP) may be added in the following cases:
In the SYNOPSIS, a long function prototype may need to be continued over to the next line. The continuation line is indented according to the following rules:
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);
The preferred wording to describe how errno is set is "errno is set to indicate the error" or similar. This wording is consistent with the wording used in both POSIX.1 and FreeBSD.
Также заметим следующее:
For examples of all of the above, see the source code of various pages.
В следующих абзацах представлен предпочтительный стиль написания страница в проекте man-pages. Если что-то не описано подробно, то следует придерживаться чикагского стилистического справочника (Chicago Manual of Style); также постарайтесь поискать схожие примеры в исходном коде дерева проекта.
Используйте гендерно-нейтральный язык в тексте справочных страниц насколько это возможно. Приемлемо использовать местоимения «они» («им», «себя», «их»).
Для справочных страниц, описывающих команду (как правило в разделах 1 и 8), аргументы всегда указываются с помощью курсива, даже в разделе ОБЗОР.
Имя команд и их опции, всегда должны быть оформленными полужирным стилем.
В справочных страницах, которые описывают функции (обычно, в разделах 2 и 3), параметры всегда оформляются, используя курсив; даже в разделе ОБЗОР, где остальная часть функции определена полужирным:
int имя_функции(int argc, char **argv);
Имена переменных, как и имена параметров, должны быть оформлены курсивом.
Любая ссылка на тему текущей справочной страницы должна быть записана с именем оформленным полужирным, включая пару круглых скобок, в прямом(нормальном) шрифте. Например, на странице fcntl(2), ссылки на тему страницы были бы записаны как: fcntl(). Рекомендуемый способ записи в исходном файле:
.BR fcntl ()
(используйте этот формат вместо б\fB...\fP ()» — такой подход упрощает создание инструментов разбора исходных файлов справочных страниц)
In the source of a manual page, new sentences should be started on new lines, long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on), and long clauses should be split at phrase boundaries. This convention, sometimes known as "semantic newlines", makes it easier to see the effect of patches, which often operate at the level of individual sentences, clauses, or phrases.
There are different kinds of lists:
There should always be exactly 2 spaces between the list symbol and the elements. This doesn't apply to "tagged paragraphs", which use the default indentation rules.
Параграфы должны разделяться подходящими маркерами (обычно .PP или .IP). Не разделяйте параграфы пробельными строками, так как это приводит к плохому отображению в некоторых выходных форматах (в частности, PostScript и PDF).
Имена файлов (также пути или ссылки на заголовочные файлы) всегда должны быть оформлены курсивом (например, <stdio.h>), кроме раздела ОБЗОР, где включаемые файлы должны быть полужирным (например, #include <stdio.h>). Тут ссылка на стандартный заголовочный файл включает имя заголовочного файл, окружённого угловыми скобками, это типично для C (например, <stdio.h>).
Специальные макросы, которые обычно находятся в верхнем регистре, оформляют полужирным (например, MAXINT). Исключение: не делайте полужирным NULL.
В списке, при перечислении кодов ошибок, коды оформляют полужирным (в этом списке обычно используют макрос .TP).
Составные команды, если они длинные, должны быть записаны с отступом по линии, как самодостаточные, с пустой строкой перед и после команды, например
man 7 man-pages
If the command is short, then it can be included inline in the text, in italic format, for example, man 7 man-pages. In this case, it may be worth using nonbreaking spaces (\[ti]) at suitable places in the command. Command options should be written in italics (e.g., -l).
Выражения, если не записаны на отдельной строке с отступом, должны выделяться курсивом. Здесь также может потребоваться задавать неразрывные пробелы, если выражение встроено в обычный текст.
При показе примера сеанса оболочки пользовательский ввод должен быть выделен жирным, например
$ date Thu Jul 7 13:01:27 CEST 2016
Все ссылки на другие справочные страницы должны выделяться жирным шрифтом, всегда должен быть указан номер раздела шрифтом Roman (обычным) и без пробелов (например, intro(2)). В исходном файле это лучше записывать так:
.BR intro (2)
(включение номера раздела в перекрёстных ссылках позволяет таким инструментам как man2html(1) создавать правильные гиперссылки между страницами)
Control characters should be written in bold face, with no quotes; for example, ^X.
Начиная с версии man-pages следует при написании Американским соглашениям (до этого использовалось английское и американское написание); пишите новые страницы и присылайте заплаты с учётом этих соглашений.
Кроме известных различий в написании, есть несколько других тонкостей, которые следует учесть:
Классической схемой обозначения версий BSD является x.yBSD, где x.y - номер версии (например, 4.2BSD). Избегайте написания в стиле BSD 4.3.
В заголовках разделов («SS») начинайте первое слово заголовка с заглавной буквы, а остальные буквы должны быть строчными, если обратного не требуют правила английского языка (например, имён собственных) или языка программирования (например, идентификаторы имён). Пример:
.SS Unicode under Linux
When structure definitions, shell session logs, and so on are included in running text, indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the .EX and .EE macros, and surround them with suitable paragraph markers (either .PP or .IP). For example:
.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 | |
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 (сохранённый saved 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 | |
символьная ссылка | 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 | 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 |
A null pointer is a pointer that points to nothing, and is normally indicated by the constant NULL. On the other hand, NUL is the null byte, a byte with the value 0, represented in C via the character constant '\0'.
Данный указатель лучше называть «указатель null» или просто «NULL»; не используйте «указатель NULL».
Для описания байта используйте «байт null». Не пишите «NUL», так как такое наименование легко спутать с «NULL». Также избегайте терминов «нулевой байт» и «символ null». Байт, которым заканчиваются строки в C, нужно описывать как «завершающий байт null» (terminating null byte); про строки можно сказать как «завершающиеся null» (null-terminated), но не используйте «завершающиеся NUL».
Для указания гиперссылок используйте пару макросов .UR/.UE (смотрите groff_man(7)). Они создаёт корректные гиперссылки, которые можно использовать при просмотре в браузере, например так:
BROWSER=firefox man -H pagename
In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", "cf.", and "a.k.a." should be avoided, in favor of suitable full wordings ("for example", "that is", "and so on", "compare to", "also known as").
Единственным приемлемым местом для их использования является короткая сноска (как, напр., эта).
Всегда указывайте точки в подобных аббревиатурах. Также после «напр.р» и «т.е.» всегда ставится запятая.
The way to write an em-dash—the glyph that appears at either end of this subphrase—in *roff is with the macro "\[em]". (On an ASCII terminal, an em-dash typically renders as two hyphens, but in other typographical contexts it renders as a long dash.) Em-dashes should be written without surrounding spaces.
Составные термины пишутся через дефис при использовании в качестве определителя (т. е., для уточнения последующего существительного). Примеры:
32-bit value |
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 |
non-English |
non-NULL |
non-real-time |
И напоследок заметим, что «re-create» и «recreate» — это два различных глагола и первый, вероятно то, что нужно.
Если требуется символ математического минуса (например, для чисел (-1), перекрёстных ссылок справочных страниц (utf-8(7) или при записи параметров, у которых есть начальные тире (ls -l)), используйте следующую форму записи в справочной странице:
\-
Это правило применимо и в примерах кода.
The use of real minus signs serves the following purposes:
To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, use "\[aq]" ("apostrophe quote"); for example
\[aq]C\[aq]
где C — символ в кавычках. Это правило применимо и в примерах кода.
Where a proper caret (^) that renders well in both a terminal and PDF is required, use "\[ha]". This is especially necessary in code samples, to get a nicely rendered caret when rendering to PDF.
Using a naked "~" character results in a poor rendering in PDF. Instead use "\[ti]". This is especially necessary in code samples, to get a nicely rendered tilde when rendering to 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 Program source
Если включаете лог вывода в терминал, демонстрирующий использование программы или системной функции:
Ознакомиться с тем, как должны выглядеть примеры программ Вы можете, прочитав 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>
Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.
Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.
5 февраля 2023 г. | Linux man-pages 6.03 |