Differences between revisions 5 and 22 (spanning 17 versions)
Revision 5 as of 2008-08-03 15:51:55
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 9: Line 9:
Классическая UNIX-идеология, когда всё писалось сильно связанным сообществом, сразу подразумевала, что любая сущность сопровождается документацией, страницей руководства (Usage Manual). Такое название и получила соответствующая подсистема --- man pages. Структура всех страниц и каждой страницы в отдельности чётко задана. К сожалению, есть разработчики, которые считают себя выше написания соответствующих этой структуре страниц. В Debian Policy на этот счёт сказано, что пакет не может существовать без хоть какой-нибудь правильной страницы руководства. А вообще говоря,
 * Каждая сущность (утилиты, системные вызовы) должна быть документирована
 * Структура страницы руководства жёстко регламентирована. Например, NAME --- имя сущности
С одной стороны, это людей жёстко дисциплинирует, с другой --- облегчает пользователю поиск.
Классическая UNIX-идеология, когда всё писалось сильно связанным сообществом, подразумевала, что любой программный продукт сопровождается документацией, страницей руководства (Usage Manual). Отсюда и получила название соответствующая подсистема --- man pages. Структура всех страниц и каждой страницы в отдельности чётко сформулирована. К сожалению, есть разработчики, которые не создают страниц руководства, соответствующих этой структуре. Разработчики дистрибутива Debian используют стандарт, согласно которому, пакет не может существовать в хранилище без правильно оформленной страницы руководства, чем сильно упростили многим жизнь.
Line 14: Line 11:
Пример: man man. (man --- программа просмотра страниц руководства, по ней тоже есть руководство)
 * Секция NAME. Название и краткое описание
 * SYNOPSIS. Описание объекта. В квадратных скобках указываются необязательные параметры, подчёркнутое --- имена объектов. Фигурные скобки --- выбор одного из элементов, разделённых вертикально чертой.
 * DESCRIPTION. Достаточное описание того, что делает объект.
 * RETURN. Возвращаемые утилитой значения.
 * Если это утилит и там есть ключи, то есть раздел OPTIONS.
 * FILES. Ссылки на используемые (конфигурационные) файлы данной утилиты.
 * Дальше есть секции необязательного вида
 * Если команда использует переменные окружения, то должна быть секция ENVIROMENT
 * SEE ALSO. Одна из самых важных секций. Таким образом организуется семантическая сеть. Здесь описано, какие другие страницы руководства рекомендует автор посмотреть, если вы этой темой интересуетесь.
  * apropos, whatis --- поиск по секции NAME страниц руководства
  * groff --- форматирование страниц для вывода на терминал
 * BUGS
 * TIPS, EXAMPLES
Наличие тех или иных секций --- исключительно дело автора, единственным обязательным является NAME, но указанные очень рекомендуются.
Итак, имеем две аксиомы:
 * Каждый программный продукт (утилиты, системные вызовы) должен быть документирован;
 * Структура страницы руководства жёстко регламентирована.
Введение таких мер облегчает пользователю информационный поиск.
Line 30: 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 32: 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 44: Line 31:
Такая структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Таким образом получается довольно хитрая иерархия, условно, гипертекст, в котором несколько видов ссылок.
 * Ссылки внутри текста
 * Ссылки родовые (ссылки внутри раздела)
 * Ссылки в see also
К сожалению, программа less (программа-pager, то есть, программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Если так хочется, то, например, в KDE есть смотрелка манов с хождением по ссылкам подобно веб-браузеру.
Традиционно все страницы руководства разделяются на несколько разделов, общепринятая нумерация разделов означает следующее:
 * 1 --- утилиты;
 * 2 --- системные вызовы;
 * 3 --- библиотечные вызовы;
 * 4 --- устройства;
 * 5 --- структура разл. файлов (конфигурационные);
 * 6 --- игры;
 * 7 --- всё остальное;
 * 8 --- административные команды;
 * 9 --- внутренние ядерные вызовы;
 * n --- new --- документация, еще не направленная в соответствующий раздел.
Line 50: Line 43:
Если бы дисциплина оформления соблюдалась, то хватало бы манов. Но это не так по нескольким причинам:
 * Страницы руководства это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём речь.
 * Очень много есть ситуаций, когда ман --- неудобная форма представления информации Например, если есть приложение, которое работает в графической среде, и оно довольно развесистое (опенофис), то проще будет встроить документацию прямо в него.
 * Далеко не все хотят это делать.
Страницы руководства находятся в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в специальном формате, сжатые с помощью gzip. Если существует документация на языке, отличном от стандартного, то она лежит в подкаталоге с названием языка.

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

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

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

Как устроены страницы руководства: они лежат в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в специальном формате, зажатые gzip. При это, если есть документация на языке, отличном от стандартного, то она лежит в подкаталоге с названием языка.
И man, и info распространяются вместе с программными продуктами, и пишет их та же команда, что и сам продукт. С другой стороны, у этого есть недостаток: страницы руководства обычно написаны на английском. Существует проект перевода страниц руководства на русский, но нельзя забывать, что это слабомотивируемая идея (ведь программные продукты обновляются, а с обновлением придётся переводить всё по новой). Поэтому далеко не всё переведено, а то, что переведено, не всегда актуально.
Line 71: Line 68:
Кроме того, есть вариант, что автор поленился сделать документацию в формате man/info, то может быть несколько случаев: Кроме того, бывает так, что автор поленился сделать документацию в формате man/info, то может быть несколько случаев:
Line 83: Line 80:
|| 19 || 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)