--- description: 'Как работать со Cправочником FreeBSD' next: books/fdp-primer/writing-style params: path: /books/fdp-primer/manual-pages/ prev: books/fdp-primer/weblate showBookMenu: true tags: ["manual pages", "introduction", "guide", "reference"] title: 'Глава 11. Справочник' weight: 11 --- [[manual-pages]] = Справочник :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 11 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[manual-pages-introduction]] == Введение _Справочник_, часто сокращаемый до _man-страниц_, изначально задумывались как легкодоступные напоминания о синтаксисе команд, деталях драйверов устройств или форматах конфигурационных файлов. Со временем они стали крайне полезным справочным материалом для быстрого ознакомления прямо из командной строки для пользователей, системных администраторов и программистов. Хотя они предназначены скорее как справочные материалы, а не учебные руководства, разделы EXAMPLES в manual pages часто содержат подробные примеры использования. Страницы Справочника обычно отображаются интерактивно с помощью команды man:man[1]. Когда пользователь вводит `man ls`, выполняется поиск страницы Справочника, соответствующей `ls`. Первый найденный результат отображается. [[manual-pages-sections]] == Разделы Страницы справочника (man-страницы) сгруппированы по _разделам_. Каждый раздел содержит man-страницы для определённой категории документации: [.informaltable] [cols="1,8", options="header"] |=== | Номер раздела | Категория |1 |Общие команды |2 |Системные вызовы |3 |Функции библиотек |4 |Интерфейсы ядра |5 |Форматы файлов |6 |Игры |7 |Разное |8 |Системный администратор |9 |Разработчик ядра |=== [[manual-pages-markup]] == Язык разметки Для man-страниц использовались различные формы разметки и программы отображения. FreeBSD использовала man:groff[7] и более новую man:mandoc[1]. Большинство существующих man-страниц FreeBSD, а также все новые, используют разметку в формате man:mdoc[7]. Это простая построчная разметка, обладающая достаточной выразительностью. В основном она семантическая: части текста помечаются по их назначению, а не по тому, как они должны выглядеть при отображении. Существует некоторая разметка, основанная на внешнем виде, которую обычно лучше избегать. Исходный код страницы справочника обычно интерпретируется и отображается на экране в интерактивном режиме. Исходные файлы могут быть обычными текстовыми файлами или сжатыми с помощью man:gzip[1] для экономии места. Страницы справочника также могут быть преобразованы в другие форматы, включая PostScript для печати или генерации PDF. См. man:man[1]. [[manual-pages-markup-sections]] === Разделы Справочника Страницы справочника состоят из нескольких стандартных разделов. Каждый раздел имеет заголовок в верхнем регистре, а разделы для определённого типа man-страниц следуют в строго определённом порядке. Для man-страниц категории 1 (Общие команды) разделы идут в следующем порядке: [.informaltable] [cols="2,4", options="header"] |=== | Название Раздела | Описание |NAME (ИМЯ) |Название команды |SYNOPSIS (СИНТАКСИС) |Формат опций и аргументов |DESCRIPTION (ОПИСАНИЕ) |Описание назначения и использования |ENVIRONMENT (ОКРУЖЕНИЕ) |Настройки окружения, влияющие на работу |EXIT STATUS (СТАТУС ВЫХОДА) |Коды ошибок, возвращаемые при завершении |EXAMPLES (ПРИМЕРЫ) |Примеры использования |COMPATIBILITY (СОВМЕСТИМОСТЬ) |Совместимость с другими реализациями |SEE ALSO (СМ. ТАКЖЕ) |Перекрестная ссылка на связанные страницы руководства |STANDARDS (СТАНДАРТЫ) |Совместимость со стандартами, такими как POSIX |HISTORY (ИСТОРИЯ) |История реализации |BUGS (ИЗВЕСТНЫЕ ОШИБКИ) |Известные ошибки |AUTHORS (АВТОРЫ) |Люди, которые создали команду или написали справочную страницу. |=== Некоторые разделы являются необязательными, и сочетание разделов для конкретного типа справочной страницы может различаться. Примеры наиболее распространённых типов приведены далее в этой главе. [[manual-pages-markup-macros]] === Макросы Разметка man:mdoc[7] основана на _макросах_. Строки, начинающиеся с точки, содержат макрокоманды, каждая длиной в две или три буквы. Например, рассмотрим эту часть man-страницы man:ls[1]: [.programlisting] .... .Dd December 1, 2015 <.> .Dt LS 1 .Sh NAME <.> .Nm ls .Nd list directory contents .Sh SYNOPSIS <.> .Nm <.> .Op Fl -libxo <.> .Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, <.> .Op Fl D Ar format <.> .Op Ar <.> .Sh DESCRIPTION <.> For each operand that names a .Ar file of a type other than directory, .Nm displays its name as well as any requested, associated information. For each operand that names a .Ar file of type directory, .Nm displays the names of files contained within that directory, as well as any requested, associated information. .... <.> Определены _Дата документа_ (.Dd) и _Название документа_ (.Dt). <.> Для раздела NAME определяется _Заголовок раздела_ (.Sh). Затем определяется _Имя_ (.Nm) команды и _Описание имени_ (.Nd) в одну строку. <.> Начинается раздел SYNOPSIS (.Sh). В этом разделе описываются параметры командной строки и аргументы, которые принимаются. <.> _Имя_ (`.Nm`) уже определено, и его повторение здесь просто отображает заданное значение в тексте. <.> Отображается _необязательный_ _флаг_ (.Op Fl) `-libxo`. Макрос `Fl` добавляет тире в начало флагов, поэтому в руководстве он отображается как `--libxo`. <.> Отображается длинный список необязательных флагов, состоящих из одного символа. <.> Определён необязательный флаг `-D`. Если указан флаг `-D`, за ним должен следовать _аргумент_. Аргумент представляет собой _формат_ — строку, которая указывает man:ls[1], что и как отображать. Подробности о строке формата приведены далее на странице руководства. <.> Определен последний необязательный аргумент. Поскольку для аргумента не указано имя, используется значение по умолчанию `file ...`. <.> _Заголовок раздела_ (.Sh) для раздела DESCRIPTION определен. При отображении с помощью команды `man ls` результат выводится на экран следующим образом: [.programlisting] .... LS(1) FreeBSD General Commands Manual LS(1) NAME ls - list directory contents SYNOPSIS ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format] [file ...] DESCRIPTION For each operand that names a file of a type other than directory, ls displays its name as well as any requested, associated information. For each operand that names a file of type directory, ls displays the names of files contained within that directory, as well as any requested, associated information. .... Необязательные значения указаны в квадратных скобках. [[manual-pages-markup-guidelines]] === Руководство по разметке Язык разметки man:mdoc[7] не является очень строгим. Для ясности и согласованности проект FreeBSD Documentation добавляет некоторые дополнительные рекомендации по стилю: Только первая буква макросов пишется с заглавной буквы:: Всегда используйте заглавную букву для первого символа макроса и строчные буквы для остальных символов. Начинайте новые предложения с новых строк:: Начинайте новое предложение с новой строки, не начинайте его на той же строке, что и существующее предложение. Обновите `.Dd` при внесении значительных изменений в справочную страницу:: _Дата документа_ сообщает читателю, когда страница руководства была последний раз обновлена. Важно обновлять её при внесении значительных изменений в страницы руководства. Незначительные правки, такие как исправления орфографии или пунктуации, которые не влияют на использование, могут быть сделаны без обновления `.Dd`. Приведите примеры:: Показывайте читателю примеры, когда это возможно. Даже простые примеры ценны, потому что то, что тривиально для автора, не обязательно тривиально для читателя. Хорошей целью являются три примера. Простой пример демонстрирует минимальные требования, серьезный пример показывает реальное использование, а углубленный пример демонстрирует неочевидную или нестандартную функциональность. Включить лицензию BSD:: Включите лицензию BSD в новые руководства. Предпочтительная лицензия доступна в extref:{committers-guide}[Руководстве коммиттера]. [[manual-pages-markup-tricks]] === Приемы Разметки Добавьте пробел перед пунктуацией на строке с макросами. Пример: [.programlisting] .... .Sh SEE ALSO .Xr geom 4 , .Xr boot0cfg 8 , .Xr geom 8 , .Xr gptboot 8 .... Обратите внимание, как запятые в конце строк `.Xr` размещены после пробела. Макрос `.Xr` ожидает два параметра: имя внешней страницы руководства и номер раздела. Пробел отделяет пунктуацию от номера раздела. Без пробела внешние ссылки будут некорректно указывать на разделы `4,` или `8,`. [[manual-pages-markup-important-macros]] === Важные макросы Здесь будут показаны некоторые очень распространённые макросы. Для большего количества примеров использования см. man:mdoc[7], man:groff_mdoc[7] или выполните поиск реальных примеров в каталогах [.filename]#/usr/share/man/man*#. Например, чтобы найти примеры макроса `.Bd` (_Begin display_): [source, shell] .... % find /usr/share/man/man* | xargs zgrep '.Bd' .... [[manual-pages-markup-important-macros-organizational]] ==== Организационные Макросы Некоторые макросы используются для определения логических блоков страницы руководства. [.informaltable] [cols="1,8", options="header"] |=== | Организационные Макро | Используйте |`.Sh` |Заголовок раздела. За ним следует название раздела, традиционно записанное в верхнем регистре. Можно рассматривать их как названия глав. |`.Ss` |Подзаголовок раздела. За ним следует название подраздела. Используется для разделения раздела `.Sh` на подразделы. |`.Bl` |Начало списка (Begin list). Начать перечень элементов. |`.El` |Конец списка (End List). |`.Bd` |Начало отображения (Begin display). Начать специальную область текста, например, область с отступом. |`.Ed` |Завершить отображение (End display). |=== [[manual-pages-markup-important-macros-inline]] ==== Встроенные макросы Многие макросы используются для разметки текста внутри строк. [.informaltable] [cols="1,8", options="header"] |=== | Встроенный макрос | Используйте |`.Nm` |Имя (Name). При первом использовании вызывается с именем в качестве параметра, затем используется без параметра для отображения уже определенного имени. |`.Pa` |Путь к файлу (Path to a file). Используется для обозначения имен файлов и путей к каталогам. |=== [[manual-pages-sample-structures]] == Пример структуры страницы руководства Этот раздел демонстрирует минимально желаемое содержание man-страниц для нескольких распространённых категорий руководств. [[manual-pages-sample-structures-section-1-8]] === Раздел 1 или 8 — Команда Предпочтительная базовая структура для раздела 1 или 8 — Команда: [.programlisting] .... .Dd August 25, 2017 .Dt EXAMPLECMD 8 .Os .Sh NAME .Nm examplecmd .Nd "command to demonstrate section 1 and 8 man pages" .Sh SYNOPSIS .Nm .Op Fl v .Sh DESCRIPTION The .Nm utility does nothing except demonstrate a trivial but complete manual page for a section 1 or 8 command. .Sh SEE ALSO .Xr exampleconf 5 .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com .... [[manual-pages-sample-structures-section-4]] === Раздел 4 — Драйверы устройств Предпочтительная базовая структура для раздела 4 — драйверы устройств: [.programlisting] .... .Dd August 25, 2017 .Dt EXAMPLEDRIVER 4 .Os .Sh NAME .Nm exampledriver .Nd "driver to demonstrate section 4 man pages" .Sh SYNOPSIS To compile this driver into the kernel, add this line to the kernel configuration file: .Bd -ragged -offset indent .Cd "device exampledriver" .Ed .Pp To load the driver as a module at boot, add this line to .Xr loader.conf 5 : .Bd -literal -offset indent exampledriver_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides an opportunity to show a skeleton or template file for section 4 manual pages. .Sh HARDWARE The .Nm driver supports these cards from the aptly-named Nonexistent Technologies: .Pp .Bl -bullet -compact .It NT X149.2 (single and dual port) .It NT X149.8 (single port) .El .Sh DIAGNOSTICS .Bl -diag .It "flashing green light" Something bad happened. .It "flashing red light" Something really bad happened. .It "solid black light" Power cord is unplugged. .El .Sh SEE ALSO .Xr example 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 49.2 . .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com .... [[manual-pages-sample-structures-section-5]] === Раздел 5 — Файл конфигурации Предпочтительная базовая структура для раздела 5 — файл конфигурации: [.programlisting] .... .Dd August 25, 2017 .Dt EXAMPLECONF 5 .Os .Sh NAME .Nm example.conf .Nd "config file to demonstrate section 5 man pages" .Sh DESCRIPTION .Nm is an example configuration file. .Sh SEE ALSO .Xr example 8 .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com .... [[manual-pages-testing]] == Тестирование Проверка новой страницы руководства может быть непростой задачей. К счастью, существуют инструменты, которые могут помочь в этом. Некоторые из них, например man:man[1], не ищут в текущем каталоге. Хорошей практикой является добавление префикса `./` к имени файла, если новая страница руководства находится в текущем каталоге. Также можно использовать абсолютный путь. Используйте линтер man:mandoc[1] для проверки на ошибки парсинга: [source, shell] .... % mandoc -T lint ./mynewmanpage.8 .... Используйте package:textproc/igor[] для проверки страниц Справочника: [source, shell] .... % igor ./mynewmanpage.8 .... Еще один полезный инструмент — package:textproc/vale[]. Он не поддерживает синтаксис man:mdoc[7], но обработанную страницу руководства можно прочитать из стандартного ввода: [source, shell] .... % man ls | vale .... package:textproc/vale[] обладает высокой степенью настраиваемости. Рекомендуется ознакомиться с его документацией. Используйте man:man[1] для проверки конечного результата ваших изменений: [source, shell] .... % man ./mynewmanpage.8 .... Вы можете использовать man:col[1] для фильтрации вывода man:man[1] и удаления backspace-символов перед загрузкой результата в ваш любимый редактор для проверки орфографии: [source, shell] .... % man ./mynewmanpage.8 | col -b | vim -R - .... Проверка орфографии с использованием полнофункциональных словарей рекомендуется и может быть выполнена с помощью package:textproc/hunspell[] или package:textproc/aspell[] в сочетании с package:textproc/en-hunspell[] или package:textproc/en-aspell[] соответственно. Например: [source, shell] .... % aspell check --lang=en --mode=nroff ./mynewmanpage.8 .... [[manual-pages-examples-as-templates]] == Примеры страниц Справочника для использования в качестве шаблонов Некоторые страницы Справочника могут служить подробными примерами. [.informaltable] [cols="1,4", options="header"] |=== | Страница Справочника | Путь к расположению исходного кода |man:cp[1] |[.filename]#/usr/src/bin/cp/cp.1# |man:vt[4] |[.filename]#/usr/src/share/man/man4/vt.4# |man:crontab[5] |[.filename]#/usr/src/usr.sbin/cron/crontab/crontab.5# |man:gpart[8] |[.filename]#/usr/src/sbin/geom/class/part/gpart.8# |=== [[manual-pages-resources]] == Ресурсы Ресурсы для авторов справочных страниц: * man:man[1] * man:mandoc[1] * man:style.mdoc[5] * man:groff_mdoc[7] * http://manpages.bsd.lv/mdoc.html[Практические руководства UNIX: mdoc] * http://manpages.bsd.lv/history.html[История man-страниц UNIX]