Написание документации, часть IV: Texinfo

By Christoph Spiel



Перекрестные ссылки

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

Узлы [Nodes] -- самые частые "мишени", на которые "нацеливаются" ссылки. Команда @anchor{имя-метки} создает в документе дополнительную метку [anchor], на которую можно ссылаться из другого места. Сама по себе команда @anchor в оттранслированном документе не видна. Имена меток не должны конфликтовать с именами узлов.

@xref

Вставляет "декорированную" перекрестную ссылку. Команда @xref создает оформление для ссылки в начале предложения.

Пример:

    ... является основой для нескольких многоточечных
методов. @xref{Multi-point Methods}. Мы
изучаем одноточечные методы ...
@pxref

@pxref ведет себя подобно @xref, но предназначен для использования внутри скобок.

Пример:

    Алгоритм терпит неудачу в случае корней
более высокого порядка (@pxref{Higher Order Root}) и
корней первого порядка, заданных неверными условиями.
@ref

Вставляет простую (не "декорированную") перекрестную ссылку. В остальном ведет себя подобно @xref.

До сих пор мы использовали команды создания перекрестных ссылок с одним аргументом. Команды эти, однако, могут принимать до пяти параметров. Ниже представлены примеры того, как, в зависимости от числа аргументов, изменяется внешний вид оттранслированного текста. Я привожу примеры "гибкого" использования команды @xref

Один аргумент
@xref{имя-метки}

дает на выходе

*Note имя-метки::

при трансляции в Info и

Смотри раздел имя-раздела [имя-метки], страница номер-страницы

при трансляции для печати, здесь имя-радела и номер-страницы -- соответственно название раздела и номер страницы, где в версии для печати располагается метка "имя-метки".

Два аргумента
@xref{имя-метки, имя-перекрестной-ссылки}

после трансляции даст:

*Note имя-перекрестной-ссылки: имя-метки

и

Смотри раздел имя-раздела [имя-метки], страница номер-страницы

Три аргумента
@xref{имя-метки, имя-перекрестной-ссылки, заголовок-темы}

дает:

*Note имя-перекрестной-ссылки: имя-метки

и

Смотри раздел имя-раздела [заголовок-темы], страница номер-страницы

Пять аргументов
@xref{имя-метки, имя-перекрестной-ссылки, заголовок-темы, имя-файла-info, заголовок-печатного-руководства}

в результате трансляции получаем:

*Note имя-перекрестной-ссылки: (имя-файла-info)имя-метки

и

Смотри раздел "заголовок-темы" в заголовок-печатного-руководства

Прямое форматирование

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

Инструменты

makeinfo

makeinfo преобразует файлы Texinfo (.texi) в

  1. Файлы Info

    По умолчанию, makeinfo создает файл Info с именем, указанным параметром @setfilename. Опция --no-split не разрешает makeinfo дробить выходной файл на отдельные файлы [chunks] приблизительно по 50KB каждый.

    Помимо всего прочего, обработка файла Texinfo программой makeinfo тщательно проверяет его синтаксическую структуру.

  2. Текстовой файл ASCII

    Опция --no-headers требует от makeinfo создать простой текстовой ASCII-файл. Формат текстового файла полезен при вычитке экранной версии и удобен для проверки правописания с помощью, например, diction(1).

texi2html

По названию команды вы, наверное, уже догадались, что texi2html преобразует файлы Texinfo в HTML. С помощью опции -monolithic вывод осуществляется в виде одного файла. Другая опция, -split указывает создать отдельный файл для каждого узла.

По умолчанию texi2html транслирует секции @iftex и не использует разделы @ifinfo. С помощью опции -expandinfo можно получить противоположный результат.

Обратите внимание на то, что опции texi2html начинаются с одного дефиса.

texi2dvi

Создает из исходного файла Texinfo файл в независимом от устройства формате .dvi. Применение dvips(1) к файлу .dvi позволяет получить на выходе код Postscript. Я нахожу полезными опции --clean и --quiet. Первая удаляет промежуточные файлы, оставляя только файл .dvi. А вторая отключает вывод необязательных сообщений (тут автор использует "непереводимую игру слов": No gnews is good gnews!'', т.е. "Отсутствие гнуовостей -- хорошая гнуовость" -- прим. перев.).

texi2pdf

texi2pdf за "один присест" создает из исходного файла Texinfo файл в формате Переносимого Документа [Portable Document File] (.pdf). Можно использовать те же опции, что и в случае texi2dvi. Я, однако, заметил, что texi2pdf определенно требуется опция --pdf, иначе он останавливается, громко требуя файл .dvi, даже когда этот файл точно существует. Гр-р! Так что я обычно выполняю следующее:

    texi2pdf --quiet --clean --pdf foobar.texi

Программы просмотра (браузеры)

От других рассмотренных нами систем подготовки документации Texinfo отличается тем, что для целей экранного просмотра документы Texinfo могут быть транслированы в отличный от HTML формат, а именно -- в формат Info. Естественно, что для формата экранного просмотра требуется браузер!

info

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

Для того, чтобы просмотреть страницы Info по теме Тема используйте вызов

    info Тема

Для просмотра файла Info файл-info к вызову info добавьте параметр --file=файл-info, где файл-info содержит полный путь к нужному файлу Info.

Если вы желаете начать просмотр с конкретного узла имя-node, добавьте параметр --node=имя-node.

Моя любимая ошибка -- смешивание темы с -- -- файлом-info, т.е. набор команды

    info ./cache-profiler.info

вместо подразумеваемого

    info --file=./cache-profiler.info
pinfo

Это основанный на curses(3) браузер с навигацией в стиле lynx(1). pinfo очень красиво раскрашивает страницы Info

emacs

Скриншот доказывает улучшение возможностей просмотра фалов Info в emacs 21.x.

Я знаю, что это лишь Emacs Info, но оно мне сильно-сильно нравится! Я его даже люблю!

Можно просмотреть установленную документацию в формате Info (C-h i', info). Или же можно загрузить файл Info и командой Info-on-current-buffer превратить буфер в браузер Info (обратите внимание на заглавную букву "I"). Если нет желания переключаться между рабочими буферами и режимом просмотра Info, то можно открыть файл в режиме просмотра (C-x 5 f', find-file-other-frame). Для того, чтобы открыть новый фрейм с браузером Info, переключитесь в буфер *info* в текущем окне emacs и выполните команду view-buffer-other-frame.

Чтобы получить от "браузенья" дополнительное удовольствие, попробуйте команду Info-speedbar-browser.

xinfo

xinfo -- древнейшая программа для просмотра Info-файлов в среде X11. Цветовой разметки текста нет. Более всего меня в нем раздражает -- до такой степени, что я его никогда не использую -- то, что навигация и отображение полностью разделены. Я имею в виду, что для перехода по ссылке в одной панели, приходиться "кликать" мышью по панели верхнего уровня. Щелчки мыши по самому меню ни к чему не приводят.

Скриншот можно посмотреть здесь.

tkinfo

Ну, это мой любимый браузер Info для X! В нем есть все "приятности" info(1): он быстро стартует, а его окно удобно устроено.

gnome-help-browser

Если вы используете Gnome, то, наверное, знакомы сgnome-help-browser(1x). В нем можно просматривать и страницы Info.

kdehelp

То же самое относится и к пользователям KDE... Вы, вероятно, знакомы с kdehelp(1x). Среди других форматов в нем поддерживается и страницы Info.

kdehelp легко убедить показать конкретный Info-файл:

    kdehelp ./cache-profiler.info

Просто на большой?!

konqueror тоже показывает файлы info (по крайней мере konqueror 2.2.2): просто надо напечатать "info:" в строке адреса.

Обзор распространенных программ просмотра Info

Обзор распространенных Info-браузеров. "Поддержка других форматов" означает умение показывать документы в других форматах. "требует X11" означает, что программа работает только в среде X Window. "Навигация в стиле info" означает, что в программе дублируется команды навигации info(1).
Приложение Поддержка других форматов требует X11 Навигация в стиле info
info нет нет да
pinfo нет нет нет
emacs нет нет да
xinfo нет да да
tkinfo нет да да
gnome-help-browser да да нет
kdehelp да да нет

Плюсы и минусы

За
  • Формат Texinfo: определяемые пользователем макросы (в этой статье не обсуждались)
  • Вывод в формате TeX: совершенство верстки, фантастическое качество печатной версии
  • Формат Info: альтернатива вездесущему HTML
  • Программы просмотра Info: стандартизированная, быстрая и удобная навигация
Против
  • Формат исходного текста документов Texinfo:

    • Узлы, требующие четыре аргумента, трудно поддерживать без помощи emacs(1). (В этой статье я не показал форму с четырьмя аргументами. Вместо этого я предлагаю упрощенную форму синтаксиса создания узла с одним аргументом.)
    • Использующие один аргумент узлы плюс команды секционирования чрезмерно трудны
  • Сам формат Info: Info отображается статически, то есть браузеры не переформатируют абзацы если длина строк в браузере отличается от длины строк, использованной при создании страницы Info. Браузеры HTML обычно автоматически справляются с этой проблемой.

Дополнительные материалы

Домашняя страница Texinfo, на которой можно найти много справочной информации http://texinfo.org/

Существующие конвертеры Texinfo перечислены здесь: http://www.fido.de/kama/texinfo/texinfo-en.html

Кристоф Шпиль [Christoph Spiel]

Крис руководит расположенной в Верхней Баварии (Германия) компанией, консультирующей по вопросам Open Source Software. Не смотря на то, что по образованию он физик (он получил ученую степень Доктора Философии в Мюнхенском Технологическом Университете), его главные интересы вращаются вокруг численных методов, гетерогенных сред программирования и разработки программного обеспечения. Связаться с ним можно по адресу [email protected].