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

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

Введение#

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

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

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

[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) содержит ее краткое описание.

                  Справочная информация
┌─────────────────────────────────────────────────────────────┐
│  Тематический раздел #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. Перечислите источники справочной информации о программах в системе.

  2. Вызовите встроенную справку интерпретатора python, текстового редактора vi, утилиты less.

  3. На какой утилите основана справочная система UNIX?

  4. Сравните встроенную и внешнюю информацию об утилите grep. Чем они отличаются?

  5. Как получить подробную справочную информацию по утилите touch?

  6. Что такое справочная страница, тематический раздел?

  7. Что такое заголовок, краткое описание и содержимое справочной страницы?

  8. Как выглядят ссылки на справочные страницы man?

  9. Перечислите не менее четырех стандартных тематических разделов в man.

  10. Перечислите секции справочной страницы map(1), close(2), printf(3), passwd(5), intro(6), libc(7), ping(8).

  11. О чем написано в странице man-pages(7)?

  12. Как выполняется поиск по названиям справочных страниц?

  13. Как выполняется поиск по кратким описаниям справочных страниц?

  14. Как выполняется поиск по содержимому справочных страниц?

  15. Как можно использовать страницы-введения и ссылки при поиске информации?

  16. Найдите справочные страницы, содержащие секции SYNOPSIS, DESCRIPTION, EXAMPLE, SEE ALSO, BUGS, OPTIONS, EXIT STATUS, ENVIRONMENT, HISTORY, AUTHORS, RETURN VALUE, ERRORS.

  17. Какую проблему man решает справочная система info?

Contents