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

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

В формате 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 определяет обширный набор команд прямого или "физического" форматирования, помечающих части текста, как код, пользовательский ввод, имя файла и т.д.

• @emph{набранный-курсивом-текст}

  Отображает набранный-курсивом-текст (сюрприз:) курсивом. В Info курсивное начертание "приближенно" изображается с помощью символов подчеркивания, как скобки охватывающих _набранный-курсивом-текст_.

  Пример:

      Для обработки файлов Texinfo
  
      пользуйтесь tex(1) @emph{а не}latex(1).
  
  

• @strong{текст-набранный-жирным}

  Отображает текст-набранный-жирным шрифтом жирного начертания. В Info этому "примерно" соответствует символы "звездочка", охватывающие *текст-набранный-жирным*.

  Пример:

      Файлы Info @strong{не могут} содержать
  
      графику высокого разрешения.
  
  

• @file{имя_файла}

  Выделяет имя_файла, окружая его одиночными кавычками, например так filename'. При подготовке версии для печати имя_файла печатается шрифтом пишущей машинки.

  Пример:

      Убедитесь, что в вашей Linux-системе
  
      установлена самая свежая версия @file{texinfo.tex}.
  
  

• @url{универсальный-локатор-ресурса}

  Таким образом в тексте выделяется универсальный локатор ресурса (URL). В экранной версии универсальный-локатор-ресурса будет помещен в угловые скобки. При выводе на печать угловые скобки не добавляются, но универсальный-локатор-ресурса набирается моноширинным шрифтом "пишущей машинки".

  Пример:

      Дополнительная информация по Texinfo
  
      можно найти на @url{http://texinfo.org/}.
  
  

• @code{код-программы}

  Служит для выделения коротких участков программного кода.

      Предпочтительной является форма @code{bless}
  
      с двумя аргументами, поэтому всегда пишите
  
      @code{bless $objref, $class}.
  
  

• @samp{текст, набираемый "как есть", буквально}

  Помечает символы, непосредственно набираемый текст, имена символов и т.д.

      Угловые скобки (@samp{<}, @samp{>}) являются
  
      основным разделителем в HTML.
  
  

• @var{текст, подлежащий замене}

  Помечает мета-синтаксические [meta-syntactic] переменные, знаменитые foo и bar.

      Команды Perl @code{bless} лучше всего вызывать
  
      с двумя аргументами, например так @code{bless
  
      @var{object_reference}, @var{classname}}.
  
  

• @kbd{названия клавиш}

  Помечает отдельные клавиши или серии клавиш.

      В emacs, нажмите @kbd{C-h i} для вызова
  
      встроенного браузера Info, или наберите @kbd{M-x
  
      info}.
  
  

• @command{имя-команды}

  Помечает имя команды.

      Двумя наиболее важными командами шелла являются
  
      @command{ls} и @command{cd}.
  
  

• @option{имя-опции}

  Метит имя опции командной строки @option вот так:

      Опция @option{--html} заставляет
  
      @command{makeinfo} создавать на выходе файл HTML
  
      вместо файла Info.
  
  

  @option не подходит для форматирования синопсиса команды. Для того, чтобы оформить краткое описание использования команды лучше воспользоваться окружением @example. Скажем так:

      @example
  
          makeinfo --html --output=@var{output-filename} @var{input-filename}
  
      @end example
  
  

  а в блоке текста к опциям обращаться, как @option{--html} и @option{--output}, а к аргументам команд как @var{output-filename} и @var{input-filename}.

Инструменты

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

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

За

• Формат 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. Не смотря на то, что по образованию он физик (он получил ученую степень Доктора Философии в Мюнхенском Технологическом Университете), его главные интересы вращаются вокруг численных методов, гетерогенных сред программирования и разработки программного обеспечения. Связаться с ним можно по адресу cspiel@hammersmith-consulting.com.