Pull to refresh

Comments 34

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

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


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


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

$ curl example.com | jq | pbcopy


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

$ curl example.com | jq '' | pbcopy


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

)

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


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

Спасибо, информация была полезной!
Sign up to leave a comment.