.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
