Поля руководства

Все грамотно написанные страницы руководства состоят из нескольких полей, названия которых во всех руководствах одинаковы, но не обязательно все поля должны присутствовать в одном руководстве. Названия полей располагаются в начале строки (остальной текст идет с отступом) и выделяются повышенной яркостью. В каждом поле объект, которому посвящено руководство, рассматривается с определенной точки зрения (Среди руководств ALT Linux есть совершенно очаровательное - по объекту baby. Помимо прочего, в нем аккуратно расписаны все основные поля, так что настоятельно советуем почитать его на предмет изучения структурной организации страницы руководства. К тому же там содержится немало ценных сведений о самом объекте).

Краткое описание Семантическое

Первое поле - NAME - содержит только имя объекта и его очень краткое, на одну строку, описание. NAME - суть всего руководства, поэтому очень важно, чтобы описание, при всей краткости, давало полную и четкую картину описываемого.

Синтаксическое

Поле SYNOPSIS описывает общий вид использования объекта. Например, в случае утилиты оно представляет собой командную строку со всеми возможными параметрами. В таком виде утилита, скорее всего, никогда не будет вызвана, однако общий вид описывает, как передавать ей параметры и какие именно. В SYNOPSIS должны быть представлены все варианты использования; для этого разработан даже специальный язык сокращений. Например, квадратные скобки обозначают необязательность параметра, фигурные - выбор одного параметра из списка (тогда они разделяются символами "|"), многоточие - повторение и т. д. Тем не менее SYNOPSIS - тоже очень краткое поле, позволяющее "единым взглядом" охватить возможности и специфику объекта.

Описание

Поле DESCRIPTION содержит развернутое описание объекта. Сюда попадает любая разъяснительная информация: принципы работы данной утилиты или функции, назначение и общая структура данного системного файла, описание внешних устройств, соответствующих данному драйверу и т. п. Поле может быть довольно большим: информации в нем должно быть достаточно для понимания устройства и работы объекта. Если утилита сама по себе сложна и описание принципов ее работы в DESCRIPTION довольно пространно, перечень возможных параметров командной строки (иными словами, ключей) с подробным изложением того, как и зачем их применять, выносят в поле OPTIONS. Если работа инструмента зависит от каких-либо переменных окружения (см. лекцию 17), их список помещается в поле ENVIRONMENT.

Результат

Функция или системный вызов, как правило, возвращают какое-нибудь значение. По окончании работы утилиты вырабатывается так называемый код возврата (или код ошибки, который не равен нулю в случае неудачного завершения работы). Наконец, функция или системный вызов могут завершиться с разными видами ошибок. Для описания результатов работы в руководствах имеются поля RETURN VALUES, DIAGNOSTICS и ERRORS соответственно.

Использование

Иногда использование объекта невозможно или некоторый, на первый взгляд очевидный путь его применения приводит к неочевидным последствиям. Тогда стоит поместить примеры такого рода ситуаций в поле CAVEATS. Небольшие примеры успешного использования объекта с описанием решаемой в них задачи приводятся в поле EXAMPLES, а типичные ошибки при работе с объектом, равно как и недочеты в его реализации, - в поле BUGS.