Differences between revisions 2 and 22 (spanning 20 versions)
Revision 2 as of 2008-07-21 20:49:44
Size: 10500
Editor: eSyr
Comment:
Revision 22 as of 2009-03-22 21:53:28
Size: 13788
Editor: eSyr
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 используют стандарт, согласно которому, пакет не может существовать в хранилище без правильно оформленной страницы руководства, чем сильно упростили многим жизнь.
Line 28: Line 11:
Номера разделов --- традиц. все стр. руководства разделяются на неск. разделв --- 8 плюс ещё неск.
 * 1 --- утилиты
 * 2 --- системные вызовы
 * 3 --- библиотечные вызовы
 * 4 --- устройства
 * 5 --- структура разл. файлов (конфигурационные)
 * 6 --- игры
 * 7 --- всё остальне
 * 8 --- административные команды
 * 9 --- внутр. ядерные вызовы
 * n --- new --- куда всякие лентяи складывают документацию, если лень документироывать
Итак, имеем две аксиомы:
 * Каждый программный продукт (утилиты, системные вызовы) должен быть документирован;
 * Структура страницы руководства жёстко регламентирована.
Введение таких мер облегчает пользователю информационный поиск.
Line 40: Line 16:
Такая структура manpages. Внутри стр. руководств может быть ссылка вида (See something(*)). Такми образом получается довлоьно хитрая иерархия, гипертекст, в котором неск. видов ссылок.
 * Ссылки внутри текста
 * Ссылки родовые (ссылки внутри раздела)
 * Ссылки в see also
К сожалению, прграмма less не умеет интерп. ссылки. Если так хчется, то, например, в kde есть смотрелка манов.
Man --- программа просмотра страниц руководства, по ней тоже существует руководство. Чтобы просмотреть его, выполним {{{ man man}}}. Рассмотрим структуру руководства. Оно подразделяется на секции:
 * NAME. Она содержит название и краткое описание программного продукта;
 * SYNOPSIS содержит описание объекта. Здесь в квадратных скобках указываются необязательные параметры, фигурные скобки означают выбор одного из элементов, разделённых вертикально чертой, имена объектов подчеркиваются;
 * DESCRIPTION. Достаточно полное описание того, что делает объект;
 * RETURN. Возвращаемые утилитой значения;
 * Если этот программнный продукт является утилитой, и в нем есть ключи, то существует раздел OPTIONS, их описывающий;
 * FILES. Ссылки на используемые конфигурационные файлы данной утилиты;
 * Если описываемый объект использует переменные окружения, то должна существовать секция ENVIROMENT;
 * SEE ALSO --- одна из самых важных секций, с ее помощью организуется семантическая сеть. Здесь описаны другие страницы руководства, которые автор рекомендует посмотреть, так как они связаны с описываемым объектом;
 * Секция BUGS описывает известные неполадки в работе программного продукта;
 * Секция TIPS, EXAMPLES содержит в себе примеры.
Наличие тех или иных секций --- исключительно дело автора, единственной обязательной является NAME, но указанные очень рекомендуются.
Line 46: Line 29:
Если бы дисц. сблюдалась, то хватало бы манов. Но это не так по неск. причинам:
 * Страницы руководства это не учебники. Главная их цель --- внешняя память. Факт., страницы рук-ва написаны для тех, кт знает, о чём речь.
 * Очеь много есть ситуаций, когда ман --- неудобная форма предст. инф. Например, если есть приложение, которое работает в граф. среде, и оно довольно развесистое (опенофис), то правильно всроить документацию прямо в него.
 * Далеко не все хотят это делать.
Рассмотрим программы apropos и whatis, осуществляющие поиск по секции NAME страниц руководства. Из всех страниц помощи создаётся сводная таблица (mandb), в который содержатся строчки из NAME. И apropos, и whatis занимаются поиском слова по таблице. Результатом whatis является те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой части. Среди прочих программ, полезных при информационным поиске, стоит выделить groff, отвечающую за форматирование страниц для вывода на терминал.
Line 51: Line 31:
Есть ещё одн система, которая исп. для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне ссылки на документы, в каждом документе ссылки на другие дкументы, каждый документ представляет собой книжку. Традиционно все страницы руководства разделяются на несколько разделов, общепринятая нумерация разделов означает следующее:
 * 1 --- утилиты;
 * 2 --- системные вызовы;
 * 3 --- библиотечные вызовы;
 * 4 --- устройства;
 * 5 --- структура разл. файлов (конфигурационные);
 * 6 --- игры;
 * 7 --- всё остальное;
 * 8 --- административные команды;
 * 9 --- внутренние ядерные вызовы;
 * n --- new --- документация, еще не направленная в соответствующий раздел.
Line 53: Line 43:
Дел в том, что документация для info оформляется в виде книги. Т. о., в info моожно вложить инф. более разного вдиа, чем в man. Поэтому руководство некторые любят делать в info. Страницы руководства находятся в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в специальном формате, сжатые с помощью gzip. Если существует документация на языке, отличном от стандартного, то она лежит в подкаталоге с названием языка.
Line 55: Line 45:
Спасибо дебиану, у кторого в полиси прописано, что у каждй утилиты должна быть страница руководства. В таком случае страница руководства маленькая и в SEE ALSO есть ссылка на страницу в info или место, где лежит документация в другом формате. Такова структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Таким образом, получается довольно сложная иерархическая система, условно говоря, гипертекст, в котором несколько видов ссылок:
 * Ссылки внутри текста;
 * Ссылки родовые (ссылки внутри раздела);
 * Ссылки в SEE ALSO.
К сожалению, программа less (программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Эта проблема решается различными способами, например, в KDE есть просмотрщик страниц руководств, в котором переход по ссылкам реализован подобно Web-браузеру (man:<название> в адресной строке Konqueror). Или можно воспользоваться командой ! в программе less, при помощи которой можно выполнить произвольную команду шелла, и выполнить там, соответственно, переход на нужную страницу руководства.
Line 57: Line 51:
Почему лектор начал с man и info --- птому что она расп. вместе с прогр. прдуктами, пишет её та же команда, что и сам прдукт. С другой стороны, у этого есть недостаток --- стр. руководства пишутся бычно на английском. Существует проект перевод страниц руководства на русский, но надо понимать, что это слабомотивируемая идея. В принципе, кому интересно, как происх перевод, была лекция на эту тему в прошлом году. Поэтому не всё переведено, а что переведено, не всегда актуально. Если бы дисциплина оформления всегда соблюдалась, то хватало бы только страниц руководств. Но это не так по нескольким причинам:
 * Страницы руководства --- это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём идет речь;
 * Существует очень много ситуаций, когда страница руководства --- неудобная форма представления информации. Например, если существует приложение, которое работает в графической среде, и оно довольно большое (например, !OpenOffice), то проще будет встроить документацию прямо в него;
 * Далеко не все разработчики создают отвечающие стандартам страницы руководств.
Line 59: Line 56:
Как устроены страницы руководства: они лежат в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в формате, зажатые gzip. При это, если есть документация на языке, отл. т стандартная, то она ледит в подкаталоге с наз. языка. === info ===

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

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

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

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

Информационный поиск: 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/имя_пакета-номер-версии

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


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

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

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

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

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

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

Level

Maintainer

Start date

End date

90

1

1

1

1

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


CategoryLectures CategoryPspo CategoryMpgu CategoryUneex

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