company_banner

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

    Впрочем, всё это не отменяет необходимости в полноценной документации, которая даёт гораздо более полное представление о принципах работы и возможностях утилиты, имеется у каждого продукта (где минимально об этом позаботились сами разработчики), содержит все актуальные сведения (а они могут меняться с разными версиями).
    Флант
    DevOps-as-a-Service, Kubernetes, обслуживание 24×7

    Комментарии 34

      +4
      Имхо было бы правильнее доки мана помечать секциями, которые подразделять на essential, general, advanced, examples и может ещё что (а-ля Powershell «get-help command»), а потом, если надо тебе полную справку, man command --full, получи все секции, --advanced — получи всё кроме примеров, --examples — только примеры, без доп.параметра — только essential и general, --brief — только essential. В этом плане в Powershell довольно приятно сделали.
        +2
        Или разделить ман по уровням сложности Дума: сначала самое базовое (I'm too young to die), потом более развернуто (Hey, not too rough) и так далее до Nightmare с какими-нибудь дикими примерами.
          0

          Наверное так было бы лучше, но на самом деле большие маны принято разделять по подкомандам. Например Git обладает манами git-push, git-commit и т.д.


          При чем следующие команды дают один и тот же результат:


          man git-push
          man git push
            0
            Ну да, какой-нибудь man ip rule. Хорошо, но имхо маловато, особенно когда описание одного параметра на десяток строк, а их в средней команде в линуксе дюжины две.
          –5
          Тезисно:
          1) Лучше бы про info рассказали
          2) tldr хрень, потому что не даёт понимания того, как работает программа. Это инструкции в духе «нажмите сюда, чтобы получить это». Подходит программистам, котроые не желают разбираться в вопросе и им нужно просто быстро сделать.
          3) В man просто зачастую не хватает примеров использования (они есть только у некоторых программ).
            +12
            Как будто чтение 5-страничного перечисления ключей и их комбинаций даёт понимание, как работает программа. Не говоря уж о том, что для конечного пользователя это знание вторично и часто бесполезно.
              +3
              Ну возьмём jq. Без чтения мана не поймёте вы до конца как им пользоваться. Да, можно наугад по примерам получить желаемое поведение. В мане же достаточно внятно описано, как работают операторы и как происходит обработка. То есть описание как делает, а не что делает.
              Верно и обратное — без примеров освоить прочитанный материал иногда непросто.
                0
                Соглашусь.
                Регулярно приходится прогонять ответ от сервера через jq, чтобы потом положить его в буфер обмена.
                Кто бы знал, что просто так передать через pipe результат разбора json нельзя.

                $ curl example.com | jq | pbcopy
                


                Такое работать не будет.
                Нужно добавить пустые кавычку в качестве параметра для jq.

                $ curl example.com | jq '' | pbcopy
                


                Такие сценарии, как скопировать результат в буфер, вполне можно было бы положить в tldr.
                  0
                  Можно просто точку, даже без кавычек. Да и сама документация jq неплохо наполнена базовыми примерами, так что jq тут только в качестве примера программы, которую однми примерами можно и не осилить. Есть недочёты, конечно, но что-то менее тривиальное решается или вдумчивым чтением и/или гуглением.
                –2
                Юзеры делятся на программистов и пользователей. Первые умеют собирать из мелких компонентов программы, решающие их задачи; вторые хотят получить готовую программу, которая позволяет решить их задачу тыканьем на кнопки. Проблема в том, что вторые лезут в сферы, созданные для первых, и при этом умудряются жаловаться.
                  0
                  Если первые не предоставили вторым инструментов для решения повседневных задач, вторым приходится выходить из положения самостоятельно.
                  Но вообще, ваше деление слишком бинарно, ещё и намекает на некое превосходство первых над вторыми. Хотя именно первые пишут запутанные и корявые программы, в которых невозможно разобраться, не прочитав три разных форума.
                +8

                Я уже знаю, как работает tar, уже прочитал man. Но ключи не запомнил и не планирую. Короткий список примеров — это самое то.

                  –9
                  Вы попадаете под пункт 2.
                    +2
                    А вы себя к какому пункту причисляете?
                    Реально знаете все-все команды и их ключи, с учетом версий программ?
                    0
                    Для tar проще запомнить «стрелочку» («гарпун»?) на клавиатуре из букв zxcvf, из которой при использовании надо выбросить c или x (оставить x или c, соответственно — eXtract или Create) и можно выбросить v (Verbose, если не хочется видеть, что происходит).
                    0
                    > Это инструкции в духе «нажмите сюда, чтобы получить это». Подходит программистам, котроые не желают разбираться в вопросе и им нужно просто быстро сделать.

                    Джвадцать два года жду таких мануалов.

                    Но, конечно, это всё не взлетит. Man — это уже навсегда.
                    +9
                    node.js да ещё и в snap для программы чуть более сложной чем cat это, конечно, 5.
                    Остановите планету, я сойду.
                      0
                      В чём-то согласен, но не спешите сходить: есть ведь клиент и на плюсах с Makefile… и много других вариантов (на их список приведена ссылка в статье). Обычный для наших дней зоопарк разнообразие от Open Source-сообщества, что лишь подтверждает интерес людей к проекту.
                        0

                        А можно готовый нативный deb пакет в базовом репозитории ubuntu или debian?

                          0
                          Я тоже не нашел. Хотел просто консольный вариант.
                            0
                            Обсуждалось много тут, но 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
                              0
                              Без зависимостей говорите? Попробовал установить на роутер. Всё отлично, кроме того, что при установке нужен curl, которого в роутере естественно нет. Ну ладно загрузил через wget. А потом:

                              /home/root/bin # ~/bin/tldr ls
                              tldr requires `curl` installed in your path
                              /home/root/bin # ~/bin/tldr ls
                                0
                                Каюсь, был не прав, т.к. предположил, а не попробовал. Справедливости ради, об этом написано в README:
                                Prerequisites

                                curl needs to be available somewhere in your $PATH. The script is otherwise self-contained.
                        +9
                        Всегда умиляли man-ы отсутствием примеров(!). Это заговор какой-то?
                        Трудно написать пару-тройку примеров для наиболее типовых ситуаций использования?
                          0

                          с недавнего времени пользуюсь официальным tldr и iOS. Не хватает возможности приватных страниц. То есть хочется примеров и отдельных страниц, которые не стоит класть в общий репозиторий. Думаю как это лучше сделать.

                            +9
                            Зачем создавать свой формат, своих клиентов? Есть же уже стандартные форматы man, info, для которых уже созданы просмотрщики на любой вкус.

                            Ну делали бы себе страницы с суффиксом -tldr. Тогда
                            man ls

                            выдавал бы стандартную доку, а
                            man ls-tldr

                            упрощённую. Или просто дополнили бы уже имеющиеся страницы документации.

                            Нет, нужно всё выкинуть и мы наш, мы новый мир построим, с блэджеком…
                              +1

                              Меня вся эта фигня тоже смутила, когда она появилась (bropages, tldr, вот это всё). Сделал конвертирующий скрипт и репозиторий с настоящими манами, на github лежит.


                              На всякий случай ещё призову тех, кто про нормальный формат выше обсуждал: BeppeGrillo, webkumo, Meklon, LESHIY_ODESSA.

                                0
                                Спасибо) посмотрю обязательно.
                              0
                              Это несомненно шаг в правильном направлении. Жаль, что эволюция в этой области идет очень медленно.

                              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]
                                0
                                как то он напоминает незаслуженно забытый info.
                                  0
                                  Он забыт умышленно, потому что подход 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).
                                  0
                                  У меня какой-то другой 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.

                                  )
                                    0

                                    На Linux и Mac пользуюсь man и проблем не знаю. Если недостаточно информации или примеров, то изучаю документацию на сайте разработчика или «гуглю». Сомнительно, что в tldr угодят всем, иначе они превратятся в man. В tldr непонятно как будут поддерживать всё существующее ПО. Многие man пишут сами разработчики. Зачем придумывать свой формат? В заметке об этом не сказано. Т.е. tldr, на мой взгляд, это что-то нишево-хипстерское.


                                    Интересное решение со справкой реализовано в QNX. Справочная информация внедряется в виде отдельной секции в исполняемый файл или подгружаемый модуль (.so). В QNX 6 это ELF, а в QNX 4 это MLF. Называется это дело usage. Одноимённая утилита добавляет справку в модуль, а просматривать можно при помощи утилиты use. Достоинства очевидны — справка всегда доступна, когда доступен исполняемый модуль.

                                      0
                                      Спасибо, информация была полезной!

                                      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                                      Самое читаемое