Различия между версиями 2 и 4 (по 2 версиям)
Версия 2 от 2008-07-21 20:49:44
Размер: 10500
Редактор: eSyr
Комментарий:
Версия 4 от 2008-08-03 15:35:07
Размер: 12237
Редактор: MaximByshevskiKonopko
Комментарий:
Удаления помечены так. Добавления помечены так.
Строка 3: Строка 3:
В процессе обычно очень часто приходиться обращаться к документации: к домкументцию по test, по bash... Без того, чтобы рассказать что-то дже человеку, который в теме, без того, чтбы посм. в дк., дело не обходится. Прежде, чем закруглиться, неплохо было бы наметить напрвления, куда двигаться дальше, где искать инфрмацию. ## В процессе работы обычно приходиться обращаться к документации. Без того, чтобы рассказать что-то дже человеку, который в теме, без того, чтбы посм. в дк., дело не обходится. Прежде, чем закруглиться, неплохо было бы наметить напрвления, куда двигаться дальше, где искать инфрмацию.
Строка 5: Строка 5:
Надо начать вот с чего. Классическая UNIX-идеология, когда всё писалсь сильно связанным собществом. Классическая никсовая иделогия сразу подразумевала, что люая суцщность сопрвождается дкументацией, страницей руководства. Такое назхвание и получил соотв. подсистем --- man pages. В чём смысл стрниц рук-в: это жёстко секционированные тексты, в кторых сначал формально объясн., что это такое.
 * Каждая сущнсть (утилиты, сист. вызовы) должна быть дкументирована
Даже для гуру в процессе работы с системой неизбежны обращения к документации. Не каждый сможет запомнить всё то многообразие утилит и параметров этих утилит, которые существуют в обычной современной UNIX-подобной системе. Так, команда ls версии GNU имеет в качестве своих коротких параметров все буквы латинского алфавита, кроме j и y (хотя, вероятно, и их скоро займут).

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

=== man ===

Классическая UNIX-идеология, когда всё писалсь сильно связанным собществом, сразу подразумевала, что любая суцщность сопрвождается дкументацией, страницей руководства (Usage Manual). Такое назхвание и получил соответствующая подсистема --- man pages. Структура всех страниц и каждой странцы в отдельности чётко задана. К сожалению, есть разработчики, которые считают себя выше написания соответствующих этой структуре страниц. В Debian Policy на этот счёт сказано, что пакет не может существовать без хоть какой-нибудь правильной страницы руководства. А вообще говоря,
 * Каждая сущность (утилиты, системные вызовы) должна быть дкументирована
Строка 12: Строка 18:
 * SYNOPSIS. Описание объекта. В квадр. скобках указываются необяз. праметры, подчёркнутое --- имена объектв. Фигурные скобки --- выбор одного из элементов, разд. верт. чертой.
 * DESCRIPTION. Достаточное описание тог, что делает объект.
 * RETURN
 * Если эт утилит и там есть ключи, то есть раздел OPTIONS.
 * FILES если есть файлы, для которых нет страниц рук-ва
 * SYNOPSIS. Описание объекта. В квадратных скобках указываются необязательные праметры, подчёркнутое --- имена объектов. Фигурные скобки --- выбор одного из элементов, разделённых вертикально чертой.
 * DESCRIPTION. Достаточное описание того, что делает объект.
 * RETURN. Возвращаемые утилитой значения.
 * Если это утилит и там есть ключи, то есть раздел OPTIONS.
 * FILES. Ссылки на используемые (конфигурационные) файлы данной утилиты.
Строка 18: Строка 24:
 * Если команда испольует переменные окр, т должн быть секиця ENVIROMENT
 * SEE ALSO. Одна из самых вжных секций. Тким обрзом орг. семнтическая сеть. Здесь опис., какие другие стрницы руководста рекомендует автор посмотреть, если вы этой темой интересуетесь.
 * Если команда испольует переменные окружения, то должн быть секиця ENVIROMENT
 * SEE ALSO. Одна из самых важных секций. Тким обрзом организуется семнтическая сеть. Здесь описано, какие другие стрницы руководста рекомендует автор посмотреть, если вы этой темой интересуетесь.
Строка 21: Строка 27:
  * groff --- форматировние страниц терминл для вывода   * groff --- форматировние страниц терминал для вывода
Строка 24: Строка 30:
Наличие тех или иных секции --- искл. дело автора, един. обязательным является NAME, но указанные очень рекмендуются Наличие тех или иных секции --- исключительно дело автора, единственным обязательным является NAME, но указанные очень рекмендуются
Строка 26: Строка 32:
apropos и whatis. Из всех страниц помощи создаётся сводная таблица, в ктороый сдержатся строчки из NAME. И apropos и whatis занимаются поиском слова по таблице. Результатом whatis явл. те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой стороне. apropos и whatis. Из всех страниц помощи создаётся сводная таблица (mandb), в ктороый сдержатся строчки из NAME. И apropos и whatis занимаются поиском слова по таблице. Результатом whatis явл. те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой стороне.
Строка 28: Строка 34:
Номера разделов --- традиц. все стр. руководства разделяются на неск. разделв --- 8 плюс ещё неск. Номера разделов --- традиционно все страницы руководства разделяются на несколько разделв --- 8 плюс ещё несколько
Строка 37: Строка 43:
 * 9 --- внутр. ядерные вызовы  * 9 --- внутренние ядерные вызовы
Строка 40: Строка 46:
Такая структура manpages. Внутри стр. руководств может быть ссылка вида (See something(*)). Такми образом получается довлоьно хитрая иерархия, гипертекст, в котором неск. видов ссылок. Такая структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Такми образом получается довлоьно хитрая иерархия, условно, гипертекст, в котором несколько видов ссылок.
Строка 44: Строка 50:
К сожалению, прграмма less не умеет интерп. ссылки. Если так хчется, то, например, в kde есть смотрелка манов. К сожалению, прграмма less не умеет интерпретировать ссылки. Если так хочется, то, например, в kde есть смотрелка манов с хождением по ссылкам подобно веб-браузеру.
Строка 46: Строка 52:
Если бы дисц. сблюдалась, то хватало бы манов. Но это не так по неск. причинам:
 * Страницы руководства это не учебники. Главная их цель --- внешняя память. Факт., страницы рук-ва написаны для тех, кт знает, о чём речь.
 * Очеь много есть ситуаций, когда ман --- неудобная форма предст. инф. Например, если есть приложение, которое работает в граф. среде, и оно довольно развесистое (опенофис), то правильно всроить документацию прямо в него.
Если бы дисциплина оформления сблюдалась, то хватало бы манов. Но это не так по нескольким причинам:
 * Страницы руководства это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кт знает, о чём речь.
 * Очеь много есть ситуаций, когда ман --- неудобная форма представления информации Например, если есть приложение, которое работает в графической среде, и оно довольно развесистое (опенофис), то проще будет всроить документацию прямо в него.
Строка 51: Строка 57:
Есть ещё одн система, которая исп. для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне ссылки на документы, в каждом документе ссылки на другие дкументы, каждый документ представляет собой книжку. === info ===
Строка 53: Строка 59:
Дел в том, что документация для info оформляется в виде книги. Т. о., в info моожно вложить инф. более разного вдиа, чем в man. Поэтому руководство некторые любят делать в info. Есть ещё одн система, которая используется для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне ссылки на документы, в каждом документе ссылки на другие дкументы, каждый документ представляет собой книжку.
Строка 55: Строка 61:
Спасибо дебиану, у кторого в полиси прописано, что у каждй утилиты должна быть страница руководства. В таком случае страница руководства маленькая и в SEE ALSO есть ссылка на страницу в info или место, где лежит документация в другом формате. Дел в том, что документация для info оформляется в виде книги. Таким образом, в info моожно вложить информацию более разного вдиа, чем в man. Поэтому руководство некторые любят делать в info.
Строка 57: Строка 63:
Почему лектор начал с man и info --- птому что она расп. вместе с прогр. прдуктами, пишет её та же команда, что и сам прдукт. С другой стороны, у этого есть недостаток --- стр. руководства пишутся бычно на английском. Существует проект перевод страниц руководства на русский, но надо понимать, что это слабомотивируемая идея. В принципе, кому интересно, как происх перевод, была лекция на эту тему в прошлом году. Поэтому не всё переведено, а что переведено, не всегда актуально. Спасибо Debian Policy, в котором сказано, что у каждй утилиты должна быть страница руководства. В таком случае страница руководства маленькая и в SEE ALSO есть ссылка на страницу в info или место, где лежит документация в другом формате.
Строка 59: Строка 65:
Как устроены страницы руководства: они лежат в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в формате, зажатые gzip. При это, если есть документация на языке, отл. т стандартная, то она ледит в подкаталоге с наз. языка. Почему лектор начал с man и info --- птому что она распространяется вместе с программными прдуктами, пишет её та же команда, что и сам прдукт. С другой стороны, у этого есть недостаток --- страницы руководства пишутся бычно на английском. Существует проект перевод страниц руководства на русский, но надо понимать, что это слабомотивируемая идея. В принципе, кому интересно, как происх перевод, была лекция на эту тему в прошлом году. Поэтому не всё переведено, а что переведено, не всегда актуально.

Как устроены страницы руководства: они лежат в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в специальном формате, зажатые gzip. При это, если есть документация на языке, отличном от стандартного, то она ледит в подкаталоге с названием языка.
Строка 75: Строка 83:
|| 0 || 1 || 1 || 1 || || 1 || PavelSutyrin, ОльгаТочилкина, MaximByshevskiKonopko || || || || 9 || 1 || 1 || 1 || || 1 || MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko || || ||

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

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

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

man

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

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

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

Пример: 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 не умеет интерпретировать ссылки. Если так хочется, то, например, в 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/shre/doc/имя_пакета-номер-версии

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


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

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

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

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

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

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

Level

Maintainer

Start date

End date

9

1

1

1

1

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


CategoryLectures CategoryPspo CategoryMpgu CategoryUneex

PspoClasses/080718/01ManInfo (последним исправлял пользователь eSyr 2009-03-22 21:53:28)