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

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

Страницы руководства

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

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

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

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

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

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

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

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

sudo apt-get install pandoc

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

sudo dnf install pandoc

На Манджаро введите:

sudo pacman -Syu pandoc

Разделы мужской страницы

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

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

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

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

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

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

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

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

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

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

Формат страницы руководства

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

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

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

Передняя Материя

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

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

имя

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

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

Синопсис

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

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

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

Раздел описания страницы руководства в разметке.

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

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

Раздел параметров на странице руководства в markdown.

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

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

Раздел примеров на странице руководства в markdown.

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

Выйти из раздела значений на странице руководства в markdown.

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

Раздел с ошибками на странице руководства в разметке.

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

Раздел авторских прав на странице руководства в markdown.

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

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

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

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

pandoc ms.1.md -s -t человек | / usr / bin / man -l — в окне терминала.

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

Эта команда также вызывает pandoc в файле уценки (здесь он называется «ms.1.md»):
Параметр -s (автономный) создает полную страницу руководства сверху вниз, а не просто текст в формате man.

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

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

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

Создание вашей мужской страницы

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

pandoc ms.1.md -s -t man -o ms.1 в окне терминала.

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

manpath

manpath в окне терминала.

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

/ usr / local / man: Здесь нам нужно разместить нашу новую страницу руководства.

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

sudo mkdir /usr/local/man/man1

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

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

Затем мы копируем файл «ms.1» в правильный каталог: man ожидает, что страницы руководства будут сжаты, поэтому мы будем использовать gzipсжать это

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

:

sudo mandb

sudo mkdir / usr / local / man / man1 в окне терминала.

man ms

man ms в окне терминала.

верхний раздел новой страницы руководства.

средний раздел новой страницы руководства.

Нижний раздел новой страницы руководства.

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

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