Ссылки на другие объекты

Если утилита работает с какими-нибудь файлами, использует или изменяет их, эти файлы перечисляются в поле FILES, даже если на них нет руководства. Поработав с некоторым инструментом системы, пользователь может просмотреть все файлы из поля FILES руководства, и узнать, откуда этот инструмент взял дополнительные данные и что изменил. Одно из самых важных - поле SEE ALSO. В него включаются ссылки на те источники информации, которые автор руководства считает относящимися к теме: на книги, включенные в систему учебники и статьи и - главное - на другие страницы руководства. Кроме того, в тексте всего руководства непременно встретятся ссылки на другие объекты, по которым тоже есть руководства. В этом случае, как и в поле SEE ALSO, после имени объекта в скобках указывается номер раздела, в котором стоит искать руководство.

Прочее

На самом деле структура руководства совсем не такая жесткая, как это может показаться из нашего описания. Зачастую даже хотелось бы, чтобы она была пожестче (например, чтобы ключи утилит всегда выносились в отдельное поле OPTIONS или чтобы поле EXAMPLES присутствовало всегда). Вполне допустимо вводить новые поля, особенно когда руководство весьма велико и его надо структурировать (например, COMMANDS - для команд с клавиатуры, COMPATIBILITY - для описания совместимости с предыдущими версиями и т. п.); ненужные поля можно опускать.

Родословная

Нередко в руководство включается поле HISTORY, где кратко описывается, когда в какой именно системе впервые появился объект и как он впоследствии развивался. Сведения об авторах, адрес, куда присылать жалобы и предложения (электронный и обычный) и прочую контактную информацию помещают в поле AUTHORS.

Особенности руководств

Бывают объекты с одинаковыми именами, но принадлежащие разным разделам, например утилита passwd, позволяющая пользователю менять пароль, и файл passwd, в котором хранится учетная запись пользователя (по иронии судьбы в современных версиях UNIX именно пароля там и нет). Для того чтобы посмотреть руководство по passwd из пятого раздела, надо использовать команду man 5 passwd, а если вам неизвестно, к какому разделу относится объект, - man -a passwd (тогда вы увидите руководства по всем объектам с именем passwd). При ссылке на страницу руководства принято после имени объекта указывать в круглых скобках номер раздела passwd(1) и passwd(5).

В каждом разделе существует специальный объект intro, руководство по которому описывает назначение раздела и определяет основные термины. Кроме того, в поле SEE ALSO этих руководств помещаются ссылки на страницы руководства по крупным темам (например, security(7)).

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