Информационное наполнение UNIX

Особенности руководств

Бывают объекты с одинаковыми именами, но принадлежащие разным разделам, например утилита passwd, позволяющая пользователю менять пароль, и файл passwd, в котором хранится учетная запись пользователя (по иронии судьбы в современных версиях UNIX именно пароля там и нет). Для того чтобы посмотреть руководство по passwd из пятого раздела, надо использовать команду man 5 passwd, а если вам неизвестно, к какому разделу относится объект, - man -a passwd (тогда вы увидите руководства по всем объектам с именем passwd ). При ссылке на страницу руководства принято после имени объекта указывать в круглых скобках номер раздела passwd(1) и passwd(5).

В каждом разделе существует специальный объект intro, руководство по которому описывает назначение раздела и определяет основные термины. Кроме того, в поле SEE ALSO этих руководств помещаются ссылки на страницы руководства по крупным темам (например, security(7) ).

Тем не менее сеть страниц руководства - это совсем не учебник по UNIX. Тому есть три причины. Во-первых, учебник - это свод только основных знаний о предмете изучения (отрасли науки, сфере деятельности человека, некотором инструментарии и т. п.) и цель его - донести эти знания в наиболее доступном изложении. Поэтому основную часть учебника занимают вопросы обучающего плана: упражнения, разъяснения, попытки увязать факты в единую схему и т. д. Цель же руководства - сообщить все, что известно об объекте (например, поточном текстовом редакторе sed ), и указать на то, что существует некий предмет рассмотрения, с которым этот объект связан (автоматическая обработка текстов). Причем указание это делается не напрямую, а путем ссылок на иные объекты, тоже относящиеся к делу. Руководство - это справочник; его читают, когда имеют представление о том, что делать, но не знают в точности - как.

Во-вторых, У требует, чтобы при решении некоторой задачи открывающийся информационный контекст был по возможности минимален. Должен быть способ отсекать те области знания, которые не имеют отношения к текущей задаче. И вот с этой точки зрения любые дидактические надстройки над справочником - ненужный шум и, следовательно, вред.

В-третьих, учебникам, "рецептурным книгам" (cookbook) и прочим документам иного формата и назначения в UNIX отведено свое место, поэтому никакой необходимости закладывать все возможные свойства документации в одну подсистему нет.

Смысловая структура системы руководств

Первое, что бросается в глаза, - это ее совершенно естественное происхождение. Трудно поверить, что создатели этой структуры потратили много времени на ее измышление, штудируя труды по эргономике, проектированию систем, гипертекстам и т. д. Кажется, если бы нам самим захотелось разработать систему информационной поддержки, мы бы сделали ее почти такой же. Тем не менее устройство подсистемы руководств носит следы и основ эргономики (правило "7 $$\pm$$ 2", ), и принципов построения компьютерных систем, а также очевидной гипертекстовой структуры: в страницах руководства есть несколько видов гипертекстовых ссылок. Никаких механизмов перехода по ссылкам в manpages не предусмотрено: предполагается, что, во-первых, сначала лучше дочитать открытое руководство, а во-вторых, если потребуется, всегда можно запустить команду man на соседнем терминальном устройстве (виртуальной консоли или X-терминале). К тому же технически переход по некоторым видам ссылок реализовать не так просто, как это предлагают, скажем, средства просмотра HTML, где используются только контекстные гиперссылки.

Контекстными называются те ссылки, что встречаются внутри текста. Если упоминаемый в руководстве объект имеет собственное руководство, пользователю, возможно, стоит прочесть и его. Для этого, как уже было сказано, после имени объекта ставится в круглых скобках номер раздела, в котором хранится его руководство. Контекстные ссылки не выделяются из текста и почти не мешают чтению, однако именно они задают сеть, связывающую все объекты системы. Расставлять контекстные ссылки надо с осторожностью. Не каждое встреченное имя документированного объекта должно ссылаться на его документацию. Лучше всего превращать объект в контекстную ссылку, только когда читателю действительно может понадобиться соответствующее руководство: при первом упоминании объекта и в тех случаях, когда объект упоминается после продолжительного перерыва или в какой-нибудь иной ипостаси.

Объектные ссылки указывают на реальные объекты системы, например файлы в поле FILES . Этот вид ссылок определяет область действия инструмента, т. е. определяет не смысловую, а актуальную, действующую связь. Объектные ссылки помогают определить список объектов, которые надо скопировать или проверить перед применением соответствующего инструмента, или изучить после воздействия на систему. Это - род концевых ссылок, потому что из информационного пространства рассмотрение переходит в объектное.

Внешние ссылки отсылают к документации, оформленной не в формате manpage. Это может быть учебник, документация в формате info (о ней мы поговорим позже), статья по теме и т. п. Главная особенность внешних ссылок - в том, что за ними стоит по-другому и для другого организованное информационное пространство. Так что нужны они тем читателям, кто ищет в руководстве нечто, ему не свойственное: например, ответ на типовой вопрос. Из типовых вопросов и ответов обычно составляется документ под названием FAQ (frequently asked questions, или часто задаваемые вопросы, ЧаВо), а специфике руководства это не соответствует. Поэтому где-нибудь в поле SEE ALSO должна находиться внешняя ссылка на подобный документ.

Летописными ссылками мы будем называть всякое упоминание не относящихся к предмету рассмотрения объектов: историю создания утилиты, авторов, www-страницу и пр., что встречается чаще всего в полях AUTHORS, HISTORY, AVAILABILITY и т. п. Эти ссылки либо вообще приводятся для удовлетворения любопытства пользователей, либо просто косвенно дополняют описание.

Особую роль в руководстве играет поле SEE ALSO . Состоит оно обыкновенно из информационно нагруженных контекстных или внешних ссылок, список которых целиком остается на совести составителя руководства. Функция поля SEE ALSO заключается в создании контекста вокруг описываемого объекта, или, как было сказано выше, в указании предмета рассмотрения путем перечисления относящихся к делу объектов. Используемые в таком качестве ссылки можно называть предметными . В случае предметных ссылок особенно отчетливо работает О: от того, насколько продуманным будет контекст, зависит не только положение страницы руководства в информационной сети системы, но и состояние и качество самой сети (под "сетью" мы имеем в виду стандартное представление гипертекста в виде узлов-страниц, соединенных ссылками). Неаккуратное оформление руководства может привести к смысловой нестыковке важных частей системы (если мы забыли упомянуть что-то важное), образованию ложной связи (если упомянули что-то не относящееся к делу), зашумлению (если, нарушив У, мы положили в SEE ALSO слишком много наименований) и т. д. Во многих случаях руководство - главный источник актуальной информации об объекте, поэтому, согласно И, чем лучше руководство, тем лучше сам объект, так как он чаще и правильнее используется.

Утилита man

Утилита man(1) - составная, ее вызов - это последовательное выполнение трех операций: поиск страницы руководства, форматирование найденной страницы и просмотр отформатированного текста.

Сами страницы помощи - это файлы, имена которых включают имена объектов (об этом будет подробнее рассказано в лекции 13). Файлы расположены в некотором базовом каталоге (например, в /usr/share/man или в /usr/X11R6/share/man ) в подкаталогах man1, man2 и т. д. по количеству разделов. Таким образом, первая стадия работы утилиты man сводится к поиску первой страницы с именем объекта во всех секциях базовых каталогов. Кстати, именно поэтому секция, посвященная администрированию, сделана восьмой: если пользователь вызовет man без указания раздела, то при совпадении имен объектов он получит руководство по утилите, а системному администратору ничего не стоит написать в командной строке man 8.

Во многих системах страницы руководства запакованы программой compress(1) или gzip(1), так что перед форматированием страница распаковывается. Руководства хранятся в формате ROFF. Это специальный язык разметки текста для представления его в виде документа. Первые его версии появились аж в начале 60-х, еще до рождения UNIX, а после его многократно расширяли и совершенствовали разработчики UNIX и GNU (наиболее популярная на сегодня версия этой системы документирования называется GNU roff, или groff(1) ). В отличие от Д. Кнута, автора системы TeX (кстати, ), авторы ROFF не имели целью создать язык разметки полноценной книги.

Им нужно было подготовить систему документирования, продукт которой одинаково хорошо смотрелся бы и в полиграфическом исполнении, и на простейшем устройстве вывода текстов (например, алфавитно-цифровом терминале, см. лекцию 8). В ROFF включены все необходимые средства, man использует утилиту nroff, которая форматирует ROFF-документ для выдачи его на алфавитно-цифровое печатающее устройство (или АЦПУ, это что-то вроде электрической печатной машинки с возможностью принимать текстовые данные). Шрифт в АЦПУ один, моноширинный, псевдографики нет. Однако nroff умеет даже на таком устройстве выделять текст повышенной яркостью и подчеркиванием! Чтобы на печати буква выглядела ярче, сразу после нее выводится символ Backspace (возврат печатающей головки на одно знакоместо назад) и буква выводится повторно (в машинописи это называется "двойной удар"). Для подчеркивания текста сначала выводится не сама буква, а символ подчеркивания _.

Третья стадия работы man - вызов утилиты постраничного просмотра текста more(1). Подобие more, лишенное всех функций, кроме главной, можно найти даже в DOS. Во многих современных системах вместо more используется более мощная утилита less(1). Говорят: "Less is more than more". Утилита позволяет просматривать простой текст и текст, выходящий из-под nroff, при этом используются возможности терминала: "двойной удар" превращается в текст повышенной яркости, а подчеркивание - в подчеркнутый. (В системе Solaris man почему-то вызывает more с ключом, запрещающим обрабатывать подчеркнутый текст, отчего внешний вид руководства ухудшается. Исходные тексты утилиты more в Solaris недоступны, и приходится подменять ее командным сценарием, в котором параметры командной строки передаются настоящей утилите more уже поправленными.) Если вы хотите вывести руководство на печать, причем не на АЦПУ, а на современный PostScript-принтер, лучше не обрабатывать выдачу man , а воспользоваться предназначенной для этого утилитой troff(1). Получившаяся командная строка может быть, например, такой:

zcat /usr/share/man/man1/man.1.gz | 
    troff -man -Tps | grops | lpr

Для каждой из этих утилит есть руководство, а о том, что такое " | " ("конвейер"), рассказано в лекции 11.

Утилиты whatis и apropos

Самая краткая часть страницы руководства - однострочное поле NAME - тоже играет очень важную роль в системе информационной поддержки. Дело в том, что при установке руководства в систему содержимое этого поля добавляется в файл whatis , лежащий в базовом каталоге. Текстовый файл whatis - оглавление всей системы руководств, находящейся в соответствующем каталоге. Если поискать некоторое слово в этом файле, мы увидим только те заголовки руководств, в которых оно встречается. Поиском ключевых слов в whatis занимаются утилита whatis(1) и apropos(1), которая ищет не целое слово, а просто подстроку в строке.

Вообще говоря, в поле, формирующее поиск, надо было бы складывать ключевые слова. Но ключевые слова (в чистом виде) - информация не для человека, а для машины, а с другой стороны, толковое и внятное краткое описание будет содержать как раз ключевые слова (только не все, в первую очередь - без синонимов). Поэтому, чтобы не нарушать У (правило human writeable), для поиска используется поле NAME . Работоспособной такая система будет при строгом соблюдении О: только поместив в это поле значимый текст, а не что попало, мы можем рассчитывать, что пользователь, если потребуется, найдет наше руководство. Поле NAME вместе с полем SEE ALSO задают довольно простой, но эффективный алгоритм работы с manpages.

Работа с руководствами

Допустим, мы хотим слить два файла, left и right, в один, состоящий из двух колонок (содержимое одного файла - слева, другого - справа). Спрашиваем, в описании каких утилит есть слово column:

$ apropos column
...

Команда apropos выдает несколько сотен строк, относящихся в основном, к графическим функциям (секция 3). Нас же интересует утилита (секция 1). Используем grep(1), чтобы выбрать только строки, содержащие (1) ( поле NAME начинается с контекстной ссылки на само руководство).

$ apropos column | grep "(1)"
colrm(1)    - remove columns from a file
column(1)   - columnate lists

Другое дело! Наверное, нам нужна утилита column? Читаем руководство.

$ man column
...

Не тут-то было... Смотрим поле SEE ALSO

$ man column | colcrt | sed -n '/SEE ALSO/,/^$/p'
SEE ALSO
    colrm(1), ls(1), paste(1), sort(1)

(В примере за нас все сделал UNIX. Как именно? Читайте руководство по colcrt и главу 14). Из полученного списка на подозрении одна только команда paste

$ whatis paste
paste(1)    - merge corresponding or subsequent lines of files

Точно! Читаем руководство.

$ man paste
...

Вот и результат:

$ paste left right

RTFM

Имейте в виду, что обращаться к опытному пользователю или системному администратору за справкой, которую можно было бы найти в руководстве, очень опасно! Это раздражает их сверх всякой меры, потому что является вопиющим нарушением и О, и И. Строго говоря, вы сами в состоянии ответить на свой вопрос, оставив коллегу решать задачи, соответствующие его уровню ответственности за систему. Для этого достаточно прочесть руководство. Так вы получите некоторый опыт поиска информации, что всегда полезно. Ответственный человек пойдет за советом, только если документация неполна или в информационной сети есть какая-то несвязность. А ну как ответственный администратор примется эту несвязность исправлять, а окажется, что на самом деле в руководстве все написано?

В UNIX-сообществе существует краткая формулировка единственно верного стиля поведения перед лицом еще не решенной задачи: . Вы можете услышать ее в качестве ответа на не слишком умный вопрос. В расшифрованном виде она читается так: Read Those Fine Manuals.

Система info

Альтернатива manpages - гипертекстовая система info(1). Info - часть системы документирования texinfo, разработанной GNU. У texinfo есть масса преимуществ перед roff. Во-первых, из texinfo-документации можно изготавливать не только info-файлы, но и документы в формате HTML и XML, и даже настоящие книжки в формате TeX. Во-вторых, формат texinfo более новый, в нем существенно больше средств разметки, индексирования текста, организации таблиц и т. п. В-третьих, в отличие от man , info - система документирования, в которой на уровне просмотра реализован переход по гипертекстовым ссылкам.

Структура info-документации опирается на понятия " узел ", " меню ", " ссылка " и " индекс ". Узел - это некоторый цельный текст, посвященный определенной теме, имеющий собственное имя. Узлы строго упорядочены (так из них получается книга), но еще они включены в иерархию отделов книги (по принципу часть - лекция - раздел - подраздел). Узлом может быть, например, текст в начале и в конце главы, разделенный меню.

Меню - это оглавление соответствующего узла (например, раздела), каждый элемент которого ссылается на нижележащий узел (в данном случае - подраздел). Тексты всех нижележащих узлов меню и самого узла составят весь текст раздела.

Ссылка - один из двух видов гипертекстовых ссылок в info . При просмотре документации утилитой info достаточно переместить текстовый курсор при помощи клавиши Tab к нужному пункту меню и нажать enter, чтобы перейти к соответствующему узлу, т. е. проследовать по ссылке. Другой вид гипертекстовых ссылок называется перекрестными ссылками. Перекрестные ссылки возникают в тексте узла и указывают на какой-нибудь другой узел документа вне всякой иерархии. В книге перекрестная ссылка обычно возникает в случаях наподобие "эта тема подробнее рассматривается в гл. 3, разд. 7".

Индекс - сводное меню, содержащее ссылки на узлы, в описании которых помечено, что они этому меню принадлежат. Иными словами, индекс не надо писать вручную, он собирается при изготовлении info-файла из texinfo-документации. Несколько индексов в info-странице всегда определено, например, concept index - список всех сущностей, упоминающихся в документе.

Такая структура делает texinfo-документ пригодным для создания разветвленной и подробной документации: учебника, статьи, содержащей научные и исторические сведения, полного описания некоторой прикладной системы и т. д. Авторы texinfo-документа - сами разработчики этой системы, чаще всего независимой от какой-либо операционной среды. Под этим углом зрения можно рассматривать сообщество GNU, в котором документирование при помощи texinfo считается стандартом. Однако именно по причине независимости включать info-страницы в общее информационное пространство определенной ОС бывает затруднительно.

Тем самым texinfo занимает иную экологическую нишу, нежели man : документирование больших, сложных и замкнутых проектов. Для того чтобы поместить такую документацию в общий внутрисистемный информационный контекст, не нужно перелопачивать ее всю, в руководстве достаточно указать только основные принципы работы с установленным пакетом и поместить внешнюю ссылку на info-страницу, содержащую полную документацию. При этом страницу руководства сможет написать уже не разработчик прикладной системы, а тот, кто отвечает за включение ее в виде пакета в конкретную операционную среду (package maintainer).

Многим пользователям, незнакомым с текстовым редактором GNU Emacs, набор клавиш, управляющих утилитой info , представляется несколько неестественным. Можно использовать пакет pinfo, который занимается тем же, что и info , но навигация в нем устроена более привычным образом.

К сожалению, авторы небольших программных продуктов частенько ленятся писать документацию в формате info , отделываясь простыми текстами или html-файлами. Кроме того, система и многие пакеты содержат разнообразную неклассифицируемую документацию (статьи, вопросники, howto и пр.). Все это следует искать в каталоге /usr/share/doc/имя-пакета (в случае BSD - еще и в /usr/local/share/doc/имя-пакета, в некоторых системах - /opt/имя-пакета/share/doc, см. главу 13). Но будьте настороже: если вы нашли в пакете только текстовую документацию, но не увидели ни man-, ни info-страниц, значит, автор пакета мог и еще где-нибудь полениться довести свое детище до ума. Отсутствие документации в общей схеме нарушает связность информационного пространства системы и противоречит тем самым И.