Explainshell — это попытка осовременить документацию Linux, сделать её максимально понятной и доступной для широкого круга пользователей.

Знаете в чём прелесть работы в Linux для меня? Это возможность использовать для разных задач консоль, то есть командную оболочку или как её ещё называют — командную строку Линукс. Ведь большинство программ берёт своё начало из командной оболочки, и поэтому запуск и выполнение многих из них происходит намного быстрее и нагляднее именно в командной строке. Естественно, запуск команды редко происходит без добавления дополнительных опций. И как пример, самая используемая, по моему мнению, — это опция «—help», которая быстро подскажет вам, как, в самом простейшем случае, использовать ту или иную команду.

Man-страницы

Но помощь в командой строке не ограничивается только опцией «—help», и почти у всех программ командной оболочки имеется подробная документация, так называемые «man-страницы» (от английского слова manual — руководство). Это целая библиотека в Линукс, которая содержит руководства по командам, утилитам, программированию и другим областям системы. Впервые подобная документация появилась в далёком 1971 году и была рассчитана на небольшую группу экспертов. Документация для удобства была разделена по тематикам на разделы. Всего существует 8 основных разделов.

Раздел	Описание
1	Основные команды
2	Системные вызовы
3	Библиотечные функции, включая стандартную библиотеку языка C
4	Специальные файлы (обычно устройства из /dev) и драйвера
5	Форматы файлов и соглашения
6	Игры и скринсейверы
7	Прочее
8	Команды системного администрирования и демоны

Для вызова руководства по какой-либо программе нужно в командной строке набрать команду «man» и имя программы:

man ls

Как видите, документация в Линукс сама вызывается командой в консоли, и, как следствие, имеет определённые опции, а также и свою «man-страницу».

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

Документация сейчас

Как следствие, в последнее время в интернете появляются проекты, готовые устранить названные выше неудобства man-страниц. Одним из них является проект tldr, который содержит упрощённые справочники по наиболее распространённым случаям использования линукс команд. Проект поддерживается сообществом и призван стать более простым и доступным дополнением традиционным man-страницам.

Ещё один подобный инструмент именуется shell.how, который более предназначен для пользователей MacOS. Но так как и Linux, и MacOS имеют одни корни, то и используемые ими инструменты командной оболочки у них одинаковы. Однако shell.how выдаёт менее подробные результаты, и пользоваться им менее удобно.

И наконец проект, который появился недавно — онлайн-ресурс explainshell. Особенностью данного проекта является то, что это инструмент с веб-интерфейсом, который разбирает man-страницы, извлекает опции и объясняет заданную командную строку, сопоставляя каждый аргумент с соответствующим текстом справки на man-странице. А ещё этот инструмент может оказаться хорошим помощником в обучении.

Explainshell

Explainshell написал Идан Камара в рамках постоянно проводимой сообществом работы по повышению доступности руководства Линукс. В настоящий момент explainshell содержит весь архив документации Ubuntu, который включает в себя почти 30 тысяч man-страниц.

Разработчик использует скрипты Python для преобразования man- страниц в HTML документ, который даёт разъяснение по заданной команде. Если команда была введена с аргументами, то на каждую опцию выводится отдельный абзац с соответствующей справкой. Результаты выводятся с помощью Flask, легкого веб-приложения для Python, что обеспечивает быстроту работы explainshell.

Запуск explainshell локально

Для того чтобы запустить explainshell на своём компьютере необходимо создать рабочую среду, позволяющую запускать веб-интерфейс, с помощью docker. Сначала надо будет скачать дамп базы данных explainshell.

curl -L -o /tmp/dump.gz https://github.com/idank/explainshell/releases/download/db-dump/dump.gz

Затем клонировать (скопировать) репозиторий локально:

git clone https://github.com/idank/explainshell.git

Далее необходимо запустить контейнер, загрузить man-страницы из дампа:

docker-compose build

docker-compose up

docker-compose exec -T db mongorestore --archive --gzip < /tmp/dump.gz

Осталось провести тест, чтобы убедиться в работоспособности контейнера:

docker-compose exec -T web make tests

В случае успешного завершения теста документацию можно открыть в браузере по адресу: http://localhost:5000

Помощь в программировании

Explainshell судя по названию предназначен для работы с документацией командной оболочки. Это впрочем и не удивительно, учитывая, что языки программирования не включены в man-страницы Ubuntu. Но автор explainshell разработал ещё один инструмент, который может помочь разобрать не понятные фрагменты кода. Этот инструмент он назвал «showthedocs».

«Showthedocs — это попытка улучшить рабочий процесс. Он является одновременно подсветкой синтаксиса и браузером документации. Получив код, showthedocs разбирает и выделяет его, а также позволяет перейти непосредственно к тому месту в документации, где объясняется тот или иной элемент», — комментирует Идан Камара.

Стоит иметь в виду, что проект находится в стадии разработки, поэтому в настоящее время поддерживается не так много языков (PostgreSQL, MySQL, NGINX и git config). Автор продолжает работать над улучшением проекта и приветствует любую помощь.

Заключение

Идан Камара утверждает, что showthedocs является расширением появившегося ранее его же проекта explainshell. Будет ли showthedocs продолжать развиваться отдельно или в конечном итоге будет объединен с explainshell, неизвестно.

Одним из больших минусов проекта explainshell является отсутствие удобного способа добавления man-страниц в свои ресурсы. Если говорить об интерфейсе, то было бы неплохо добавить кнопки навигации для тех случаев, когда справочная информация может растянуться на несколько экранов. А поле ввода явно нуждается в кнопке «Очистить».

Тем не менее по моему скромному мнению, основы мега полезного инструмента заложены. Разработчика Explainshell можно поздравить с тем, что он нашёл способ сделать архаичные man-страницы полезными для современных пользователей. Я не удивлюсь, если какой-нибудь дистрибутив, ориентированный на новичков, со временем включит локальную версию explainshell в свой репозиторий и будет устанавливать его по умолчанию.