Comments 34
Наверное так было бы лучше, но на самом деле большие маны принято разделять по подкомандам. Например Git обладает манами git-push, git-commit и т.д.
При чем следующие команды дают один и тот же результат:
man git-push
man git push
1) Лучше бы про
info
рассказали2) tldr хрень, потому что не даёт понимания того, как работает программа. Это инструкции в духе «нажмите сюда, чтобы получить это». Подходит программистам, котроые не желают разбираться в вопросе и им нужно просто быстро сделать.
3) В man просто зачастую не хватает примеров использования (они есть только у некоторых программ).
jq
. Без чтения мана не поймёте вы до конца как им пользоваться. Да, можно наугад по примерам получить желаемое поведение. В мане же достаточно внятно описано, как работают операторы и как происходит обработка. То есть описание как делает, а не что делает.Верно и обратное — без примеров освоить прочитанный материал иногда непросто.
Регулярно приходится прогонять ответ от сервера через jq, чтобы потом положить его в буфер обмена.
Кто бы знал, что просто так передать через pipe результат разбора json нельзя.
$ curl example.com | jq | pbcopy
Такое работать не будет.
Нужно добавить пустые кавычку в качестве параметра для jq.
$ curl example.com | jq '' | pbcopy
Такие сценарии, как скопировать результат в буфер, вполне можно было бы положить в tldr.
Но вообще, ваше деление слишком бинарно, ещё и намекает на некое превосходство первых над вторыми. Хотя именно первые пишут запутанные и корявые программы, в которых невозможно разобраться, не прочитав три разных форума.
Я уже знаю, как работает tar, уже прочитал man. Но ключи не запомнил и не планирую. Короткий список примеров — это самое то.
Джвадцать два года жду таких мануалов.
Но, конечно, это всё не взлетит. Man — это уже навсегда.
Остановите планету, я сойду.
А можно готовый нативный deb пакет в базовом репозитории ubuntu или debian?
Самый простой вариант без зависимостей и компиляции — это клиенты на 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
/home/root/bin # ~/bin/tldr ls
tldr requires `curl` installed in your path
/home/root/bin # ~/bin/tldr ls
Трудно написать пару-тройку примеров для наиболее типовых ситуаций использования?
с недавнего времени пользуюсь официальным tldr и iOS. Не хватает возможности приватных страниц. То есть хочется примеров и отдельных страниц, которые не стоит класть в общий репозиторий. Думаю как это лучше сделать.
Ну делали бы себе страницы с суффиксом -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]
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).
(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. Достоинства очевидны — справка всегда доступна, когда доступен исполняемый модуль.
tldr — альтернатива man с названием, говорящим за себя