.\" -*- coding: UTF-8 -*- '\" t .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler .\" (faith@cs.unc.edu and dwheeler@ida.org) .\" and (C) Copyright 2007 Michael Kerrisk .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" 2007-05-30 created by mtk, using text from old man.7 plus .\" rewrites and additional text. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH man\-pages 7 "5 февраля 2023 г." "Linux man\-pages 6.03" .SH ИМЯ man\-pages — правила написания справочных страниц Linux .SH СИНТАКСИС \fBman\fP [\fIраздел\fP] \fIимя\fP .SH ОПИСАНИЕ На этой странице описаны правила, которые необходимо применять при написании справочных страниц для проекта \fIman\-pages\fP Linux, который, в свою очередь, документирует программный интерфейс пространства пользователя, предоставляемый ядром Linux и библиотекой GNU C. Таким образом, проект отвечает за большинство страниц из Раздела 2, за многие страницы из Разделов 3, 4, и 7, и за несколько страниц из Разделов 1, 5 и 8 справочной системы Linux. Данные правила также могут быть полезны при написании справочных страниц для других проектов. .SS "Разделы справочных страниц" Традиционно они следующие: .TP \fB1 Команды пользователя (Программы)\fP Commands that can be executed by the user from within a shell. .TP \fB2 Системные вызовы\fP Functions which wrap operations performed by the kernel. .TP \fB3 Библиотечные вызовы\fP Все библиотечные функции (в основном функции \fIlibc\fP), за исключением представленных в Разделе 2. .TP \fB4 Специальные файлы (устройства)\fP Файлы из \fI/dev\fP, дающие доступ к устройствам через ядро. .TP \fB5 Форматы файлов и конфигурационные фалы\fP Описывает различные подходящие для чтения форматы файлов и конфигурационные файлы. .TP \fB6 Игры\fP Игры и забавные небольшие программы .TP \fB7 Обзоры, соглашения и разное\fP Описания или обзоры, касающиеся различных тем, соглашений и протоколов, а также наборов символов, стандартный шаблон файловой системы, разное. .TP \fB8 Команды для системного администрирования\fP .\" .TP .\" .B 9 Kernel routines .\" This is an obsolete manual section. .\" Once it was thought a good idea to document the Linux kernel here, .\" but in fact very little has been documented, and the documentation .\" that exists is outdated already. .\" There are better sources of .\" information for kernel developers. Команды подобные \fBmount\fP(8), большинство из которых могут запускаться только суперпользователем. .SS "Пакет макросов" Новые справочные страницы должны размечаться с помощью пакета \fBgroff an.tmac\fP, описанного в \fBman\fP(7). Данный выбор основан, в основном, на том, что большинство из существующих страниц Linux размечены с помощью этих макросов. .SS "Правила, касающиеся формата исходных файлов" Длина строки не должна превышать 75 символов. В некоторых почтовых клиентах это помогает избежать переноса строк в заплатах, встроенные в письмо. .SS Заголовок Первой должна быть команда \fBTH\fP: .PP .RS \fB\&.TH\fP \fItitle section date source manual\-section\fP .RE .PP The arguments of the command are as follows: .TP \fIзаголовок\fP Название страницы, написанное заглавными буквами (например \fIMAN\-PAGES\fP). .TP \fIраздел\fP Номер раздела для размещения страницы (например \fI7\fP). .TP \fIдата\fP Дата последнего значительного изменения справочной страницы (в проекте \fIman\-pages\fP необходимые обновления временных отметок выполняются автоматически при помощи сценариев, вручную устанавливать её заплатой не нужно). Дата должна иметь вид YYYY\-MM\-DD, т. е. год\-месяц\-день. .TP \fIисточник\fP The name and version of the project that provides the manual page (not necessarily the package that provides the functionality). .TP \fImanual\-section\fP .\" Normally, this should be empty, since the default value will be good. .SS "Разделы внутри справочной страницы" Следующий список содержит общепринятые и рекомендуемые разделы. Большинство справочных страниц должно включать в себя по крайней мере \fBвыделенные жирным\fP разделы. Соблюдайте очередность, как показано в списке. .PP .RS .TS l l. \fBNAME\fP LIBRARY [Normally only in Sections 2, 3] \fBОБЗОР\fP НАСТРОЙКА [Normally only in Section 4] \fBОПИСАНИЕ\fP ПАРАМЕТРЫ [Normally only in Sections 1, 8] КОД РЕЗУЛЬТАТА [Normally only in Sections 1, 8] ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ [Normally only in Sections 2, 3] .\" May 07: Few current man pages have an ERROR HANDLING section,,, .\" ERROR HANDLING, ОШИБКИ [Typically only in Sections 2, 3] .\" May 07: Almost no current man pages have a USAGE section,,, .\" USAGE, .\" DIAGNOSTICS, .\" May 07: Almost no current man pages have a SECURITY section,,, .\" SECURITY, ОКРУЖЕНИЕ ФАЙЛЫ ВЕРСИИ [Normally only in Sections 2, 3] АТРИБУТЫ [Normally only in Sections 2, 3] СТАНДАРТЫ ЗАМЕЧАНИЯ CAVEATS ДЕФЕКТЫ ПРИМЕРЫ .\" AUTHORS sections are discouraged АВТОРЫ [Discouraged] ИНФОРМАЦИЯ ОБ ОШИБКАХ [Not used in man\-pages] АВТОРСКИЕ ПРАВА [Not used in man\-pages] \fBСМОТРИ ТАКЖЕ\fP .TE .RE .PP \fIТам, где обычно используются заголовки\fP, \fIиспользуйте их\fP; это правило может сделать информацию более доступной для понимания. Если это необходимо, Вы можете создать свои собственные заголовки, если они сделают текст более понятным (это может быть особенно полезным для страниц в разделах 4 и 5). Тем не менее, прежде чем создавать их, подумайте, можно ли обойтись традиционными заголовками с созданием своих собственных подразделов (\fI.SS\fP) в пределах стандартных разделов. .PP В приведённом ниже списке объясняется назначение каждого из разделов. .TP \fBNAME\fP Название данной справочной страниц. .IP Смотрите \fBman\fP(7), чтобы ознакомиться с правилами написания заголовков, которые должны следовать за командой \fB.SH NAME\fP. Все слова в этой строке (в том числе идущие сразу после «\e\-») должны быть в нижнем регистре, за исключением тех случаев, когда правилами языка, на котором написана страница, или сложившейся практикой употребления технических терминов определено иное. .TP \fBLIBRARY\fP The library providing a symbol. .IP It shows the common name of the library, and in parentheses, the name of the library file and, if needed, the linker flag needed to link a program against it: (\fIlibfoo\fP[, \fI\-lfoo\fP]). .TP \fBОБЗОР\fP Краткое описание команды или интерфейса функции .IP Для команд здесь показываются синтаксис и аргументы (включая параметры); полужирное начертание используется для неизменяемого текста, а курсивом обозначаются меняющиеся аргументы. Квадратные скобки ([]) показывают необязательные аргументы, вертикальная черта (|) указывает на выбор одного из вариантов, многоточие (\&...) означает возможное повторение. Для функций показываются все необходимые объявления данных или \fB#include\fP директивы с последующим объявлением функции. .IP .\" FIXME . Say something here about compiler options Если для получения объявления функции (или переменной) из заголовочного файла требуется определить макрос тестирования свойств, то это указывается в ОБЗОРЕ согласно описанию из \fBfeature_test_macros\fP(7). .TP \fBКОНФИГУРАЦИЯ\fP Особенности настройки устройства .IP Этот раздел, как правило, присутствует только в разделе 4. .TP \fBОПИСАНИЕ\fP Объяснение того, для чего предназначена программа, функция или формат .IP .\" If there is some kind of input grammar or complex set of subcommands, .\" consider describing them in a separate .\" .B USAGE .\" section (and just place an overview in the .\" .B DESCRIPTION .\" section). Здесь описывается взаимодействие с файлами и стандартным вводом, и что записывается в стандартный вывода вывод или ошибок; не приводятся детали реализации, если они не критичны для понимания интерфейса; показывается типичное использование; информация о параметрах командной строки программы даётся в разделе \fBOPTIONS\fP. .IP Если описывается новое поведение или новые флаги системного вызова или библиотечной функции, отметьте где введено изменение — версию ядра или библиотеки С. Данную информацию целесообразно приводить в виде части списка \&\fB.TP\fP в следующем виде (здесь показан новый флаг системного вызова): .RS 16 .TP \fBXYZ_FLAG\fP (начиная с Linux 3.7) Описание флагов… .RE .IP Включает информацию о версии, что особенно востребовано пользователями, которые вынуждены использовать старые версии ядра или библиотеки C (что характерно, например, для встраиваемых систем). .TP \fBПАРАМЕТРЫ\fP Описание параметров командной строки и их влияния на поведение программы. .IP .\" .TP .\" .B USAGE .\" describes the grammar of any sublanguage this implements. Этот раздел как правило содержится только в разделах 1 и 8. .TP \fBКОД ВЫХОДА\fP Перечень возможных значений кода выхода программы и ситуаций, при которых программа возвращает данное значение кода. .IP Этот раздел как правило содержится только в разделах 1 и 8. .TP \fBВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ\fP Для разделов 2 и 3 эта секция содержит перечень значений, возвращаемых библиотеками вызывающей их программе и условия, при которых библиотеки возвращают данные значения. .TP \fBОШИБКИ\fP В справочных страницах разделов 2 и 3 здесь описываются значения ошибок, которые могут быть помещены в \fIerrno\fP, а также приводится описание причин ошибок. .IP Если ошибка возникает при нескольких различных условиях, предпочтительней создавать отдельные записи списка (с повторением имени ошибки) для каждого из условий. Такое разделение делает условия более понятными, этот список проще читать и можно указывать метаинформацию (например, номер версии ядра, в котором условие начало действовать) на каждое условие. .IP \fIСписок ошибок должен быть в алфавитном порядке\fP. .TP \fBОКРУЖЕНИЕ\fP Перечень переменных окружения, влияющих на программу и оказываемый ими эффект. .TP \fBФАЙЛЫ\fP Список файлов, используемых программой или функцией, таких как конфигурационные файлы, файлы запуска и файлы, с которыми непосредственно работает программа. .IP .\" May 07: Almost no current man pages have a DIAGNOSTICS section; .\" "RETURN VALUE" or "EXIT STATUS" is preferred. .\" .TP .\" .B DIAGNOSTICS .\" gives an overview of the most common error messages and how to .\" cope with them. .\" You don't need to explain system error messages .\" or fatal signals that can appear during execution of any program .\" unless they're special in some way to the program. .\" .\" May 07: Almost no current man pages have a SECURITY section. .\".TP .\".B SECURITY .\"discusses security issues and implications. .\"Warn about configurations or environments that should be avoided, .\"commands that may have security implications, and so on, especially .\"if they aren't obvious. .\"Discussing security in a separate section isn't necessary; .\"if it's easier to understand, place security information in the .\"other sections (such as the .\" .B DESCRIPTION .\" or .\" .B USAGE .\" section). .\" However, please include security information somewhere! Указывайте полный путь к этим файлам, также используйте возможность изменить во время установки изменить путь в соответствии с предпочтениями пользователя. .TP \fBАТРИБУТЫ\fP Общая информация о различных атрибутах функции(функций), описанной на этой странице. Смотри \fBattributes\fP(7) для получения дополнительных сведений. .TP \fBВЕРСИИ\fP Краткое описание ядра Linux или версии glibc, где впервые появился системный вызов или функция библиотеки, либо существенно изменилось их действие. .IP As a general rule, every new interface should include a VERSIONS section in its manual page. Unfortunately, many existing manual pages don't include this information (since there was no policy to do so when they were written). Patches to remedy this are welcome, but, from the perspective of programmers writing new code, this information probably matters only in the case of kernel interfaces that have been added in Linux 2.4 or later (i.e., changes since Linux 2.2), and library functions that have been added to glibc since glibc 2.1 (i.e., changes since glibc 2.0). .IP Справочная страница \fBsyscalls\fP(2) также содержит информацию о версиях ядра, в которых были впервые реализованы различные системные вызовы. .TP \fBСТАНДАРТЫ\fP Описание любых стандартов или соглашений, относящихся к функции или команде, речь о которой идет на странице. .IP Предпочтительные обозначения для различных стандартов указаны в качестве заголовков на странице \fBstandards\fP(7). .IP Для страницы из раздела 2 или 3, данный раздел должен показывать версию POSIX.1, которой соответствует вызов, а также есть ли вызов в C99 (наличие в других стандартах, таких как SUS, SUSv2 и XPG, или реализациях стандартов SVr4 и 4.xBSD, не важно; если вызов был в этих стандартах, но отсутствует в текущей версии POSIX.1, то это стоит упомянуть). .IP Если вызов не соответствует какому\-либо стандарту, но существует во многих системах, также упомяните об этом. Если вызов есть только в Linux, то это также стоит отметить. .IP If this section consists of just a list of standards (which it commonly does), terminate the list with a period (\[aq].\[aq]). .TP \fBЗАМЕЧАНИЯ\fP Различные замечания. .IP For Section 2 and 3 man pages you may find it useful to include subsections (\fBSS\fP) named \fILinux Notes\fP and \fIglibc Notes\fP. .IP В разделе 2 используйте заголовок \fIРазличия между ядром и библиотекой С\fP, чтобы отметить различия (если имеются) между системными вызовами функций библиотеки и ядра. .TP \fBCAVEATS\fP Warnings about typical user misuse of an API, that don't constitute an API bug or design defect. .TP \fBДЕФЕКТЫ\fP Перечень известных ошибок, ограничений, недостатков причиняющих неудобство а также других сомнительных свойств. .TP \fBПРИМЕРЫ\fP Один или несколько примеров, демонстрирующих, каким образом данная функция, команда или файл используются. .IP Для получения более подробной информации о написании примеров программ смотрите раздел \fIПримеры программ\fP далее. .TP \fBАВТОРЫ\fP Список авторов документа или программы. .IP \fBИспользовать раздел АВТОРЫ настоятельно не рекомендуется\fP. Лучше не загромождать каждую страницу списком авторов (список со временем увеличивается); если вы написали или значительно исправили страницу, добавьте уведомление об авторском праве в виде комментария в исходный файл. Если вы автор драйвера устройства и хотите включить адрес для отправки сообщений об ошибках, то сделайте это в разделе ДЕФЕКТЫ. .TP \fBREPORTING BUGS\fP The \fIman\-pages\fP project doesn't use a REPORTING BUGS section in manual pages. Information on reporting bugs is instead supplied in the script\-generated COLOPHON section. However, various projects do use a REPORTING BUGS section. It is recommended to place it near the foot of the page. .TP \fBАВТОРСКОЕ ПРАВО\fP The \fIman\-pages\fP project doesn't use a COPYRIGHT section in manual pages. Copyright information is instead maintained in the page source. In pages where this section is present, it is recommended to place it near the foot of the page, just above SEE ALSO. .TP \fBСМОТРИ ТАКЖЕ\fP Разделённый запятыми список уместных справочных страниц, возможно, ведущих на другие страницы или документы. .IP Список должен быть упорядочен по номеру раздела, а затем по алфавиту. Не заканчивайте список точкой. .IP Если список \fBСМОТРИТЕ ТАКЖЕ\fP содержит много длинных имён справочных страниц, то для улучшения визуального представления может быть полезно воспользоваться командами \fI.ad l\fP (не выравнивать по правому краю) и \fI.nh\fP (отключить перенос). Запретить перенос имён справочных страниц можно с помощью указания перед словом строки «\e%». .IP Given the distributed, autonomous nature of FOSS projects and their documentation, it is sometimes necessary\[em]and in many cases desirable\[em]that the SEE ALSO section includes references to manual pages provided by other projects. .SH "FORMATTING AND WORDING CONVENTIONS" The following subsections note some details for preferred formatting and wording conventions in various sections of the pages in the \fIman\-pages\fP project. .SS СИНТАКСИС Wrap the function prototype(s) in a \fI.nf\fP/\fI.fi\fP pair to prevent filling. .PP In general, where more than one function prototype is shown in the SYNOPSIS, the prototypes should \fInot\fP be separated by blank lines. However, blank lines (achieved using \fI.PP\fP) may be added in the following cases: .IP \[bu] 3 to separate long lists of function prototypes into related groups (see for example \fBlist\fP(3)); .IP \[bu] in other cases that may improve readability. .PP 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: .IP (1) 5 If there is a single such prototype that needs to be continued, then align the continuation line so that when the page is rendered on a fixed\-width font device (e.g., on an xterm) the continuation line starts just below the start of the argument list in the line above. (Exception: the indentation may be adjusted if necessary to prevent a very long continuation line or a further continuation line where the function prototype is very long.) As an example: .IP .in +4n .nf \fBint tcsetattr(int \fP\fIfd\fP\fB, int \fP\fIoptional_actions\fP\fB,\fP \fB const struct termios *\fP\fItermios_p\fP\fB);\fP .fi .in .IP (2) But, where multiple functions in the SYNOPSIS require continuation lines, and the function names have different lengths, then align all continuation lines to start in the same column. This provides a nicer rendering in PDF output (because the SYNOPSIS uses a variable width font where spaces render narrower than most characters). As an example: .IP .in +4n .nf \fBint getopt(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP \fB const char *\fP\fIoptstring\fP\fB);\fP \fBint getopt_long(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP \fB const char *\fP\fIoptstring\fP\fB,\fP \fB const struct option *\fP\fIlongopts\fP\fB, int *\fP\fIlongindex\fP\fB);\fP .fi .in .SS "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" .\" Before man-pages 5.11, many different wordings were used, which .\" was confusing, and potentially made scripted edits more difficult. The preferred wording to describe how \fIerrno\fP is set is \[dq]\fIerrno\fP is set to indicate the error" or similar. This wording is consistent with the wording used in both POSIX.1 and FreeBSD. .SS АТРИБУТЫ .\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf Также заметим следующее: .IP \[bu] 3 Wrap the table in this section in a \fI.ad\ l\fP/\fI.ad\fP pair to disable text filling and a \fI.nh\fP/\fI.hy\fP pair to disable hyphenation. .IP \[bu] Ensure that the table occupies the full page width through the use of an \fIlbx\fP description for one of the columns (usually the first column, though in some cases the last column if it contains a lot of text). .IP \[bu] Make free use of \fIT{\fP/\fIT}\fP macro pairs to allow table cells to be broken over multiple lines (also bearing in mind that pages may sometimes be rendered to a width of less than 80 columns). .PP For examples of all of the above, see the source code of various pages. .SH "РУКОВОДСТВО ПО СТИЛЮ ОФОРМЛЕНИЯ" В следующих абзацах представлен предпочтительный стиль написания страница в проекте \fIman\-pages\fP. Если что\-то не описано подробно, то следует придерживаться чикагского стилистического справочника (Chicago Manual of Style); также постарайтесь поискать схожие примеры в исходном коде дерева проекта. .SS "Использование гендерно\-нейтральных выражений" .\" Используйте гендерно\-нейтральный язык в тексте справочных страниц насколько это возможно. Приемлемо использовать местоимения «они» («им», «себя», «их»). .SS "Соглашения о форматировании справочных страниц, описывающих команды" Для справочных страниц, описывающих команду (как правило в разделах 1 и 8), аргументы всегда указываются с помощью курсива, \fIдаже в разделе ОБЗОР\fP. .PP .\" Имя команд и их опции, всегда должны быть оформленными полужирным стилем. .SS "Соглашения по оформлению справочных страниц, описывающих функции" В справочных страницах, которые описывают функции (обычно, в разделах 2 и 3), параметры всегда оформляются, используя курсив; \fIдаже в разделе ОБЗОР\fP, где остальная часть функции определена полужирным: .PP \fB int имя_функции(int \fP\fIargc\fP\fB, char **\fP\fIargv\fP\fB);\fP .PP Имена переменных, как и имена параметров, должны быть оформлены курсивом. .PP Любая ссылка на тему текущей справочной страницы должна быть записана с именем оформленным полужирным, включая пару круглых скобок, в прямом(нормальном) шрифте. Например, на странице \fBfcntl\fP(2), ссылки на тему страницы были бы записаны как: \fBfcntl\fP(). Рекомендуемый способ записи в исходном файле: .PP .EX .BR fcntl () .EE .PP .\" (используйте этот формат вместо б\efB...\efP ()» — такой подход упрощает создание инструментов разбора исходных файлов справочных страниц) .SS "Использование семантики новых строк" .\" 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. .SS Списки There are different kinds of lists: .TP Tagged paragraphs These are used for a list of tags and their descriptions. When the tags are constants (either macros or numbers) they are in bold. Use the \fB.TP\fP macro. .IP An example is this "Tagged paragraphs" subsection is itself. .TP Ordered lists Elements are preceded by a number in parentheses (1), (2). These represent a set of steps that have an order. .IP When there are substeps, they will be numbered like (4.2). .TP Positional lists Elements are preceded by a number (index) in square brackets [4], [5]. These represent fields in a set. The first index will be: .IP .RS .PD 0 .TP \fB0\fP When it represents fields of a C data structure, to be consistent with arrays. .TP \fB1\fP When it represents fields of a file, to be consistent with tools like \fBcut\fP(1). .PD .RE .TP Alternatives list Elements are preceded by a letter in parentheses (a), (b). These represent a set of (normally) exclusive alternatives. .TP Bullet lists Elements are preceded by bullet symbols (\fB\e[bu]\fP). Anything that doesn't fit elsewhere is usually covered by this type of list. .TP Numbered notes Not really a list, but the syntax is identical to "positional lists". .PP .\" 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. .SS "Общие соглашения по оформлению" Параграфы должны разделяться подходящими маркерами (обычно \fI.PP\fP или \&\fI.IP\fP). \fIНе\fP разделяйте параграфы пробельными строками, так как это приводит к плохому отображению в некоторых выходных форматах (в частности, PostScript и PDF). .PP Имена файлов (также пути или ссылки на заголовочные файлы) всегда должны быть оформлены курсивом (например, \fI\fP), кроме раздела ОБЗОР, где включаемые файлы должны быть полужирным (например, \fB#include \fP). Тут ссылка на стандартный заголовочный файл включает имя заголовочного файл, окружённого угловыми скобками, это типично для C (например, \fI\fP). .PP Специальные макросы, которые обычно находятся в верхнем регистре, оформляют полужирным (например, \fBMAXINT\fP). Исключение: не делайте полужирным NULL. .PP В списке, при перечислении кодов ошибок, коды оформляют полужирным (в этом списке обычно используют макрос \fB\&.TP\fP). .PP Составные команды, если они длинные, должны быть записаны с отступом по линии, как самодостаточные, с пустой строкой перед и после команды, например .PP .in +4n .EX man 7 man\-pages .EE .in .PP If the command is short, then it can be included inline in the text, in italic format, for example, \fIman 7 man\-pages\fP. In this case, it may be worth using nonbreaking spaces (\e[ti]) at suitable places in the command. Command options should be written in italics (e.g., \fI\-l\fP). .PP Выражения, если не записаны на отдельной строке с отступом, должны выделяться курсивом. Здесь также может потребоваться задавать неразрывные пробелы, если выражение встроено в обычный текст. .PP При показе примера сеанса оболочки пользовательский ввод должен быть выделен жирным, например .PP .in +4n .EX $ \fBdate\fP Thu Jul 7 13:01:27 CEST 2016 .EE .in .PP Все ссылки на другие справочные страницы должны выделяться жирным шрифтом, \fIвсегда\fP должен быть указан номер раздела шрифтом Roman (обычным) и без пробелов (например, \fBintro\fP(2)). В исходном файле это лучше записывать так: .PP .EX .BR intro (2) .EE .PP (включение номера раздела в перекрёстных ссылках позволяет таким инструментам как \fBman2html\fP(1) создавать правильные гиперссылки между страницами) .PP Control characters should be written in bold face, with no quotes; for example, \fB\[ha]X\fP. .SS Орфография Начиная с версии \fIman\-pages\fP следует при написании Американским соглашениям (до этого использовалось английское и американское написание); пишите новые страницы и присылайте заплаты с учётом этих соглашений. .PP Кроме известных различий в написании, есть несколько других тонкостей, которые следует учесть: .IP \[bu] 3 Американский вариант английского языка имеет обыкновение использовать формы «backward» (назад), «upward» (вверх), «toward» (к) и т. д., а в британском варианте это «backwards», «upwards», «towards» и т. д. .IP \[bu] Opinions are divided on "acknowledgement" vs "acknowledgment". The latter is predominant, but not universal usage in American English. POSIX and the BSD license use the former spelling. In the Linux man\-pages project, we use "acknowledgement". .SS "Номера версий BSD" Классической схемой обозначения версий BSD является \fIx.yBSD\fP, где \fIx.y\fP \- номер версии (например, 4.2BSD). Избегайте написания в стиле \fIBSD 4.3\fP. .SS "Печать заглавными буквами" В заголовках разделов («SS») начинайте первое слово заголовка с заглавной буквы, а остальные буквы должны быть строчными, если обратного не требуют правила английского языка (например, имён собственных) или языка программирования (например, идентификаторы имён). Пример: .PP .in +4n .EX \&.SS Unicode under Linux .EE .in .\" .SS "Отступ при определении структур, содержимого журналов сеансов оболочек и т. п." 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 \fI.in\ +4n\fP and \fI.in\fP), format them using the \fI.EX\fP and \fI.EE\fP macros, and surround them with suitable paragraph markers (either \fI.PP\fP or \fI.IP\fP). For example: .PP .in +4n .EX \&.PP \&.in +4n \&.EX int main(int argc, char *argv[]) { return 0; } \&.EE \&.in \&.PP .EE .in .SS "Предпочтительные термины" В следующей таблице перечислены некоторые предпочтительные термины, для использования в справочных страницах, главным образом, для непротиворечивости информации на страницах. .ad l .TS l l l --- l l ll. Термин (перевод) Не используйте Примечания bit mask (маска битов) bitmask built\-in (встроенный) builtin Epoch (эпоха) epoch T{ Эпоха UNIX (00:00:00, 1 января 1970 UTC) T} 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 (привилегированный порт) T{ reserved port, system port T} real\-time (реальное время) T{ realtime, real time T} run time (время исполнения) runtime saved set\-group\-ID (сохранённый set\-group\-ID) T{ saved group ID, saved set\-GID T} saved set\-user\-ID (сохранённый saved set\-user\-ID) T{ saved user ID, saved set\-UID T} set\-group\-ID set\-GID, setgid set\-user\-ID set\-UID, setuid superuser (суперпользователь) T{ super user, super\-user T} superblock (суперблок) T{ super block, super\-block T} символьная ссылка symlink timestamp (метка времени) time stamp timezone (часовой пояс) time zone uppercase (прописные) upper case, upper\-case usable (приемлемый) useable user space (пространство пользователя) userspace username (имя пользователя) user name x86\-64 x86_64 T{ Кроме случая, когда ссылаются на результат «uname\ \-m» или подобных T} zeros (нули) zeroes .TE .PP Смотрите также \fIДефисы в составных терминах\fP далее. .SS "Термины, которых следует избегать" В следующей таблице перечислены некоторые термины, которые лучше не использовать в справочных страницах и предлагаемые им альтернативы, использование которых поможет избежать противоречий между справочными страницами. .ad l .TS l l l --- l l l. Не используйте Для использования Примечания 32bit 32\-bit (32\-битный) T{ это же с 8\-bit, 16\-bit и т. п. T} current process (текущий процесс) calling process (вызывающий процесс) T{ Частая ошибка, делаемая программистами ядра при написании справочных страниц T} manpage T{ man page, manual page (справочная страница) T} 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) .TE .ad .\" .SS "Торговые марки" При упоминании торговых марок соблюдайте правильное написание с соблюдением регистра. Вот список правильного написания различных торговых марок, которые иногда указывают неправильно: .IP .TS l. DG/UX HP\-UX UNIX UnixWare .TE .SS "NULL, NUL, null pointer, and null byte" A \fInull pointer\fP is a pointer that points to nothing, and is normally indicated by the constant \fINULL\fP. On the other hand, \fINUL\fP is the \fInull byte\fP, a byte with the value 0, represented in C via the character constant \fI\[aq]\e0\[aq]\fP. .PP Данный указатель лучше называть «указатель null» или просто «NULL»; не используйте «указатель NULL». .PP Для описания байта используйте «байт null». Не пишите «NUL», так как такое наименование легко спутать с «NULL». Также избегайте терминов «нулевой байт» и «символ null». Байт, которым заканчиваются строки в C, нужно описывать как «завершающий байт null» (terminating null byte); про строки можно сказать как «завершающиеся null» (null\-terminated), но не используйте «завершающиеся NUL». .SS Гиперссылки Для указания гиперссылок используйте пару макросов \fI.UR\fP/\fI.UE\fP (смотрите \fBgroff_man\fP(7)). Они создаёт корректные гиперссылки, которые можно использовать при просмотре в браузере, например так: .PP .in +4n .EX BROWSER=firefox man \-H pagename .EE .in .SS "Использование сокращений e.g. (например), i.e. (т. е.), a.k.a. (также известно как) и подобных" 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"). .PP Единственным приемлемым местом для их использования является \fIкороткая\fP сноска (как, напр., эта). .PP Всегда указывайте точки в подобных аббревиатурах. Также после «напр.р» и «т.е.» всегда ставится запятая. .SS "Длинное тире" The way to write an em\-dash\[em]the glyph that appears at either end of this subphrase\[em]in *roff is with the macro "\e[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 \fIwithout\fP surrounding spaces. .SS "Дефисы в составных терминах" Составные термины пишутся через дефис при использовании в качестве определителя (т. е., для уточнения последующего существительного). Примеры: .IP .TS l. 32\-bit value command\-line argument floating\-point number run\-time check user\-space function wide\-character string .TE .SS "Дефис с multi, non, pre, re, sub и т. п." Общая тенденция на современном английском языке состоит в том, чтобы не ставить дефисы после префиксов «multi», «non», «pre», «re», «sub» и т. д. В справочных страницах, в основном, нужно следовать этому правилу, когда эти префиксы используются в естественных английских конструкциях с простыми суффиксами. В следующем списке приведены некоторые примеры правильного написания: .IP .TS l. interprocess multithreaded multiprocess nonblocking nondefault nonempty noninteractive nonnegative nonportable nonzero preallocated precreate prerecorded reestablished reinitialize rearm reread subcomponent subdirectory subsystem .TE .PP Дефисы должны быть сохранены после префиксов для нестандартных английских слов, торговых марок, имён собственных, акронимов или составных терминов. Несколько примеров: .IP .TS l. non\-ASCII non\-English non\-NULL non\-real\-time .TE .PP .\" И напоследок заметим, что «re\-create» и «recreate» — это два различных глагола и первый, вероятно то, что нужно. .SS "Generating optimal glyphs" Если требуется символ математического минуса (например, для чисел (\-1), перекрёстных ссылок справочных страниц (\fButf\-8\fP(7) или при записи параметров, у которых есть начальные тире (\fIls\ \-l\fP)), используйте следующую форму записи в справочной странице: .PP .in +4n .EX \e\- .EE .in .PP Это правило применимо и в примерах кода. .PP .\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/ The use of real minus signs serves the following purposes: .IP \[bu] 3 To provide better renderings on various targets other than ASCII terminals, notably in PDF and on Unicode/UTF\-8\-capable terminals. .IP \[bu] To generate glyphs that when copied from rendered pages will produce real minus signs when pasted into a terminal. .PP To produce unslanted single quotes that render well in ASCII, UTF\-8, and PDF, use "\e[aq]" ("apostrophe quote"); for example .PP .in +4n .EX \e[aq]C\e[aq] .EE .in .PP где \fIC\fP — символ в кавычках. Это правило применимо и в примерах кода. .PP Where a proper caret (\[ha]) that renders well in both a terminal and PDF is required, use "\e[ha]". This is especially necessary in code samples, to get a nicely rendered caret when rendering to PDF. .PP .\" Using a naked "\[ti]" character results in a poor rendering in PDF. Instead use "\e[ti]". This is especially necessary in code samples, to get a nicely rendered tilde when rendering to PDF. .SS "Примеры программ и сценариев оболочки" Справочные страницы могут включать примеры программ, демонстрирующие использование системных вызовов или библиотечных функций. При этом нужно учитывать ряд условий: .IP \[bu] 3 Примеры программ должны быть написаны на языке C. .IP \[bu] Примеры программ необходимы и полезны лишь в тех случаях, когда они демонстрируют что\-то сверх того, что может быть легко представлено в текстовом описании командного интерфейса. Примеры программ, которые не показывают ничего кроме вызова команды, как правило обладают незначительной полезностью. .IP \[bu] Example programs should ideally be short (e.g., a good example can often be provided in less than 100 lines of code), though in some cases longer programs may be necessary to properly illustrate the use of an API. .IP \[bu] Expressive code is appreciated. .IP \[bu] Comments should included where helpful. Complete sentences in free\-standing comments should be terminated by a period. Periods should generally be omitted in "tag" comments (i.e., comments that are placed on the same line of code); such comments are in any case typically brief phrases rather than complete sentences. .IP \[bu] В примерах программ должна быть реализована проверка ошибок после системных вызовов и вызовов библиотечных функций. .IP \[bu] Примеры программ должны быть полными и компилироваться без предупреждений при использовании \fIcc\ \-Wall\fP. .IP \[bu] Там, где это возможно и целесообразно, примеры программ должны демонстрировать эксперимент, изменяя свое поведение в зависимости от входных параметров (в идеале от параметров командной строки или получаемых программой через стандартный ввод). .IP \[bu] Примеры программ должны быть написаны в стиле Кернигана (Kernighan) и Ритчи (Ritchie), с отступом, состоящим из 4 пробелов. (Избегайте использования символа табуляции в исходном коде!) Следующие команды могут быть использованы для форматирования исходного кода в что\-то близкое к предпочтительному стилю: .IP .in +4n .EX indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c .EE .in .IP \[bu] Для удобства восприятия, все программы должны завершаться с использованием одного из вариантов: .IP .in +4n .EX exit(EXIT_SUCCESS); exit(EXIT_FAILURE); .EE .in .IP Избегайте использования следующих форм завершения программы: .IP .in +4n .EX exit(0); exit(1); return n; .EE .in .IP \[bu] В случаях, когда примеру программы предшествует обширный пояснительный текст, определите код в подраздел и пометьте соответствующим заголовком \fIКод программы\fP, как показано ниже: .IP .in +4n .EX \&.SS Program source .EE .in .IP Всегда делайте это, если пояснительный текст включает примеры вывода в терминал. .PP Если включаете лог вывода в терминал, демонстрирующий использование программы или системной функции: .IP \[bu] 3 Place the session log above the source code listing. .IP \[bu] Обозначьте лог терминала четырьмя пробелами. .IP \[bu] Выделите полужирным вводимый пользователем текст, чтобы отличить его от вывода системы. .PP Ознакомиться с тем, как должны выглядеть примеры программ Вы можете, прочитав \fBwait\fP(2) и \fBpipe\fP(2). .SH ПРИМЕРЫ В качестве канонического примера того, как должны выглядеть страницы в пакете \fIman\-pages\fP, смотрите \fBpipe\fP(2) и \fBfcntl\fP(2). .SH "СМ. ТАКЖЕ" \fBman\fP(1), \fBman2html\fP(1), \fBattributes\fP(7), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7), \fBmdoc\fP(7) .PP .SH ПЕРЕВОД Русский перевод этой страницы руководства был сделан aereiae , Alexey , Azamat Hackimov , Dmitriy S. Seregin , Dmitry Bolkhovskikh , ITriskTI , Max Is , Yuri Kozlov , Иван Павлов и Малянов Евгений Викторович . .PP Этот перевод является бесплатной документацией; прочитайте .UR https://www.gnu.org/licenses/gpl-3.0.html Стандартную общественную лицензию GNU версии 3 .UE или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ. .PP Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на .MT man-pages-ru-talks@lists.sourceforge.net .ME .