Как создать справочную страницу в Linux

Хотите, чтобы ваша новая программа для Linux выглядела профессионально? Дайте ему страницу man. Мы покажем вам самый простой и быстрый способ сделать это.

справочные страницы

В старой шутке про Unix есть зерно истины: «Единственная команда, которую вам нужно знать, это man». Страницы man содержат массу информации, и они должны быть первым местом, куда вы обращаетесь, когда хотите узнать о команде.

Предоставление страницы man для написанной вами утилиты или команды превращает ее из полезного фрагмента кода в полноценный пакет Linux. Люди ожидают, что для программы, написанной для Linux, будет предоставлена страница man. Если вы изначально поддерживаете Linux, страница man обязательна, если вы хотите, чтобы к вашей программе относились серьезно.

Исторически страницы man писались с использованием набора макросов форматирования. Когда вы вызываете man для открытия страницы, он вызывает groff для чтения файла и создания форматированного вывода в соответствии с макросами в файле. Вывод передается в less, а затем отображается для вас.

Если вы не создаете страницы man часто, написание одной страницы и вставка макросов вручную будет тяжелой работой. Процесс создания страницы man, которая правильно анализируется и выглядит правильно, может превзойти вашу цель предоставить краткое, но подробное описание вашей команды.

Вы должны сосредоточиться на своем контенте, а не бороться с непонятным набором макросов.

пандок спешит на помощь

Программа pandoc читает файлы разметки и создает новые примерно на 40 различных языках разметки и форматах документов, включая страницу man. Он полностью меняет процесс написания страницы man, поэтому вам не нужно возиться с иероглифами.

Для начала вы можете установить pandoc в Ubuntu с помощью этой команды:

sudo apt-get install pandoc

В Fedora вам нужна следующая команда:

sudo dnf install pandoc

В Manjaro введите:

sudo pacman -Syu pandoc

Разделы man-страницы

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

Как минимум, большинство справочных страниц содержат следующие разделы:

• Имя: название команды и краткий однострочный текст, описывающий ее функцию.
• Краткий обзор: краткое описание вызовов, которые можно использовать для запуска программы. Они показывают типы допустимых параметров командной строки.
• Описание: описание команды или функции.
• Параметры. Список параметров командной строки и их назначение.
• Примеры: некоторые примеры общего использования.
• Значения выхода: возможные коды возврата и их значения.
• Ошибки: список известных ошибок и особенностей. Иногда это дополняется (или заменяется) ссылкой на систему отслеживания проблем для проекта.
• Автор: человек или люди, написавшие команду.
• Авторское право: Ваше сообщение об авторских правах. Они также обычно включают тип лицензии, под которой выпускается программа.

Если вы просмотрите некоторые из более сложных страниц man, вы увидите, что есть много других разделов. Например, попробуйте man man. Однако вам не обязательно включать их все — только те, которые вам действительно нужны. Страницы man не место для многословия.

Некоторые другие разделы, которые вы будете видеть довольно часто:

• См. также: другие команды, относящиеся к теме, которые некоторые сочтут полезными или актуальными.
• Файлы: список файлов, включенных в пакет.
• Предупреждения. Другие моменты, которые следует знать или на которые следует обратить внимание.
• История: история изменений команды.

Разделы руководства

Руководство по Linux состоит из всех страниц man, которые затем разбиты на следующие пронумерованные разделы:

1. Исполняемые программы: или команды оболочки.
2. Системные вызовы: функции, предоставляемые ядром.
3. Вызовы библиотек: функции внутри программных библиотек.
4. Специальные файлы.
5. Форматы файлов и соглашения: например, «/etc/passwd».
6. Игры.
7. Разное: пакеты макросов и соглашения, такие как groff.
8. Команды системного администрирования: обычно зарезервированы для root.
9. Подпрограммы ядра: обычно не устанавливаются по умолчанию.

На каждой странице man должно быть указано, к какому разделу она принадлежит, а также она должна храниться в соответствующем месте для этого раздела, как мы увидим позже. Страницы man для команд и утилит относятся к первому разделу.

Формат man-страницы

Формат макроса groff не так просто визуально проанализировать. Напротив, уценка — это легкий ветерок.

Ниже представлена справочная страница в groff.

Эта же страница показана ниже в уценке.

Передний вопрос

Первые три строки составляют нечто, называемое вступительная часть. Все они должны начинаться со знака процента (%) без начальных пробелов, но с одним после него, за которым следует:

• Первая строка: содержит название команды, за которым следует раздел руководства в круглых скобках без пробелов. Имя становится левой и правой частями заголовка страницы man. По соглашению имя команды пишется в верхнем регистре, хотя вы найдете множество других. Все, что следует за именем команды и номером раздела руководства, становится левой частью нижнего колонтитула. Это удобно использовать для номера версии программного обеспечения.
• Вторая строка: имя(а) автора(ов). Они отображаются в автоматически сгенерированном разделе авторов на странице man. Вам не нужно добавлять раздел «Авторы» — просто укажите здесь хотя бы одно имя.
• Третья строка: дата, которая также становится центральной частью нижнего колонтитула.

Имя

Разделы обозначаются строками, начинающимися со знака номера (#), который представляет собой разметку, обозначающую заголовок в уценке. Знак номера (#) должен быть первым символом в строке, за которым следует пробел.

Раздел имени содержит яркую однострочную строку, которая включает в себя имя команды, пробел, дефис (-), пробел, а затем очень краткое описание того, что делает команда.

Синопсис

Синопсис содержит различные форматы, которые может принимать командная строка. Эта команда может принимать шаблон поиска или параметр командной строки. Две звездочки (**) по обе стороны от имени команды означают, что это имя будет отображаться жирным шрифтом на странице man. Одна звездочка (*) по обе стороны от некоторого текста приводит к тому, что на странице man он отображается подчеркнутым.

По умолчанию за разрывом строки следует пустая строка. Чтобы принудительно разорвать текст без пустой строки, можно использовать обратную косую черту (\).

Описание

Описание объясняет, что делает команда или программа. Он должен кратко освещать важные детали. Помните, вы не пишете руководство пользователя.

Использование двух цифровых знаков (##) в начале строки создает заголовок второго уровня. Вы можете использовать их, чтобы разбить описание на более мелкие фрагменты.

Параметры

Раздел параметров содержит описание любых параметров командной строки, которые можно использовать с командой. По соглашению они отображаются полужирным шрифтом, поэтому добавьте две звездочки (**) до и после них. Включите текстовое описание параметров в следующую строку и начните ее с двоеточия (:), за которым следует пробел.

Если описание достаточно короткое, man отобразит его в той же строке, что и параметр командной строки. Если он слишком длинный, он отображается как абзац с отступом, который начинается в строке ниже параметра командной строки.

Примеры

Раздел примеров содержит набор различных форматов командной строки. Обратите внимание, что мы начинаем строки описания с двоеточия (:), так же, как и в разделе параметров.

Выходные значения

В этом разделе перечислены возвращаемые значения, которые ваша команда отправляет вызывающему процессу. Это может быть оболочка, если вы вызвали ее из командной строки, или сценарий, если вы запустили ее из сценария оболочки. Строки описания в этом разделе также начинаются с двоеточия (:).

Ошибки

В разделе «Ошибки» перечислены известные ошибки, подводные камни или особенности, о которых нужно знать. Для проектов с открытым исходным кодом сюда обычно включают ссылку на систему отслеживания проблем проекта, чтобы проверить статус любых ошибок или сообщить о новых.

Авторские права

Раздел об авторских правах содержит ваше заявление об авторских правах и, как правило, описание типа лицензии, по которой выпущено программное обеспечение.

Эффективный рабочий процесс

Вы можете редактировать страницу man в своем любимом редакторе. Большинство из тех, которые поддерживают подсветку синтаксиса, будут знать об уценке и раскрашивать текст, чтобы выделять заголовки, а также выделять его жирным шрифтом и подчеркивать. Это здорово, но вы не смотрите на отрендеренную страницу man, которая является настоящим доказательством в пудинге.

Откройте окно терминала в каталоге, содержащем ваш файл уценки. Открыв его в редакторе, периодически сохраняйте файл на жесткий диск. Каждый раз, когда вы это делаете, вы можете выполнить следующую команду в окне терминала:

pandoc ms.1.md -s -t man | /usr/bin/man -l -

После того, как вы использовали эту команду, вы можете нажать стрелку вверх, чтобы повторить ее, а затем нажать Enter.

Эта команда также вызывает pandoc для файла уценки (здесь он называется «ms.1.md»):

• Опция -s (автономная) создает полную сверху вниз страницу man, а не просто текст в формате man. .
• Опция -t (тип вывода) с оператором «man» указывает pandoc генерировать вывод в формате man. Мы не указали pandoc на отправку вывода в файл , поэтому он будет отправлен на stdout.

Мы также передаем этот вывод в man с параметром -l (локальный файл). Он сообщает man не искать в базе данных man страницу man. Вместо этого он должен открыть указанный файл. Если имя файла -, man будет получать данные из stdin.

Это сводится к тому, что вы можете сохранить из своего редактора и нажать Q, чтобы закрыть man если он запущен в окне терминала. Затем вы можете нажать стрелку вверх, а затем Enter, чтобы увидеть визуализированную версию вашей страницы man прямо внутри man.

Создание вашей справочной страницы

После того, как вы завершили работу со страницей man, вам необходимо создать ее окончательную версию, а затем установить в своей системе. Следующая команда указывает pandoc создать страницу man с именем «ms.1»:

pandoc ms.1.md -s -t man -o ms.1

Это следует соглашению об именовании страницы man после команды, которую она описывает, и добавлении номера раздела руководства, как если бы это было расширение файла.

Это создает файл «ms.1», который является нашей новой страницей man. Куда мы его положим? Эта команда сообщит нам, где man ищет man страницы:

manpath

Результаты дают нам следующую информацию:

• /usr/share/man: расположение стандартной библиотеки страниц man. Мы не добавляем страницы в эту библиотеку.
• /usr/local/share/man: эта символическая ссылка указывает на «/usr/local/man».
• /usr/local/man: здесь нам нужно разместить нашу новую страницу man.

Обратите внимание, что различные разделы руководства находятся в своих собственных каталогах: man1, man2, man3 и т. д. Если каталог для раздела не существует, нам нужно его создать.

Для этого набираем следующее:

sudo mkdir /usr/local/man/man1

Затем мы копируем файл «ms.1» в правильный каталог:

sudo cp ms.1 /usr/local/man/man1

man ожидает, что страницы man будут сжаты, поэтому мы будем использовать gzip для их сжатия:

sudo gzip /usr/local/man/man1/ms.1

Чтобы заставить man добавить новый файл в свою базу данных, введите следующее:

sudo mandb

Вот и все! Теперь мы можем вызвать нашу новую страницу man так же, как и любую другую, набрав:

man ms

Наша новая страница man найдена и отображена.

Она выглядит точно так же, как и любая другая страница man, с полужирным шрифтом, подчеркнутым текстом и отступом в соответствующих местах.

Строки описания, которые подходят рядом с опцией, которую они описывают, отображаются в той же строке. Строки, длина которых слишком велика, отображаются под параметром, который они описывают.

Мы также автоматически создали раздел «Авторы». Нижний колонтитул также содержит номер версии программного обеспечения, дату и имя команды, как указано во вступительной части.

Если вы хотите . . .

После того, как pandoc создал вашу man-страницу, вы также можете напрямую отредактировать файл в формате макроса groff, прежде чем переместить его на man-страницу. каталог страницы и gzip его.