Как создать справочную страницу в Linux
Гайд в разделе Linux "Как создать справочную страницу в Linux" содержит информацию, советы и подсказки, которые помогут изучить самые важные моменты и тонкости вопроса….
Фатмавати Ахмад Зэнури / Shutterstock
Хотите, чтобы ваша новая программа для Linux выглядела профессионально? Дайте ему страницу руководства. Мы покажем вам самый простой и быстрый способ сделать это.
Страницы руководства
В старой шутке про Unix есть доля правды: «Единственная команда, которую вам нужно знать, – это man». Страницы руководства содержат множество знаний, и они должны быть первым местом, куда вы обращаетесь, когда хотите узнать о команде.
Предоставление страницы руководства для написанной вами утилиты или команды поднимает ее из полезного фрагмента кода в полностью сформированный пакет Linux. Люди ожидают, что для программы, написанной для Linux, будет предоставлена справочная страница. Если вы изначально поддерживаете Linux, страница руководства является обязательной, если вы хотите, чтобы к вашей программе относились серьезно.
Исторически страницы руководства создавались с использованием набора макросов форматирования. Когда вы вызываете man для открытия страницы, он вызывает groff для чтения файла и генерации форматированного вывода в соответствии с макросами в файле. Вывод передается в less, а затем отображается для вас.
Если вы не создаете часто страницы руководства, написание одной и вставка макросов вручную – тяжелая работа. Создание справочной страницы, которая правильно анализирует и выглядит правильно, может превзойти вашу цель и предоставить краткое, но подробное описание вашей команды.
Вы должны сконцентрироваться на своем контенте, а не бороться с непонятным набором макросов.
pandoc на помощь
Программа pandoc считывает файлы разметки и генерирует новые примерно на 40 различных языках разметки и документирует форматы, в том числе страницы руководства. Он полностью меняет процесс написания страниц руководства, так что вам не придется ломать голову над иероглифами.
Для начала вы можете установить pandoc в Ubuntu с помощью этой команды:
sudo apt-get install pandoc
В Fedora команду, которую вы необходимо следующее:
sudo dnf install pandoc
На Manjaro введите:
sudo pacman -Syu pandoc
Разделы справочной страницы
Справочные страницы содержат разделы, соответствующие стандартному соглашению об именах. Разделы, необходимые для вашей справочной страницы, продиктованы сложностью описываемой команды.
Как минимум, большинство справочных страниц содержат следующие разделы:
- Имя: Имя команда и краткое описание ее функции.
- Краткое описание: краткое описание вызовов, которые кто-то может использовать для запуска программы. Здесь показаны типы допустимых параметров командной строки.
- Описание: описание команды или функции.
- Параметры: список параметров командной строки и их назначение.
- Примеры: некоторые примеры общего использования.
- Значения выхода: возможный возврат коды и их значение.
- Ошибки: список известных ошибок и причуд. Иногда это дополняется (или заменяется) ссылкой на систему отслеживания проблем для проекта.
- Автор: человек или люди, написавшие команду.
- Авторские права: ваши авторские права сообщение. Они также обычно включают тип лицензии, под которой выпущена программа.
Если вы просмотрите некоторые из более сложных страниц руководства, вы увидите, что есть много других разделов, а также . Например, попробуйте человек мужчина. Однако необязательно включать их все – только те, которые вам действительно нужны. На страницах руководства нет места многословию.
Некоторые другие разделы, которые вы будете видеть достаточно часто:
- См. также: Другие команды, относящиеся к предмету, которые некоторые сочтут полезными или актуальными.
- Файлы: список файлов, включенных в пакет.
- Предостережения: другие моменты, на которые следует обратить внимание или на которые следует обратить внимание.
- История: история изменений для команды.
Разделы руководства
Руководство Linux состоит из всех страниц руководства, которые затем делятся на пронумерованные разделы:
Каждая страница руководства должна указывать, к какому разделу она принадлежит, и он также должен храниться в соответствующем месте для этого раздела, как мы увидим позже. Страницы руководства для команд и утилит относятся к первому разделу.
Формат страницы руководства
Формат макроса groff непросто визуально проанализировать. Напротив, уценка – это легкий ветерок.
Ниже представлена страница руководства в groff.
Та же самая страница показана ниже в разметке.
Передний вопрос
Первые три строки образуют нечто, называемое передним материалом. Все они должны начинаться со знака процента (%), без начальных пробелов, кроме одного после него, за которым следует:
- Первая строка: содержит имя команды, за которой следует раздел руководства в круглых скобках , без пробелов. Имя становится левым и правым разделами заголовка страницы руководства. По соглашению, имя команды пишется в верхнем регистре, хотя вы найдете много таких, которые таковыми не являются. Все, что следует за именем команды и номером раздела руководства, становится левым разделом нижнего колонтитула. Это удобно использовать для номера версии программного обеспечения.
- Вторая строка: имя (имена) автора (авторов). Они отображаются в автоматически созданном разделе авторов на странице руководства. Вам не нужно добавлять раздел «Авторы» – просто укажите здесь хотя бы одно имя.
- Третья строка: дата, которая также становится центральной частью нижнего колонтитула.
Имя
Разделы обозначаются строками, которые начинаются со знака числа (#), который является разметкой, указывающей заголовок в уценке. Знак числа (#) должен быть первым символом в строке, за которым следует пробел.
Раздел имени содержит краткую однострочную строку, которая включает имя команды, пробел, дефис (-), пробел, а затем очень краткое описание того, что делает команда.
Синопсис
Синопсис содержит различные форматы, которые может принимать командная строка. Эта команда может принимать шаблон поиска или параметр командной строки. Две звездочки (**) по обе стороны от имени команды означают, что имя будет отображаться жирным шрифтом на странице руководства. Одна звездочка (*) по обе стороны от некоторого текста заставляет страницу man отображать его подчеркнутым.
По умолчанию за разрывом строки следует пустая строка. Чтобы принудительно прервать разрыв без пустой строки, вы можете использовать обратную косую черту в конце ().
Описание
Описание объясняет, что делает команда или программа. Он должен кратко освещать важные детали. Помните, вы не пишете руководство пользователя.
Использование двух цифровых знаков (##) в начале строки создает заголовок второго уровня. Вы можете использовать их, чтобы разбить описание на более мелкие части.
Параметры
Раздел параметров содержит описание любых параметров командной строки, которые можно использовать с командой . По соглашению они выделены жирным шрифтом, поэтому перед и после них стоит поставить две звездочки (**). Включите текстовое описание параметров в следующую строку и начните его с двоеточия (:), за которым следует пробел.
Если описание достаточно короткое, man отобразит его в той же строке, что и команда -строчный вариант. Если он слишком длинный, он отображается в виде абзаца с отступом, который начинается в строке под параметром командной строки.
Примеры
Раздел примеров содержит выбор различных форматы командной строки. Обратите внимание, что мы начинаем строки описания с двоеточия (:), как и в разделе параметров.
Значения выхода
В этом разделе перечислены возвращаемые значения вашей команды отправляет обратно вызывающему процессу. Это может быть оболочка, если вы вызывали ее из командной строки, или сценарий, если вы запускали ее из сценария оболочки. В этом разделе мы тоже начинаем строки описания с двоеточия (:).
Ошибки
В разделе ошибок перечислены известные ошибки, подводные камни и причуды, о которых людям необходимо знать. Для проектов с открытым исходным кодом обычно включают ссылку на систему отслеживания проблем проекта, чтобы проверить статус любых ошибок или сообщить о новых.
Авторское право
Раздел об авторских правах содержит ваше заявление об авторских правах и, как правило, описание типа лицензии, по которой выпущено программное обеспечение.
Эффективный рабочий процесс
Вы можете редактировать свою справочную страницу в своем любимом редакторе. Большинство из тех, кто поддерживает выделение синтаксиса, будут знать о разметке и раскрасить текст, чтобы выделить заголовки, а также выделить жирным шрифтом и подчеркнуть его. Это замечательно, но вы не смотрите на обработанную страницу руководства, которая является настоящим доказательством в пудинге.
Откройте окно терминала в каталоге, содержащем ваш файл разметки. Открыв его в редакторе, периодически сохраняйте файл на жесткий диск. Каждый раз вы можете выполнять следующую команду в окне терминала:
pandoc ms.1.md -s -t man | / usr / bin / man -l –
После того, как вы использовали эту команду, вы можете нажать стрелку вверх, чтобы повторить ее, а затем нажать Enter.
Эта команда также вызывает pandoc в файле уценки (здесь он называется «ms.1.md ”):
- Параметр -s (автономный) создает полную страницу руководства сверху вниз, а не просто текст в формате man.
- Параметр -t Параметр (тип вывода) с оператором «man» указывает pandoc генерировать вывод в формате man. Мы не сказали pandoc отправлять свой вывод в файл, поэтому он будет отправлен на stdout.
Мы также передаем этот вывод в man с -l (local file ) вариант. Он говорит man не искать в базе данных man страницу руководства. Вместо этого он должен открыть указанный файл. Если имя файла -, man будет вводить данные со стандартного ввода.
Все сводится к тому, что вы можете сохранить в редакторе и нажать Q, чтобы закрыть man, если он запущен в окне терминала. Затем вы можете нажать стрелку вверх, а затем Enter, чтобы увидеть визуализированную версию вашей справочной страницы прямо внутри man.
Создание вашей справочной страницы
После того, как вы заполнили свою справочную страницу, вам нужно создать окончательную версию, а затем установите ее в своей системе. Следующая команда указывает pandoc создать страницу руководства с именем «ms.1»:
pandoc ms.1.md -s -t man -o ms.1
Это соответствует соглашению о присвоении имени странице руководства после команды, которую она описывает, и добавления номера раздела руководства, как если бы это было расширение файла.
Это создает файл «ms.1», который является нашим новым человеком страница. Куда мы его положим?Эта команда сообщит нам, где man ищет страницы руководства:
manpath
Результаты дают нам следующую информацию:
- / usr / share / man: расположение стандартной библиотеки страниц руководства. Мы не добавляем страницы в эту библиотеку.
- / usr / local / share / man: эта символическая ссылка указывает на «/ usr / local / man».
- / usr / local / man: Здесь нам нужно разместить нашу новую страницу руководства.
Обратите внимание, что различные разделы руководства содержатся в своих собственных каталогах: man1, man2, man3 и так далее. Если каталог для раздела не существует, нам нужно его создать.
Для этого мы вводим следующее:
sudo mkdir / usr / local / man / man1
Затем мы скопируйте файл «ms.1» в правильный каталог:
sudo cp ms.1 / usr / local / man / man1
man ожидает, что страницы руководства будут сжаты, поэтому мы будем использовать gzip для его сжатия :
sudo gzip / usr / local / man / man1 / ms.1
Чтобы заставить человека добавить новый файл в свою базу данных, введите следующее:
sudo mandb
Вот и все! Теперь мы можем вызвать нашу новую страницу руководства так же, как любую другую, набрав:
man ms
Наша новая страница руководства найдена и отображена.
Она выглядит так же, как и любая другая справочная страница, с полужирным, подчеркнутым текстом и с отступом в соответствующих местах.
Строки описания, которые соответствуют параметрам, которые они описывают, появляются в той же строке. Строки, которые слишком длинные, чтобы уместиться, появляются под опцией, которую они описывают.
Мы также автоматически создали раздел «Авторы». Нижний колонтитул также включает номер версии программного обеспечения, дату и имя команды, как определено в титульном листе.
Если хотите. .
После того, как pandoc создаст вашу справочную страницу, вы также можете напрямую отредактировать файл в формате макроса groff перед перемещением его в каталог справочной страницы и сжать его с помощью gzip.