12237
Комментарий:
|
12702
|
Удаления помечены так. | Добавления помечены так. |
Строка 2: | Строка 2: |
## В процессе работы обычно приходиться обращаться к документации. Без того, чтобы рассказать что-то дже человеку, который в теме, без того, чтбы посм. в дк., дело не обходится. Прежде, чем закруглиться, неплохо было бы наметить напрвления, куда двигаться дальше, где искать инфрмацию. |
|
Строка 11: | Строка 9: |
Классическая UNIX-идеология, когда всё писалсь сильно связанным собществом, сразу подразумевала, что любая суцщность сопрвождается дкументацией, страницей руководства (Usage Manual). Такое назхвание и получил соответствующая подсистема --- man pages. Структура всех страниц и каждой странцы в отдельности чётко задана. К сожалению, есть разработчики, которые считают себя выше написания соответствующих этой структуре страниц. В Debian Policy на этот счёт сказано, что пакет не может существовать без хоть какой-нибудь правильной страницы руководства. А вообще говоря, * Каждая сущность (утилиты, системные вызовы) должна быть дкументирована * Структур стрницыв руководства жёстко регламентирована. Например, NAME --- имя сущности С одной стороны, это людей жёстко дисциплинирует, с другй --- облегчет пользвателю поиск. |
Классическая UNIX-идеология, когда всё писалось сильно связанным сообществом, сразу подразумевала, что любая сущность сопровождается документацией, страницей руководства (Usage Manual). Такое название и получила соответствующая подсистема --- man pages. Структура всех страниц и каждой страницы в отдельности чётко задана. К сожалению, есть разработчики, которые считают себя выше написания соответствующих этой структуре страниц. В Debian Policy на этот счёт сказано, что пакет не может существовать без хоть какой-нибудь правильной страницы руководства. А вообще говоря, * Каждая сущность (утилиты, системные вызовы) должна быть документирована * Структура страницы руководства жёстко регламентирована. Например, NAME --- имя сущности С одной стороны, это людей жёстко дисциплинирует, с другой --- облегчает пользователю поиск. |
Строка 16: | Строка 14: |
Пример: man man. (man --- программа просмотра стрниц руководства, по ней тоже есть руководство) * Секция NAME. Название и краткое описание * SYNOPSIS. Описание объекта. В квадратных скобках указываются необязательные праметры, подчёркнутое --- имена объектов. Фигурные скобки --- выбор одного из элементов, разделённых вертикально чертой. * DESCRIPTION. Достаточное описание того, что делает объект. * RETURN. Возвращаемые утилитой значения. * Если это утилит и там есть ключи, то есть раздел OPTIONS. * FILES. Ссылки на используемые (конфигурационные) файлы данной утилиты. * Дальше есть секции необязательного вида * Если команда испольует переменные окружения, то должн быть секиця ENVIROMENT * SEE ALSO. Одна из самых важных секций. Тким обрзом организуется семнтическая сеть. Здесь описано, какие другие стрницы руководста рекомендует автор посмотреть, если вы этой темой интересуетесь. * apropos, whatis --- поиск по секции NAME страниц руководства * groff --- форматировние страниц терминал для вывода * BUGS * TIPS, EXAMPLES Наличие тех или иных секции --- исключительно дело автора, единственным обязательным является NAME, но указанные очень рекмендуются |
Man --- программа просмотра страниц руководства, по ней тоже есть руководство. Чтобы просмотреть его, выполним {{{ man man}}}. Рассмотрим структуру руководства: * Секция NAME. Она содержит название и краткое описание; * SYNOPSIS --- описание объекта. Здесь в квадратных скобках указываются необязательные параметры, фигурные скобки означают выбор одного из элементов, разделённых вертикально чертой, имена объектов подчеркиваются; * DESCRIPTION. Достаточное описание того, что делает объект; * RETURN. Возвращаемые утилитой значения; * Если это утилита и в ней есть ключи, то существует раздел OPTIONS; * FILES. Ссылки на используемые конфигурационные файлы данной утилиты. * Существуют также секции необязательного вида: * Если описываемый объект использует переменные окружения, то должна существовать секция ENVIROMENT; * SEE ALSO. Одна из самых важных секций, с ее помощью организуется семантическая сеть. Здесь описаны другие страницы руководства, которые автор рекомендует посмотреть, если вы интересуетесь этой темой; * apropos, whatis --- поиск по секции NAME страниц руководства; * groff --- форматирование страниц для вывода на терминал; * Секция BUGS описывает известные неполадки в работе программного продукта; * Секция TIPS, EXAMPLES содержит в себе примеры. Наличие тех или иных секций --- исключительно дело автора, единственным обязательным является NAME, но указанные очень рекомендуются. |
Строка 32: | Строка 30: |
apropos и whatis. Из всех страниц помощи создаётся сводная таблица (mandb), в ктороый сдержатся строчки из NAME. И apropos и whatis занимаются поиском слова по таблице. Результатом whatis явл. те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой стороне. | Рассмотрим утилиты apropos и whatis. Из всех страниц помощи создаётся сводная таблица (mandb), в который содержатся строчки из NAME. И apropos, и whatis занимаются поиском слова по таблице. Результатом whatis является те строки, в которых есть ключевое слово в левой части. Apropos ищет в любой части. |
Строка 34: | Строка 32: |
Номера разделов --- традиционно все страницы руководства разделяются на несколько разделв --- 8 плюс ещё несколько | Номера разделов --- традиционно все страницы руководства разделяются на несколько разделов --- канонически, 8 плюс ещё несколько: |
Строка 41: | Строка 39: |
* 7 --- всё остальне | * 7 --- всё остальное |
Строка 44: | Строка 42: |
* n --- new --- куда всякие лентяи складывают документацию, если лень документироывать | * n --- new --- куда всякие лентяи, которым лень положить страницу в правильный раздел, складывают документацию. |
Строка 46: | Строка 44: |
Такая структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Такми образом получается довлоьно хитрая иерархия, условно, гипертекст, в котором несколько видов ссылок. | Такая структура manpages. Внутри страниц руководств может быть ссылка вида (See something(*)). Таким образом получается довольно хитрая иерархия, условно, гипертекст, в котором несколько видов ссылок. |
Строка 50: | Строка 48: |
К сожалению, прграмма less не умеет интерпретировать ссылки. Если так хочется, то, например, в kde есть смотрелка манов с хождением по ссылкам подобно веб-браузеру. | К сожалению, программа less (программа-pager, то есть, программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Если так хочется, то, например, в KDE есть смотрелка манов с хождением по ссылкам подобно веб-браузеру. |
Строка 52: | Строка 50: |
Если бы дисциплина оформления сблюдалась, то хватало бы манов. Но это не так по нескольким причинам: * Страницы руководства это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кт знает, о чём речь. * Очеь много есть ситуаций, когда ман --- неудобная форма представления информации Например, если есть приложение, которое работает в графической среде, и оно довольно развесистое (опенофис), то проще будет всроить документацию прямо в него. |
Если бы дисциплина оформления соблюдалась, то хватало бы манов. Но это не так по нескольким причинам: * Страницы руководства это не учебники. Главная их цель --- внешняя память. Фактически, страницы руководства написаны для тех, кто знает, о чём речь. * Очень много есть ситуаций, когда ман --- неудобная форма представления информации Например, если есть приложение, которое работает в графической среде, и оно довольно развесистое (опенофис), то проще будет встроить документацию прямо в него. |
Строка 59: | Строка 57: |
Есть ещё одн система, которая используется для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне ссылки на документы, в каждом документе ссылки на другие дкументы, каждый документ представляет собой книжку. | Есть ещё одн система, которая используется для хранения подобной информации --- info. В отличие от жёсткой структуры страниц руководств, info --- дерево, в корне ссылки на документы, в каждом документе ссылки на другие документы, каждый документ представляет собой книжку. |
Строка 61: | Строка 59: |
Дел в том, что документация для info оформляется в виде книги. Таким образом, в info моожно вложить информацию более разного вдиа, чем в man. Поэтому руководство некторые любят делать в info. | Дел в том, что документация для info оформляется в виде книги. Таким образом, в info можно вложить информацию более разного вида, чем в man. Поэтому руководство некоторые любят делать в info. |
Строка 63: | Строка 61: |
Спасибо Debian Policy, в котором сказано, что у каждй утилиты должна быть страница руководства. В таком случае страница руководства маленькая и в SEE ALSO есть ссылка на страницу в info или место, где лежит документация в другом формате. | Спасибо Debian Policy, в котором сказано, что у каждой утилиты должна быть страница руководства. В таком случае страница руководства маленькая и в SEE ALSO есть ссылка на страницу в info или место, где лежит документация в другом формате. |
Строка 65: | Строка 63: |
Почему лектор начал с man и info --- птому что она распространяется вместе с программными прдуктами, пишет её та же команда, что и сам прдукт. С другой стороны, у этого есть недостаток --- страницы руководства пишутся бычно на английском. Существует проект перевод страниц руководства на русский, но надо понимать, что это слабомотивируемая идея. В принципе, кому интересно, как происх перевод, была лекция на эту тему в прошлом году. Поэтому не всё переведено, а что переведено, не всегда актуально. | Почему лектор начал с man и info --- птому что она распространяется вместе с программными продуктами, пишет её та же команда, что и сам продукт. С другой стороны, у этого есть недостаток --- страницы руководства пишутся обычно на английском. Существует проект перевода страниц руководства на русский, но надо понимать, что это слабомотивируемая идея. В принципе, кому интересно, как происходит перевод, была лекция на эту тему в прошлом году. Поэтому не всё переведено, а что переведено, не всегда актуально. |
Строка 67: | Строка 65: |
Как устроены страницы руководства: они лежат в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в специальном формате, зажатые gzip. При это, если есть документация на языке, отличном от стандартного, то она ледит в подкаталоге с названием языка. | Как устроены страницы руководства: они лежат в /usr/share/man в каталогах man[1-8n], и в каждом каталоге лежат файлы в специальном формате, зажатые gzip. При это, если есть документация на языке, отличном от стандартного, то она лежит в подкаталоге с названием языка. === Другие источники документации === |
Строка 71: | Строка 71: |
Кроме того, есть вариант, что автор поленился сделать док. в формате man/info, то может быть неск. случаев: * Сказать имя программы с ключём -h/--help * Можно посмотреть, нет ли документации к программному продукту в непонятном фрмате. Такая инф. лежит в каталоге /usr/shre/doc/имя_пакета-номер-версии |
Кроме того, есть вариант, что автор поленился сделать документацию в формате man/info, то может быть несколько случаев: * Вызвать программу с ключом -h или --help * Посмотреть, нет ли документации к программному продукту в непонятном формате. Такая информация лежит в каталоге /usr/share/doc/имя_пакета-номер-версии |
Строка 75: | Строка 75: |
Эта документация частично составляется манейнером. | Эта документация частично составляется мэйнтейнером. |
Строка 83: | Строка 83: |
|| 9 || 1 || 1 || 1 || || 1 || MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko || || || | || 25 || 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 (программа-pager, то есть, программа для поэкранного вывода длинного текста, использующаяся по-умолчанию в большинстве систем для просмотра man) не умеет интерпретировать ссылки. Если так хочется, то, например, в 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/share/doc/имя_пакета-номер-версии
Эта документация частично составляется мэйнтейнером.
Сведения о ресурсах
Готовность (%) |
Продолжительность (ак. ч.) |
Подготовка (календ. ч.) |
Полный текст (раб. д.) |
Предварительные знания |
Level |
Maintainer |
Start date |
End date |
25 |
1 |
1 |
1 |
|
1 |
MaximByshevskiKonopko, ОльгаТочилкина, MaximByshevskiKonopko |
|
|