Утилита man

Утилита man(1) - составная, ее вызов - это последовательное выполнение трех операций: поиск страницы руководства, форматирование найденной страницы и просмотр отформатированного текста.

Сами страницы помощи - это файлы, имена которых включают имена объектов. Файлы расположены в некотором базовом каталоге (например, в /usr/share/man) в подкаталогах man1, man2 и т. д. по количеству разделов. Таким образом, первая стадия работы утилиты man сводится к поиску первой страницы с именем объекта во всех секциях базовых каталогов. Во многих системах страницы руководства запакованы программой compress(1) или gzip(1), так что перед второй стадией - форматированием страница распаковывается. Руководства хранятся в формате ROFF. Это специальный язык разметки текста для представления его в виде документа. Третья стадия работы man - вызов утилиты постраничного просмотра текста more(1). Во многих современных системах вместо more используется более мощная утилита less(1). Утилита позволяет просматривать простой текст и текст, выходящий из-под nroff.

Утилиты whatis и apropos

Самая краткая часть страницы руководства - однострочное поле NAME - тоже играет очень важную роль в системе информационной поддержки. При установке руководства в систему содержимое этого поля добавляется в файл whatis, лежащий в базовом каталоге. Текстовый файл whatis - оглавление всей системы руководств, находящейся в соответствующем каталоге. Если поискать некоторое слово в этом файле, мы увидим только те заголовки руководств, в которых оно встречается. Поиском ключевых слов в whatis занимаются утилита whatis(1) и apropos(1), которая ищет не целое слово, а просто подстроку в строке. Для поиска используется поле NAME. Работоспособной такая система будет только, если поместить в это поле значимый текст, а не что попало, таким образом пользователь, если потребуется, найдет руководство.

Поле NAME вместе с полем SEE ALSO задают довольно простой, но эффективный алгоритм работы с manpages.

Система info

Альтернатива manpages - гипертекстовая система info(1). Info - часть системы документирования texinfo, разработанной GNU. У texinfo есть масса преимуществ. Во-первых, из texinfo-документации можно изготавливать не только info-файлы, но и документы в формате HTML и XML, и даже настоящие книжки в формате TeX. Во-вторых, в нем существенно больше средств разметки, индексирования текста, организации таблиц и т. п. В-третьих, в отличие от man, info - система документирования, в которой на уровне просмотра реализован переход по гипертекстовым ссылкам.

Структура info-документации опирается на понятия "узел", "меню", "ссылка" и "индекс".

• Узел - это некоторый цельный текст, посвященный определенной теме, имеющий собственное имя. Узлы строго упорядочены (так из них получается книга), но еще они включены в иерархию отделов книги (по принципу часть - лекция - раздел - подраздел). Узлом может быть, например, текст в начале и в конце главы, разделенный меню.

• Меню - это оглавление соответствующего узла (например, раздела), каждый элемент которого ссылается на нижележащий узел (в данном случае - подраздел). Тексты всех нижележащих узлов меню и самого узла составят весь текст раздела.

• Ссылка - один из двух видов гипертекстовых ссылок в info. При просмотре документации утилитой info достаточно переместить текстовый курсор при помощи клавиши Tab к нужному пункту меню и нажать enter, чтобы перейти к соответствующему узлу, т. е. проследовать по ссылке. Другой вид гипертекстовых ссылок называется перекрестными ссылками. Перекрестные ссылки возникают в тексте узла и указывают на какой-нибудь другой узел документа вне всякой иерархии. В книге перекрестная ссылка обычно возникает в случаях наподобие "эта тема подробнее рассматривается в гл. 3, разд. 7".

• Индекс - сводное меню, содержащее ссылки на узлы, в описании которых помечено, что они этому меню принадлежат. Иными словами, индекс не надо писать вручную, он собирается при изготовлении info-файла из texinfo-документации. Несколько индексов в info-странице всегда определено, например, concept index - список всех сущностей, упоминающихся в документе.

Такая структура делает texinfo-документ пригодным для создания разветвленной и подробной документации: учебника, статьи, содержащей научные и исторические сведения, полного описания некоторой прикладной системы и т. д.

Задача texinfo - документирование больших, сложных и замкнутых проектов. Для того чтобы поместить такую документацию в общий внутрисистемный информационный контекст, не нужно перелопачивать ее всю, в руководстве достаточно указать только основные принципы работы с установленным пакетом и поместить внешнюю ссылку на info-страницу, содержащую полную документацию.