Все мы любим --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 удалось далеко уйти вперёд своих конкурентов. Так что если потребность в подобном приложении/сервисе есть — однозначно стоит обратить внимание на эту утилиту.

Впрочем, всё это не отменяет необходимости в полноценной документации, которая даёт гораздо более полное представление о принципах работы и возможностях утилиты, имеется у каждого продукта (где минимально об этом позаботились сами разработчики), содержит все актуальные сведения (а они могут меняться с разными версиями).