Differences between revisions 1 and 11 (spanning 10 versions)
Revision 1 as of 2008-07-21 20:43:02
Size: 10432
Editor: eSyr
Comment:
Revision 11 as of 2008-08-05 23:15:24
Size: 12811
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
В процессе обычно очень часто приходиться обращаться к документации: к домкументцию по test, по bash... Без того, чтобы рассказать что-то дже человеку, который в теме, без того, чтбы посм. в дк., дело не обходится. Прежде, чем закруглиться, неплохо было бы наметить напрвления, куда двигаться дальше, где искать инфрмацию. В процессе работы с системой неизбежны обращения к документации, неважно, насколько Вы опытный пользователь. Не каждый сможет запомнить всё то многообразие утилит и параметров этих утилит, которые существуют в обычной современной UNIX-подобной системе. Так, команда ls версии GNU имеет в качестве своих коротких параметров все буквы латинского алфавита, кроме j и y (хотя, вероятно, и их скоро займут).
Line 5: Line 5:
Надо начать вот с чего. Классическая UNIX-идеология, когда всё писалсь сильно связанным собществом. Классическая никсовая иделогия сразу подразумевала, что люая суцщность сопрвождается дкументацией, страницей руководства. Такое назхвание и получил соотв. подсистем --- man pages. В чём смысл стрниц рук-в: это жёстко секционированные тексты, в кторых сначал формально объясн., что это такое.
 * Каждая сущнсть (утилиты, сист. вызовы) должна быть дкументирована
 * Структур стрницыв руководства жёстко регламентирована. Например, NAME --- имя сущности
С одной стороны, это людей жёстко дисциплинирует, с другй --- облегчет пользвателю поиск.
Рассмотрим, как организована локальная система чтения документации.
Line 10: Line 7:
Пример: man man. (man --- программа просмотра стрниц руководства, по ней тоже есть руководство)
 * Секция NAME. Название и краткое описание
 * SYNOPSIS. Описание объекта. В квадр. скобках указываются необяз. праметры, подчёркнутое --- имена объектв. Фигурные скобки --- выбор одного из элементов, разд. верт. чертой.
 * DESCRIPTION. Достаточное описание тог, что делает объект.
 * RETURN
 * Если эт утилит и там есть ключи, то есть раздел OPTIONS.
 * FILES если есть файлы, для которых нет страниц рук-ва
 * Дальше есть секции необязательного вида
 * Если команда испольует переменные окр, т должн быть секиця ENVIROMENT
 * SEE ALSO. Одна из самых вжных секций. Тким обрзом орг. семнтическая сеть. Здесь опис., какие другие стрницы руководста рекомендует автор посмотреть, если вы этой темой интересуетесь.
  * apropos, whatis --- поиск по секции NAME страниц руководства
  * groff --- форматировние страниц терминл для вывода
 * BUGS
 * TIPS, EXAMPLES
Наличие тех или иных секции --- искл. дело автора, един. обязательным является NAME, но указанные очень рекмендуются
=== man ===
Line 26: Line 9:
apropos и whatis. Из всех страниц помощи создаётся сводная таблица, в ктороый сдержатся строчки из NAME. И apropos и whatis занимаются поиском слова по таблице. Результатом whatis явл. те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой стороне. Классическая UNIX-идеология, когда всё писалось сильно связанным сообществом, сразу подразумевала, что любая сущность сопровождается документацией, страницей руководства (Usage Manual). Такое название и получила соответствующая подсистема --- man pages. Структура всех страниц и каждой страницы в отдельности чётко сформулирована. К сожалению, есть разработчики, которые не зоздают страниц руководства, соответствующих этой структуре. В Debian Policy на этот счёт сказано, что пакет не может существовать без хоть какой-нибудь правильной страницы руководства. Итак,имеем две аксиомы:
 * Каждая сущность (утилиты, системные вызовы) должна быть документирована
 * Структура страницы руководства жёстко регламентирована.
Введение таких мер облегчает пользователю информационный поиск.
Line 28: Line 14:
Номера разделов --- традиц. все стр. руководства разделяются на неск. разделв --- 8 плюс ещё неск.
 * 1 --- утилиты
 * 2 --- системные вызовы
 * 3 --- библиотечные вызовы
 * 4 --- устройства
 * 5 --- структура разл. файлов (конфигурационные)
 * 6 --- игры
 * 7 --- всё остальне
 * 8 --- административные команды
 * 9 --- внутр. ядерные вызовы
 * n --- new --- куда всякие лентяи складывают документацию, если лень документироывать
Man --- программа просмотра страниц руководства, по ней тоже есть руководство. Чтобы просмотреть его, выполним {{{ man man}}}. Рассмотрим структуру руководства:
 * Секция NAME. Она содержит название и краткое описание;
 * SYNOPSIS --- описание объекта. Здесь в квадратных скобках указываются необязательные параметры, фигурные скобки означают выбор одного из элементов, разделённых вертикально чертой, имена объектов подчеркиваются;
 * DESCRIPTION. Достаточное описание того, что делает объект;
 * RETURN. Возвращаемые утилитой значения;
 * Если это утилита и в ней есть ключи, то существует раздел OPTIONS;
 * FILES. Ссылки на используемые конфигурационные файлы данной утилиты.
 * Если описываемый объект использует переменные окружения, то должна существовать секция ENVIROMENT;
 * SEE ALSO. Одна из самых важных секций, с ее помощью организуется семантическая сеть. Здесь описаны другие страницы руководства, которые автор рекомендует посмотреть, так как они связаны с описываемым объетов;
 * apropos, whatis --- поиск по секции NAME страниц руководства;
 * groff --- форматирование страниц для вывода на терминал;
 * Секция BUGS описывает известные неполадки в работе программного продукта;
 * Секция TIPS, EXAMPLES содержит в себе примеры.
Наличие тех или иных секций --- исключительно дело автора, единственным обязательным является NAME, но указанные очень рекомендуются.
Line 40: Line 29:
Такая структура manpages. Внутри стр. руководств может быть ссылка вида (See something(*)). Такми образом получается довлоьно хитрая иерархия, гипертекст, в котором неск. видов ссылок.
 * Ссылки внутри текста
 * Ссылки родовые (ссылки внутри раздела)
 * Ссылки в see also
К сожалению, прграмма less не умеет интерп. ссылки. Если так хчется, то, например, в kde есть смотрелка манов.
Рассмотрим утилиты apropos и whatis. Из всех страниц помощи создаётся сводная таблица (mandb), в который содержатся строчки из NAME. И apropos, и whatis занимаются поиском слова по таблице. Результатом whatis является те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой части.
Line 46: Line 31:
Если бы дисц. сблюдалась, то хватало бы манов. Но это не так по неск. причинам:
 * Страницы руководства это не учебники. Главная их цель --- внешняя память. Факт., страницы рук-ва написаны для тех, кт знает, о чём речь.
 * Очеь много есть ситуаций, когда ман --- неудобная форма предст. инф. Например, если есть приложение, которое работает в граф. среде, и оно довольно развесистое (опенофис), то правильно всроить документацию прямо в него.
 * Далеко не все хотят это делать.
Номера разделов --- традиционно все страницы руководства разделяются на несколько разделов --- канонически, 8 плюс ещё несколько:
 * 1 --- утилиты;
 * 2 --- системные вызовы;
 * 3 --- библиотечные вызовы;
 * 4 --- устройства;
 * 5 --- структура разл. файлов (конфигурационные);
 * 6 --- игры;
 * 7 --- всё остальное;
 * 8 --- административные команды;
 * 9 --- внутренние ядерные вызовы;
 * n --- new --- куда всякие лентяи, которым лень положить страницу в правильный раздел, складывают документацию.
Line 51: Line 43:
Есть ещё одн система, которая исп. для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне ссылки на документы, в каждом документе ссылки на другие дкументы, каждый документ представляет собой книжку. Такова структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Таким образом, получается довольно сложная иерархическая система, условно говоря, гипертекст, в котором несколько видов ссылок:
 * Ссылки внутри текста;
 * Ссылки родовые (ссылки внутри раздела);
 * Ссылки в SEE ALSO.
К сожалению, программа less (программа-pager, то есть, программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Эта проблема решается различными способами, например, в KDE есть просмотрщик страниц руководств, в котором переход по ссылкам реализован подобно веб-браузеру.
Line 53: Line 49:
Дел в том, что документация для info оформляется в виде книги. Т. о., в info моожно вложить инф. более разного вдиа, чем в man. Поэтому руководство некторые любят делать в info. Если бы дисциплина оформления соблюдалась, то хватало бы только страниц руководств. Но это не так по нескольким причинам:
 * Страницы руководства --- это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём речь.
 * Существует очень много ситуаций, когда страница руководства --- неудобная форма представления информации. Например, если существует приложение, которое работает в графической среде, и оно довольно большое (например, опенофис), то проще будет встроить документацию прямо в него.
 * Далеко не все хотят создавать отвечающие стандартам страницы руководств.
Line 55: Line 54:
Спасибо дебиану, у кторого в полиси прописано, что у каждй утилиты должна быть страница руководства. В таком случае страница руководства маленькая и в SEE ALSO есть ссылка на страницу в info или место, где лежит документация в другом формате. === info ===
Line 57: Line 56:
Почему лектор начал с man и info --- птому что она расп. вместе с прогр. прдуктами, пишет её та же команда, что и сам прдукт. С другой стороны, у этого есть недостаток --- стр. руководства пишутся бычно на английском. Существует проект перевод страниц руководства на русский, но надо понимать, что это слабомотивируемая идея. В принципе, кому интересно, как происх перевод, была лекция на эту тему в прошлом году. Поэтому не всё переведено, а что переведено, не всегда актуально. Существует ещё одна система, которая используется для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне которого находятся ссылки на документы, в каждом документе --- ссылки на другие документы, каждый документ представляет собой книжку. Дело в том, что документация для info оформляется в виде книги. Таким образом, в info можно вложить информацию гораздо более разнообразную, чем в man. Поэтому руководство некоторые любят делать в info.
Line 59: Line 58:
Как устроены страницы руководства: они лежат в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в формате, зажатые gzip. При это, если есть документация на языке, отл. т стандартная, то она ледит в подкаталоге с наз. языка. Благодаря Debian Policy, в котором сказано, что у каждой утилиты должна быть страница руководства, в случае, если страница руководства маленькая, в SEE ALSO есть ссылка на страницу в info или место, где лежит документация в другом формате.

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

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

=== Другие источники документации ===
Line 63: Line 68:
Кроме того, есть вариант, что автор поленился сделать док. в формате man/info, то может быть неск. случаев:
 * Сказать имя программы с ключём -h/--help
 * Можно посмотреть, нет ли документации к программному продукту в непонятном фрмате. Такая инф. лежит в каталоге /usr/shre/doc/имя_пакета-номер-версии
Кроме того, есть вариант, что автор поленился сделать документацию в формате man/info, то может быть несколько случаев:
 * Вызвать программу с ключом -h или --help
 * Посмотреть, нет ли документации к программному продукту в непонятном формате. Такая информация лежит в каталоге /usr/share/doc/имя_пакета-номер-версии
Line 67: Line 72:
Эта документация частично составляется манейнером. Эта документация частично составляется мэйнтейнером.
Line 69: Line 74:
----
Line 75: Line 80:
|| 0 || 1 || 1 || 1 || || 1 || PavelSutyrin, ОльгаТочилкина, MaximByshevskiKonopko || || || || 39 || 1 || 1 || 1 || || 1 || MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko || || ||
----
CategoryLectures CategoryPspo CategoryMpgu CategoryUneex

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

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

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

man

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

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

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

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

39

1

1

1

1

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


CategoryLectures CategoryPspo CategoryMpgu CategoryUneex

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