Искусство программирования для 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).

Данные строки снова, как и "Это непрерывный текст", будут

отформатированы как заполненный абзац.

.bp

Запрос bp приводит к созданию новой страницы и разрыву абзаца.

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

.sp 3

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

.nf

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

До тех пор, пока оно снова не будет включено запросом fi,

пустые места и макет страницы будут сохраняться.

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

.fi

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

Средства инструментария Documenter's Workbench очень хорошо решают задачи по форматированию технических документов, для которых они и предназначены, именно поэтому они непрерывно используются в течение более чем 30 лет, тогда как производительность компьютеров возросла в тысячи раз. Они создают форматированный текст приемлемого качества на графических принтерах и способны корректно отображать форматированные man-страницы на экране.

Однако в некоторых областях они плохо применимы. Их стандартный выбор доступных шрифтов ограничен. Они слабо обрабатывают изображения. Сложно обеспечить точное управление позиционированием текста, изображений или диаграмм внутри страницы. Поддержка многоязычных документов отсутствует. Существует множество других проблем. Некоторые из них хронические, но незначительные, другие абсолютно затрудняют специфическое применение. Но наиболее серьезная причина заключается в том, что, ввиду того, что большая часть разметки осуществляется на уровне представления, создавать хорошие Web-страницы из немодифицированных troff-текстов очень трудно.

Тем не менее, на момент написания книги man-страницы остаются единственной наиболее важной формой Unix-документации.

Пример 18.2. Разметка man-страниц

.SH ПРИМЕР РАЗДЕЛА

Макрос SH начинает раздел, выделяя его заголовок жирным шрифтом.

.Р

Запрос Р начинает новый абзац. Запрос I форматирует

свой

аргумент

.I курсивом.

.IP *

Данный запрос начинает абзац с отступом, отмеченным звездочкой.

Дополнительный текст для первого абзаца списка.

.TP

Эта первая строка станет меткой абзаца

Данная строка будет первой строкой в абзаце, с отступом

по отношению к метке.

Пустая строка выше интерпретируется почти так же, как

разрыв абзаца (фактически как troff-запрос .sp 1).

.SS Подраздел

Это текст подраздела.

18.3.2. TEX

TEX (произносится как "теХ") представляет собой очень мощную программу подготовки документов, которая, подобно редактору Emacs, возникла за пределами Unix-культуры, но теперь "прижилась" в ней. Она была создана видным компьютерным ученым Дональдом Кнуттом (Donald Knuth), когда ему надоело качество доступной в конце 70-х годов прошлого века типографской разметки текста и особенно форматирования математических выражений.

TEX, подобно утилите troff(1), является системой, ориентированной на разметку. TEX имеет гораздо более мощный язык запросов, чем troff. Среди прочего, данная программа лучше приспособлена для обработки изображений, точного позиционирования содержимого страницы и интернационализации. особенно хорошо проявляет себя в форматировании математических выражений и является непревзойденным инструментом для решения базовых задач форматирования, таких как кернинг, заполнение строк и расстановка переносов. ТEХ стал стандартным форматом для представления материалов в большинство математических журналов. В настоящее время TEX курируется как программа с открытым исходным кодом рабочей группой Американского математического общества (American Mathematical Society). Программа также широко используется для создания научных документов.

Как и в случае с troff(1), пользователь обычно не пишет вручную множество чистых TEX-макросов. Вместо этого используются макро-пакеты и различные вспомогательные программы. Один особый макропакет, TEX является почти универсальным, и большинство пользователей, которые говорят о том, что создают документы в TEX, почти всегда фактически имеют в виду написание LATEX-макросов. Как и макропакеты troff, множество запросов LATEX являются полуструктурными.

Одно важное применение TEX, которое обычно скрыто от пользователя, заключается в том, что другие инструменты обработки документов часто генерируют LATEX-код, преобразуемый впоследствии в PostScript, вместо того, чтобы самостоятельно пытаться выполнять гораздо более трудную работу по созданию PostScript-документа. Такой прием используется в управляющем сценарии xmlto(1), который рассматривался в главе 14 в качестве учебного примера shell-программирования. Аналогично данная проблема решается в инструментарии XML-DocBook, который описывается ниже в настоящей главе.

TEX имеет более широкий диапазон применений, чем troff(1), и в основном лучшую конструкцию. Во все более связанном с Web мире рассматриваемая программа имеет те же фундаментальные проблемы, что и troff. Ее разметка сильно привязана к уровню представления, и автоматическое создание хороших Web-страниц из исходных текстов TEX затруднено и чревато сбоями.

Программа TEX никогда не используется для создания Unix-документации и только иногда используется для документирования приложений. Для таких целей достаточно использовать troff. Однако некоторые программные пакеты, которые возникли в академических учреждениях за пределами Unix-сообщества, заимствовали использование TEX как главного формата документации; одним из примеров является язык Python. Как было сказано выше, он также интенсивно используется для создания математических и научных документов и, вероятно, будет доминировать в этой нише еще несколько лет.

18.3.3. Texinfo