Шрифт:
$ 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