UNIX — универсальная среда программирования

9.4 Справочник

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

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

 $ man 7 man

В результате печатается только описание макрокоманд пакета 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 COMMAND номер раздела
 .SH NAME
 команда \- краткое описание функций
 .В команда возможные аргументы
 .SH DESCRIPTION
 Подробное объяснение команд и флагов.
 Абзацы вводятся .PP.
 .PP
 Это новый абзац.
 .SH FILES
 Файлы, используемые командой, например, passwd(1)
 упоминает /etc/passwd
 .SH "SEE ALSO."
 Ссылки к связанным документам, включая другие справочники
 .SH DIAGNOSTICS
 Описание некоторого необычного выходного потока
 (например, см. cmp(1))
 .SH BUGS
 Неожиданные черты (не всегда ошибки; см. ниже)

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

 .TH COMMAND номер раздела

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

 .SH NAME
 ed \- text editor
 .SH SYNOPSIS
 .В ed
 [
 .B \-
 ][
 .B \-x
 ][ name ]

 NAME
  ed - text editor
 SYNOPSIS
  ed [ - ][ -x ][ name ]

Заметьте, что используется \-, а не просто – .

Раздел DESCRIPTION описывает команду и ее флаги. В большинстве случаев это описание команды, а не языка, определяемого командой. Справочник сс(1) не определяет язык Си: он указывает, как запустить команду ее, чтобы компилировать программы на Си, как вызвать оптимизатор, где оставлен результат и т.п. Язык описывается в руководстве для пользователя по Си, на которое есть ссылки в разделе сс(1) SEE ALSO. С другой стороны, разделение не абсолютно: man(7) есть описание языка макрокоманд руководства.

По соглашению имена команд и метки флагов (такие, как "name" в справочнике ed) печатаются курсивом с помощью макрокоманды .I (первый аргумент печатается курсивом, второй обычным шрифтом). Макрокоманда .IR используется здесь потому, что макрокоманда .I в пакете не обеспечивает недокументированного, но удобного применения второго флага в ms.

Раздел FILES упоминает любые файлы, неявно используемые командой. DIAGNOSTICS следует включать только в том случае, если команда вырабатывает необычный выходной поток. Это могут быть диагностические сообщения, сведения о состоянии выхода или информация о неожиданных отклонениях от стандартного выполнения команды. Раздел BUGS тоже назван отчасти неверно. Дефекты, о которых здесь сообщается, представляют собой не столько ошибки, сколько недостатки - просто ошибки должны быть исправлены прежде, чем команда будет введена в систему. Чтобы понять, для чего нужны разделы DIAGNOSTICS и BUGS, вам следует пролистать стандартное руководство.

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

 $ man -t hoc
 .TH HOC 1
 .SH NAME
 hoc \- диалоговый язык для арифметики с плавающей точкой
 .SH SYNOPSYS
 .В hoc
 [ файл ... ]
 .SH DESCRIPTION
 .I Hoc
 интерпретирует простой язык для арифметики с плавающей
 точкой, примерно уровня Бейсика, с синтаксисом, подобным
 Си, и с процедурами и функциями с аргументами, а также
 с рекурсией.
 .PP
 Поименованные
 .IR файлы
 читаются и интерпретируются по порядку. Если
 .I файл
 не указан или если