# Справочная система man

% Про опцию `--version`.


## Введение

Невозможно удержать в голове всю необходимую информацию об инструментах и средствах, которые понадобятся при решении задач.
Приобретенный ранее опыт забывается, если не воспользоваться им в течение продолжительного времени.
Помнить подробности не обязательно, если уметь находить нужную информацию.
Огромный массив постоянно обновляемой неструктурированной информации предоставляет веб, а инструментом поиска является поисковые системы `yandex` и `google`.
Система UNIX укомплектована собственной справочной системой с подробной и структурированной информацией о системе и установленных программах.
В отличие от веба, она доступна и без подключения к интернету.

В мире UNIX распространено убеждение, что программа без справки -- это некачественная программа.
Все популярные программы дополнены подробной документацией, в которой пользователи ищут ответы на свои вопросы.
Технические тексты в UNIX написаны разработчиками для разработчиков и отлажены в течение долгих лет.
Их содержание однозначно и лаконично, что заставляет читать документацию неспешно и вдумчиво.
В среде русскоязычных пользователей процесс изучения документации UNIX описывают выражением "курить маны", где под словом "ман" подразумевают утилиту `man`, используемую для работы со справочной системой.

*Краткую информацию* о себе любая консольная программа выдает самостоятельно, если запустить ее с опцией `--help`, `-h` или `-help`.
Ту же самую информацию программа распечатает, если аргументов команды не хватает или они оформлены неверно:

```console
[skt@machine ~]$ grep
Usage: grep [OPTION]... PATTERN [FILE]...
Try `grep --help' for more information.
```

В краткой информации обычно содержится версия исполняемого файла и описание опций и аргументов.
Многофункциональные утилиты как `bash`, `python`, `git` обладают более обширным описанием.
Такой объем текста следует структурировать (разбивать на разделы, выделять заголовки, ставить ссылки), искать по нему и перемещаться.
Поэтому *дополнительная справочная информация* поставляется отдельно и обслуживается справочной системой.


## О справочной системе `man`

В системе UNIX наиболее популярна справочная система `man`.
Название системы и одноименной утилиты произошло от сокращения английского слова "manual", что в переводе значит "справочник", "руководство".
Формат вызова утилиты выглядит как `man [опции] [раздел] заголовок`.
Команда находит и отображает на экране справочную страницу, связанную с переданным ей аргументом-заголовком.
Так, команда `man pwd` отобразит на экране справку об утилите `pwd`, а команда `man bash` -- о командном интерпретаторе `bash`.

```{note}
В описании формата командной строки аргументы, указанные в квадратных скобках, могут быть пропущены.
```

Для отображения и навигации по справочной странице `man` использует утилиту `less`.
За раз отображается только одна справочная страница.
Передаваемый в командную строку `man` *заголовок* является также *названием страницы*.
Содержимое страницы поделено на *секции*, одна из которых (`NAME`) содержит ее краткое описание.

```text
                  Справочная информация
┌─────────────────────────────────────────────────────────────┐
│  Тематический раздел #1       Тематический раздел #2        │
│┌─────────────────────────┐ ┌─────────────────────────┐ ...  │
││      man-страницы       │ │      man-страницы       │ ...  │
││┌────┐ ┌────┐<- секция 1 │ │┌────┐ ┌────┐ ...  ┌────┐│ ...  │
││├────┤ ├────┤<- секция 2 │ │├────┤ ├────┤ ...  ├────┤│ ...  │
││├────┤ ├────┤    ...     │ │├────┤ ├────┤ ...  ├────┤│ ...  │
││├────┤ ├────┤    ...     │ │├────┤ ├────┤ ...  ├────┤│ ...  │
││└────┘ └────┘            │ │└────┘ └────┘ ...  └────┘│ ...  │
│└─────────────────────────┘ └─────────────────────────┘ ...  │
└─────────────────────────────────────────────────────────────┘
```

Справочная система охватывает не только информацию об утилитах, но и функциях библиотеки Си, форматах файлов, об устройстве системы и многом другом.
Это приводит к тому, что названия страниц (заголовки) повторяются.
Например, заголовок `man` связан как с утилитой, так и с названием макросов для форматирования справочных страниц.
С заголовком `close` связаны как системный вызов (функция ядра ОС), так и функция стандартной библиотеки Си.
Чтобы разрешить противоречия в заголовках, справочные страницы поделены на 8 стандартных *тематических разделов*, обозначенных числами от 1 до 8.
1. Команды (вызываемые пользователем прикладные программы и утилиты).
2. Системные вызовы (функции ядра ОС, вызываемые прикладными программами).
3. Функции библиотек (стандартной библиотеки Си и C++, библиотеки времени выполнения
и других).
4. Специальные файлы (файлы из каталога `/dev`, чтение и запись на которые привязана к устройствам ввода/вывода).
5. Форматы файлов и соглашения (спецификации используемых форматов).
6. Игры.
7. Остальное (что не попало в другие разделы).
8. Утилиты для управления системой (системные утилиты для настройки компьютера, обычно запускаемые с правами суперпользователя).

Уникальность имени страницы ограничивается пределами одного раздела, а в разных разделах имена могут повторяться.
Чтобы точно идентифицировать справочную страницу, к ее имени добавляют номер раздела в скобках.
Таким образом, `man (1)` ссылается на утилиту, а `man (7)` -- группу макросов, `close (2)` указывает на системный вызов, а `close (3)` -- на функцию стандартной библиотеки Си.
Чтобы отобразить страницу из конкретного раздела, его номер указывается в командной строке: `man 2 close`.
Если номер раздела не указан, то отобразится страница из раздела с наименьшим номером.

Разделов не всегда достаточно для обеспечения уникальности заголовков.
Как пример, одна утилита может иметь два описания -- одна задается стандартом POSIX, а вторая как фактическая реализация.
Поэтому разделы расширяются -- вводятся новые или разбиваются старые.
Подразделы `1p`, `3p` собирают страницы, посвященные стандарту POSIX.
Суффикс `x` выделяет подразделы для документации `X Windows System`.
Дополнительно, могут быть добавлены нестандартные разделы.


## Структура справочной страницы

Справочная страница обладает структурой за счет разделения содержимого на секции.
Существуют следующие стандартные секции:
* NAME
* SYNOPSIS
* CONFIGURATION
* DESCRIPTION
* OPTIONS
* EXIT STATUS
* RETURN VALUE
* ERRORS
* ENVIRONMENT
* FILES
* VERSIONS
* CONFORMING TO
* NOTES
* BUGS
* EXAMPLE
* SEE ALSO

К обязательным относятся NAME, SYNOPSIS, DESCRIPTION и SEE ALSO.
Подробности о справочных страницах показаны в `man-pages(7)`.

Секция NAME содержит имя команды (функции, системного вызова или другого описываемого объекта), за которым следует ее краткое описание.
Подробное описание приводится в секции DESCRIPTION.
Ссылки на другие страницы перечисляются в секции SEE ALSO.

Секция SYNOPSIS содержит краткое описание способа вызова команды или функции.
Если страница посвящена библиотечной функции, то в ней указывается заголовочный файл и объявление с названием функции, перечислением формальных параметров и типа возвращаемого значения.
Для команды она задает формат командной строки, включающий перечисление и порядок аргументов.
В квадратные скобки помещают необязательные аргументы, символ `|` разделяет альтернативные аргументы для выбора одного из нескольких, символы `...` показывают, что аргумент может повторяться, подчеркнутый (или наклонный) текст указывает на замещаемые пользователем данные.

Перечисление и описание опций и возвращаемых кодов команд содержатся в секциях `OPTIONS` и `EXIT STATUS`.
Эти секции характерны только для разделов 1 и 8.
Аналогичны по сути формальные параметры и возвращаемые значения библиотечных функций.
Формальные параметры раскрываются по мере описания функции в секции `DESCRIPTION`.
Возвращаемые значения, если они есть у функции, раскрываются в секции `RETURN VALUE`.

Семейство ОС UNIX разработано на основе соглашений и стандартов.
Их полный список приведен на man-странице `standards(7)`.
Секция `CONFORMING TO` перечисляет стандарты, которым соответствует описываемая команда (функция).

Коротко опишем остальные секции:
* `ENVIRONMENT` перечисляет переменные окружения и то, как они влияют на выполнение команды или функции;
* `EXAMPLE` содержит примеры использования;
* `BUGS` указывает на известные ошибки и проблемы в использовании;
* `ERRORS`, сценариев вызова функции, приводящих к ошибке выполнения;
* `HISTORY` содержит историю изменений утилиты;
* `AUTHORS` перечисляет имена разработчиков;
* `COPYRIGHT` содержит лицензию на распространяемую программу;
* `CONFIGURATION`
* `FILES`
* `VERSIONS`
* `NOTES`


## Поиск информации

Одна из главных задач, решаемая справочной системой -- это поиск информации.
Нужную страницу можно отобразить, если известен ее заголовок.
В остальных случаях необходимо найти страницу, содержащее аргумент поиска -- ключевое слово.
Время поиска существенно зависит от того, на каких данных он совершается.
Существует три уровня поиска, отличающихся объемом данных -- это:
* поиск по заголовкам страниц;
* поиск в кратких описаниях страниц;
* полнотекстовый поиск;

Во всех трех случаях поиск не зависит от регистра символа.

Поиск по заголовкам страниц осуществляется по команде `man -f keyword`, которая эквивалентна `whatis keyword`.

Команда `man -k ls` ищет вхождение ключевого слова в кратких описаниях справочных страниц (в секции NAME). Команда эквивалента `apropos keyword`.

Поиск по всему содержимому страницы (полнотекстовый) наиболее медленный.
Он запускается по команде `man -K keyword`.
Найденная страница и фрагмент текста отображаются сразу по обнаружению.
Поиск можно в любой момент остановить комбинацией клавиш `Ctrl-C`.

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

Поиск по ссылкам.
Одна из характеристик справочной информации -- это ссылки, которые связывают страницы друг с другом.
Ссылки перечисляются в секции `SEE ALSO`.
С каждым из тематических разделов связана страница `intro` с введением.
Введение в первый раздел отображается командой `man 1 intro`.
Страницы с ключевым словом `intro` в кратком описании часто соответствуют введениям в самостоятельные темы, тематические разделы и подразделы.
Список имен таких страниц выводит на экран команда `apropos intro`.
Примеры некоторых из них:
* `C++Intro` -- введение в стандартную библиотеку языка программирования C++;
* `Kerberos` -- введение в систему Kerberos;
* `perlintro` -- введение в язык программирования Perl.


## Заключение

В отличие от современных справочных систем в `man` нет перекрестных ссылок.
Некоторое подобие связности добавляют указатели на man-страницы.
Но чтобы ими воспользоваться, необходимо выйти из просмотра и заново набрать команду.
Современная документация представлена преимущественно в виде иерархических гипертекстовых документов, связанных с гиперссылками.
Этот недостаток исправляет утилита `info`.
По популярности она единственная, кто сравнится с `man`.
Утилита `info` в связке с `GNU Emacs` организует подобие связанных веб-страницы и поддерживает работу с мышью.


## Вопросы для самоконтроля

1. Перечислите источники справочной информации о программах в системе.
1. Вызовите встроенную справку интерпретатора python, текстового редактора vi, утилиты less.
1. На какой утилите основана справочная система UNIX?
1. Сравните встроенную и внешнюю информацию об утилите grep. Чем они отличаются?
1. Как получить подробную справочную информацию по утилите `touch`?
1. Что такое справочная страница, тематический раздел?
1. Что такое заголовок, краткое описание и содержимое справочной страницы?
1. Как выглядят ссылки на справочные страницы man?
1. Перечислите не менее четырех стандартных тематических разделов в man.
1. Перечислите секции справочной страницы `map(1)`, `close(2)`, `printf(3)`, `passwd(5)`, `intro(6)`, `libc(7)`, `ping(8)`.
1. О чем написано в странице `man-pages(7)`?
1. Как выполняется поиск по названиям справочных страниц?
1. Как выполняется поиск по кратким описаниям справочных страниц?
1. Как выполняется поиск по содержимому справочных страниц?
1. Как можно использовать страницы-введения и ссылки при поиске информации?
1. Найдите справочные страницы, содержащие секции SYNOPSIS, DESCRIPTION, EXAMPLE, SEE ALSO, BUGS, OPTIONS, EXIT STATUS, ENVIRONMENT, HISTORY, AUTHORS, RETURN VALUE, ERRORS.
1. Какую проблему `man` решает справочная система `info`?