--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 удалось далеко уйти вперёд своих конкурентов. Так что если потребность в подобном приложении/сервисе есть — однозначно стоит обратить внимание на эту утилиту.
Впрочем, всё это не отменяет необходимости в полноценной документации, которая даёт гораздо более полное представление о принципах работы и возможностях утилиты, имеется у каждого продукта (где минимально об этом позаботились сами разработчики), содержит все актуальные сведения (а они могут меняться с разными версиями).
Комментарии (33)
KawaiDesu
05.12.2017 11:18Тезисно:
1) Лучше бы проinfoрассказали
2) tldr хрень, потому что не даёт понимания того, как работает программа. Это инструкции в духе «нажмите сюда, чтобы получить это». Подходит программистам, котроые не желают разбираться в вопросе и им нужно просто быстро сделать.
3) В man просто зачастую не хватает примеров использования (они есть только у некоторых программ).VioletGiraffe
05.12.2017 11:32Как будто чтение 5-страничного перечисления ключей и их комбинаций даёт понимание, как работает программа. Не говоря уж о том, что для конечного пользователя это знание вторично и часто бесполезно.
KawaiDesu
05.12.2017 11:43Ну возьмём
jq. Без чтения мана не поймёте вы до конца как им пользоваться. Да, можно наугад по примерам получить желаемое поведение. В мане же достаточно внятно описано, как работают операторы и как происходит обработка. То есть описание как делает, а не что делает.
Верно и обратное — без примеров освоить прочитанный материал иногда непросто.
TITnet
05.12.2017 14:21Соглашусь.
Регулярно приходится прогонять ответ от сервера через jq, чтобы потом положить его в буфер обмена.
Кто бы знал, что просто так передать через pipe результат разбора json нельзя.
$ curl example.com | jq | pbcopy
Такое работать не будет.
Нужно добавить пустые кавычку в качестве параметра для jq.
$ curl example.com | jq '' | pbcopy
Такие сценарии, как скопировать результат в буфер, вполне можно было бы положить в tldr.KawaiDesu
05.12.2017 15:01Можно просто точку, даже без кавычек. Да и сама документация
jqнеплохо наполнена базовыми примерами, так чтоjqтут только в качестве примера программы, которую однми примерами можно и не осилить. Есть недочёты, конечно, но что-то менее тривиальное решается или вдумчивым чтением и/или гуглением.
Delphinum
05.12.2017 17:12-1Юзеры делятся на программистов и пользователей. Первые умеют собирать из мелких компонентов программы, решающие их задачи; вторые хотят получить готовую программу, которая позволяет решить их задачу тыканьем на кнопки. Проблема в том, что вторые лезут в сферы, созданные для первых, и при этом умудряются жаловаться.
VioletGiraffe
05.12.2017 17:15+1Если первые не предоставили вторым инструментов для решения повседневных задач, вторым приходится выходить из положения самостоятельно.
Но вообще, ваше деление слишком бинарно, ещё и намекает на некое превосходство первых над вторыми. Хотя именно первые пишут запутанные и корявые программы, в которых невозможно разобраться, не прочитав три разных форума.
Hardcoin
05.12.2017 12:46+1Я уже знаю, как работает tar, уже прочитал man. Но ключи не запомнил и не планирую. Короткий список примеров — это самое то.
ainoneko
06.12.2017 09:02Для tar проще запомнить «стрелочку» («гарпун»?) на клавиатуре из букв zxcvf, из которой при использовании надо выбросить c или x (оставить x или c, соответственно — eXtract или Create) и можно выбросить v (Verbose, если не хочется видеть, что происходит).
mistergrim
05.12.2017 20:31> Это инструкции в духе «нажмите сюда, чтобы получить это». Подходит программистам, котроые не желают разбираться в вопросе и им нужно просто быстро сделать.
Джвадцать два года жду таких мануалов.
Но, конечно, это всё не взлетит. Man — это уже навсегда.
BeppeGrillo
05.12.2017 15:12node.js да ещё и в snap для программы чуть более сложной чем cat это, конечно, 5.
Остановите планету, я сойду.
shurup Автор
05.12.2017 15:18В чём-то согласен, но не спешите сходить: есть ведь клиент и на плюсах с Makefile… и много других вариантов (на их список приведена ссылка в статье). Обычный для наших дней
зоопаркразнообразие от Open Source-сообщества, что лишь подтверждает интерес людей к проекту.
webkumo
05.12.2017 20:10А можно готовый нативный deb пакет в базовом репозитории ubuntu или debian?
shurup Автор
06.12.2017 05:52Обсуждалось много тут, но TL;DR заключается в том, что так и не сделали, даже в PPA.
Самый простой вариант без зависимостей и компиляции — это клиенты на Bash (инструкции по установке взяты от разработчиков — понятно, что исправляются по вкусу):
№1
loc=/usr/local/bin/tldr # elevated privileges needed for some locations sudo wget -qO $loc https://4e4.win/tldr sudo chmod +x $loc
№2
mkdir -p ~/bin curl -o ~/bin/tldr https://raw.githubusercontent.com/raylee/tldr/master/tldr chmod +x ~/bin/tldr export PATH=~/bin:$PATH
LESHIY_ODESSA
06.12.2017 16:08Без зависимостей говорите? Попробовал установить на роутер. Всё отлично, кроме того, что при установке нужен curl, которого в роутере естественно нет. Ну ладно загрузил через wget. А потом:
/home/root/bin # ~/bin/tldr ls
tldr requires `curl` installed in your path
/home/root/bin # ~/bin/tldr ls
shurup Автор
06.12.2017 16:56Каюсь, был не прав, т.к. предположил, а не попробовал. Справедливости ради, об этом написано в README:
Prerequisites
curl needs to be available somewhere in your $PATH. The script is otherwise self-contained.
mihmig
05.12.2017 15:15Всегда умиляли man-ы отсутствием примеров(!). Это заговор какой-то?
Трудно написать пару-тройку примеров для наиболее типовых ситуаций использования?
mibori
05.12.2017 17:41с недавнего времени пользуюсь официальным tldr и iOS. Не хватает возможности приватных страниц. То есть хочется примеров и отдельных страниц, которые не стоит класть в общий репозиторий. Думаю как это лучше сделать.
sena
05.12.2017 20:00Зачем создавать свой формат, своих клиентов? Есть же уже стандартные форматы man, info, для которых уже созданы просмотрщики на любой вкус.
Ну делали бы себе страницы с суффиксом -tldr. Тогда
man ls
выдавал бы стандартную доку, а
man ls-tldr
упрощённую. Или просто дополнили бы уже имеющиеся страницы документации.
Нет, нужно всё выкинуть и мы наш, мы новый мир построим, с блэджеком…JIghtuse
06.12.2017 17:45Меня вся эта фигня тоже смутила, когда она появилась (bropages, tldr, вот это всё). Сделал конвертирующий скрипт и репозиторий с настоящими манами, на github лежит.
На всякий случай ещё призову тех, кто про нормальный формат выше обсуждал: BeppeGrillo, webkumo, Meklon, LESHIY_ODESSA.
lxsmkv
05.12.2017 21:09Это несомненно шаг в правильном направлении. Жаль, что эволюция в этой области идет очень медленно.
Design of information presentation is undergoing significant changes.
Documents are information interfaces that must dynamically reconfigure
themselves based on their content, the medium in which theyare displayed,
and the intended use of the information they present.
— Louis Murray Weitzman, 1995 «The Architecture of Information» [p.3]
kalininmr
06.12.2017 04:11как то он напоминает незаслуженно забытый info.
shurup Автор
06.12.2017 06:00Он забыт умышленно, потому что подход GNU к инструкциям/документации в корне отличается от идеи tldr. Цитата из GNU Coding Standards:
Make sure your manual is clear to a reader who knows nothing about the topic and reads it straight through. This means covering basic topics at the beginning, and advanced topics only later. This also means defining every specialized term when it is first used. [..] In general, a GNU manual should serve both as tutorial and reference. It should be set up for convenient access to each topic through Info, and for reading straight through (appendixes aside).
ainoneko
06.12.2017 09:13У меня какой-то другой tldr поставился
(Python-клиент, черезpip install tldr.py:
другие параметры используются:neko@venus:~$ tldr
Usage: tldr [OPTIONS] COMMAND [ARGS]...
A python client for tldr: simplified and community-driven man pages.
Options:
-V, --version Show the version and exit.
-h, --help Show this message and exit.
Commands:
find Find the command usage.
init Init config file.
locate Locate the command's man page.
reindex Rebuild the index.
update Update to the latest pages.
ob1
06.12.2017 10:59На Linux и Mac пользуюсь man и проблем не знаю. Если недостаточно информации или примеров, то изучаю документацию на сайте разработчика или «гуглю». Сомнительно, что в tldr угодят всем, иначе они превратятся в man. В tldr непонятно как будут поддерживать всё существующее ПО. Многие man пишут сами разработчики. Зачем придумывать свой формат? В заметке об этом не сказано. Т.е. tldr, на мой взгляд, это что-то нишево-хипстерское.
Интересное решение со справкой реализовано в QNX. Справочная информация внедряется в виде отдельной секции в исполняемый файл или подгружаемый модуль (.so). В QNX 6 это ELF, а в QNX 4 это MLF. Называется это дело usage. Одноимённая утилита добавляет справку в модуль, а просматривать можно при помощи утилиты use. Достоинства очевидны — справка всегда доступна, когда доступен исполняемый модуль.
vesper-bot
Имхо было бы правильнее доки мана помечать секциями, которые подразделять на essential, general, advanced, examples и может ещё что (а-ля Powershell «get-help command»), а потом, если надо тебе полную справку, man command --full, получи все секции, --advanced — получи всё кроме примеров, --examples — только примеры, без доп.параметра — только essential и general, --brief — только essential. В этом плане в Powershell довольно приятно сделали.
eoffsock
Или разделить ман по уровням сложности Дума: сначала самое базовое (I'm too young to die), потом более развернуто (Hey, not too rough) и так далее до Nightmare с какими-нибудь дикими примерами.
acmnu
Наверное так было бы лучше, но на самом деле большие маны принято разделять по подкомандам. Например Git обладает манами git-push, git-commit и т.д.
При чем следующие команды дают один и тот же результат:
vesper-bot
Ну да, какой-нибудь man ip rule. Хорошо, но имхо маловато, особенно когда описание одного параметра на десяток строк, а их в средней команде в линуксе дюжины две.