Поля руководства
Все грамотно написанные страницы руководства состоят из нескольких полей, названия которых во всех руководствах одинаковы, но не обязательно все поля должны присутствовать в одном руководстве. Названия полей располагаются в начале строки (остальной текст идет с отступом) и выделяются повышенной яркостью. В каждом поле объект, которому посвящено руководство, рассматривается с определенной точки зрения (Среди руководств ALT Linux есть совершенно очаровательное - по объекту baby. Помимо прочего, в нем аккуратно расписаны все основные поля, так что настоятельно советуем почитать его на предмет изучения структурной организации страницы руководства. К тому же там содержится немало ценных сведений о самом объекте).
Краткое описание
Семантическое
Первое поле - NAME - содержит только имя объекта и его очень краткое, на одну строку, описание. NAME - суть всего руководства, поэтому очень важно, чтобы описание, при всей краткости, давало полную и четкую картину описываемого.
Синтаксическое
Поле SYNOPSIS описывает общий вид использования объекта. Например, в случае утилиты оно представляет собой командную строку со всеми возможными параметрами. В таком виде утилита, скорее всего, никогда не будет вызвана, однако общий вид описывает,как передавать ей параметры и какие именно. В SYNOPSIS должны быть представлены все варианты использования; для этого разработан даже специальный язык сокращений. Например, квадратные скобки обозначают необязательность параметра, фигурные - выбор одного параметра из списка (тогда они разделяются символами "|"), многоточие - повторение и т. д. Тем не менее SYNOPSIS - тоже очень краткое поле, позволяющее "единым взглядом" охватить возможности и специфику объекта.
Описание
Поле DESCRIPTION содержит развернутое описание объекта. Сюда попадает любая разъяснительная информация: принципы работы данной утилиты или функции, назначение и общая структура данного системного файла, описание внешних устройств, соответствующих данному драйверу и т. п. Поле может быть довольно большим: информации в нем должно быть достаточно для понимания устройства и работы объекта. Если утилита сама по себе сложна и описание принципов ее работы в DESCRIPTIONдовольно пространно, перечень возможных параметров командной строки (иными словами, ключей) с подробным изложением того, как и зачем их применять, выносят в поле OPTIONS. Если работа инструмента зависит от каких-либо переменных окружения (см. лекцию 17), их список помещается в поле ENVIRONMENT.
Результат
Функция или системный вызов, как правило, возвращают какое-нибудь значение. По окончании работы утилиты вырабатывается так называемый код возврата (или код ошибки, который не равен нулю в случае неудачного завершения работы). Наконец, функция или системный вызов могут завершиться с разными видами ошибок. Для описания результатов работы в руководствах имеются поляRETURN VALUES, DIAGNOSTICS и ERRORS соответственно.
Использование
Иногда использование объекта невозможно или некоторый, на первый взгляд очевидный путь его применения приводит к неочевидным последствиям. Тогда стоит поместить примеры такого рода ситуаций в поле CAVEATS. Небольшие примеры успешного использования объекта с описанием решаемой в них задачи приводятся в поле EXAMPLES, а типичные ошибки при работе с объектом, равно как и недочеты в его реализации, - в поле BUGS.
Ссылки на другие объекты
Если утилита работает с какими-нибудь файлами, использует или изменяет их, эти файлы перечисляются в поле FILES, даже если на них нет руководства. Поработав с некоторым инструментом системы, пользователь может просмотреть все файлы из поля FILESруководства, и узнать, откуда этот инструмент взял дополнительные данные и что изменил. Одно из самых важных - поле SEE ALSO. В него включаются ссылки на те источники информации, которые автор руководства считает относящимися к теме: на книги, включенные в систему учебники и статьи и - главное - на другие страницы руководства. Кроме того, в тексте всего руководства непременно встретятся ссылки на другие объекты, по которым тоже есть руководства. В этом случае, как и в поле SEE ALSO, после имени объекта в скобках указывается номер раздела, в котором стоит искать руководство.
Прочее
На самом деле структура руководства совсем не такая жесткая, как это может показаться из нашего описания. Зачастую даже хотелось бы, чтобы она была пожестче (например, чтобы ключи утилит всегда выносились в отдельное поле OPTIONS или чтобы полеEXAMPLES присутствовало всегда). Вполне допустимо вводить новые поля, особенно когда руководство весьма велико и его надо структурировать (например, COMMANDS - для команд с клавиатуры, COMPATIBILITY - для описания совместимости с предыдущими версиями и т. п.); ненужные поля можно опускать.
Родословная
Нередко в руководство включается поле HISTORY, где кратко описывается, когда в какой именно системе впервые появился объект и как он впоследствии развивался. Сведения об авторах, адрес, куда присылать жалобы и предложения (электронный и обычный) и прочую контактную информацию помещают в поле AUTHORS.