Искусство программирования для Unix

Большая часть документации по программному обеспечению написана "техническими писателями", стремящимися найти наименьший общий знаменатель незнания — "умное написание для неосведомленных". Документация, которая поставляется с Unix-системами, традиционно пишется программистами для коллег. Даже если документация не написана программистами для программистов, то она часто находится под влиянием стиля и формата огромной массы такой документации, поставляемой с Unix-системами.

Данные различия можно объединить одним замечанием: man-страницы в Unix обычно содержат раздел, который называется "BUGS" (ошибки). В других культурах "технические писатели" пытаются придать продукту лучший вид, минуя известные ошибки или касаясь их вскользь. В культуре операционной системы Unix разработчики беспощадно описывают известные недостатки своего программного обеспечения, а пользователи рассматривают краткий, но информативный раздел "BUGS" как обнадеживающий знак качественной работы. Коммерческие дистрибутивы Unix, нарушившие данное соглашение, либо исключив раздел "BUGS", либо заменив его название более мягкими формулировками "LIMITATIONS" (ограничения) или "ISSUES" (проблемы), или "APPLICATION USAGE" (использование приложения), неизменно приходят в упадок.

Тогда как большая часть остальной программной документации часто колеблется между "непонятностью" и чрезмерно упрощенным, снисходительным изложением, классическая Unix-документация пишется в сжатом стиле, но вместе с тем является полной. Она "не ведет читателя за руку", а обычно указывает верное направление. Данный стиль предполагает активное чтение, при котором читатель способен сделать очевидный, но не высказанный вывод, на основе написанного и обладает достаточной уверенностью, чтобы доверять своим заключениям.

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

18.3. Многообразие форматов документации в Unix

Все основные форматы Unix-документации, кроме самых новых, являются разметками уровня представления, созданными с помощью макропакетов. Ниже они рассматриваются в порядке их возникновения.

18.3.1. troff и инструментарий Documenter's Workbench

Структура и инструменты Documenter's Workbench рассматривались в главе 8 как пример интеграции системы, состоящей из нескольких мини-языков. Здесь рассматривается функциональная роль данного инструментария как системы форматирования документов.

Форматер troff интерпретирует язык разметки уровня представления. Последние реализации данной программы, такие как GNU-проект groff(1), по умолчанию на выходе создают PostScript-представление, хотя существует возможность получать другие формы вывода путем выбора подходящего драйвера. В примере 18.1 приводится несколько troff-кодов, которые можно встретить в исходных текстах документов.

troff(1) имеет множество других запросов, но большинство из них вряд ли можно увидеть немедленно. Весьма немногие документы написаны на чистом troff. Он поддерживает макросредства, и в нем более или менее широко используются около десятка макропакетов. Среди них наибольшее распространение получил макропакет man(7), который используется для написания man-страниц Unix. См. пример 18.2.

Две из почти десяти исторических библиотек макросов troff, ms(7) и mm(7) используются до сих пор. В BSD Unix имеется собственный замысловатый расширенный набор макросов, mdoc(7). Все они предназначены для написания технических руководств и длинных документов. Они имеют подобный стиль, но более сложны, чем man-макросы, и ориентированы на создание форматированного вывода.

Сокращенный вариант troff(1), который называется nroff(1), генерирует вывод для устройств, поддерживающих только моноширинные шрифты, например, для построчно-печатающих устройств и символьных терминалов. Отображаемая для пользователя внутри терминального окна man-страница Unix форматируется с помощью nroff.

Пример 18.1. Разметка groff(1)

Это непрерывный текст.

.\" Комментарии начинаются с обратной косой черты и двойных кавычек.

.ft В

Данный текст будет выделен жирным шрифтом.

.ft R

Данный текст будет выведен снова стандартным шрифтом (Roman).