- PVSM.RU - https://www.pvsm.ru -
Все мы любим --help
и man
. Несмотря на появление многочисленных форумов, Stack Exchange и прочих ресурсов, хорошим тоном в начале решения своих проблем по-прежнему остаётся самостоятельный поиск ответа в официальной документации (и на этих ресурсах вам скорее всего об этом сразу напомнят). Однако лень продолжает двигать прогресс даже там, где не всегда того ожидаешь. Впрочем, это не только лень — бывают и другие аргументы в пользу «упрощений»…
В общем, оказалось, что классический man
утраивает не всех. Поэтому появился проект tldr [1], который, следуя своей расшифровке «Too long; didn't read», решил принести в консоль лаконичную документацию, содержащую только самое главное. Проекту tldr уже больше 3 лет, но про него ещё почему-то не писали на хабре.
Авторы tldr описывают своё детище как «коллекцию упрощённых и создаваемых сообществом man-страниц». Главным продуктом их деятельности является собственно библиотека [2] из markdown-файлов, являющихся альтернативными справочными страницами для популярных консольных утилит. Основная их часть относится к категориям «общие» и «Linux», однако есть также отдельные страницы для macOS и даже Windows.
Что хранится в этих страницах? В качестве примера в GitHub проекта [3] демонстрируется tldr-справка по tar
:
Как видно, это минимальное описание назначения утилиты и компактный список из самых частых команд. Для tar
приводится 7 готовых команд, для ls
— 6, для top
— 5.
Кому это нужно? Хороший вопрос, ответ на который оставлю на усмотрение читающим. Очевидный вариант назначения — начинающим постигать консоль (не всех получается убедить прочитать всю документацию в начале их пути, чтобы жизнь была легче потом). Так или иначе, у проекта уже более 15 тысяч stars на GitHub, более тысячи форков и больше 20 клиентов (подробнее о них см. в следующем разделе) — этих показателей достаточно для констатации: спрос есть.
ⓒ xkcd #1168: tar [4]
Чтобы получить доступ к страницам tldr, нужно установить один из клиентов. Актуальный их список приводится на этой wiki-странице [5]. Доступны реализации на Node.js (считается «наиболее зрелым клиентом»), PHP, Python, Ruby, Perl, Go, Bash, C++, Haskell, Rust, Emacs… есть по паре версий для Android и для iOS, бот для Slack, есть два веб-интерфейса (один из которых, к слову, размещён на DistroWatch [6]).
Веб-интерфейс tldr.ostera.io [7]
Установка основного клиента должна выглядеть так:
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 вхождение. Откуда они берутся [8]? Зафиксировано в config.json [9] клиента. А дальше всё просто:
$ 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-страниц:
Глядя на имеющиеся альтернативы, очевидно, что tldr удалось далеко уйти вперёд своих конкурентов. Так что если потребность в подобном приложении/сервисе есть — однозначно стоит обратить внимание на эту утилиту.
Впрочем, всё это не отменяет необходимости в полноценной документации, которая даёт гораздо более полное представление о принципах работы и возможностях утилиты, имеется у каждого продукта (где минимально об этом позаботились сами разработчики), содержит все актуальные сведения (а они могут меняться с разными версиями).
Автор: shurup
Источник [14]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/bash/269882
Ссылки в тексте:
[1] tldr: https://tldr.sh/
[2] библиотека: https://github.com/tldr-pages/tldr/tree/master/pages
[3] GitHub проекта: https://github.com/tldr-pages/tldr
[4] xkcd #1168: tar: https://xkcd.com/1168/
[5] этой wiki-странице: https://github.com/tldr-pages/tldr/wiki/TLDR-clients
[6] DistroWatch: https://distrowatch.com/dwres.php?resource=man-pages
[7] tldr.ostera.io: https://tldr.ostera.io/
[8] берутся: https://github.com/tldr-pages/tldr-node-client/blob/1788753d9d82058478a0cfc43891d50839e121a3/lib/remote.js#L8
[9] config.json: https://github.com/tldr-pages/tldr-node-client/blob/a938b7f6291a334cc1ddabee22921e202fa47882/config.json#L3
[10] Cheat: https://github.com/chrisallenlane/cheat
[11] eg: https://github.com/srsudar/eg
[12] bropages: http://bropages.org/
[13] консольный клиент: https://github.com/hubsmoke/bro
[14] Источник: https://habrahabr.ru/post/343702/
Нажмите здесь для печати.