Differences between revisions 4 and 22 (spanning 18 versions)
Revision 4 as of 2008-08-03 15:35:07
Size: 12237
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:
## В процессе работы обычно приходиться обращаться к документации. Без того, чтобы рассказать что-то дже человеку, который в теме, без того, чтбы посм. в дк., дело не обходится. Прежде, чем закруглиться, неплохо было бы наметить напрвления, куда двигаться дальше, где искать инфрмацию.

Даже для гуру в процессе работы с системой неизбежны обращения к документации
. Не каждый сможет запомнить всё то многообразие утилит и параметров этих утилит, которые существуют в обычной современной UNIX-подобной системе. Так, команда ls версии GNU имеет в качестве своих коротких параметров все буквы латинского алфавита, кроме j и y (хотя, вероятно, и их скоро займут).
В процессе работы с системой неизбежны обращения к документации, это справедливо как для новичка, так и для опытного пользователя. Не каждый сможет запомнить всё то многообразие утилит и параметров этих утилит, которые существуют в обычной современной UNIX-подобной системе. Так, команда ls версии GNU имеет в качестве своих коротких параметров все буквы латинского алфавита, кроме j и y (хотя, вероятно, и их скоро займут).
Line 11: Line 9:
Классическая UNIX-идеология, когда всё писалсь сильно связанным собществом, сразу подразумевала, что любая суцщность сопрвождается дкументацией, страницей руководства (Usage Manual). Такое назхвание и получил соответствующая подсистема --- man pages. Структура всех страниц и каждой странцы в отдельности чётко задана. К сожалению, есть разработчики, которые считают себя выше написания соответствующих этой структуре страниц. В Debian Policy на этот счёт сказано, что пакет не может существовать без хоть какой-нибудь правильной страницы руководства. А вообще говоря,
 * Каждая сущность (утилиты, системные вызовы) должна быть дкументирована
 * Структур стрницыв руководства жёстко регламентирована. Например, NAME --- имя сущности
С одной стороны, это людей жёстко дисциплинирует, с другй --- облегчет пользвателю поиск.
Классическая UNIX-идеология, когда всё писалось сильно связанным сообществом, подразумевала, что любой программный продукт сопровождается документацией, страницей руководства (Usage Manual). Отсюда и получила название соответствующая подсистема --- man pages. Структура всех страниц и каждой страницы в отдельности чётко сформулирована. К сожалению, есть разработчики, которые не создают страниц руководства, соответствующих этой структуре. Разработчики дистрибутива Debian используют стандарт, согласно которому, пакет не может существовать в хранилище без правильно оформленной страницы руководства, чем сильно упростили многим жизнь.
Line 16: Line 11:
Пример: man man. (man --- программа просмотра стрниц руководства, по ней тоже есть руководство)
 * Секция NAME. Название и краткое описание
 * SYNOPSIS. Описание объекта. В квадратных скобках указываются необязательные праметры, подчёркнутое --- имена объектов. Фигурные скобки --- выбор одного из элементов, разделённых вертикально чертой.
 * DESCRIPTION. Достаточное описание того, что делает объект.
 * RETURN. Возвращаемые утилитой значения.
 * Если это утилит и там есть ключи, то есть раздел OPTIONS.
 * FILES. Ссылки на используемые (конфигурационные) файлы данной утилиты.
 * Дальше есть секции необязательного вида
 * Если команда испольует переменные окружения, то должн быть секиця ENVIROMENT
 * SEE ALSO. Одна из самых важных секций. Тким обрзом организуется семнтическая сеть. Здесь описано, какие другие стрницы руководста рекомендует автор посмотреть, если вы этой темой интересуетесь.
  * apropos, whatis --- поиск по секции NAME страниц руководства
  * groff --- форматировние страниц терминал для вывода
 * BUGS
 * TIPS, EXAMPLES
Наличие тех или иных секции --- исключительно дело автора, единственным обязательным является NAME, но указанные очень рекмендуются
Итак, имеем две аксиомы:
 * Каждый программный продукт (утилиты, системные вызовы) должен быть документирован;
 * Структура страницы руководства жёстко регламентирована.
Введение таких мер облегчает пользователю информационный поиск.
Line 32: Line 16:
apropos и whatis. Из всех страниц помощи создаётся сводная таблица (mandb), в ктороый сдержатся строчки из NAME. И apropos и whatis занимаются поиском слова по таблице. Результатом whatis явл. те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой стороне. Man --- программа просмотра страниц руководства, по ней тоже существует руководство. Чтобы просмотреть его, выполним {{{ man man}}}. Рассмотрим структуру руководства. Оно подразделяется на секции:
 * NAME. Она содержит название и краткое описание программного продукта;
 * SYNOPSIS содержит описание объекта. Здесь в квадратных скобках указываются необязательные параметры, фигурные скобки означают выбор одного из элементов, разделённых вертикально чертой, имена объектов подчеркиваются;
 * DESCRIPTION. Достаточно полное описание того, что делает объект;
 * RETURN. Возвращаемые утилитой значения;
 * Если этот программнный продукт является утилитой, и в нем есть ключи, то существует раздел OPTIONS, их описывающий;
 * FILES. Ссылки на используемые конфигурационные файлы данной утилиты;
 * Если описываемый объект использует переменные окружения, то должна существовать секция ENVIROMENT;
 * SEE ALSO --- одна из самых важных секций, с ее помощью организуется семантическая сеть. Здесь описаны другие страницы руководства, которые автор рекомендует посмотреть, так как они связаны с описываемым объектом;
 * Секция BUGS описывает известные неполадки в работе программного продукта;
 * Секция TIPS, EXAMPLES содержит в себе примеры.
Наличие тех или иных секций --- исключительно дело автора, единственной обязательной является NAME, но указанные очень рекомендуются.
Line 34: Line 29:
Номера разделов --- традиционно все страницы руководства разделяются на несколько разделв --- 8 плюс ещё несколько
 * 1 --- утилиты
 * 2 --- системные вызовы
 * 3 --- библиотечные вызовы
 * 4 --- устройства
 * 5 --- структура разл. файлов (конфигурационные)
 * 6 --- игры
 * 7 --- всё остальне
 * 8 --- административные команды
 * 9 --- внутренние ядерные вызовы
 * n --- new --- куда всякие лентяи складывают документацию, если лень документироывать
Рассмотрим программы apropos и whatis, осуществляющие поиск по секции NAME страниц руководства. Из всех страниц помощи создаётся сводная таблица (mandb), в который содержатся строчки из NAME. И apropos, и whatis занимаются поиском слова по таблице. Результатом whatis является те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой части. Среди прочих программ, полезных при информационным поиске, стоит выделить groff, отвечающую за форматирование страниц для вывода на терминал.
Line 46: Line 31:
Такая структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Такми образом получается довлоьно хитрая иерархия, условно, гипертекст, в котором несколько видов ссылок.
 * Ссылки внутри текста
 * Ссылки родовые (ссылки внутри раздела)
 * Ссылки в see also
К сожалению, прграмма less не умеет интерпретировать ссылки. Если так хочется, то, например, в kde есть смотрелка манов с хождением по ссылкам подобно веб-браузеру.
Традиционно все страницы руководства разделяются на несколько разделов, общепринятая нумерация разделов означает следующее:
 * 1 --- утилиты;
 * 2 --- системные вызовы;
 * 3 --- библиотечные вызовы;
 * 4 --- устройства;
 * 5 --- структура разл. файлов (конфигурационные);
 * 6 --- игры;
 * 7 --- всё остальное;
 * 8 --- административные команды;
 * 9 --- внутренние ядерные вызовы;
 * n --- new --- документация, еще не направленная в соответствующий раздел.
Line 52: Line 43:
Если бы дисциплина оформления сблюдалась, то хватало бы манов. Но это не так по нескольким причинам:
 * Страницы руководства это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кт знает, о чём речь.
 * Очеь много есть ситуаций, когда ман --- неудобная форма представления информации Например, если есть приложение, которое работает в графической среде, и оно довольно развесистое (опенофис), то проще будет всроить документацию прямо в него.
 * Далеко не все хотят это делать.
Страницы руководства находятся в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в специальном формате, сжатые с помощью gzip. Если существует документация на языке, отличном от стандартного, то она лежит в подкаталоге с названием языка.

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

Если бы дисциплина оформления всегда соблюдалась, то хватало бы только страниц руководств. Но это не так по нескольким причинам:
 * Страницы руководства --- это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём идет речь;
 * Существует очень много ситуаций, когда страница руководства --- неудобная форма представления информации. Например, если существует приложение, которое работает в графической среде, и оно довольно большое (например, !OpenOffice), то проще будет встроить документацию прямо в него;
 * Далеко не все разработчики создают отвечающие стандартам страницы руководств.
Line 59: Line 58:
Есть ещё одн система, которая используется для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне ссылки на документы, в каждом документе ссылки на другие дкументы, каждый документ представляет собой книжку. Существует ещё одна система, которая используется для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне которого находятся ссылки на документы, в каждом документе --- ссылки на другие документы, и каждый документ представляет собой книгу. Таким образом, в info можно вложить информацию гораздо более разнообразную, чем в man. Поэтому руководство некоторые разработчики делают в info.
Line 61: Line 60:
Дел в том, что документация для info оформляется в виде книги. Таким образом, в info моожно вложить информацию более разного вдиа, чем в man. Поэтому руководство некторые любят делать в info. В Debian Policy сказано, что у каждой утилиты должна быть страница руководства, в случае, если страница руководства маленькая, в секции SEE ALSO есть ссылка на страницу в info или место, где находится документация в другом формате.
Line 63: Line 62:
Спасибо Debian Policy, в котором сказано, что у каждй утилиты должна быть страница руководства. В таком случае страница руководства маленькая и в SEE ALSO есть ссылка на страницу в info или место, где лежит документация в другом формате. И man, и info распространяются вместе с программными продуктами, и пишет их та же команда, что и сам продукт. С другой стороны, у этого есть недостаток: страницы руководства обычно написаны на английском. Существует проект перевода страниц руководства на русский, но нельзя забывать, что это слабомотивируемая идея (ведь программные продукты обновляются, а с обновлением придётся переводить всё по новой). Поэтому далеко не всё переведено, а то, что переведено, не всегда актуально.
Line 65: Line 64:
Почему лектор начал с man и info --- птому что она распространяется вместе с программными прдуктами, пишет её та же команда, что и сам прдукт. С другой стороны, у этого есть недостаток --- страницы руководства пишутся бычно на английском. Существует проект перевод страниц руководства на русский, но надо понимать, что это слабомотивируемая идея. В принципе, кому интересно, как происх перевод, была лекция на эту тему в прошлом году. Поэтому не всё переведено, а что переведено, не всегда актуально.

Как устроены страницы руководства: они лежат в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в специальном формате, зажатые gzip. При это, если есть документация на языке, отличном от стандартного, то она ледит в подкаталоге с названием языка.
=== Другие источники документации ===
Line 71: Line 68:
Кроме того, есть вариант, что автор поленился сделать док. в формате man/info, то может быть неск. случаев:
 * Сказать имя программы с ключём -h/--help
 * Можно посмотреть, нет ли документации к программному продукту в непонятном фрмате. Такая инф. лежит в каталоге /usr/shre/doc/имя_пакета-номер-версии
Кроме того, бывает так, что автор поленился сделать документацию в формате man/info, то может быть несколько случаев:
 * Вызвать программу с ключом -h или --help
 * Посмотреть, нет ли документации к программному продукту в непонятном формате. Такая информация лежит в каталоге /usr/share/doc/имя_пакета-номер-версии
Line 75: Line 72:
Эта документация частично составляется манейнером. Эта документация частично составляется мэйнтейнером.
Line 83: Line 80:
|| 9 || 1 || 1 || 1 || || 1 || MaximByshevskiKonopko, ОльгаТочилкина, 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)