Texinfo -- основная система докумнтации в проектах GNU.
Главная цель формата Texinfo -- создание из единого набора исходных файлов (.texi) документы и безупречно выглядящие при печати, и удобные для просмотра и навигации на экране компьютера. Основа высококачественной типографики достигается в Texinfo с помощью "военной хитрости": за основу взят plain TeX (основной язык TeX, как он описан Д. Кнутом. По сути -- это язык описания страниц и графического вывода вообще, как и более поздний язык PostScript. Надеюсь, я тут ни в чем особенно не наврал:) -- прим. перев.), который приспосабливается к специфике Texinfo после чтения файла texinfo.tex (В вашей системе может быть несколько копий этого файла. Проверьте, что используется свежая версия (на момент написания статьи -- 2002-01-04.07)). texinfo.tex выполняет всю работу по настройке TeX-форматирования. Он расширяет TeX, давая возможность распознавания гиперссылок и остальных "прибамбасов", нужных для экранной он-лайновой документации. Будучи скомпилированным для просмотра на экране, из исходника Texinfo получается файл Info (.info).
Info -- это файлы в ASCII-формате с возможностью перехода между связанными
гиперссылками различными документами и удобные для просмотра на экране. При
проектировании предполагалось, что формат будет переносимым между всеми
платформами, на которых возможно выполнение программ проекта GNU. Info
ориентирован на текст, так что файл Info можно просмотреть и в консоли
текстового режима. Высококачественная графика доступна только при выводе на
печать. Таким образом, формат Info дублирует возможности HTML, за вычетом
некоторых графических добавок. Тем не менее, texi2html(1)
может преобразовывать
исходники Texinfo (.texi) непосредственно в HTML, о чем можно прочесть
в разделе Средства просмотра.
Поскольку Texinfo основан на TeX (см. вторую из статей этой серии "LaTeX плюс latex2html" ), мы ожидаем еще раз столкнуться с делением на заголовок и тело документа. Кроме того, поддержка гиперссылок требует дополнительного структурирования, а именно так называемых узлов [nodes].
Каждый документ Texinfo начинается с команды plain TeX \input
,
читающей файл texinfo.tex. Это единственное место, где TeX
"просачивается" в Texinfo. Часть файла, начиная с включения texinfo.tex
и до так называемого корневого узла [Top node] -- об узлах мы поговорим позже --
составляет заголовок документа. Корневой узел или корень документа открывает
собой тело документа, простирающееся до заключительной команды
@bye
.
Все команды Texinfo вводятся символом @
. За at-символом должна
быть как минимум одна буква. Немногие команды нуждаются в фигурных скобках для
группировки аргументов. С командой @bye
, указывающей на конец
документа, мы уже встречались. Приведенный ниже пример простейшего файла Texinfo
вводит команду @c
, обозначающую комментарий. Комментарии Texinfo
продолжаются до конца строки, в которой они появились.
\input texinfo
@c === заголовок
===
...
@c === тело ===
@c --- Головной узел [Top Node]
---
...
@c --- Вложенные узлы ---
...
@bye
Заголовок -- необязательная часть файла Texinfo, но она появляется во всех докумнетах. В ней по меньшей мере содержится имя выходного файла для просмотра на экране и заголовок, который используется при выводе на печать.
Имя выходного файла задается командой @setfilename
output-filename. Я советую добавлять к имени-выходного-файла
расширение .info, поскольку файлы с расширением удобнее для работы --
просто представьте результат ls *.info
! Вся строка справа от
@setfilename
является аргументом команды, так что никаких
коментариев после имени выходного файла. Кошмар!
Заголовок устанавливается командой @settitle
заголовок-документа. Как и раньше, весь текст до конца строки является
аргументом команды. Заголовок (как он задан командой @settitle
)
используется для печати колонтитулов. Он не имеет ничего общего с названием
документа, которое ставиться на первой странице (если таковая имеется).
Простейший заголовок выглядит так:
@setfilename example.info
@settitle Пример Texinfo
Другие полезные в заголовках команды:
По умолчанию в Texinfo размер бумаги полагается равным 8,5 дюймов на 11
дюймов. За пределами Северной Америки размеры бумаги принято указывать в
соответствии с DIN -- Deutsche Industrie Norm -- Германским промышленным
стандартом. Командыљ@afourpaper
и @afourwide
изменяют область вывода текста в соответсвии с размером бумаги DIN A4, при
этом @afourwide
делает область печати несколько шире, что,
впрочем, не означает перехода к альбомной ориентации листа.
Совет: никогда не вредно проверить размер бумаги перед печатью "импортного" документа.
Имейте в виду, что команда @setchapternewpage even
не
определена.
Совет: Все разработки GNU поставляются с документацией в формате Texinfo. Если вы хотите распечатать ее сами, то сначала лучше изменить заголовок файлов Texinfo в соответствии с применяемым размером бумаги (Letter, A4) и используемым оборудованием (принтер для двусторонней печати и т.д.).
Тело документа Texinfo представляет собой смесь команд секционирования, используемых при печати (части TeX-публикации: главы, разделы, подразделы и т.д.) и команд группировки, используемых при просмотре на экране (собственно Info: узлы [nodes]). Теоретически, каждая из этих двух "ипостасей" может задавать свою структуру документа. Такая ситуация, однако, может изрядно обескуражить читателя, а это, вероятно, не входит в план написания технической документации.
Я изложу упрощенный подход к созданию тела документа, в котором структура он-лайновой и печатной версий максимально близки. Ценой незначительного ограничения возможностей навигации это избавляет пишущего от головной боли ручной разбивки документа для экранного просмотра. Упрощенная метода требует, чтобы структура информации в Info-версии соответствовала структуре печатной версии.
Структура Info определяется командами @node
node-name,
в то время как структура печатного документа задается -- среди прочего --
командами @chapter
chapter-title, @section
section-title и @subsection
subsection-title.
Команда @node
всегда появляется первой. Вот некоторые примеры:
@node Введение @chapter Введение
или
@node Итеративные-процессы @section Итеративные процессы
или
@node Численная стабильность @subsection Численная стабильность итеративных алгоритмов
Аргумент команды @node
присваевает узлу имя node-name.
Имя состоит из одного или более слов. Пробелы в node-name вполне
допустимы, но точка .'', запятая ,'', двоеточие :'' и апостроф ' -- запрещены. В
имени узла также рекомендуется избегать команд (чего-либо, начинающегося с "@").
Имена узлов чувствительны к регистру. В документе Texinfo каждый узел должен
иметь уникальное имя. Существует соглашение, по которому слова в именах узлов
начинают с заглавной буквы, как это делается в именах глав и разделов (автор
имеет в виду традицию англоязычной типографики, согласно которой все значимые
слова -- существительные, прилагательные и глаголы, но не предлоги и артикли,
пишут с заглавной буквы. прим. пер.).
Узел может либо содержать исключительно данные (а именно текст, таблицы, иллюстрации и перекрестные ссылки), либо узел должен определять меню навигации. Далее узлы "первого рода" я называю терминальными, а узлы второго рода -- узлами-меню.
Структура терминального узла такова
@node
имя-узла@section
заголовок-секции
текст-узла-главы
я воспользовался командой @section
, как примером команды
секционирования.
Терминальные узлы -- плоть документа. В них заключена вся информация, которая видна читателю. текст-узла-главы обычно содержит один или более абзацев, таблиц и т.д.
Узлы-меню обеспечивают "децентрализованные" оглавления (что уже является мета-информацией), из которых можно быстро "перескочить" к любому из перечисленных в меню разделов.
Структура узла-меню схожа с терминальным узлом за исключением того, что узел-меню заканчивается определением меню навигации. Меню навигации вставляется исключительно в Info-версию и никогда не появляется в печатной версии.
@node
имя-узла@chapter
заголовок-главы
необязательный-вводный-текст-и-для-узла-и-для-главы@menu
*
Имя узла для первого раздела::
Синопсис первого раздела*
Имя узла для второго раздела::
Синопсис второго раздела
...*
Имя узла для последнего раздела::
Синопсис последнего раздела@end menu
Меню навигации заключается "в скобки"
@menu
@end menu
и каждая строка между ними превращается в пункт меню. Каждый пункт должен
начинаться с символа "звездочки" *
'', за которым следует имя
узла, на который этот пункт указывает [target node]. Далее идет двойное
двоеточие ::
'', а за ним может помещаться необязательное краткое
описание "указУемого" раздела:
*
Имя раздела ::
Необязательное
описание раздела
Top
и определяется двумя командами:
@node Top
@top
имя-корневого-узла
Поскольку корневой узел оказывается первым каждый раз, когда документ
загружается для просмотра на экране (если нет явного указания начинать
просмотр с какого-либо иного узла), то желательно включить в него вводный
текст. Такой вводный текст обычно не годится для печатной версии. Не забыли,
что в печатной версии вообще нет меню? Поэтому нам надо исключить вводный
текст из печатной версии, что достигается с помощью команд условной трансляции: парных команд
@ifinfo
и @end ifinfo
. Несложный корневой узел
выглядит следующим образом:
@ifinfo
@node
Top@top
Пример
Это пример документа Texinfo.@end ifinfo
@menu
*
Имя первой главы::
Синопсис первой главы*
Имя второй главы::
Синопсис второй главы*
Имя третьей главы::
Синопсис третьей главы@end menu
Вот мы и готовы написать полный документ Texinfo.
\input texinfo @setfilename example.info @settitle Texinfo Example @ifinfo @node Top @top Пример Это пример документа Texinfo. @end ifinfo @menu * Введение:: Определения, Меры, Сложность * Исчисление полиномов:: Изучение обычных операций @end menu @node Введение @chapter Введение В этой главе обсуждаются концепции, в дальнейшем используемые в разных частях этого документа. Более того, здесь вводятся мера эффективности и мера ограничения сложности. @menu * Определения:: Основы * Меры эффективности:: Как измерять эффективность * Ограничения сложности:: Типичные ограничения сложности @end menu @node Определения @section Определения ... @node Меры эффективности @section Меры эффективности ... @node Ограничения сложности @section Ограничения сложности ... @node Исчисление полиномов @chapter Исчисление полиномов ... @bye
Мы уже заметили, что команды Texinfo начинаются с символа "собаки" --
"@
". За ним либо следует единственный небуквенный символ, либо один
или несколко букв. Вот несколько команд первой группы:
@@
@
").
@"
символ@'
символ), циркумфлексом
(@^
символ) или цедилью (@,
символ).
За подробностями обратитесь к узлу "Вставка акцентов [Inserting Accents] в
документации Texinfo. а вот примеры из второй группы:
Команда может требовать один, два, три и более аргументов или не требовать их
совсем. Некоторые команды требуют, чтобы агрументы заключались в фигурные
скобки, например команда перекрестной ссылки
@xref{
имя-узла,
имя-перекрестной-ссылки,
заголовок-раздела}
. Мы уже видели команды, считающими
своим аргументом остаток той строки, в которой они появляются (например, команда
@setfilename
).
Как и в TeX'е, мы просто набираем текст, разделяя абзацы пустыми строками. В зависимости от используемых средств трансляции абзацы получаться с выключкой или даже выравненными по ширине.
Главные команды секционирования введены в разделе Тело документа. Команды
@node
групируют вводимый текст и разбивает его на куски, пригодные
для чтения с экрана. Сопровождающие их TeX-подобные команды секционирования
делают то же самое, но при печати. В частности, Texinfo предлагает следующие
команды разделов: chapter
, section
,
subsection
и subsubsection
.
Пожалуйста не забывайте, что -- для упрощения дальнейшего сопровождения -- за
каждой командой @node
должна следовать одна из команд
секционирования при печати.
Сделать приличную титульную страницу легко. Команда @titlepage
,
а также дополнительные команды [sub-commands] @title
,
@subtitle
(необязательно) и @author
, берут на себя
заботы о компановке титульной страницы. Если вы хотите, чтобы материал,
следующий за титулом, располагался на нечетной странице -- нужно добавить разрыв
страницы непосредственно после @end titlepage
.
Пример:
@titlepage
@title Образец документа Texinfo
@subtitle Пробуем, как Texinfo форматирует текст
@author Joanne H. Acker
@page @c -- начинаем последующий текст с нечетной страницы
@end titlepage
В разделе Корень документа мы столкнулись с
командами условной трансляции @ifinfo
/@end info
.
Условная трансляция означает, что определенные части документа направляются на
вход только одного определенного транслятора (в нашем примере это makeinfo), или
же, в случае @ifnotinfo
/@end notinfo
, что определенный
транслятор не используется при обработке части документа.
На одной строке вместе с открывающей (@if
format) и
закрывающей (@end
format) последовательностью команд
условной трансляции не должно быть больше ничего.
Имеются три парных директивы включения (исключения) части материала при конвертации документа в формат Info, TeX и HTML соответственно.
@iftex
...
@end tex
@ifinfo
...
@end info
@ifhtml
...
@end html
@ifnottex
...
@end nottex
@ifnotinfo
...
@end notinfo
@ifnothtml
...
@end nothtml
В Texinfo есть возможность создавать перечисления тех основных типов, которые ожидает найти любой автор: ненумерованные и нумерованные списки. Списки определений оформляются в терминах таблиц.
Все списки могут быть вложенными.
Команда @item
начинает элемент списка или таблицы. Элемент
списка может охватывать несколько абзацев текста или других списков. Я уже
говорил, что все списки могут быть вложенными? Так и есть!
@itemize
маркер списка@item
Первый пункт@item
Второй пункт
...@item
Последний пункт@end itemize
Символ маркера списка будет помещен перед каждым пунктом. Обычными
у практичными вариантами маркера списка являются
@bullet
, @minus
и *
.
@enumerate
селектор нумератора@item
Первый пункт@item
Второй пункт
...@item
Последний пункт@end enumerate
Селектор нумератора указывает тип счетчика (числовой или буквенный) и его начальное значение. Если селектор нумератора пропущен, то список будет оформлен с использованием арабских цифр начиная с единицыe.
Указание для селектора нумератора положительного целого значения начинает счет элементов с этого значения. Это полезно при необходимости продолжения прерванного списка. Указание в селекторе нумератора буквы верхнего или нижнего регистра создает список, пронумерованный буквами, причем нумерация начинается с указанной.
Texinfo не умеет работать со списками, пронумерованные римскими цифрами.
@table
селектор формата@item
Первый термин
Описание первого термина@item
Второй термин
Описание второго термина
...@item
Последний термин
Описание последнего термина@end table
Селектор формата определяет, как будет выглядеть термин. Если вы,
в случае простого списка определений, не хотите использовать дополнительного
форматирования, то в качестве селектора формата следует использовать
@asis
. Если в качестве терминов оказываются элементы программного
кода, примеры пользовательского ввода, программного вывода, переменных или
комбинаций клавиш, то можно воспользоваться @code
,
@samp
, @var
или @kbd
соответственно. За
подробностями обращайтесь к разделу Прямое
форматирование.
Внутри такой таблицы, аргументом @item
служит весь текст от
самой команды @item
до конца строки. Обратите внимание на это
отличие от ненумерованных и нумерованных списков! Определением в таком "списке
определений" должно занимать не более одной строки. Текст после такой
@item
-строки и до следующего элемента @item
или
конца таблицы становится описанием термина. Описание может состоять из
нескольких абзацев, содержать другие списки и т.д.
Поскольку иногда нам нужны дополнительные термины на отдельных строках.
Поскольку @item
помещает свой аргумент на одной строке, для этого
требуется другая команда: @itemx
помещает дополнительный термин
непосредственно под уже существующим. Команда @itemx
допустима
только сразу после команд @item
или
@itemx
.
Команда переводчиков:
Владимир Меренков, Александр Михайлов, Иван
Песин, Сергей Скороходов, Александр Саввин, Роман Шумихин, Александр Куприн,
Андрей Киселев
Со всеми предложениями, идеями и комментариями обращайтесь к Сергею Скороходову ([email protected]). Убедительная просьба: указывайте сразу, не возражаете ли Вы против публикации Ваших отзывов в рассылке.
Сайт рассылки: http://gazette.linux.ru.net
В
Интернете эту статью пока взять негде, ждите второй половины:)