В прошлом году я много работал над Git man page, поэтому начал больше думать о том, что делает man-страницу (man page) по-настоящему хорошей.

Я провёл немало времени, составляя шпаргалки для инструментов (tcpdump, git, dig и др.), у которых man-страница является основной документацией. Во многом потому, что мне часто сложно ориентироваться в man-страницах, чтобы быстро найти нужную информацию.

В последнее время я думаю — а может ли сама man-страница содержать отличную шпаргалку? Что вообще может сделать man-страницу более удобной? Я пока только в начале этих размышлений, но захотел написать о некоторых моментах.

Если Linux и терминал пока даются с трудом, подготовительный курс «Linux для начинающих» поможет разобраться с базовыми командами и консольными инструментами — тем самым фундаментом, на котором держится работа с man-страницами.

Я спросил у людей в Mastodon про их любимые man-страницы и обнаружил несколько интересных решений.

Сводка опций (OPTIONS SUMMARY)

Если вы читали много man-страниц, то наверняка видели в разделе SYNOPSIS что-то вроде этого — когда перечисляется почти весь алфавит, ориентироваться становится сложно

ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]

grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]

В man-странице rsync есть решение, которое я раньше не встречал: раздел SYNOPSIS там максимально лаконичный, например:

 Local:
     rsync [OPTION...] SRC... [DEST]

А затем идёт раздел «OPTIONS SUMMARY» с однострочным описанием каждой опции:

--verbose, -v            increase verbosity
--info=FLAGS             fine-grained informational verbosity
--debug=FLAGS            fine-grained debug verbosity
--stderr=e|a|c           change stderr output mode (default: errors)
--quiet, -q              suppress non-error messages
--no-motd                suppress daemon-mode MOTD

Позже идёт привычный раздел OPTIONS с полным описанием каждой опции.

Раздел OPTIONS, сгруппированный по категориям

В man-странице strace опции сгруппированы по категориям (например, «General», «Startup», «Tracing», «Filtering», «Output Format»), а не по алфавиту.

В качестве эксперимента я попробовал взять man-страницу grep и сделать в ней раздел «OPTIONS SUMMARY», сгруппированный по категориям — результат можно посмотреть на github. Не уверен, что сам думаю об этом результате, но это был интересный эксперимент. Когда я это делал, я думал о том, как никогда не запомню название опции -l в grep. Каждый раз ее поиск в man-странице занимает целую вечность, и я пытался понять, какая структура помогла бы ускорить процесс. Возможно, категории?

Шпаргалка

Пара человек указали мне на набор Perl man-страниц (perlfunc, perlre и т. д.), и среди них я заметил man perlcheat, где есть разделы-шпаргалки вроде такого:

 SYNTAX
 foreach (LIST) { }     for (a;b;c) { }
 while   (e) { }        until (e)   { }
 if      (e) { } elsif (e) { } else { }
 unless  (e) { } elsif (e) { } else { }
 given   (e) { when (e) {} default {} }

Мне кажется, это очень круто, и я задумался, есть ли другие способы делать компактные ASCII-шпаргалки шириной 80 символов, которые можно было бы использовать в man-страницах.

Сила примеров

Часто мне отвечали примерно так: «Мне нравится любая man-страница, где есть примеры». Кто-то упомянул man-страницы OpenBSD, и в openbsd tail man-странице в конце есть примеры ровно двух способов, которыми я сам пользуюсь tail.

Мне кажется, чаще всего я видел раздел EXAMPLES в конце man-страницы, но некоторые man-страницы, например уже упомянутая man-страница rsync, начинаются именно с примеров. Когда я работал над man-страницами git-add и git rebase, я тоже помещал короткий пример в начало.

Оглавление и ссылки между разделами

Это не свойство самой man-страницы как таковой, но одна из проблем man-страниц в терминале в том, что по ним трудно понять, какие вообще разделы в них есть.

Когда мы работали над man-страницами Git, мы с Мари добавили оглавление на боковую панель HTML-версий man-страниц, размещённых на сайте Git.

Ещё я хотел бы в какой-то момент добавить больше гиперссылок в HTML-версии man-страниц Git, чтобы, например, можно было нажать на «INCOMPATIBLE OPTIONS» и сразу перейти к нужному разделу. В проекте Git такие ссылки добавлять очень просто, потому что man-страницы Git генерируются с помощью AsciiDoc.

Мне кажется, что добавление оглавления и внутренних гиперссылок — это хороший компромисс: так можно немного улучшить формат man-страниц, по крайней мере в их HTML-версии, не поддерживая при этом полностью отдельный формат документации. Хотя для этого, конечно, нужна цепочка инструментов вроде той, что используется у Git на базе AsciiDoc.

Было бы здорово, если бы существовала какая-то универсальная система, которая позволяла бы легко находить конкретную опцию в man-странице: например, «что делает -a?». Лучший приём, который я знаю, — искать в просмотрщике man-страницы что-то вроде ^ *-a, но я сам всё время забываю так делать и вместо этого просто просматриваю каждое вхождение -a в man-странице, пока не найду то, что мне нужно.

Примеры для каждой опции

В man-странице curl есть примеры для каждой опции, а в HTML-версии ещё и добавлено оглавление, чтобы было проще перейти именно к той опции, которая вас интересует.

Например, по примеру для --cert сразу понятно, что, скорее всего, вам также нужно передать опцию --key, вот так:

curl --cert certfile --key keyfile https://example.com

Реализовано это так: для каждой опции есть отдельный файл (https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583 25/docs/cmdline-opts/append.md), и в этом файле предусмотрено поле «Example».

Оформление данных в виде таблицы

Довольно много людей сказали, что их любимая man-страница — это man ascii, и выглядит она вот так:

Очевидно, man ascii — это довольно необычная man-страница, но, как мне кажется, в ней здорово то, что, помимо очевидной пользы самой ASCII-таблицы, нужную информацию в ней очень легко находить взглядом именно благодаря табличному формату. И я задумался, нет ли и в других случаях возможностей представлять информацию в man-странице в виде «таблицы», чтобы по ней было проще скользить глазами.

Подход GNU

Когда я говорю о man-страницах, часто всплывает тема, что в man-страницах GNU coreutils, например в man tail, нет примеров, в отличие от man-страниц OpenBSD, где примеры есть.

Я не буду слишком глубоко в это уходить, потому что тема, похоже, довольно политизированная, и я точно не смогу здесь отдать ей должное, но вот что, как мне кажется, соответствует действительности:

• Проект GNU предпочитает поддерживать документацию в виде руководств «info», а не man-страниц. На этой странице прямо сказано, что «man-страницы больше не поддерживаются».

• Есть три способа читать руководства «info»: в HTML-версии, в Emacs или с помощью отдельной утилиты info. От некоторых пользователей Emacs я слышал, что им нравится встроенный в Emacs просмотрщик info. Думаю, что отдельной утилитой info вообще мало кто пользуется.

• Ссылка на раздел руководства info для tail находится внизу man-страницы, и в нём примеры как раз есть.

• Раньше FSF продавал печатные книги с руководствами по программам GNU, и, возможно, иногда делает это (?) до сих пор.

После определённого уровня сложности man-страница становится по-настоящему трудной для навигации: хотя я никогда не пользовался руководством coreutils и, скорее всего, не буду, почти наверняка я предпочёл бы читать справочное руководство GNU Bash или справочное руководство по библиотеке GNU C Library в их HTML-версии, а не в формате man-страницы.

Ещё несколько вещей, смежных с man-страницами

Вот несколько инструментов, которые кажутся мне интересными:

• В комплекте с fish shell идёт Python-скрипт, который автоматически генерирует автодополнение по табуляции на основе man-страниц.

• tldr.sh — это поддерживаемая сообществом база примеров. Например, можно выполнить команду tldr grep. Многие говорили мне, что считают этот инструмент полезным.

• В браузере документации Dash для Mac есть хороший просмотрщик man-страниц. Я сам по-прежнему пользуюсь просмотрщиком man-страниц в терминале, но мне нравится, что в Dash есть оглавление. Выглядит это так:

Если вам близка тема удобных инструментов, понятной документации и нормальной инженерной навигации, можно продолжить в смежных темах на бесплатных уроках. Будем разбирать не абстрактные подходы, а практику: CLI, рабочее окружение, архитектуру Kubernetes и то, как с этим жить в реальных проектах.

• 6 мая 20:00. «Rust в деле: пишем многопользовательский чат с сервером, клиентом и CLI». Записаться

• 7 мая 20:00. «Настройка удобного рабочего окружения для Python проекта». Записаться

• 18 мая 20:00. «Основы Kubernetes: архитектура и абстракции». Записаться

Больше обучающих материалов смотрите в дайджесте по ИТ-инфраструктуре.