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

Тогда как большая часть остальной программной документации часто колеблется между "непонятностью" и чрезмерно упрощенным, снисходительным изложением, классическая 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) и тт(7) используются до сих пор. В BSD Unix имеется собственный замысловатый расширенный набор макросов, mdoc(7). Все они предназначены для написания технических

руководств и длинных документов. Они имеют подобный стиль, но более сложны, чем man-макросы, и ориентированы на создание форматированного вывода.

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

Пример 18.1. Разметка groff (1) Это непрерывный текст.

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

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

• ft R

Данный текст будет выведен снова стандартным шрифтом (Roman). Данные строки снова, как и "Это непрерывный текст", будут отформатированы как заполненный абзац, .bp

Запрос bp приводит к созданию новой страницы и разрыву абзаца. Эта строка будет частью второго заполненного абзаца.

• sp 3

Запрос .sp выводит заданное аргументом количество пустых строк, .nf

Запрос nf отключает заполнение абзаца.

До тех пор, пока оно снова не будет включено запросом fi, пустые места и макет страницы будут сохраняться.

Одно слово данной строки будет выделено \fBbold\fR жирным шрифтом, .fi

Снова включено заполнение абзаца.