Differences between revisions 5 and 6
Revision 5 as of 2008-08-03 12:51:55
Size: 12237
Comment:
Revision 6 as of 2008-08-03 12:52:33
Size: 12237
Comment:
Deletions are marked like this. Additions are marked like this.
Line 83: Line 83:
|| 19 || 1 || 1 || 1 || || 1 || MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko || || || || 20 || 1 || 1 || 1 || || 1 || MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko || || ||

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

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

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

man

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

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

С одной стороны, это людей жёстко дисциплинирует, с другой --- облегчает пользователю поиск.

Пример: man man. (man --- программа просмотра страниц руководства, по ней тоже есть руководство)

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

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

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

Номера разделов --- традиционно все страницы руководства разделяются на несколько разделов --- канонически, 8 плюс ещё несколько

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

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

  • Ссылки внутри текста
  • Ссылки родовые (ссылки внутри раздела)
  • Ссылки в see also

К сожалению, программа less (программа-pager, то есть, программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Если так хочется, то, например, в KDE есть смотрелка манов с хождением по ссылкам подобно веб-браузеру.

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

  • Страницы руководства это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём речь.
  • Очень много есть ситуаций, когда ман --- неудобная форма представления информации Например, если есть приложение, которое работает в графической среде, и оно довольно развесистое (опенофис), то проще будет встроить документацию прямо в него.
  • Далеко не все хотят это делать.

info

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

Дел в том, что документация для info оформляется в виде книги. Таким образом, в info можно вложить информацию более разного вида, чем в man. Поэтому руководство некоторые любят делать в info.

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

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

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

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

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

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

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

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


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

Готовность (%)

Продолжительность (ак. ч.)

Подготовка (календ. ч.)

Полный текст (раб. д.)

Предварительные знания

Level

Maintainer

Start date

End date

20

1

1

1

1

MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko


CategoryLectures CategoryPspo CategoryMpgu CategoryUneex

PspoClasses/080718/01ManInfo (last edited 2009-03-22 18:53:28 by eSyr)