Pull to refresh
Флант
DevOps-as-a-Service, Kubernetes, обслуживание 24×7

tldr — альтернатива man с названием, говорящим за себя

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

Впрочем, всё это не отменяет необходимости в полноценной документации, которая даёт гораздо более полное представление о принципах работы и возможностях утилиты, имеется у каждого продукта (где минимально об этом позаботились сами разработчики), содержит все актуальные сведения (а они могут меняться с разными версиями).
Tags:mantldrbash
Hubs: Флант corporate blog Configuring Linux *nix
Total votes 54: ↑51 and ↓3 +48
Views18.4K

Comments 34

Only those users with full accounts are able to leave comments. Log in, please.

Top of the last 24 hours

Information

Founded
Location
Россия
Website
flant.ru
Employees
101–200 employees
Registered
Representative
Дмитрий Шурупов