Главная » Программирование для UNIX » Страница руководства программы написаной для UNIX

0

Основной документацией по команде обычно является страница руко водства – одностраничное описание в справочном руководстве по UNIX  (см.  рис.  9.2). Страница руководства хранится в стандартном каталоге, обычно  /usr/man, в подкаталоге с номером, соответствующим номеру раздела руководства. Страница руководства по hoc, например, хранится в /usr/man/man1/hoc.1 (так как  она описывает пользовательскую команду).

Страницы руководства выводятся при помощи команды man(1) – файла оболочки, который запускает nroff –man, поэтому man  hoc печатает руководство по hoc.  Если  одно  имя  встречается  в нескольких разделах (это касается, например, самой  команды man, так как в разделе 1 описывается команда, а в разделе 7 – макрос), можно указать для  man номер раздела:

$ man  7 man

выводит только описание макроса. По умолчанию выводятся все стра ницы с  указанным именем (используется nroff), а man  –t генерирует набранные страницы при помощи troff.

Автор  страницы руководства создает файл в соответствующем подкаталоге /usr/man. Команда man вызывает nroff или  troff с макропакетом для печати страницы, что можно увидеть, просматривая команду man в поиске  обращения к форматирующим программам.  Результат будет выглядеть следующим образом:

$ grep  roff `which  man`

nroff $opt  –man  $all ;;

neqn  $all  |  nroff  $opt  –man  ;; troff  $opt  –man  $all  ;;

troff  –t  $opt  –man  $all |  tc ;; eqn  $all |  troff  $opt  –man  ;;

eqn $all | troff –t  $opt  –man  | tc ;;

$

Многообразие возникает из-за возможности задания различных пара метров: nroff или troff, запускать или нет eqn, и т. д. Макросы руководства, вызываемые troff –man, определяют команды troff, которые осуществляют форматирование в нужном стиле. По существу, они похожи на макросы ms, но есть и отличия, в частности это относится к командам изменения шрифтов и вывода названия. Об этих макросах можно прочитать в man(7) (там представлено их  краткое описание), основные же нетрудно запомнить. Макет страницы руководства выглядит так:

.TH  КОМАНДА номер раздела

.SH  NAME

команда \–  краткое описание функции

.SH  SYNOPSIS

.B  команда параметры

.SH  DESCRIPTION

Подробный рассказ о программах и параметрах.

Новые абзацы вводятся командой .PP.

.PP

Это новый абзац.

.SH  FILES

файлы, используемые командой, например в  passwd(1)  упоминается /etc/  passwd

.SH  "SEE ALSO"

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

.SH  DIAGNOSTICS

Описание любого необычного вывода (например, см.  cmp(1))

.S     H  BUGS

Неожиданные свойства (не обязательно ошибки, см. ниже)

Если какая-то секция пуста, ее заголовок опускается. Строка .TH и секции NAME, SYNOPSIS и DESCRIPTION обязательны.

Строка

.T     H  КОМАНДА номер5раздела

представляет имя  команды и  указывает  номер  раздела. Разнообразные  строки .SH идентифицируют секции страницы руководства. Секции  NAME и SYNOPSIS являются специальными; в остальных содержится обычная скучная информация. Секция NAME называет команду (на этот раз  в  нижнем  регистре) и  предоставляет ее  однострочное  описание. Секция SYNOPSIS перечисляет параметры, но не описывает их.  Как  и в любой другой секции, входные данные могут  вводиться в любом виде, поэтому можно задать изменения шрифта с помощью макросов .B, .I и .R . В секции SYNOPSIS название команды и параметры напечатаны полужирным шрифтом, а  остальная информация –  обычным прямым. Например, секции NAME и SYNOPSIS для ed(1) задаются так:

.SH  NAME

ed \–  text editor

.SH  SYNOPSIS

.B ed [

.B \–

] [

.B \–x

] [ name ]

Выводятся они следующим образом:

NAME

ed text editor

SYNOPSIS

ed  [ – ] [ –x  ] [ name ]

Обратите внимание, что вместо  простого символа – используется \–.

Секция DESCRIPTION описывает команду и ее параметры. В большинстве случаев это именно описание команды, а не языка, который команда определяет. Страница руководства cc(1) не описывает язык Си; в ней рассказывается о том,  как запустить команду cc, чтобы  скомпилировать  программу, написанную на Си, как вызвать оптимизатор, где остаются выходные данные, и т. д. Язык описывается в справочном руководстве по Си, ссылка на которое приводится в секции SEE  ALSO стра-

ницы cc(1).   С  другой стороны,  не  бывает  правил без  исключений:

man(7) – это описание языка макросов man.

Принято выводить курсивом имена команд и теги для  параметров (например, «name» на странице про ed) в секции DESCRIPTION. Макросы .I (выводить первый аргумент курсивом) и .IR  (выводить первый аргу мент  курсивом, а  второй –  прямым  шрифтом) делают эту  операцию чрезвычайно простой. Макрос .IR нужен потому, что макрос .I пакета man  не  обрабатывает второй аргумент тем  недокументированным, но удобным способом, каким это делает макрос пакета ms.

Секция FILES указывает файлы, неявно используемые командой. DIAG– NOSTICS нужна, только если команда выводит какие-то необычные данные. Это могут  быть  диагностические сообщения, коды  завершения или  непонятные вариации нормального поведения команды. Секция BUGS также названа не очень удачно. Те дефекты, о которых в ней сообщается, являются не столько ошибками, сколько недостатками, ведь ошибки должны быть исправлены до того, как команда инсталлируется.  Для того чтобы прочувствовать, что же попадает в секцию DIAGNOS– TICS, а что – в BUGS, просмотрите стандартное руководство.

Пример должен пролить свет на то, как написать страницу руководства.   Исходный  текст для   hoc(1),  /usr/man/man1/hoc.1,  представлен  на рис.  9.1, а рис.  9.2. отображает вывод команды

$ man  -t hoc

Упражнение 9.8.  Напишите страницу руководства для doctype. Напишите версию команды man, которая просматривала бы собственный ка талог пользователя man в поиске документации на его личные программы.  ~

Источник: Керниган Б., Пайк Р., UNIX. Программное окружение. – Пер. с англ. – СПб: Символ-Плюс, 2003. – 416 с., ил.

По теме:

  • Комментарии