Изменения в «PspoClasses/080718/01ManInfo»

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

В процессе обычно очень часто приходиться обращаться к документации: к домкументцию по test, по bash... Без того, чтобы рассказать что-то дже человеку, который в теме, без того, чтбы посм. в дк., дело не обходится. Прежде, чем закруглиться, неплохо было бы наметить напрвления, куда двигаться дальше, где искать инфрмацию.

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

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

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

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

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

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

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

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

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

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

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

К сожалению, прграмма less не умеет интерп. ссылки. Если так хчется, то, например, в kde есть смотрелка манов.

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

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

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

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

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

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

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

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

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

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

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

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

CategoryLectures CategoryPspo CategoryMpgu CategoryUneex