tldr — альтернатива man с названием, говорящим за себя
Все мы любим --help и man. Несмотря на появление многочисленных форумов, Stack Exchange и прочих ресурсов, хорошим тоном в начале решения своих проблем по-прежнему остаётся самостоятельный поиск ответа в официальной документации (и на этих ресурсах вам скорее всего об этом сразу напомнят). Однако лень продолжает двигать прогресс даже там, где не всегда того ожидаешь. Впрочем, это не только лень — бывают и другие аргументы в пользу «упрощений»…
В общем, оказалось, что классический man утраивает не всех. Поэтому появился проект tldr, который, следуя своей расшифровке «Too long; didn’t read», решил принести в консоль лаконичную документацию, содержащую только самое главное. Проекту tldr уже больше 3 лет, но про него ещё почему-то не писали на хабре.
Что это?
Авторы tldr описывают своё детище как «коллекцию упрощённых и создаваемых сообществом man-страниц». Главным продуктом их деятельности является собственно библиотека из markdown-файлов, являющихся альтернативными справочными страницами для популярных консольных утилит. Основная их часть относится к категориям «общие» и «Linux», однако есть также отдельные страницы для macOS и даже Windows.
Что хранится в этих страницах? В качестве примера в GitHub проекта демонстрируется tldr-справка по tar:
Как видно, это минимальное описание назначения утилиты и компактный список из самых частых команд. Для tar приводится 7 готовых команд, для ls — 6, для top — 5.
Кому это нужно? Хороший вопрос, ответ на который оставлю на усмотрение читающим. Очевидный вариант назначения — начинающим постигать консоль (не всех получается убедить прочитать всю документацию в начале их пути, чтобы жизнь была легче потом). Так или иначе, у проекта уже более 15 тысяч stars на GitHub, более тысячи форков и больше 20 клиентов (подробнее о них см. в следующем разделе) — этих показателей достаточно для констатации: спрос есть.
ⓒ xkcd #1168: tar
Установка и использование
Чтобы получить доступ к страницам tldr, нужно установить один из клиентов. Актуальный их список приводится на этой wiki-странице. Доступны реализации на Node.js (считается «наиболее зрелым клиентом»), PHP, Python, Ruby, Perl, Go, Bash, C++, Haskell, Rust, Emacs… есть по паре версий для Android и для iOS, бот для Slack, есть два веб-интерфейса (один из которых, к слову, размещён на DistroWatch).
Веб-интерфейс tldr.ostera.io
Установка основного клиента должна выглядеть так:
npm install -g tldr
… однако в моём случае (Ubuntu) вела к необходимости инсталляции большого числа зависимостей (т.к. в системе не установлены Node.js/npm), поэтому я предпочёл такой «молодёжный» Linux-путь:
$ sudo snap install tldr
Этой командой в систему устанавливается тот самый «главный» Node.js-клиент tldr (версия 3.1.0 в текущем snap-пакете).
Что он умеет?
$ tldr
Usage: tldr command [options]
Simplified and community-driven man pages
Options:
-h, --help output usage information
-V, --version output the version number
-l, --list List all commands for the chosen platform in the cache
-a, --list-all List all commands in the cache
-1, --single-column List single command per line (use with options -l or -a)
-r, --random Show a random command
-e, --random-example Show a random example
-f, --render [file] Render a specific markdown [file]
-m, --markdown Output in markdown format
-o, --os [type] Override the operating system [linux, osx, sunos]
--linux Override the operating system with Linux
--osx Override the operating system with OSX
--sunos Override the operating system with SunOS
-t, --theme [theme] Color theme (simple, base16, ocean)
-s, --search [keywords] Search pages using keywords
-u, --update Update the local cache
-c, --clear-cache Clear the local cache
Examples
$ tldr tar
$ tldr du --os=linux
$ tldr --search "create symbolic link to file"
$ tldr --list
$ tldr --list-all
$ tldr --random
$ tldr --random-example
To control the cache
$ tldr --update
$ tldr --clear-cache
To render a local file (for testing)
$ tldr --render /path/to/file.md
Посмотрим список доступных страниц:
$ tldr -l
Local cache is empty
Please run tldr --update
Их (локально) ещё нет, но дело поправимое:
$ tldr --update
Updating...
{ Error: ENOENT: no such file or directory, unlink '/home/user/snap/tldr/162/.tldr/cache/pages/shortIndex.json'
at Error (native)
errno: -2,
code: 'ENOENT',
syscall: 'unlink',
path: '/home/user/snap/tldr/162/.tldr/cache/pages/shortIndex.json' }
Done
Creating index...
Done
$ tldr -l
7z, 7za, 7zr, ab, ack, adb, adduser, ag, alias, alpine, ansible, ansible-galaxy, ansible-playbook, ...
Всего там было 671 вхождение. Откуда они берутся? Зафиксировано в config.json клиента. А дальше всё просто:
$ tldr ls
ls
List directory contents.
- List files one per line:
ls -1
- List all files, including hidden files:
ls -a
- Long format list (permissions, ownership, size and modification date) of all files:
ls -la
- Long format list with size displayed using human readable units (KB, MB, GB):
ls -lh
- Long format list sorted by size (descending):
ls -lS
- Long format list of all files, sorted by modification date (oldest first):
ls -ltr
$ tldr tldr
tldr
Simplified man pages.
- Get typical usages of a command (hint: this is how you got here!):
tldr command
- Update the local cache of tldr pages:
tldr --update
Учтите, что все справки только на английском языке (и инициатив по их локализации не видно).
Альтернативы и резюме
Прямо в README проекта tldr приводятся и альтернативные варианты, решающие ту же задачу — «упрощения» man-страниц:
- Cheat — написанная на Python утилита (имеет и реализации на Bash), поддерживает около 180 страниц;
- eg — ещё один аналог на Python, который обладает гораздо меньшей библиотекой и реже обновляется;
- bropages — веб-проект (и консольный клиент на Ruby, но он давно не обновлялся), где сообщество пополняет в онлайне базу лаконичных примеров использования консольных команд.
Глядя на имеющиеся альтернативы, очевидно, что tldr удалось далеко уйти вперёд своих конкурентов. Так что если потребность в подобном приложении/сервисе есть — однозначно стоит обратить внимание на эту утилиту.
Впрочем, всё это не отменяет необходимости в полноценной документации, которая даёт гораздо более полное представление о принципах работы и возможностях утилиты, имеется у каждого продукта (где минимально об этом позаботились сами разработчики), содержит все актуальные сведения (а они могут меняться с разными версиями).
