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

Обязательными разделами должны быть следующие разделы страниц руководства:

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

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

Раздел 2 Системные вызовы

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

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

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

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

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

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

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

Раздел 6 Игры

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

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

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

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

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

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

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

Соглашения о форматах исходных файлов¶

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

Титульная строка¶

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

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

title - титульная строка

Титульная строка должна содержать наименование данной страницы руководства.

section - раздел

Номер раздела, в котором должна быть размещена данная страницы руководства (например, 7).

date - дата

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

source - источник

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

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

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

Внутренние разделы страницы руководства¶

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

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

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

НАИМЕНОВАНИЕ

Здесь должно быть приведено наименование данной страницы руководства (важные подробности о требованиях к тексту в этом разделе см. в man(7)) .

See man(7) for important details of the line(s) that should follow the .SH NAME command. All words in this line (including the word immediately following the "\-") should be in lowercase, except where English or technical terminological convention dictates otherwise.

БИБЛИОТЕКА

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

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

СТАНДАРТЫ

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

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

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

Если интерфейс прикладного программирования не соответствует никакому стандарту, но существует во множестве систем, то об этом также должно быть сообщено. Если данный вызов является специфичным для 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) должны быть указаны в этом разделе, а не в разделе СТАНДАРТЫ.

ПРИМЕЧАНИЯ

Этот раздел должен содержать различные примечания.

For Section 2 and 3 man pages you may find it useful to include subsections (SS) named Linux Notes and glibc Notes.

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

ПРЕДУПРЕЖДЕНИЯ

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

ПРОГРАММНЫЕ ОШИБКИ

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

ПРИМЕРЫ

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

For details on writing example programs, see Example programs below.

АВТОРЫ

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

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

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

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

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

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

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

Этот раздел должен содержать, разделённый запятыми список, дополнительных страниц руководства или иных документов, на которые имеются ссылки в данной странице руководства.

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

Если список СМОТРИТЕ ТАКЖЕ содержит много длинных названий страниц руководства, то для улучшения визуального представления может быть полезно воспользоваться командами .ad l (don't right justify) и .nh (don't hyphenate). Предотвратить перенос слов в названиях отдельных страниц руководства можно, добавив перед ними символы "\%".

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

СИНОПСИС¶

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

При предварительном объявлении параметров в функциях не следует выделять их жирным шрифтом или курсивом; это помогает визуально отличить их от реальных параметров, например:

int snprintf(size_t size;
             char str[restrict size], size_t size,
             const char *restrict format, ...);

В общем случае, если в разделе СИНОПСИС перечислено более одного образца функции, то эти образцы не должны разделяться пустыми строками. Однако пустые строки могут быть добавлены (с помощью .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 для указания на ошибку" или что-то подобное. Эта формулировка соответствует формулировке, используемой как в POSIX.1, так и в FreeBSD.

АТРИБУТЫ¶

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

•

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

•

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

•

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

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

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

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

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

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

Наименование команды и её опции всегда должны быть выделены полужирным шрифтом.

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

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

int myfunction(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 pointer) — это указатель, который ни на что не указывает и, как правило, обозначается константой NULL. С другой стороны, NUL представляет собой нулевой байт (null byte), байт со значением 0, который в Си представляется символьной константой '\0'.

Данный указатель лучше называть «указатель нуля» (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 pagename

Использование сокращений 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.» всегда ставится запятая.

Длинное тире¶

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

Дефисы в составных терминах¶

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

значение 32 бита (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)

неотрицательный (noninteractive)

непереносимый (nonportable)

nonzero - ненулевой

предварительно выделенный (preallocated)

предварительно созданный (precreate)

предварительно записанный (prerecorded)

восстановленный (reestablished)

повторно инициализировать (reinitialize)

переустановить (rearm)

перечитать (reread)

подкомпонент (subcomponent)

подкаталог (subdirectory)

подсистема (subsystem)

Дефисы должны быть сохранены после префиксов для нестандартных английских слов, торговых марок, имён собственных, сокращений или составных терминов. Несколько примеров:

не ASCII (non-ASCII)

не английский (non-English)

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

•

Желательно иметь понятный код.

•

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

•

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

•

Примеры программ должны быть полными и компилироваться без предупреждений при использовании 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 Program source
    

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

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

•

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

•

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

•

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

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