12415
Комментарий:
|
12745
|
Удаления помечены так. | Добавления помечены так. |
Строка 3: | Строка 3: |
Даже для гуру в процессе работы с системой неизбежны обращения к документации. Не каждый сможет запомнить всё то многообразие утилит и параметров этих утилит, которые существуют в обычной современной UNIX-подобной системе. Так, команда ls версии GNU имеет в качестве своих коротких параметров все буквы латинского алфавита, кроме j и y (хотя, вероятно, и их скоро займут). | В процессе работы с системой неизбежны обращения к документации, это справедливо как для новичка, так и для опытного пользователя. Не каждый сможет запомнить всё то многообразие утилит и параметров этих утилит, которые существуют в обычной современной UNIX-подобной системе. Так, команда ls версии GNU имеет в качестве своих коротких параметров все буквы латинского алфавита, кроме j и y (хотя, вероятно, и их скоро займут). |
Строка 9: | Строка 9: |
Классическая UNIX-идеология, когда всё писалось сильно связанным сообществом, сразу подразумевала, что любая сущность сопровождается документацией, страницей руководства (Usage Manual). Такое название и получила соответствующая подсистема --- man pages. Структура всех страниц и каждой страницы в отдельности чётко сформулирована. К сожалению, есть разработчики, которые не зоздают страниц руководства, соответствующих этой структуре. В Debian Policy на этот счёт сказано, что пакет не может существовать без хоть какой-нибудь правильной страницы руководства. Итак, имеем две аксиомы: * Каждая сущность (утилиты, системные вызовы) должна быть документирована |
Классическая UNIX-идеология, когда всё писалось сильно связанным сообществом, подразумевала, что любой программный продукт сопровождается документацией, страницей руководства (Usage Manual). Такое название и получила соответствующая подсистема --- man pages. Структура всех страниц и каждой страницы в отдельности чётко сформулирована. К сожалению, есть разработчики, которые не создают страниц руководства, соответствующих этой структуре. В Debian Policy сказано, что пакет не может существовать без хоть какой-нибудь правильной страницы руководства. Итак, имеем две аксиомы: * Каждый программный продукт (утилиты, системные вызовы) должен быть документирован; |
Строка 17: | Строка 17: |
* DESCRIPTION. Достаточное описание того, что делает объект; | * DESCRIPTION. Достаточно полное описание того, что делает объект; |
Строка 19: | Строка 19: |
* Если это утилита и в ней есть ключи, то существует раздел OPTIONS; | * Если это прогрманный продукт --- утилита и в ней есть ключи, то существует раздел OPTIONS, их описывающий; |
Строка 29: | Строка 29: |
Рассмотрим утилиты apropos и whatis. Из всех страниц помощи создаётся сводная таблица (mandb), в который содержатся строчки из NAME. И apropos, и whatis занимаются поиском слова по таблице. Результатом whatis является те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой части. | Рассмотрим apropos и whatis. Из всех страниц помощи создаётся сводная таблица (mandb), в который содержатся строчки из NAME. И apropos, и whatis занимаются поиском слова по таблице. Результатом whatis является те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой части. |
Строка 31: | Строка 31: |
Номера разделов --- традиционно все страницы руководства разделяются на несколько разделов --- канонически, 8 плюс ещё несколько: | Традиционно все страницы руководства разделяются на несколько разделов, общепринятая нумерация разделов означает следующее: |
Строка 41: | Строка 41: |
* n --- new --- куда всякие лентяи, которым лень положить страницу в правильный раздел, складывают документацию. | * n --- new --- документация, еще не направленная в соответствующий раздел. |
Строка 43: | Строка 43: |
Такая структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Таким образом получается довольно хитрая иерархия, условно, гипертекст, в котором несколько видов ссылок. * Ссылки внутри текста * Ссылки родовые (ссылки внутри раздела) * Ссылки в see also К сожалению, программа less (программа-pager, то есть, программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Если так хочется, то, например, в KDE есть смотрелка манов с хождением по ссылкам подобно веб-браузеру. |
Такова структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Таким образом, получается довольно сложная иерархическая система, условно говоря, гипертекст, в котором несколько видов ссылок: * Ссылки внутри текста; * Ссылки родовые (ссылки внутри раздела); * Ссылки в SEE ALSO. К сожалению, программа less (программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Эта проблема решается различными способами, например, в KDE есть просмотрщик страниц руководств, в котором переход по ссылкам реализован подобно Web-браузеру. |
Строка 49: | Строка 49: |
Если бы дисциплина оформления соблюдалась, то хватало бы манов. Но это не так по нескольким причинам: * Страницы руководства это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём речь. * Очень много есть ситуаций, когда ман --- неудобная форма представления информации Например, если есть приложение, которое работает в графической среде, и оно довольно развесистое (опенофис), то проще будет встроить документацию прямо в него. * Далеко не все хотят это делать. |
Если бы дисциплина оформления всегда соблюдалась, то хватало бы только страниц руководств. Но это не так по нескольким причинам: * Страницы руководства --- это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём идет речь; * Существует очень много ситуаций, когда страница руководства --- неудобная форма представления информации. Например, если существует приложение, которое работает в графической среде, и оно довольно большое (например, OpenOffice), то проще будет встроить документацию прямо в него; * Далеко не все разработчики создают отвечающие стандартам страницы руководств. |
Строка 56: | Строка 56: |
Существует ещё одна система, которая используется для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне которого находятся ссылки на документы, в каждом документе --- ссылки на другие документы, каждый документ представляет собой книжку. Дело в том, что документация для info оформляется в виде книги. Таким образом, в info можно вложить информацию гораздо более разнообразную, чем в man. Поэтому руководство некоторые любят делать в info. | Существует ещё одна система, которая используется для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне которого находятся ссылки на документы, в каждом документе --- ссылки на другие документы, и каждый документ представляет собой книгу. Таким образом, в info можно вложить информацию гораздо более разнообразную, чем в man. Поэтому руководство некоторые разработчики делают в info. |
Строка 58: | Строка 58: |
Благодаря Debian Policy, в котором сказано, что у каждой утилиты должна быть страница руководства, в случае, если страница руководства маленькая, в SEE ALSO есть ссылка на страницу в info или место, где лежит документация в другом формате. | Благодаря Debian Policy, в котором сказано, что у каждой утилиты должна быть страница руководства, в случае, если страница руководства маленькая, в SEE ALSO есть ссылка на страницу в info или место, где находится документация в другом формате. |
Строка 60: | Строка 60: |
И man, и info распространяются вместе с программными продуктами, и пишет их та же команда, что и сам продукт. С другой стороны, у этого есть недостаток --- страницы руководства пишутся обычно на английском. Существует проект перевода страниц руководства на русский, но нельзя забывать, что это слабомотивируемая идея. Поэтому далеко не всё переведено, а то, что переведено, не всегда актуально. | И man, и info распространяются вместе с программными продуктами, и пишет их та же команда, что и сам продукт. С другой стороны, у этого есть недостаток: страницы руководства обычно написаны на английском. Существует проект перевода страниц руководства на русский, но нельзя забывать, что это слабомотивируемая идея. Поэтому далеко не всё переведено, а то, что переведено, не всегда актуально. |
Строка 68: | Строка 68: |
Кроме того, есть вариант, что автор поленился сделать документацию в формате man/info, то может быть несколько случаев: | Кроме того, бывает так, что автор поленился сделать документацию в формате man/info, то может быть несколько случаев: |
Строка 80: | Строка 80: |
|| 35 || 1 || 1 || 1 || || 1 || MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko || || || | || 48 || 1 || 1 || 1 || || 1 || MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko || || || |
Информационный поиск: 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 ищет в любой части.
Традиционно все страницы руководства разделяются на несколько разделов, общепринятая нумерация разделов означает следующее:
- 1 --- утилиты;
- 2 --- системные вызовы;
- 3 --- библиотечные вызовы;
- 4 --- устройства;
- 5 --- структура разл. файлов (конфигурационные);
- 6 --- игры;
- 7 --- всё остальное;
- 8 --- административные команды;
- 9 --- внутренние ядерные вызовы;
- n --- new --- документация, еще не направленная в соответствующий раздел.
Такова структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Таким образом, получается довольно сложная иерархическая система, условно говоря, гипертекст, в котором несколько видов ссылок:
- Ссылки внутри текста;
- Ссылки родовые (ссылки внутри раздела);
- Ссылки в SEE ALSO.
К сожалению, программа less (программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Эта проблема решается различными способами, например, в KDE есть просмотрщик страниц руководств, в котором переход по ссылкам реализован подобно Web-браузеру.
Если бы дисциплина оформления всегда соблюдалась, то хватало бы только страниц руководств. Но это не так по нескольким причинам:
- Страницы руководства --- это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём идет речь;
Существует очень много ситуаций, когда страница руководства --- неудобная форма представления информации. Например, если существует приложение, которое работает в графической среде, и оно довольно большое (например, OpenOffice), то проще будет встроить документацию прямо в него;
- Далеко не все разработчики создают отвечающие стандартам страницы руководств.
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 |
48 |
1 |
1 |
1 |
|
1 |
MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko |
|
|