Книга: UNIX — универсальная среда программирования
9.4 Справочник
Разделы на этой странице:
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 файл
не указан или если
.I файл это '-'
.I hoc
интерпретирует стандартный входной поток.
.PP
Входной поток
.I Hoc состоит из
.I выражений и
.IR операторов.
Выражения вычисляются и их результаты печатаются.
Операторы,обычно присваивания и определения функций
или процедур, не вырабатывают выходного результата,
если они явно не вызывают
.IR print.
.SH "SEE ALSO"
.I
Hoc - Диалоговый язык для арифметики с плавающей точкой
Брайана Кернигана и
Роба Пайка.
.br
.IR bas(1),
.IR bc(1)
and
.IR dc(1).
.SH BUGS
Восстановление после ошибок в определениях функции
и процедур несовершенно.
.br
Обработка концов строк не совсем удобна для пользователя.
Рис. 9.1. /usr/man/man1/hoc.1
HOC(1) HOC(1)
NAME
hoc – диалоговый язык для арифметики с плавающей точкой
SYNOPSYS
hoc [ файл … ]
DESCRIPTION
Hoc интерпретирует простой язык для арифметики с плавающей точкой, примерно уровня Бейсика, с синтаксисом, подобным Си, и с процедурами и функциями с аргументами, а также с рекурсией.
Поименованные файлы читаются и интерпретируются по порядку. Если файл не указан или если файл — это '-' hoc интерпретирует стандартный входной поток.
Входной поток Hoc состоит из выражений и операторов. Выражения вычисляются и их результаты печатаются. Операторы, обычно присваивания и определения функций, или процедур, не вырабатывают выходного результата, если они явно не вызывают print.
"SEE ALSO"
Hoc – Диалоговый язык для арифметики с плавающей точкой Брайана Кернигана и Роба Пайка.
bas(1), bc(1) and dc(1).
BUGS
Восстановление после ошибок в определениях функции и процедур несовершенно. Обработка концов строк не совсем удобна для пользователя.
8-я версия 1
Рис. 9.2. hoc(1
)
Упражнение 9.8.
Напишите справочник для doctype
. Напишите версию команды man, которая отыскивает документацию по вашим личным программам в вашем собственном каталоге man
.
- Заполнение справочников и каталогов
- Справочник по языку
- Справочник по базовому JavaScript
- 1.11 Справочник по наиболее употребительным стандартным командам ОС
- Справочник номенклатуры
- Приложение А Электронный справочник man(1)
- Приложение 1 Справочник по языку JScript
- Приложение 2 Справочник по языку VBScript
- 2.2.5. Заполнение справочника сотрудников
- Глава 6 Все возможные для вашего бизнеса рекламные каналы и средства. Справочник маркетолога
- Заполнение справочника ответственных лиц
- Справочник валют