Diff for "PspoClasses/080718/01ManInfo"

Информационный поиск: man и info

В процессе работы с системой неизбежны обращения к документации, это справедливо как для новичка, так и для опытного пользователя. Не каждый сможет запомнить всё то многообразие утилит и параметров этих утилит, которые существуют в обычной современной UNIX-подобной системе. Так, команда ls версии GNU имеет в качестве своих коротких параметров все буквы латинского алфавита, кроме j и y (хотя, вероятно, и их скоро займут).

Рассмотрим, как организована локальная система чтения документации.

man

Классическая UNIX-идеология, когда всё писалось сильно связанным сообществом, подразумевала, что любой программный продукт сопровождается документацией, страницей руководства (Usage Manual). Отсюда и получила название соответствующая подсистема --- man pages. Структура всех страниц и каждой страницы в отдельности чётко сформулирована. К сожалению, есть разработчики, которые не создают страниц руководства, соответствующих этой структуре. Разработчики дистрибутива Debian используют стандарт, согласно которому, пакет не может существовать в хранилище без правильно оформленной страницы руководства, чем сильно упростили многим жизнь.

Итак, имеем две аксиомы:

• Каждый программный продукт (утилиты, системные вызовы) должен быть документирован;
• Структура страницы руководства жёстко регламентирована.

Введение таких мер облегчает пользователю информационный поиск.

Man --- программа просмотра страниц руководства, по ней тоже существует руководство. Чтобы просмотреть его, выполним  man man. Рассмотрим структуру руководства. Оно подразделяется на секции:

• NAME. Она содержит название и краткое описание программного продукта;
• SYNOPSIS содержит описание объекта. Здесь в квадратных скобках указываются необязательные параметры, фигурные скобки означают выбор одного из элементов, разделённых вертикально чертой, имена объектов подчеркиваются;
• DESCRIPTION. Достаточно полное описание того, что делает объект;
• RETURN. Возвращаемые утилитой значения;
• Если этот программнный продукт является утилитой, и в нем есть ключи, то существует раздел OPTIONS, их описывающий;
• FILES. Ссылки на используемые конфигурационные файлы данной утилиты;
• Если описываемый объект использует переменные окружения, то должна существовать секция ENVIROMENT;
• SEE ALSO --- одна из самых важных секций, с ее помощью организуется семантическая сеть. Здесь описаны другие страницы руководства, которые автор рекомендует посмотреть, так как они связаны с описываемым объектом;
• Секция BUGS описывает известные неполадки в работе программного продукта;
• Секция TIPS, EXAMPLES содержит в себе примеры.

Наличие тех или иных секций --- исключительно дело автора, единственной обязательной является NAME, но указанные очень рекомендуются.

Рассмотрим программы apropos и whatis, осуществляющие поиск по секции NAME страниц руководства. Из всех страниц помощи создаётся сводная таблица (mandb), в который содержатся строчки из NAME. И apropos, и whatis занимаются поиском слова по таблице. Результатом whatis является те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой части. Среди прочих программ, полезных при информационным поиске, стоит выделить groff, отвечающую за форматирование страниц для вывода на терминал.

Традиционно все страницы руководства разделяются на несколько разделов, общепринятая нумерация разделов означает следующее:

• 1 --- утилиты;
• 2 --- системные вызовы;
• 3 --- библиотечные вызовы;
• 4 --- устройства;
• 5 --- структура разл. файлов (конфигурационные);
• 6 --- игры;
• 7 --- всё остальное;
• 8 --- административные команды;
• 9 --- внутренние ядерные вызовы;
• n --- new --- документация, еще не направленная в соответствующий раздел.

Страницы руководства находятся в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в специальном формате, сжатые с помощью gzip. Если существует документация на языке, отличном от стандартного, то она лежит в подкаталоге с названием языка.

Такова структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Таким образом, получается довольно сложная иерархическая система, условно говоря, гипертекст, в котором несколько видов ссылок:

• Ссылки внутри текста;
• Ссылки родовые (ссылки внутри раздела);
• Ссылки в SEE ALSO.

К сожалению, программа less (программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Эта проблема решается различными способами, например, в KDE есть просмотрщик страниц руководств, в котором переход по ссылкам реализован подобно Web-браузеру (man:<название> в адресной строке Konqueror). Или можно воспользоваться командой ! в программе less, при помощи которой можно выполнить произвольную команду шелла, и выполнить там, соответственно, переход на нужную страницу руководства.

Если бы дисциплина оформления всегда соблюдалась, то хватало бы только страниц руководств. Но это не так по нескольким причинам:

• Страницы руководства --- это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём идет речь;

• Существует очень много ситуаций, когда страница руководства --- неудобная форма представления информации. Например, если существует приложение, которое работает в графической среде, и оно довольно большое (например, OpenOffice), то проще будет встроить документацию прямо в него;

• Далеко не все разработчики создают отвечающие стандартам страницы руководств.

info

Существует ещё одна система, которая используется для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне которого находятся ссылки на документы, в каждом документе --- ссылки на другие документы, и каждый документ представляет собой книгу. Таким образом, в info можно вложить информацию гораздо более разнообразную, чем в man. Поэтому руководство некоторые разработчики делают в info.

В Debian Policy сказано, что у каждой утилиты должна быть страница руководства, в случае, если страница руководства маленькая, в секции SEE ALSO есть ссылка на страницу в info или место, где находится документация в другом формате.

И man, и info распространяются вместе с программными продуктами, и пишет их та же команда, что и сам продукт. С другой стороны, у этого есть недостаток: страницы руководства обычно написаны на английском. Существует проект перевода страниц руководства на русский, но нельзя забывать, что это слабомотивируемая идея (ведь программные продукты обновляются, а с обновлением придётся переводить всё по новой). Поэтому далеко не всё переведено, а то, что переведено, не всегда актуально.

Другие источники документации

Всё-таки, info и man --- техническая документация.

Кроме того, бывает так, что автор поленился сделать документацию в формате man/info, то может быть несколько случаев:

• Вызвать программу с ключом -h или --help
• Посмотреть, нет ли документации к программному продукту в непонятном формате. Такая информация лежит в каталоге /usr/share/doc/имя_пакета-номер-версии

Эта документация частично составляется мэйнтейнером.

Сведения о ресурсах

CategoryLectures CategoryPspo CategoryMpgu CategoryUneex