В мире *nix справочные страницы, также известные как справочные страницы, считаются абсолютным справочником для опытных пользователей. Существует также случайная педантичность RTFM, грубо настаивающего на своей важности. Эта manкоманда даже является частью спецификации POSIX — основы для большинства современных реализаций *nix-систем. Так оправдана ли эта идея в конце концов?
Преимущества справочных страниц
- Не требует подключения к интернету
- Написано разработчиками/сопровождающими, что обеспечивает обширную информацию и точность
- Автономны, не нуждаются во внешних ресурсах
- Всегда применять к установленной версии приложения и текущему дистрибутиву
Однако, даже если они могут быть полезны, справочные страницы поначалу пугают. Эта статья призвана облегчить просмотр руководств и быстро получить необходимую помощь.
Что такое справочные страницы?
Рожденные во времена Unix, страницы man — сокращение от manual — были основным источником пользовательской документации. Они были написаны разработчиками программного обеспечения и поставлялись вместе с ним.
Сегодня в дистрибутивах Linux, когда кто-то устанавливает пакет через менеджер пакетов — apt, dnf, pacman или другие, руководства устанавливаются в каталог /usr/share/man.
Выбор одного из этих файлов и использование cat для просмотра… имеет непредвиденные последствия
$ cat /usr/share/man/man1/man.1.gz
�[ks�F���_�Ś�IS$m�Ig&��2��b=V��I�6%�
@�F����߾�>��$e�nmR�C��}��}{n�`�3M2Ŀ�
���X�Ϋ;k�����Tm�0˪άi�i*3�f]�u]eֹ��{��
YZ�uzm�q�JK��7N��C�_�4�����|�U����
... # truncated output
Это должно быть потому, что файл сжат. Давай попробуем zcat
$ zcat /usr/share/man/man1/man.1.gz '\" t .\" ** The above line should force tbl to be a preprocessor ** .\" Man page for man .\" .\" Copyright (C) 1994, 1995, Graeme W. Wilford. (Wilf.) .\" Copyright (C) 2001-2019 Colin Watson. .\" .\" You may distribute under the terms of the GNU General Public ... # truncated output
Хорошо, это дает текст. Но он по-прежнему наполнен странным синтаксисом; также настолько долго, что заполняет весь терминал.
Давайте отойдем от приключений и просмотрим справочную страницу так, как предполагалось — с помощью команды man.
$ man man
При доступе к справочной странице с помощью manкоманды она по-прежнему заполняет окно терминала. Но теперь легче читать. Кроме того, есть много форматирования: заголовки, жирный текст, курсив или подчеркнутый текст.
Как отображаются справочные страницы?
Man-страницы — это файлы разметки, написанные с использованием потомка синтаксиса roff, такого как groff из проекта GNU. Синтаксис — это система набора текста, которая устанавливает структуру и форматирование справочных страниц. Это похоже на семантический HTML для веб-страниц.
manнаходит необработанный файл roff в файловой системе и обрабатывает его для создания вывода, подходящего для текущего терминала. Обработка включает в себя настройку ширины страницы, кодировки текста, толщины шрифта и стилей в соответствии с поддержкой терминала. Результат затем отображается с помощью пейджера.
Команда man в Linux является частью набора пакетов man-db. В коллекции есть пакеты для управления различными процессами, а также для ведения указателя установленных руководств.
В большинстве систем BSD вместо этого используется проект mandoc. И отличается от него man-db в разных аспектах. Остальная часть статьи будет посвящена только man-db, его функциям и опциям.
Программа man
Как было установлено ранее, для доступа к справочной странице мы используем manкоманду. За простейшим вызовом команды manследует имя страницы, к которой вы хотите получить доступ. Итак, чтобы получить доступ к руководству по ssh
$ man ssh
Элементы пакета man-db поддерживают общую базу данных всех справочных страниц, установленных в системе. Эта база данных, скорее всего, расположенная по адресу /var/cache/man/index.db, действует как кешированный индекс справочных страниц. Он также предоставляет информацию, необходимую для других инструментов в man-db. Если в индексе нет страницы с именем ssh, команда man выполняет поиск в списке каталогов, определенных в переменной окружения /etc/manpath.config или с ее помощью $MANPATH.
Навигация
Навигация по справочной странице полностью обрабатывается используемым пейджером. По умолчанию manиспользует команду pager. И в большинстве современных систем Linux pagerэто символическая ссылка на less.
Чтобы закрыть руководство в любое время, просто нажмите q на клавиатуре. Это закрывает пейджер и возвращает в оболочку.
Прокрутка
В большинстве страниц, в том числе less, очень легко листать страницу с помощью колеса прокрутки, жестов прокрутки, а также клавиш со стрелками. Home и End также поддерживаются.
Пользователи, знакомые с Vim, также могут использовать стандартные сочетания клавиш для движений для навигации по пейджеру. Удерживая нажатой клавишу j, вы прокручиваете вниз, а k прокручиваете одну строку вверх. g и G можно использовать для начала и конца страницы соответственно.
Также можно прокручивать больше за один раз с помощью клавиатуры, но это часто затрудняет чтение. Но если вы хотите, вы можете нажать клавишу h, чтобы вызвать экран справки для всех сочетаний клавиш less.
Умение пользоваться прокруткой — это первый шаг к использованию документации для поиска информации. Но даже в этом случае было бы нелегко пройти его построчно. Вот где в игру вступает функция поиска страниц.
Идет поиск
Самый быстрый способ найти конкретную функцию или параметр на странице руководства — это выполнить поиск по слову. Чтобы начать поиск в руководстве, нажмите клавишу (косая черта)/, введите шаблон (регулярные выражения поддерживаются!) и нажмите Enter
Это полезно, когда вы ищете приблизительную «тему». Например, вы можете открыть страницу руководства rsync и выполнить поиск по слову частично, чтобы быстро перейти к первому вхождению этого слова. Затем вы можете нажать клавишу n, чтобы перейти к следующему экземпляру, или N (shift + n), чтобы вернуться к предыдущему. С использованием ? Вы также можете искать назад.
По умолчанию регистр (верхний или нижний) шаблона игнорируется. Но если есть заглавная буква, шаблон обрабатывается с учетом регистра. Такое поведение делает невозможным поиск полностью строчных букв. Поэтому иногда полезно включить поиск с учетом регистра. Это можно сделать, нажав последовательность дефис -i, чтобы переключить функцию.
Циклический просмотр экземпляров шаблона поиска и прокрутка вверх и вниз по ним — удобный способ получить информацию по определенной теме.
Еще одно хорошее применение функции поиска — с флагами. Выполнение поиска шаблона, с которого начинается строка с пробелами и шаблоном, полезно для перехода к флагу.
/^\s+--compress
Это также может быть полезно при проверке команд из Интернета перед их запуском. Переходим к флагу и проверяем, что он делает. Поиск также можно использовать для быстрого перехода к определенному разделу справочной страницы.
Разделы справочной страницы
Руководства обычно делятся на несколько разделов, обозначенных заголовками, выделенными жирным шрифтом ЗАГЛАВНЫМИ буквами. Существует список разделов, которые можно найти на большинстве страниц. Но общими и важными являются имя, синопсис, окружение и файлы.
ИМЯ
Этот раздел имеет название приложения (или раздела руководства) и краткое описание. Резюме своего рода.
СИНТАКСИС
Раздел синопсиса представляет собой краткое руководство. Для приложений это описание синтаксиса командной строки.
Полезно знать соглашения, используемые в синопсисе, иллюстрирующем, как можно использовать команду.
command [--optional-flag] [-a -b] [ -c argument ] [-A|-B] filename ...
- Первое слово это название команды
- Аргументы, которые окружены [ ], являются необязательными
- Флаги или опции |между ними нельзя использовать вместе
- Аргументы, за которыми следует …, могут повторяться
- Аргументы без [ ] обязательны
С приведенным выше образцом command /etc/passwd и command /etc/passwd /etc/group являются простейшими допустимыми вызовами, имеющими все необходимые элементы.
Все перечисленные флаги являются необязательными, но -A не могут использоваться с -B. Можно использовать только один из двух.
Также обратите внимание, что это -c argument означает, что аргумент требуется, если используется флаг -c. И только один аргумент может быть передан -c.
ОКРУЖАЮЩАЯ СРЕДА
Переменные среды полезны для управления поведением приложения. В разделе среды справочной страницы перечислены переменные, влияющие на данную команду, а также их действие. Также перечислены переменные, установленные программным обеспечением для использования другими приложениями.
ФАЙЛЫ
В разделе файлов справочной страницы перечислены и описаны пути в файловой системе, относящиеся к программному обеспечению. Обычно это пути к файлам конфигурации. Страница руководства для bash перечисляет файлы инициализации, которые анализируются оболочкой.
Секции man
Разделы в руководстве не следует путать с различными разделами справочных страниц.
По сути, все руководства, доступные в системе, классифицируются по разделам, пронумерованным от 1 до 8. И устанавливаются в соответствующие папки, man1- man8.
Иногда также существует несколько дополнительных разделов. Лучшее описание каждого раздела находится на справочной странице man.
| Раздел | Имя | Описание |
|---|---|---|
| 1 | Исполняемые программы или команды оболочки | общие команды, например, cat, man, ssh, cp |
| 2 | Системные вызовы | функции, предоставляемые ядром |
| 3 | Библиотечные звонки | функции в программных библиотеках |
| 4 | Специальные файлы | обычно находится в /dev |
| 5 | Форматы файлов и соглашения | например /etc/passwd |
| 6 | Игры | |
| 7 | Разнообразный | включая пакеты макросов и соглашения, например, man(7), groff(7) |
| 8 | Команды системного администрирования | обычно только для root |
В большинстве случаев нет необходимости указывать раздел man, автоматически проходит все разделы в заданном порядке. Но можно указать раздел.
man 5 ssh_config man rsync.1 man "passwd(5)"
Все вышеперечисленное является допустимым синтаксисом команды. И последнее — passwd(5) относится к справочной странице для /etc/passwd. С другой стороны, passwd (1 было бы приложение, чтобы изменить пароль пользователя. В таких случаях полезно указать раздел.
Часто руководства предписывают пользователю обратиться к другим родственным руководствам. Эти ссылки написаны в формате name(section number) и могут быть легко скопированы и вставлены в терминал. Но их нужно заключить в кавычки, чтобы оболочка не интерпретировала их.
Использование команды man с дополнительными параметрами
Хотя простейшим вызовом manявляется man name, также можно использовать флаги для получения других результатов.
Флаг -fдля кратких описаний
man -f name является псевдонимом другой команды whatis name, доступной как часть пакета man-db. Команда whatis выводит краткое описание из раздела ИМЯ справочной страницы. Описания извлекаются и кэшируются в базе данных, которая используется всеми утилитами man-db.
$ man -f whatis whatis (1) - display one-line manual page descriptions $ whatis whatis whatis (1) - display one-line manual page descriptions
Флаг -k для поиска по темам
Точно так же man -k nameэто псевдоним для apropos name. Команда ищет имя в базе описаний man-db и выводит те, которые совпадают. Поскольку он ищет название и описание каждого руководства, этот флажок будет полезен для поиска всех руководств по теме.
$ man -k apropos apropos (1) - search the manual page names and descriptions $ apropos apropos apropos (1) - search the manual page names and descriptions $ man -k password chage (1) - change user password expiry information chgpasswd (8) - update group passwords in batch mode chpasswd (8) - update passwords in batch mode ... #truncated
Посмотреть с –html
$ man --html
Флаг –html можно использовать для генерации HTML-вывода! manдаже откроет браузер и отобразит html-версию руководства. Обратите внимание, что это зависит от допустимости переменной среды $BROWSER.
Существуют и другие параметры CLI, перечисленные в , man(1) и их можно просмотреть с помощью команды man man. 😉
Альтернативная документация
Несмотря на свою полезность, man не всегда является ответом. Иногда все, что нужно, — найти подсказку для термина.
$ command --help | grep -i 'term'
Большинство программ имеют справку, доступную с помощью флага –help. Тем не менее, man остается лучшим способом получить подробную информацию.
Но manэто не единственный ответ. Существуют различные конкурирующие стандарты для документации программного обеспечения. Документация GNU texinfo, доступная только для Интернета, которая публикуется на веб-сайтах или на GitHub, не является чем-то необычным.
Несмотря на это, все manвыдержало испытание временем и сохраняется сегодня. Его гибкость и доступность играют большую роль. Глубина информации имеет не менее большую роль. Надеюсь, эта статья помогла вам принять его. И в следующий раз, может быть, вы тоже потянетесь к справочным страницам раньше, чем к поисковой системе.