Система создания документации POD. Часть 2

АЛЕКСЕЙ МИЧУРИН

Система создания документации POD

Часть 2

Напомню коротко, что POD – это система разработки электронной документации. Она предполагает, что документ разрабатывается в определённом достаточно простом формате, и предоставляет средства конвертирования исходного POD-документа в другие форматы для печати и просмотра.

В первой части статьи мы рассмотрели средства конвертирования в форматы «неразмеченный текст», man-страница и HTML. В этой части рассмотрим конвертирование в PostScript и PDF.

Напомню, что POD-документ состоит из абзацев, которые разделяются пустой строкой. Абзацы бывают трёх типов: форматированные, для представления обычного текста, неформатированные, для листингов программ, и управляющие, для формирования структурных элементов (заголовков, списков) и внедрения формат-специфических вставок. Неформатированные абзацы начинаются с пробела. Управляющие – с команды. В форматированных и управляющих абзацах допустимо элементарное оформление текста (например, I<курсив> или B<жирный шрифт>) и вставка не ASCII-символов (например, E – значок градуса).

Команды начинаются со знака «равно» (например, =head1 задаёт заголовок первого уровня).

В качестве примера я использовал тот же POD-документ, что и в первой части статьи.

На сайте журнала http://www.samag.ru в разделе «Исходный код» вы можете взять архив с POD-кодом и всеми обсуждаемыми здесь скриптами.

Конвертирование POD в TeX, PostScript и PDF

Для конвертирования POD-документов в форматы PostScript и PDF проще всего сперва сконвертировать POD в LaTeX, a из LaTeX-исходника получить все необходимые PostScript- и PDF-файлы.

На первый взгляд такой путь может показаться излишне сложным. Действительно, мы уже умеем создавать man-страницы (см. первую часть статьи). А из них легко можно получить PS- или PDF-файл; например так:

cat page.man | /usr/bin/tbl |

 /usr/bin/groff -S -Wall -mtty-char -man -Tps >page.ps

Но это экстенсивный путь. Во-первых, man-документ не несёт никакой информации о кодировке и корректное конвертирование русской man-страницы в тот же PostScript оказывается не такой уж простой задачей. Во-вторых, LaTeX-исходник открывает перед вами все возможности системы LaTeX. Вы можете вставлять в документ рисунки, форматировать документ в несколько колонок, формировать автоматические оглавления, пользоваться системой автоматической расстановки переносов и многое другое. В формате man все эти возможности недоступны. Согласитесь, некоторое усложнение вполне стоит того.

Первое знакомство с pod2latex

Первое знакомство с pod2latex может окончиться конфузом. Скорее всего, конвертер pod2latex откажется обрабатывать русскоязычные документы. Насколько мне удалось разобраться, скрипт pod2latex и все модули, вызываемые в нём, полностью игнорируют локализацию.

Источник проблемы – модуль Pod::Find, который с помощью Perl-оператора -T проверяет, является ли файл действительно текстовым. Этот оператор может счесть ваш документ двоичным файлом из-за присутствия в нём русских букв.

Более того, насколько я понимаю, оператор -T делает своё заключение, проанализировав только небольшую часть информации в начале файла. Поэтому если файл начинается с некоторого английского текста, а первые русские буквы начинают встречаться ниже, то pod2latex может обработать такой файл. Но если русские буквы появятся ближе к началу файла, то pod2latex наотрез откажется с ним работать. Такое поведение утилиты может сбить с толку при поиске причины недоразумений.

Идеологически верным решением является подключение в pod2latex поддержки локализации, за которую отвечает прагма locale. То есть в начало скрипта pod2latex следует добавить строку:

use locale;

И конечно, вам следует настроить локаль. Проще всего это сделать, установив переменную среды LANG. У меня LANG=ru_RU.KOI8-R. В вашей системе называние русской локали может слегка отличаться. Вы можете посмотреть полный список локалей, установленных в вашей системе, выполнив команду locale -a.

Другой, более вероломный путь, практически не потребует знания Perl и перенастройки системы (иногда настройка русской локали бывает нежелательна).

Самое простое решение – отредактировать модуль Pod::Find, удалив соответствующую проверку. Внимание! Cохраните оригинальную версию файла, прежде чем редактировать его! В моей системе это файл /usr/local/lib/perl5/5.8.5/Pod/Find.pm. У меня установлен Pod::Find версии 0.24_01, в нём проверка выполняется в строке 251. Чтобы отменить проверку замените

unless(-f $file && -T _ && ($file =~ /\.(pod|pm|plx?)\z/i || -x _ ))

на

unless(-f $file && ($file =~ /\.(pod|pm|plx?)\z/i || -x _ ))

Так или иначе теперь мы заставили pod2latex работать с русскими документами, и вы точно сможете сконвертировать русскоязычный POD-документ в формат LaTeX. Но документ окажется неполным.

Дело в том, что LaTeX-документы, как и HTML-документы, состоят из заголовка и тела. Утилита pod2latex создаёт только тело. Надо сказать, что эта утилита способна создать и полный документ, но в нём не будет содержаться никакой информации о языке и кодировке, то есть для русскоязычных документов эта возможность не очень полезна. Видимо, и разработчики POD считают её не очень полезной, так как по умолчанию она отключена.

В полученном документе не хватает завершения (его следует добавить):

\end{document}

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

Преамбула LaTeX документа

В преамбуле LaTeX-документов располагаются инструкции, в соответствии с которыми производится вёрстка документа. Вот пример преамбулы. Я постарался упомянуть в ней все пакеты и директивы, которые часто бывают полезны при разработке документов. Поэтому часть директив закомментирована (во избежание противоречий). Комментариями в LaTeX являются все символы от «%» до «конца строки» включительно. Мы обсудим и закомментированные директивы.

% Задаём глобальные атрибуты документа

\documentclass[10pt, a5paper]{article}

\usepackage[magstep2]{scale}

%\usepackage[a3paper]{geometry}

% Изменяем поля

\addtolength{\hoffset}{-1cm}

\addtolength{\textwidth}{2cm}

\addtolength{\voffset}{-1in}

\addtolength{\textheight}{2in}

% Красная строка

\setlength{\parindent}{0.3cm}

% Расстояние между абзацами

\setlength{\parskip}{0pt}

% Русский стиль оформления абзацев

\usepackage{indentfirst}

% Оговариваем кодировку документа

%\usepackage[cp866]{inputenc}

\usepackage[koi8-r]{inputenc}

\usepackage[russian]{babel}

\selectlanguage{russian}

\usepackage{draftcopy}

% Включаем графический пакет

\usepackage[dvips]{graphicx}

%\graphicspath{{ps/}}

% Макрос для вставки картинок

\newcommand{\inspsfig}[3]{

\begin{figure}[!htbp]

\begin{center}

\includegraphics[angle=0, width=#2\textwidth]{#1}

\end{center}

\caption{#3}

%\label{text}

\end{figure}

}

% Задаём межстрочный интервал

\linespread{1}

% Документ начался

\begin{document}

% В начале документа генерируем оглавление и ...

\tableofcontents

% ... список иллюстраций

\listoffigures

% Можно начать документ со следующей страницы

%\newpage

% а можно просто задать отступ

%\vspace{50mm}

Первым делом мы задаём класс документа (document-class). Настраиваем размер шрифта (10pt), размер бумаги (A5), если вам необходимо сверстать документ в две колонки, добавьте через запятую параметр twocolumn. Здесь же указан класс документа (article). LaTeX поддерживает три размера шрифта 10, 11 и 12 пунктов. Необычный размер бумаги мы используем умышленно. Стиль article наиболее подходит для короткой статьи, LaTeX поддерживает и другие стили.

При разработке крупных пакетов документации вам может пригодиться стиль report (документы, объёмом около пятисот тысяч печатных знаков) или даже book. От стиля article они отличаются практически только одной, но очень важной особенностью.

В документах класса article предусмотрены заголовки section, subsection и subsubsection, то есть заголовки первого второго и третьего уровней. В классах report и book добавляется возможность разбивать документы на главы, новая команда chapter (и её близнец part), создаёт заголовок как бы нулевого уровня. Pod2latex не создаёт глав. С одной стороны, это делает результаты работы pod2latex малопригодными для вёрстки в классах report и book; с другой стороны, получаемые article-документы легко и естественно могут входить как отдельные главы в большой report-документ.

Если вы планируете разрабатывать документы большого объёма и объединять POD-документы, в первую очередь обратите внимание на ключ -h1level утилиты pod2latex. Он позволяет получить документы, в которых все заголовки логически «сдвинуты», например POD-команде =head1 соответствует подзаголовок (второй уровень) и так далее. Такие документы можно использовать, как разделы или подразделы более крупных документов.

Из возможностей LaTeX обратите внимание на колонтитулы (команды pagestyle и thispagestyle). Если в вашем документе более ста страниц, колонтитулы перестают быть просто украшением. Очень полезной при слиянии документов может оказаться LaTeX-команда include.

В завершение отступления о больших документах позволю себе небольшой психологический этюд. Весь мой опыт показывает, что большие документы отпугивают поль-зователя. Если предоставить пользователю пару десятков коротеньких инструкций, то он в них легко ориентируется. А если ту же самую информацию сверстать на полусотне страниц одного документа, то пользователь не читает этот документ вообще (даже оглавление не читает), а вместо этого звонит (пишет по e-mail, ICQ...) разработчику. Если вы создаёте руководства, чтобы уменьшить количество глупых вопросов на вашу голову, то следует избегать пугающих документов.

Если вы будете создавать одностраничные инструкции-памятки, то наверняка захотите подавить нумерацию страниц. Это делается командой pagestyle{empty}.

Продолжим наше знакомство с преамбулой.

В следующей строке мы подключаем пакет scale, который масштабирует листы, увеличивая их в 1.4 раза. Таким образом, мы получим документ на бумаге привычного формата A4 и шрифт из «десятого» превратится в «четырнадцатый». Если вам нужен, скажем, «двенадцатый» шрифт, то вы можете просто сразу указать 12pt, размер бумаги A4 и не использовать пакет scale.

Пакет geometry позволяет задать размер бумаги A3 и больше. Это можно использовать, чтобы потом отмасштабировать документ и получить необычно мелкий шрифт.

Серия команд addtolength изменяет поля документа. По умолчанию LaTeX делает очень большие поля. Считается, что это правильно с точки зрения профессиональной вёрстки, но людям, навсегда испорченным программой MSWord, невозможно привыкнуть к этой красоте.

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

Пакет indentfirst предписывает делать красную строку и у первого абзаца. По умолчанию LaTeX следует западному стандарту, не делая красную строку у первого в главе абзаца.

Пакет inputenc задаёт кодировку LaTeX-файла. Я использовал koi8-r. LaTeX поддерживает огромное количество кодировок, среди которых cp866, cp1251, maccyr. Поддерживаются и украинские кодировки.

Пакет babel и команда selectlanguage{russian} русифицирует LaTeX. После подключения этого пакета LaTeX будет автоматически использовать русские слова «Оглавление», «Рисунок», «Глава» и другие.

Пакет draftcopy выполняет чисто декоративную функцию. На всех страницах наискосок печатается слово draft. Это удобно, когда вы распечатываете неокончательную, «черновую» версию документа.

Далее мы подключаем графический пакет graphicx. Если вы храните включаемые графические файлы в отдельной директории, удобно использовать директиву graphicspath, чтобы раз и навсегда указать путь к картинкам. Вам, во-первых, не придётся указывать путь к каждому графическому файлу, а во-вторых, будет легко изменить сразу все пути, если вы переместите файлы.

С помощью команды ewcommand я создал макрос, позволяющий в дальнейшем легко добавлять иллюстрации. Подробное описание способов включения графики в LaTeX выходит за рамки настоящей статьи.

На первых порах вы вполне можете ограничиться этим макросом или его подредактированными версиями. Подробнее о том, как его использовать, я расскажу чуть позже.

В конце преамбулы задаём межстрочный интервал командой linespread.

С команды egin{document} начинается тело LaTeX-документа. Преамбула закончилась, всё дальнейшее будет попадать на страницы.

Я включил в тело автоматически создаваемые оглавление (команда ableofcontents) и список иллюстраций (list-offigures).

Если вы хотите, чтобы кроме оглавления на первой странице ничего не было, раскомментируйте директиву ewpage. Если вы предпочитаете просто сделать дополнительный отступ, укажите его величину в аргументе директивы vspace.

LaTeX – мощная система вёрстки. Я, конечно, не смогу осветить здесь все её возможности. Тем не менее я постарался не забыть ничего, что когда-либо требовалось мне при подготовке документа.

Тем, кто хочет лучше узнать LaTeX, я бы очень рекомендовал книгу «Не очень краткое введение в LaTeX2e». Она очень проста, компактна и охватывает широкий спектр возможностей LaTeX. Перевод этой книги (Б. Тоботрас) доступен по адресу: http://xtalk.msk.su/tex.

О кириллизации LaTeX (включая настройку системы автоматических переносов) подробно написано в «The Linux Cyrillic HOWTO (russian)» Евгения Балдина, доступном по адресу: http://www.inp.nsk.su/~baldin.

Вот как выглядят первые две страницы моего примера, свёрстанные с приведённой преамбулой.

Рисунок 1

Незначительные изменения в преамбуле позволяют существенно изменить результат.

Рисунок 2

Здесь документ свёрстан «двенадцатым» шрифтом в две колонки.

Итак, конвертируем POD в PostScript и PDF

Вы видите, что pod2latex выдаёт достаточно «сырой» материал. С одной стороны, это хорошо, потому что из этого «материала» можно «вылепить» практически что угодно. С другой стороны, «лепить» каждый раз с нуля – не оправданно трудоёмко.

В собранном мною архиве вы найдёте скрипты, выполняющие всю сборку автоматически. Принцип их действия прост.

Сперва создаём «сырой» файл:

pod2latex -out file file.pod

Будет создан файл file.tex (расширение добавляется автоматически).

Затем чуть корректируем «сырой» файл:

cat file.tex |

sed "s/label{_}//g" |

sed "s/(subsection)*/1/g" > file.tex.temp

Первый sed-конвейер уничтожает пустые метки, которые создаются из-за нашей русскоязычности. Второй sed-конвейер удаляет звёздочку во всех директивах «subsection*». Это не обязательная операция. Звёздочка говорит о том, что раздел не должен отображаться в оглавлении. Pod2latex предполагает, что в оглавление войдут только заголовки первого уровня. Обычно, это как раз то, что нужно. Но мне захотелось, чтобы все заголовки попали в оглавление. Как видите, добиться этого совсем не сложно.

Далее мы присоединяем к документу преамбулу и завершение:

cat doc-head-14pt.tex file.tex.temp doc-tail.tex > file-14pt.tex

Теперь мы получили полноценный LaTeX-файл file-14pt.tex. Дважды обработав его системой latex, мы получаем одноимённый dvi-файл. DVI (DeVice Independent) – стандартный формат, генерируемый системой LaTeX. Несмотря на громкое название, его не следует использовать для обмена информацией. Дело в том, что dvi-файл обычно далеко не самодостаточен. Например, он не включает графические объекты, а содержит только ссылки на них. Поэтому, если вы перенесёте dvi-файл на другую машину или просто перепишете его в другую директорию, не предприняв никаких дополнительных мер, то скорее всего его уже не удастся просмотреть или конвертировать в другой формат. К счастью, из dvi-файла можно сделать полноценный PostScript- и/или PDF-файл:

latex file-14pt.tex

latex file-14pt.tex

dvips -o file-14pt.ps file-14pt.dvi

ps2pdf file-14pt.ps

Двойная обработка необходима, чтобы latex смог создать оглавление.

Кстати, утилита dvips тоже может масштабировать документы (ключ -x). Можно было не использовать пакет scale, а отмасштабировать страницы на этапе конвертирования dvi-файла в PostScript-формат.

В скрипте, который я включил в архив примеров, все эти команды вложены в цикл, в котором «собираются» две модификации документа: в одну колонку шрифтом 14pt и в две колонки шрифтом 12pt, как это было показано на рисунках.

Напоследок скажу, что я даже не ставил перед собой задачу описать все опции конвертера pod2latex. Эта утилита предоставляет возможности и выделения только части документа, и включения преамбулы и завершения, указанные пользователем, и многие другие. Просто мой опыт показывает, что использование многих из этих возможностей или неоправданно, или невозможно для русскоязычных документов. Если вы хотите получить исчерпывающую информацию по pod2latex, обращайтесь к соответствующей документации perldoc pod2latex.

Графика в PostScript и PDF

Для LaTeX естественным форматом представления графики является PostScript. Существуют средства, позволяющие работать и со многими другими форматами, но эти средства представлены отдельными пакетами, которые могут и не входить в ваш дистрибутив LaTeX (особенно если вы пользуетесь LaTeX под Windows). Я бы советовал работать только с PostScript, тем более что получить файл в этом формате совсем не сложно. С таким преобразованием легко может справиться, например, утилита convert из набора ImageMagic.

convert file.bmp file.ps

LaTeX предоставляет множество способов вставки графики. Мой способ далеко не единственный, но, как мне кажется, наиболее неприхотливый и простой.

Пользуясь предлагаемым мною макросом, вы можете легко вставить картинку в текст:

=for latex

inspsfig{two.eps}{.35}{Нетрудно заметить, что, совместив двух маленьких дракончиков, мы получим большого.}

Этот параграф предназначен для LaTeX-документов (=for latex). В нём вызван мой макрос inspsfig. Первый параметр, как вы видите, имя eps-файла. Второй – доля листа, которую должна занять картинка по горизонтали. Третий – подпись к картинке. Нумерацию рисунков LaTeX ведёт автоматически.

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

Итак, текст макроса таков:

\newcommand{\inspsfig}[3]{

\begin{figure}[!htbp]

\begin{center}

\includegraphics[angle=0, width=#2\textwidth]{#1}

\end{center}

\caption{#3}

%\label{text}

\end{figure}

}

В первой строке мы создаём новую команду \inspsfig, у которой будет три аргумента. В теле команды создаётся окружение \begin{figure}-\end{figure}. Команда \begin{figure} имеет строку-параметр, о которой следует сказать отдельно. Этот параметр определяет, где будет расположен плавающий объект (каковым является иллюстрация).

В строке-параметре «!htbp» первый символ заставляет LaTeX не рассматривать большинство своих правил и стараться выполнить инструкции «во что бы то ни стало». Буква h говорит о том, что первым делом LaTeX должен попытаться разместить иллюстрацию там, где она находится в тексте документа. Если это невозможно, то LaTeX рассмотрит букву t и постарается разместить картинку вверху страницы. Если и это ему не удастся, будет рассмотрена b, предписывающая размещать плавающий объект внизу страницы. И, наконец, если все попытки закончатся неудачей, то в силу вступит инструкция p, и LaTeX выделит для плавающего объекта отдельную страницу и разместит его там.

Теперь становится ясно, что если вы хотите, например, чтобы все рисунки размещались вверху страницы, то параметр должен начинаться с буквы t, за которой могут следовать альтернативные варианты.

Команда \includegraphics вложена в окружение \begin {center}-\end{center}. Картинка будет отцентрована по горизонтали. Вы видите, что мы не поворачиваем картинку (angle=0), а ширину рассчитываем как произведение второго параметра макроса \inspsfig на ширину текста (width=#2\textwidth). В качестве имени файла с картинкой будет использован первый параметр \inspsfig.

Команда \caption задаёт подпись к рисунку.

Закомментированная команда \label бывает полезна, если вы хотите ссылаться на рисунки из текста. Она (в сочетании с другими командами) позволяет автоматически поддерживать корректность ссылок. Я не буду на ней подробно останавливаться.

Конвертирование в другие форматы

В большинстве случаев уже рассмотренных форматов вполне достаточно. Не надо торопиться отказываться от Post Script. Он весьма гибок. Например, вы можете сразу подготовить документ для печати в виде брошюры:

pstops '4:-3L@.7(21cm,0)+0L@.7(21cm,14.85cm)' page-14pt.ps page-14pt-booklet-up.ps

pstops '4:1L@.7(21cm,0)+-2L@.7(21cm,14.85cm)' page-14pt.ps page-14pt-booklet-down.ps

Теперь можно на одной стороне листов напечатать содержимое файла page-14pt-booklet-up.ps, а на другой – page-14pt-booklet-down.ps и сброшюровать. Вряд ли MSWord позволит вам сделать буклет (и не только буклет) так же легко.

Подробнее о pstops вы можете почитать в соответствующем man.

Имея в распоряжении PostScript, легко сделать DjVu-файл или даже jpeg, что тоже может пригодиться, например, при написании подобной статьи.

Следующая команда обработает файл page-12pt.ps и создаст серию файлов file001.jpeg, file002.jpeg и так далее, по одному на каждую страницу.

gs  -sDEVICE=jpeg \

    -sOutputFile=file%03d.jpeg \

    -dBATCH \

    -dNOPAUSE \

    -r72x72 \

     page-12pt.ps

Улучшить качество изображения (и увеличить размер файлов) можно, изменив разрешение в параметре -r.

Создать DjVu-файл тоже несложно. Последовательность действий во многом определяется набором инструментов, которым вы располагаете. Я могу предложить следующий алгоритм.

Сперва создаём PPM-изображения каждой страницы:

gs  -sDEVICE=ppm \

    -sOutputFile=file%d.ppm \

    -dBATCH \

    -dNOPAUSE \

    -r120x120 \

     page-12pt.ps

Далее конвертируем все страницы (пусть иx будет четыре) в формат DjVu:

for i in 1 2 3 4

do

    cpaldjvu -dpi 120 file$i.ppm file$i.djvu

done

И объединяем полученные файлы в один документ:

djvm -create result.djvu file1.djvu file2.djvu file3.djvu file4.djvu

В файле result.djvu объединены все страницы.

Если проделать все эти операции с четырёхстраничным документом-примером к этой статье, то размер DjVu-файла составит менее 25 Кб.

Если вам понадобится документ MSWord или RTF, то проще всего создать HTML-документ (конвертирование в HTML мы рассматривали в предыдущей статье), скопировать его из Explorer в Word и «сохранить как...».

Хотя POD поддерживает не все существующие в природе форматы, я ни разу не сталкивался с безвыходной ситуацией.

Проверка корректности POD

Для проверки корректности POD-исходника существует очень полезная программа podchecker. Если вы укажете ей опцию -warnings, то получите все возможные предупреждения. Пример:

podchecker -warnings file.pod

Недостатки и перспективы POD

Огромным недостатком POD является отсутствие средств формирования таблиц. Частично это компенсируется возможностью вставки формат-ориентированных фрагментов. Так, HTML-таблица может быть создана средствами HTML:

=for html

<table><tr><th>A</th><th>B</th></tr>

    <tr><td>A</td><td>B</td></tr></table>

Но если вам требуется создать множество достаточно сложных таблиц, если вы хотите видеть их в документах разных форматов, то скорее всего вам следует использовать другое средство.

Существенным недостатком является и то, что POD не позволяет создавать документы, разнесённые в разные файлы. В POD-языке отсутствуют операции типа include, что не удобно при разработке больших документов. Это можно частично скомпенсировать, создавая некий гибридный документ, предназначенный для предварительной обработки каким-нибудь препроцессором, например, cpp или m4. Упростит ли это усовершенствование жизнь – решать вам.

Система POD продолжает развиваться. Наиболее многообещающей мне представляется команда =encoding. Согласно документу perlpod, она должна использоваться в начале документа.

Приведён даже пример (цитирую!):

=encoding koi8-r

Упоминается эта команда и в perldocspec. Но я, честно говоря, так и не понял, как её использовать. Podchecker сообщает, что такая команда ему не знакома. Конвертеры предупреждают об ошибке и игнорируют её.

Тем не менее, работа над форматом и средствами POD продолжается, и сделано уже немало. Работать с POD просто, приятно и эффективно.