Разделы справочных страниц¶

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

1 Команды пользователя (Программы)

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

2 Системные вызовы

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

3 Библиотечные вызовы

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

4 Специальные файлы (устройства)

Файлы из /dev, дающие доступ к устройствам через ядро.

5 Форматы файлов и конфигурационные файлы

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

6 Игры

Игры и небольшие забавные программы, доступные в системе.

7 Обзоры, соглашения и разное

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

8 Команды для системного администрирования

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

Пакет макросов¶

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

Правила, касающиеся формата исходных файлов¶

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

Заголовок¶

Первой должна быть команда TH:

Аргументы этой команды следующие:

заголовок

Название страницы, написанное заглавными буквами (например MAN-PAGES).

раздел

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

дата

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

источник

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

раздел-руководства

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

Разделы внутри справочной страницы¶

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

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

В приведённом ниже списке объясняется назначение каждого из разделов.

NAME

Название данной справочной страницы.

Смотрите man(7), чтобы ознакомиться с правилами написания заголовков, которые должны идти после команды .SH NAME. Все слова в этой строке (в том числе идущие сразу после «\-») должны быть в нижнем регистре, за исключением тех случаев, когда правилами языка, на котором написана страница, или сложившейся практикой употребления технических терминов определено иное.

БИБЛИОТЕКА

Библиотека, предоставляющая символ.

Здесь записывается общеупотребимое имя библиотеки, её имя файла (в скобках) и, если необходимо, флаги компоновщика, необходимые для сборки программы с этой библиотекой: (libfoo[, -lfoo]).

ОБЗОР

Краткое описание команды или интерфейса функции.

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

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

КОНФИГУРАЦИЯ

Особенности настройки устройства.

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

ОПИСАНИЕ

Объяснение того, для чего предназначена программа, функция или формат.

Здесь описывается взаимодействие с файлами и стандартным потоком ввода, и что записывается в стандартные потоки вывода или ошибок; детали внутреннего устройства и реализации должны опускаться, если они не критичны для понимания интерфейса; в этом разделе демонстрируется типовое использование; информация о параметрах командной строки программы даётся в разделе ПАРАМЕТРЫ.

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

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

ПАРАМЕТРЫ

Описание параметров командной строки и их влияния на поведение программы.

Этот раздел, как правило, содержится только в справочных страницах Разделов 1 и 8.

КОД ЗАВЕРШЕНИЯ

Перечень возможных значений кода выхода программы и ситуаций, при которых программа возвращает данное значение кода.

Этот раздел, как правило, содержится только в справочных страницах Разделов 1 и 8.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Для страниц из Разделов 2 и 3 данный раздел содержит перечень значений, которые библиотечные подпрограммы возвращают при их вызове, а также условия, которые приводят к возврату этих значений.

ОШИБКИ

В справочных страницах Разделов 2 и 3 здесь описываются значения ошибок, которые могут быть помещены в errno, а также приводится описание причин возникновения этих ошибок.

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

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

ОКРУЖЕНИЕ

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

ФАЙЛЫ

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

Указывайте полный путь к этим файлам, а также используйте возможность скорректировать эти пути в процессе установки в соответствии с предпочтениями пользователя. Многие программы по умолчанию устанавливаются в /usr/local, поэтому ваша страница руководства по умолчанию должна использовать /usr/local в качестве базового каталога.

АТРИБУТЫ

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

ВЕРСИИ

Краткий обзор систем, в которых данный API функционирует по-другому или в которых есть похожие API.

СТАНДАРТЫ

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

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

В данном разделе должны содержаться заметки о том, какому текущему стандарту соответствует данный API.

Если API не соответствует никакому стандарту, но существует во множестве систем, об этом также стоит упомянуть. Если вызов является специфичным для Linux или GNU, то это тоже стоит отметить. Если он доступен только в BSD-системах, отметьте и это.

Если данный раздел состоит только из списка стандартов (как это обычно и бывает), завершите список точкой ('.').

ИСТОРИЯ

Краткие сведения о том, в каких версиях ядра Linux или glibc впервые появился системный вызов или функция библиотеки, либо произошли существенные изменения в их работе.

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

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

Старые версии стандартов (например, SUS, SUSv2 и XPG или стандарты реализаций SVr4 и 4.xBSD) должны упоминаться здесь, а не в разделе СТАНДАРТЫ.

ЗАМЕЧАНИЯ

Различные замечания.

Для страниц в Разделах 2 и 3 может быть полезным создание подразделов (SS), озаглавленных Замечания, касающиеся Linux (Linux notes) и Замечания по glibc (glibc notes).

В Разделе 2 используйте заголовок Отличия между библиотекой C и ядром (C library/kernel differences), чтобы отметить различия (если имеются) между функциями-обёртками в библиотеке Си и интерфейсом системных вызовов, предоставляемым самим ядром.

ОГОВОРКИ

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

ДЕФЕКТЫ

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

ПРИМЕРЫ

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

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

АВТОРЫ

Список авторов документа или программы.

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

ИНФОРМАЦИЯ ОБ ОШИБКАХ

Проект man-pages не использует раздел ИНФОРМАЦИЯ ОБ ОШИБКАХ в своих страницах руководства. Вместо этого информация о том, как сообщать об ошибках, предоставляется в разделе ВЫХОДНЫЕ ДАННЫЕ, который генерируется сценарием. Однако, различные другие проекты используют этот раздел. Рекомендуется размещать его ближе к концу страницы.

АВТОРСКИЕ ПРАВА

Проект man-pages не использует раздел АВТОРСКИЕ ПРАВА в своих страницах руководства. Информация об авторском праве вместо этого поддерживается в исходном коде страницы. На страницах, где этот раздел присутствует, рекомендуется размещать его ближе к концу страницы, прямо перед разделом СМОТРИТЕ ТАКЖЕ.

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

Разделённый запятыми список уместных справочных страниц, возможно, ведущих на другие страницы или документы.

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

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

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

ОБЗОР¶

Оборачивайте прототипы функций в .nf/.fi, чтобы предотвратить переносы строк.

В общем случае, если в разделе ОБЗОР перечислено более одного прототипа функции, эти прототипы не должны разделяться пустыми строками. Однако пустые строки могут быть добавлены (с помощью .P) в следующих случаях:

•

чтобы разделять длинные списки прототипов функций на отдельные взаимосвязанные группы (смотрите, например, list(3));

•

в других случаях, когда это может улучшить читаемость.

В разделе ОБЗОР может потребоваться разделить длинные прототипы функций на несколько строк. В таком случае отступы в строках, перенесённых на следующую строку, расставляются по следующим правилам:

(1)

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

int tcsetattr(int fd, int optional_actions,
              const struct termios *termios_p);

(2)

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

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.

АТРИБУТЫ¶

Также заметим следующее:

•

Оборачивайте таблицы в этом разделе в .ad l/.ad, чтобы предотвратить выравнивание по ширине, а также в .nh/.hy, чтобы предотвратить переносы слов.

•

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

•

Свободно используйте макросы T{/T}, дабы ячейки таблиц могли быть разбиты на несколько строк (при этом учитывайте, что страницы иногда могут отображаться на экранах шириной менее 80 столбцов).

Для примеров всего вышеперечисленного см. исходный код различных страниц.

Использование гендерно-нейтральных выражений¶

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

Соглашения о форматировании справочных страниц, описывающих команды¶

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

Имя команды и её параметры всегда должны быть выделены полужирным.

Соглашения по оформлению справочных страниц, описывающих функции¶

В справочных страницах, которые описывают функции (обычно в Разделах 2 и 3), параметры всегда оформляются, используя курсив; даже в разделе ОБЗОР, где остальная часть функции оформляется полужирным:

int имя_функции(int argc, char **argv);

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

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

    .BR fcntl ()

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

Использование семантических переводов строк¶

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

Списки¶

Существуют разные виды списков:

Помеченные абзацы

Эти списки используются для перечисления меток и их описаний. Когда метки представляют собой константы (макросы или числа), они должны использовать полужирное начертание. Используйте для этого макрос .TP.

Примером является сам данный подраздел «Помеченные абзацы».

Упорядоченные списки

Элементы этих списков предваряются номером (индексом) в круглых скобках: (1), (2). Они представляют собой некий набор пунктов, идущих в определённом порядке.

При наличии подпунктов они будут пронумерованы как (4.2).

Позиционные списки

Элементы этих списков предваряются номером (индексом) в квадратных скобках: [4], [5]. Они представляют собой некие поля в наборе. В качестве начального индекса используется:

Списки альтернатив

Элементы этих списков предваряются буквой в скобках: (а), (б) («(a), (b)»). Они представляют собой набор (обычно) взаимоисключающих альтернатив.

Ненумерованные списки

Элементы этих списков предваряются символом маркера (\[bu]). Все списки, которые не вписываются в другие типы, обычно покрываются этим.

Нумерованные заметки

Эти заметки на самом деле не то чтобы являются списками, но их синтаксис идентичен «позиционным спискам».

Между символом начала пункта списка и самим его содержимым всегда должно быть ровно два пробела. За исключением «помеченных абзацев», которые используют стандартные правила расстановки отступов.

Общие соглашения по оформлению¶

Параграфы должны разделяться соответствующими маркерами (обычно .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 следует американским правилам орфографии (ранее использовалась произвольная смесь британской и американской орфографии); при написании всех новых страниц, а также при правке существующих придерживайтесь этого соглашения.

Кроме известных различий в написании, есть несколько других тонкостей, которые следует учитывать:

•

Американский вариант английского языка имеет обыкновение использовать формы «backward» (назад), «upward» (вверх), «toward» (к) и т. д., а в британском варианте это «backwards», «upwards», «towards» и т. д.

•

Мнения разделились по поводу написания «acknowledgement» или «acknowledgment». Последнее более распространено, но не является абсолютно общепринятым в американском английском. POSIX и лицензия BSD используют первое написание. В проекте Linux man-pages мы используем «acknowledgement».

Номера версий BSD¶

Классической схемой обозначения версий 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

Предпочтительные термины¶

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

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

Термины, которых следует избегать¶

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

Торговые марки¶

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

DG/UX

HP-UX

UNIX

UnixWare

NULL, NUL, указатель null и байт null¶

Указатель 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. (т. е.), a.k.a. (также известный как) и т. п.¶

Обычно лучше не использовать такие сокращения, как «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 и т. п.¶

Общая тенденция в современном английском языке состоит в том, чтобы не ставить дефисы после префиксов «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, в особенности в PDF и на терминалах, поддерживающих Unicode/UTF-8.

•

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

Чтобы получить одинарные кавычки, которые хорошо отображаются и в ASCII, и в UTF-8, используйте «\[aq]» («apostrophe quote», «апострофная кавычка»); например:

\[aq]C\[aq]

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

Когда требуется правильно отображаемый символ карет (^), который будет хорошо смотреться как в терминале, так и в PDF, используйте «\[ha]». Это особенно важно в примерах кода, чтобы получить красивые символы циркумфлекса при выводе в PDF.

Использование голого символа тильды «~» приводит к плохому отображению в PDF. Вместо этого используйте «\[ti]». Это также особенно важно в примерах кода, чтобы получить красивые символы тильды при выводе в PDF.

Примеры программ и сценариев оболочки¶

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

•

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

•

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

•

В идеале примеры программ должны быть краткими (например, хороший пример зачастую можно уложить в менее чем 100 строк кода), хотя в некоторых случаях могут потребоваться и более длинные программы, дабы должным образом проиллюстрировать использование API.

•

Выразительный код приветствуется.

•

Комментарии должны быть добавлены там, где они полезны. Полные предложения в отдельных комментариях должны завершаться точкой. Точки обычно следует опускать в «комментариях-метках» (т. е. комментариях, размещённых на той же строке кода); такие комментарии обычно представляют из себя лишь краткие фразы, а не полные предложения.

•

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

•

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

•

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

•

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

indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
    

•

Ради единообразия и удобства восприятия все программы в примерах должны завершаться с использованием одного из следующих вариантов:

exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
    

Избегайте использования следующих форм завершения программы:

exit(0);
exit(1);
return n;
    

•

Если перед исходным кодом программы имеется обширный пояснительный текст, выделите исходный код с помощью заголовка подраздела «Исходный код программы» (Program source), как показано ниже:

.SS Исходный код программы
    

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

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

•

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

•

Выделите журнал вывода отступом в четыре пробела.

•

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

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