Тело документа
Тело документа 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]. Далее идет двойное двоеточие ::'', а за ним может помещаться необязательное краткое описание "указУемого" раздела:
* Имя раздела :: Необязательное описание раздела
Корень документа Один узел-меню играет особую роль в каждом документе Texinfo: главный узел, которому "принадлежат" все остальные. Корень документа называется узлом 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
