В прошлом году я много работал над 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, и выглядит она вот так:
Oct Dec Hex Char
───────────────────────────────────────────
000 0 00 NUL '\0' (null character)
001 1 01 SOH (start of heading)
002 2 02 STX (start of text)
003 3 03 ETX (end of text)
004 4 04 EOT (end of transmission)
005 5 05 ENQ (enquiry)
006 6 06 ACK (acknowledge)
007 7 07 BEL '\a' (bell)
010 8 08 BS '\b' (backspace)
011 9 09 HT '\t' (horizontal tab)
012 10 0A LF '\n' (new line)
Очевидно, 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: архитектура и абстракции». Записаться
Больше обучающих материалов смотрите в дайджесте по ИТ-инфраструктуре.