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

.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 – диалоговый язык для арифметики с плавающей точкой

hoc[ файл … ]

Hoc интерпретирует простой язык для арифметики с плавающей точкой, примерно уровня Бейсика, с синтаксисом, подобным Си, и с процедурами и функциями с аргументами, а также с рекурсией.

Поименованные файлы читаются и интерпретируются по порядку. Если файл не указан или если файл — это '-' hoc интерпретирует стандартный входной поток.

Входной поток Hoc состоит из выражений и операторов . Выражения вычисляются и их результаты печатаются. Операторы, обычно присваивания и определения функций, или процедур, не вырабатывают выходного результата, если они явно не вызывают print .

Hoc – Диалоговый язык для арифметики с плавающей точкой Брайана Кернигана и Роба Пайка.

bas(1) , bc(1) and dc(1) .

Восстановление после ошибок в определениях функции и процедур несовершенно. Обработка концов строк не совсем удобна для пользователя.

8-я версия 1

Рис. 9.2 . hoc(1)

Напишите справочник для doctype. Напишите версию команды man, которая отыскивает документацию по вашим личным программам в вашем собственном каталоге man.

Для подготовки документации существует несколько дополнительных программ. Команда refer(1)отыскивает ссылки на ключевые слова, вставляет эти ссылки в строки вашего документа и помещает раздел ссылок в его конце. Определив соответствующую макрокоманду, вы можете добиться, чтобы referпечатала ссылки в том виде, в каком они вам нужны. Имеются определения для многих журналов по вычислительным наукам. Команда referявляется частью седьмой версии, но не включена в некоторые другие версии.

Программы pic(1)и ideal(1)предназначены для подготовки рисунков, так же как eqnдля уравнений. Подготовить рисунки значительно сложнее, чем уравнения (по крайней мере для набора), а поскольку традиции здесь отсутствуют, оба языка отчасти облегчают знакомство с этой техникой и ее использование. В качестве иллюстрации приведем простой рисунок и его выражение на pic.

.PS

.ps -1

box invis "document"; arrow

box dashed "pie"; arrow

box dashed "tbl";

arrow box dashed "eqn"; arrow