7.1. Источники документации
Прежде чем вы сможете разобраться в сути проблемы, вы должны понять теоретическую роль каждой программы, вовлечённой в данную проблему. Лучший способ сделать это — обратиться к документации программы; но поскольку документации может быть достаточно много и она может быть распределена по различным источникам, то вам следует знать о тех местах, где её можно найти.
7.1.1. Страницы руководств
Страницы руководств содержат достаточно много важной информации, даже если они и бывают относительно немногословны. Далее мы кратко рассмотрим команды для просмотра страниц руководств. Просто наберите
man manual-page — название страницы руководства обычно совпадает с именем команды, для которой вы ищите документацию. Например, чтоб узнать о возможных опциях команды
cp, вам следует набрать команду
man cp в терминале (см. врезку
К ОСНОВАМ Оболочка, командный интерпретатор).
В страницах руководств описываются не только те команды, что доступны из командной строки, но и конфигурационные файлы, системные вызовы, функции библиотек C и так далее. Их имена иногда могут совпадать. Например, команда оболочки read совпадает с системным вызовом read. По этой причине страницы руководств организованы в виде пронумерованных секций:
команды, выполняемые из командной строки;
системные вызовы (функции, предоставляемые ядром);
библиотечные функции (предоставляемые системными библиотеками);
устройства (в Unix-подобных системах они являются специальными файлами и обычно находятся в каталоге /dev/);
конфигурационные файлы (форматы и соглашения);
игры;
наборы макросов и стандарты;
команды администрирования системы;
процедуры ядра.
Вы можете указать необходимую секцию руководства: для чтения документации по системному вызову read вам следует набрать команду man 2 read. В том случае, когда секция явно не указана, страница руководства будет отображена из первой найденной секции, содержащей запрошенное имя. Поэтому man shadow выводит shadow(5), так как страницы руководства для shadow отсутствуют в секциях с 1 по 4.
Разумеется, если вам не известны имена команд, то от руководства будет мало пользы. В этом случае поможет команда apropos, которая выполняет поиск в страницах руководств, точнее, в их секциях коротких описаний. Каждая страница руководства начинается с однострочного описания. apropos выводит список тех страниц руководств, что содержат запрашиваемые ключевые слова в коротком описании. В случае правильного выбора ключевых слов вы найдёте необходимые вам команды.
Пример 7.1. Поиск cp с помощью apropos
$ apropos "copy file"
cp (1) - copy files and directories
cpio (1) - copy files to and from archives
gvfs-copy (1) - Copy files
gvfs-move (1) - Copy files
hcopy (1) - copy files from or to an HFS volume
install (1) - copy files and set attributes
ntfscp (8) - copy file to an NTFS volume.
The
man command is not the only means of consulting the manual pages, since
khelpcenter and
konqueror (by KDE) and
yelp (under GNOME) programs also offer this possibility. There is also a web interface, provided by the
man2html package, which allows you to view manual pages in a web browser. On a computer where this package is installed, use this URL:
Для использования этой утилиты необходим браузер. Именно по этой причине вам следует выбрать установку данного пакета на одном из ваших серверов: все пользователи локальной сети будут в выигрыше при наличии подобной службы (включая пользователей не-Linux машин) и это позволит вам не устанавливать HTTP сервер на каждой рабочей станции. В случае когда ваш сервер доступен из других сетей, доступ к этой службе желательно ограничить только локальной сетью.
Last but not least, you can view all manual pages available in Debian (even those that are not installed on your machine) on the
manpages.debian.org service. It offers each manual page in multiple versions, one for each Debian release.
В рамках проекта GNU подготовлены руководства для большинства программ проекта в формате info, поэтому страницы руководств ссылаются на соответствующую документацию info. У этого формата есть определённые преимущества, но стандартная программа для просмотра таких документов несколько сложна (она называется info). Как её замену, вам настоятельно советуется использовать pinfo из пакета pinfo.
info имеет иерархическую структуру, и если вы вызовите pinfo без параметров, то отобразится список узлов первого уровня. Обычно узлы носят имена соответствующих команд.
В
pinfo удобно использовать для перемещения между узлами клавиши управления курсором. Другой вариант — использование графического браузера:
konqueror,
yelp,
info2www.
Следует отметить, info, в отличие от man, не подходит для перевода. Поэтому документы info почти всегда написаны на английском языке. Однако если вы попросите программу pinfo отобразить несуществующую страницу info, то она обратится к странице man с тем же самым именем (если такая существует), которая может быть переведена.
7.1.3. Специфическая документация
Каждый пакет содержит свою собственную документацию. Даже программы с минимумом документации содержат файл README, в котором присутствует интересная и/или важная информация. Эта документация устанавливается в каталог /usr/share/doc/package/ (где package является именем пакета). Если документация имеет значительный размер, то её могут исключить из основного пакета программы и поместить в отдельный пакет с именем package-doc. Основной пакет обычно рекомендует к установке пакет документации, поэтому вы можете легко его найти.
В каталоге /usr/share/doc/package/ находятся файлы, предоставляемые Debian, которые дополняют документацию и в которых детально указаны особенности или усовершенствования пакета в сравнении с обычной установкой данного программного обеспечения. Также в файле README.Debian перечислены все изменения, добавленные с целью соответствия Политике Debian. Файл changelog.Debian.gz позволяет пользователю проследить все модификации пакета в течение длительного времени: иногда бывает полезно понять, какие изменения произошли между двумя установленными версиями, в поведении которых существуют отличия. В заключение, иногда присутствует ещё и файл NEWS.Debian.gz, в котором указаны основные изменения в программе и которые могут быть интересны непосредственно администратору.
Свободное программное обеспечение в большинстве случаев распространяется через сайты, которые также служат ещё и для объединения сообщества его разработчиков и пользователей. Подобные сайты зачастую содержат исчерпывающую информацию в различном виде: официальную документацию, FAQ (часто задаваемые вопросы), архивы списков рассылки и т. д. Бывает так, что проблемы, с которыми вы столкнулись, уже были предметом множества вопросов, FAQ или архивы списков рассылок могут содержать готовые решения. Хорошие навыки работы с поисковыми системами окажутся очень ценными для быстрого поиска необходимых страниц (путём ограничения запросов одним доменом или поддоменом, посвящённым программе). В том случае, когда поиск возвращает слишком много страниц или результат не удовлетворяет вашему запросу, вы можете добавить ключевое слово debian для ограничения результатов и более целенаправленного поиска.
If you do not know the address for the software's website, there are various means of getting it. First, check if there is a
Homepage field in the package's meta-information (
apt show package). Alternately, the package description may contain a link to the program's official website. If no URL is indicated, look at
/usr/share/doc/package/copyright. The Debian maintainer generally indicates in this file where they got the program's source code, and this is likely to be the website that you need to find. If at this stage your search is still unfruitful, consult a free software directory, such as FSF's Free Software Directory, or search directly with a search engine, such as Google, DuckDuckGo, Yahoo, etc.
Вы также можете заглянуть в Debian wiki — ресурс, предназначенный для совместной работы, на котором любой пользователь, даже обычный посетитель, может внести предложение непосредственно из своего браузера. Этот ресурс используется в равной мере как разработчиками для проектирования и документации своих проектов, так и пользователями, которые делятся своими знаниями и совместно работают над документацией.
7.1.5. Практические руководства (HOWTO)
Практическое руководство (HOWTO) — это документ, в котором четко, шаг за шагом, описаны действия для достижения определённой цели. Цели могут быть самыми разными, но они всегда являются техническими по своей сути: например, настройка преобразования IP адресов, программного RAID, установка сервера Samba и т. д. Эти документы зачастую пытаются охватить все возможные проблемы, которые могут возникнуть при использовании той или иной технологии.
Много руководств размещено на сайте Проекта Документации Linux (LDP), в рамках которого происходит управление подобными документами:
Вам следует скептически относиться к этим документам. Зачастую они были подготовлены несколько лет назад и поэтому могут содержать устаревшую информацию. Такое положение ещё более вероятно для переводов, поскольку обновления выполняются не систематически и не сразу после выхода обновлённой версии оригинального документа. Это следствие работы в волонтёрской среде без всяких ограничений…
