tldr-pages

tldr-pages — открытый проект, собирающий короткие справочные страницы по командам командной строки. Каждая страница описывает команду одной фразой и даёт несколько самых нужных примеров с пояснениями. Название — интернет-аббревиатура TL;DR (too long; didn't read, «слишком длинно, не читал»): проект задуман как ответ на объёмные и сухие man-страницы, в которых трудно быстро найти типичный способ использования.

Страницы пишутся в Markdown и распространяются под свободной лицензией, поэтому их читают не только люди, но и программы — в том числе языковые модели и ассистенты в терминале.

История

Проект начал Ромен Прието в 2013 году. Со временем он перерос в сообщество с тысячами участников и организацию на GitHub, которая поддерживает репозиторий страниц, спецификацию клиентов и официальный клиент.^[2] Сегодня в коллекции тысячи страниц для разных платформ и переводы на десятки языков, включая русский.

Пример страницы

Страница — это Markdown-файл строгой структуры: заголовок с именем команды, описание в цитате, ссылка на подробную документацию и пары «пояснение — команда». Так выглядит страница для curl (сокращённо):

# curl

> Transfers data from or to a server.
> Supports most protocols, including HTTP, HTTPS, FTP, SCP, etc.
> More information: <https://curl.se/docs/manpage.html>.

- Make an HTTP GET request and dump the contents in `stdout`:

`curl {{https://example.com}}`

- Send form-encoded data (POST request of type `application/x-www-form-urlencoded`):

`curl {{[-d|--data]}} '{{name=bob}}' {{http://example.com/form}}`

Значения в двойных фигурных скобках — подстановки, которые пользователь заменяет своими. Обычно на странице не больше восьми примеров: только самые частые сценарии, а не все флаги. Правила оформления — повелительное наклонение, единые обозначения параметров, длинные и короткие формы опций — описаны в руководстве по стилю.^[4]

Организация

Страницы разложены по каталогам платформ:

Переводы лежат в отдельных каталогах pages.<язык>, например pages.ru. Клиент сначала ищет страницу для текущей платформы и языка, затем откатывается на common и английскую версию.^[3]

Клиенты

Читать страницы можно через сайт tldr.sh, но обычно ставят консольный клиент. Он скачивает архив страниц, хранит его локально и показывает страницу с подсветкой:

brew install tlrc            # официальный клиент на Rust; в Linux — пакет tlrc или cargo install tlrc
tldr tar                     # примеры для tar
tldr --platform linux ss     # страница для конкретной платформы
tldr --language ru grep      # перевод, если есть
tldr --update                # обновить локальный кэш

Популярны также tealdeer (быстрый клиент на Rust) и исторический клиент на Node.js.^[6] Поведение клиентов — порядок поиска, кэширование, обязательные ключи — закреплено в спецификации, поэтому все они взаимозаменяемы.^[3]

tldr и man

tldr не заменяет man: когда нужен редкий флаг или точная семантика, приходится открывать полную документацию (ссылка на неё есть в каждой странице). Но в повседневной работе — вспомнить синтаксис tar, find, grep или ffmpeg — короткой страницы обычно достаточно.

Значение для LLM-документации

Страницы tldr — пример документации, удобной и людям, и машинам: компактный, единообразный Markdown с примерами, которые можно сразу выполнить. Похожие идеи развивает формат llms.txt — краткая карта сайта в Markdown для языковых моделей. Свободная лицензия CC BY 4.0 разрешает использовать страницы в своих проектах при указании авторства.^[5] Внести свою страницу или перевод можно обычным pull request в репозиторий проекта.^[1]

См. также

• man-страницы
• Shell и Bash
• Markdown
• llms.txt

Источники

1. tldr-pages — официальный сайт
2. tldr-pages/tldr — репозиторий на GitHub
3. tldr-pages — Client Specification
4. tldr-pages — Style guide
5. tldr-pages — License
6. tealdeer — быстрый клиент tldr на Rust