Читаем man pages: SYNOPSIS, OPTIONS, скобки

Тема дорожной карты · Английский для IT

🔊 Словарь терминов с произношением →

Man page — справочная страница Unix, и у неё есть жёсткая структура, которую нужно знать, чтобы находить ответ за секунды, а не читать всё подряд. Разделы: NAME — имя команды и однострочное описание; SYNOPSIS — формальный синтаксис вызова; DESCRIPTION — подробное описание; OPTIONS — флаги с пояснениями; EXIT STATUS — коды возврата; ENVIRONMENT — переменные окружения, влияющие на команду; FILES — используемые файлы; EXAMPLES — примеры (не у всех); SEE ALSO — связанные команды; BUGS — известные проблемы; AUTHOR, COPYRIGHT. Самый ценный и самый непонятный для новичка раздел — SYNOPSIS, потому что он написан на формальном языке: bold (жирный) — набирать буквально; italic или подчёркивание — заменить своим значением; [квадратные скобки] — необязательный элемент; многоточие … — элемент может повторяться; вертикальная черта | — выбор одного из вариантов; {фигурные скобки} — обязательный выбор из вариантов. Пример: ls [OPTION]... [FILE]... читается «ls, затем ноль или более опций, затем ноль или более файлов». Номер в скобках после имени — раздел руководства: man(1) — команды пользователя, (2) — системные вызовы, (3) — библиотечные функции, (5) — форматы файлов, (7) — обзоры и соглашения, (8) — команды администратора. man 5 crontab открывает формат файла, а man 1 crontab — команду.

Как произносится

Man page /ˈmæn peɪdʒ/, manual /ˈmænjuəl/, synopsis /sɪˈnɒpsɪs/ («синОпсис», ударение на второй слог), description /dɪˈskrɪpʃən/, options /ˈɒpʃənz/, exit status /ˈɛɡzɪt ˈsteɪtəs/ (или /ˈstætəs/ в американском), environment /ɪnˈvaɪrənmənt/ (ударение на «вай»), bracket /ˈbrækɪt/, ellipsis /ɪˈlɪpsɪs/ (многоточие), optional /ˈɒpʃənəl/, mandatory /ˈmændətəri/ (обязательный), argument /ˈɑːrɡjʊmənt/, operand /ˈɒpərænd/, section /ˈsɛkʃən/, see also /siː ˈɔːlsoʊ/, pager /ˈpeɪdʒər/ (программа постраничного просмотра, в которой открывается man).

Как употребляется

Как читать SYNOPSIS вслух:

  • grep [OPTION...] PATTERNS [FILE...] — grep, optional options, then patterns, then optional files, both repeatable.
  • tar {-c|-x|-t} [-v] [-f ARCHIVE] [FILE...] — tar, one of create, extract or list, optionally verbose, optionally a file archive, then optional files.
  • kill [-s SIGNAL | -SIGNAL] PID... — kill, optionally a signal in one of two forms, then one or more PIDs.

Фразы про man:

  • Check the man page. / RTFM (read the manual, грубовато). — Посмотри справку.
  • It's in section five: man five crontab. — Это в пятом разделе.
  • The synopsis says the file argument is optional. — В SYNOPSIS сказано, что файл необязателен.
  • Search the man page with slash. — Ищи по странице через /.
  • Man dash k searches by keyword. — man -k ищет по ключевому слову.
  • See also points to the config format. — SEE ALSO ведёт на формат конфига.

Навигация внутри man (это less): /pattern — поиск, n — следующее совпадение, q — выход, h — справка по клавишам, g / G — начало / конец.

Ловушки

Первая ловушка — читать man целиком: почти всегда нужны SYNOPSIS и один флаг из OPTIONS; ищите через /. Вторая — путать скобки: [-f FILE] означает «необязательный флаг с обязательным аргументом», а -f [FILE] — «флаг с необязательным аргументом». Третья — открывать не тот раздел: man printf покажет команду shell, а man 3 printf — функцию C. Четвёртая — option, flag, switch, argument, operand: option и flag почти синонимы (флаг чаще без значения: -v), switch — устаревший синоним из мира Windows, argument — значение для опции или команды, operand — то, над чем команда работает (файл в cat file). Пятая — ожидать раздел EXAMPLES: у многих GNU-утилит его нет, полная документация в info. Шестая — man для встроенных команд shell: man cd не работает, потому что cd — builtin; нужно help cd в bash или man bash.

Связанные понятия

Полезные ресурсы