Man-страницы - это суперполезный ресурс для каждого пользователя Linux. Они содержат исчерпывающий список всех опций с синтаксисом и пояснениями. Добавление man-страниц к вашему скрипту или пакету повышает удобство его использования и принятия. Но задавались ли вы вопросом, как создать man-страницу для вашего скрипта или модуля? В этой статье мы узнаем, как создать man-страницы для скрипта, пакета, библиотеки в Linux. Вы можете использовать эти шаги во всех дистрибутивах Linux.
Как создать Man-страницы для скрипта, пакета, библиотеки в Linux
Обычно man-страницы пишутся с использованием множества макросов форматирования. Когда вы вызываете команду man, она вызывает команду groff, которая разбирает файл man для команды и форматирует его вывод, который передается команде less и затем отображается у вас. Написание макросов форматирования - очень утомительный процесс, который может оказаться сложным для новичков.
К счастью, существует множество других инструментов, которые помогут вам создать man-страницы. Для нашей цели мы будем использовать утилиту pandoc, которая намного проще в использовании.
Программа Pandoc читает файлы в формате markdown и генерирует форматированный вывод на 40 различных языках разметки и форматах файлов, включая man-страницы. Pandoc позволяет легко определить содержимое man-страницы, используя простые файлы разметки, вместо написания макросов.
1. Установите Pandoc
Откройте терминал и выполните следующую команду для установки инструмента pandoc.
Ubuntu, Debian
| 1 | sudo apt-get install pandoc |
Redhat, Fedora, SUSE
| 1 | sudo dnf install pandoc |
CentOS
| 1 2 3 4 | wget https://github.com/jgm/pandoc/releases/download/3.1/pandoc-3.1-linux-amd64.tar.gz tar -xvf pandoc-3.1-linux-amd64.tar.gz ln -s /root/pandoc-3.1/bin/pandoc /usr/bin/pandoc yum install texlive-xetex |
2. Разделы man-страниц
Прежде чем приступить к созданию man-страницы с помощью pandoc, необходимо ознакомиться с различными разделами man-страниц, чтобы правильно ее оформить.
Вот минимальные разделы, которые должна иметь man-страница.
- Имя: Имя команды с однострочным описанием ее функции.
- Синопсис: краткое описание вызовов, которые можно использовать для запуска программы. Синтаксис команды с вставками для опций и параметров.
- Описание: Описание команды или функции.
- Опции: Список опций командной строки с пояснениями.
- Примеры: Некоторые примеры общего использования.
- Значения выхода: Коды возврата с их значениями.
- Ошибки: Список известных ошибок и проблем. Вы также можете включить ссылки на трекер проблем, если таковой имеется.
- Автор: Человек или люди, написавшие команду.
- Авторское право: Ваше сообщение об авторских правах с информацией о лицензии.
Существует множество других разделов, применимых для man-страницы, но вышеперечисленных будет достаточно.
Каждая man-страница классифицируется как один из следующих разделов руководства Linux.
- Исполняемые программы: Или команды оболочки.
- Системные вызовы: Функции, предоставляемые ядром.
- Вызовы библиотек: Функции в библиотеках программ.
- Специальные файлы.
- Форматы файлов и соглашения: Например, "/etc/passwd".
- Игры.
- Разное: Пакеты макросов и соглашения, например, groff.
- Команды системного администрирования: Обычно зарезервированы для root.
- Процедуры ядра: Обычно не устанавливаются по умолчанию.
Каждая man-страница должна указывать раздел, к которому она относится, и храниться в соответствующем месте для этого раздела.
3. Создайте разметку Man (Markdown)
Каждый раздел страницы man должен быть указан после своего знака # в начале, за которым следует пробел. Он действует как заголовок раздела. Вот упрощенная схема страницы man. Вы можете ввести свой текст под заголовком раздела.
| 1 2 3 4 5 6 7 8 9 10 11 | # НАЗВАНИЕ ... # СИНОПСИС ... # ВАРИАНТЫ ... # ПРИМЕРЫ ... |
Вы также можете отформатировать текст, добавив ** по обе стороны от текста, чтобы он отображался жирным шрифтом в man page. Вы можете добавить * по обе стороны текста, чтобы подчеркнуть его в man-странице. Вот пример раздела OPTIONS.
| 1 2 3 | # OPTIONS **-h**,**--help** : Отображает дружественное текстовое сообщение |
Использование двоеточия(:) выше вставляет текст под строку "-h, -help", а не под "OPTIONS" с отступом. Вот как это будет выглядеть в man-странице.
| 1 2 3 | OPTIONS -h, --help Отображает дружественное текстовое сообщение. |
Конечно, существует множество других правил форматирования. Для нашего примера мы рассмотрели лишь небольшое подмножество.
4. Создайте страницу Man
Допустим, вы сохранили приведенный выше текст для команды 'ms' в файле ms.1.md. Вот команда pandoc для сохранения этого файла в man-странице ms.1.
| 1 | pandoc ms.1.md -s -t man -o ms.1 |
Теперь, когда у нас есть файл man-страницы, нам нужно сохранить его в нужном месте. Для этого выполните команду manpath.
| 1 | manpath |
В результате вы получите следующую информацию.
- /usr/share/man: местонахождение стандартной библиотеки страниц man. Мы не добавляем страницы в эту библиотеку.
- /usr/local/share/man: Эта символическая ссылка указывает на "/usr/local/man".
- /usr/local/man: Здесь мы должны разместить нашу новую страницу man.
Сначала мы создадим отдельную подпапку man1 для нашей команды. Если ваша команда имеет более 1 man-страницы, вы можете хранить их в папках man2, man3, ... здесь.
| 1 | sudo mkdir /usr/local/man/man1 |
Затем скопируйте созданный файл ms.1 в эту папку.
| 1 | sudo cp ms.1 /usr/local/man/man1 |
Вам необходимо сжать этот файл для команды man, так как это необходимо.
| 1 | sudo gzip /usr/local/man/man1/ms.1 |
Выполните следующую команду, чтобы добавить страницы man в базу данных man.
| 1 | sudo mandb |
Вот и все. Теперь вы можете получить man-страницу для вашей команды ms с помощью следующей команды.
| 1 | man ms |
Заключение
В этой статье мы узнали, как создать man-страницу в Linux.