man-страницы
| Появление | Unix Programmer's Manual (1971) |
|---|---|
| Команда | man, apropos, whatis |
| Формат | roff (макросы man и mdoc) |
| Реализации | man-db (Linux), mandoc (BSD, macOS) |
| Проект Linux | man-pages (kernel.org) |
| Расположение | /usr/share/man |
| Альтернативы | info, tldr-pages, --help |
man-страницы (manual pages, страницы руководства) — традиционная справочная документация Unix-подобных систем, доступная прямо из терминала командой man. У каждой команды, системного вызова, библиотечной функции и формата конфигурационного файла обычно есть своя страница со строго заданной структурой. man-страницы работают без сети, соответствуют установленной версии программы и поэтому остаются первоисточником, даже когда под рукой есть поиск и краткие шпаргалки вроде tldr-pages.
История
Первое издание Unix Programmer's Manual Кен Томпсон и Деннис Ритчи подготовили в 1971 году; уже тогда оно делилось на разделы и состояло из отдельных страниц на каждую команду.[5] Страницы набирались в системе roff — она же использовалась для вёрстки документов в Bell Labs. Эта схема почти без изменений дожила до наших дней. В Linux страницы ядра и glibc поддерживает проект man-pages на kernel.org; страницы утилит поставляются вместе с самими пакетами.[1]
Разделы
Страницы сгруппированы по разделам; номер пишут в скобках: printf(1) — команда, printf(3) — функция языка C.[2]
| Раздел | Содержание | Пример |
|---|---|---|
| 1 | пользовательские команды | ls(1), grep(1) |
| 2 | системные вызовы ядра | open(2), fork(2) |
| 3 | функции библиотек | printf(3), malloc(3) |
| 4 | специальные файлы (устройства) | null(4) |
| 5 | форматы файлов и конфигурации | crontab(5), sshd_config(5) |
| 6 | игры | |
| 7 | обзоры, соглашения, протоколы | signal(7), regex(7) |
| 8 | команды администрирования | mount(8), iptables(8) |
Разделы помогают различать одинаковые имена: man crontab покажет команду, а man 5 crontab — формат файла расписания (см. cron и таймеры systemd).
Структура страницы
Стандартные секции:[3]
- NAME — имя и однострочное описание (по нему ищет
apropos). - SYNOPSIS — синтаксис вызова:
[...]— необязательно,...— можно повторять,|— альтернативы. - DESCRIPTION — подробное описание.
- OPTIONS — ключи командной строки.
- EXIT STATUS, ENVIRONMENT, FILES — коды возврата, переменные окружения и используемые файлы.
- EXAMPLES, SEE ALSO, BUGS — примеры, связанные страницы, известные ошибки.
Использование
man ls # страница команды ls
man 7 signal # обзор сигналов из раздела 7
man -k compress # поиск по описаниям (то же, что apropos)
whatis tar # однострочное описание
man -f printf # во всех разделах, где есть printf
man -w grep # путь к файлу страницы
Страница открывается в пейджере (обычно less), где работают привычные клавиши: /шаблон — поиск, n — следующее совпадение, g/G — начало и конец, q — выход. Быстро перейти к описанию ключа можно поиском вроде /^ +-r. Цветной вывод настраивается переменными LESS_TERMCAP_* или переменной MANPAGER (например, просмотр через bat или Vim).
Если apropos ничего не находит, нужно обновить индекс: sudo mandb (man-db) или makewhatis (BSD). В минимальных образах Docker man-страницы часто удалены ради размера — их возвращают командой unminimize в Ubuntu или установкой пакетов man-db и manpages.
Формат и реализации
Исходники страниц пишутся на языке разметки roff с набором макросов man (Linux) или более семантическим mdoc (BSD). В Linux просмотрщик — man-db, в BSD и macOS — mandoc, который также конвертирует страницы в HTML и проверяет их на ошибки.[4] Хранятся страницы сжатыми в /usr/share/man/manN/, путь поиска задаётся переменной MANPATH.
Многие проекты больше не пишут roff вручную, а генерируют страницы из Markdown или reStructuredText (pandoc, scdoc, Sphinx) или из описания аргументов CLI (например, clap_mangen в Rust).
Альтернативы
--help— краткая справка самой программы, всегда под рукой.- info — гипертекстовая документация GNU; у некоторых утилит GNU она полнее man-страниц.
- tldr-pages — примеры частых случаев использования вместо полного справочника.
- man7.org и manpages.debian.org — веб-версии страниц для разных дистрибутивов.
Для языковых моделей man-страницы — ценный источник точного синтаксиса: их удобно передавать в контекст как текст (man ls | col -b), см. Документация для ИИ.