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

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

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

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

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

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

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

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

СВЯЗАННЫЕ С: Как использовать команду Linux man: скрытые секреты и основы

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

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

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

 sudo apt-get установить пандок 

В Fedora вам понадобится следующая команда:

 sudo dnf установить пандок 

В Manjaro введите:

 sudo pacman -Сью пандок 

СВЯЗАННЫЕ С: Как использовать pandoc для преобразования файлов в командной строке Linux

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

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

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

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

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

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

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

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

Руководство по 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 .

СВЯЗАННЫЕ: Что такое stdin, stdout и stderr в Linux?

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

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

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

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

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

 тропинка 

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

• /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 добавить новый файл в свою базу данных, введите следующее:

 судо мандб 

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

 человек госпожа 

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

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

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

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

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

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