Файлы документации утилиты man

Файл документации man можно создать в любом текстовом редакторе. Его название должно совпадать с названием команды или темы, о которой идет речь в документе, а расширение должно совпадать с номером раздела. Название документа, описывающего команду who, будет иметь вид who.l. В примере, использующемся в этой главе, разра­батываемый документ описывает команду bookrec и имеет раздел с номером 1. Его имя будет иметь вид bookrec.1. Номера разделов обсуждаются чуть позже, в разделе, посвященном описанию каталогов man.

Документ утилиты man разбит на разделы, в верхней части которых размещаются названия. Разделы могут называться произвольным образом. Обычно используется со­глашение, в соответствии с которым документ man для команды LINUX должен иметь такие разделы, как NAME, SYNOPSIS и DESCRIPTION. Однако количество разделов для приложения не ограничено, и названия остальных разделов могут быть выбраны произвольно. Создаваемый документ представляет собой неформатированный текст с заданными макросами man. Любое руководство должно содержать как минимум два макроса, ТН и SH. Макрос ТН обеспечивает формирование заголовков и номеров раз­делов, которые будут отображаться в верхней части каждой страницы документа. Заго­ловки разделов формируются с помощью макроса SH. Для удобства просмотра доку­ментации можно добавить и другие макросы, такие как макрос РР для форматирования параграфов, макрос IP — для формирования отступов абзацев. Список макросов man приведен в табл. 5.

Для ввода макроса следует указать его имя (с предшествующей точкой) в начале строки. Весь текст, который вводится в последующих строках, форматируется с ис­пользованием данного макроса. Действие макроса продолжается до того места, в ко­тором будет введен следующий макрос. Некоторые макросы, такие как SH и ТН, имеют параметры. Значения параметров вводятся сразу после макроса, в той же самой строке. Для макроса SH в качестве параметра выступает название раздела. Вводить его следует в той же строке, в которой записан макрос. Затем следует текст раздела. Этот текст вводится в виде набора коротких строк. Позднее эти строки будут отформатированы с помощью man, образуя выровненные абзацы. В следующем примере пользователь вводит макрос SH и название раздела DESCRIPTION. В последующих строках поль­зователь вводит текст раздела.

.SH DESCRIPTION

. I bookrec

позволяет пользователю вводить заголовок и цену

книги. Затем отображаются оба элемента

записи

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

.ТН COMMAND Section -number

.SH NAME

Команда и краткое описание выполняемых ею функций

. SH SYNOPSIS

Команда и ее параметры. Каждый параметр заключен в скобки. Этот раздел

иногда называется SYNTAX.

.SH DESCRIPTION

Детальное описание команды и ее параметров. Для формирования абзацев

используются макросы РР, LP и IP

.SH OPTIONS

Параметры, используемые командой

. SH EXAMPLES

Примеры использования команды.SH FILE

Файлы, которые использует команда

.SH "SEE ALSO"

Ссылки на другие документы или руководства

.SH DIAGNOSTICS

Описание нестандартных ситуаций

.SH WARNINGS

Замечания о возможных проблемах, возникающих при использовании команды.SH BUGS

Побочные воздействия и известные ошибки.

Внутри текста раздела можно использовать и другие макросы, например для вы­полнения специальных операций обработки текста. Подобные макросы вводятся в от­дельной строке. Некоторые из них требуют указания параметров. Макрос.РР начинает новый абзац. Макрос.IP начинает абзац с отступом и обычно используется для описания какой-либо опции команды. Эта опция задается в качестве параметра макроса.IP. Текст, который следует за этим макросом, будет обозначен отступом. Макрос Л применяется для выполнения подчеркивания текста. Макрос.В применяется для отображения текста полужирным шрифтом. В качестве параметров для этих макросов применяется слово, которое требуется выделить или подчеркнуть. Обычно используется соглашение о вы­делении названия команды и ее параметров в разделе NAME полужирным шрифтом, для чего используется макрос.В. В остальных разделах название команды обычно вы­деляется с помощью макроса Л. Если в тексте имеются дефисы, их следует предварять символами обратной косой черты.

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

bookrec.1 — вывод справочного руководства с помощью команды man

.ТН BOOKREC 1

.SH NAME

bookrec \-Input and display a book record

.SH SYNOPSIS

.B bookrec

[ \-t ] [ \-p] [ \-f]

.SH DESCRIPTION

.I bookrec

Разрешает пользователю вводить наименование и цену книги.

Затем отображаются оба элемента записи

.SH OPTIONS

.IP t

Отображение одного названия.

.IP р

Отображение одной цены.

.IP f

Сохранение записи в файле.

.SH FILES

Для выполнения команды не требуются другие файлы.

. SH "SEE ALSO"

printbook (1).SH DIAGNOSTICS

Формат даты при выводе м/д/г.

.SH BUGS

Эта программа может считывать и отображать всего лишь одну запись.

-br

Не допускается считывание записей из файла.

Утилита man ищет справочные документы по конкретным темам в специальном системном каталоге, например в /usr/man. Сам каталог /usr/man не содержит справоч­ных документов. В нем находятся подкаталоги, называемые подкаталогами разделов, которые и содержат требуемые документы. Названия каталогов разделов начинаются со слова man, а заканчиваются номером раздела, например manl — это название каталога для первого раздела в руководстве. Обычно существует около семи отдельных каталогов, начиная с manl и заканчивая man7. В каталоге документации для конкретного прило­жения может быть столько подкаталогов разделов, сколько необходимо, и в обязатель­ном порядке там будет присутствовать подкаталог с названием manl.

Каталоги разделов позволяют создать несколько документов различной степени слож­ности, в которых всесторонне рассматривается одна и та же команда. Эти доку­менты различаются номером раздела и размещены в соответствующих каталогах раз­делов. Номер раздела в документе, как отмечено ранее, указывается в качестве параметра в макросе.ТН. Для того чтобы извлечь интерактивный документ о конкретном разделе, введите номер этого раздела перед названием команды. В следующем примере вызы­вается документ, описывающий команду bookrec, который находится в каталоге третье­го раздела. Если номер раздела не указывается, то будет выведена документация по первому разделу.

5 man 3 bookrec

Таблица 5. Команды и макросы man. используемые для создания интерактивных документов
Команды и опции____ Описание__________________________________

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

man имя_команды Поиск и отображение интерактивных справочных документов

Поиск по сайту: