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

$ 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, вам следует пролистать стандартное руководство.