Emacs для начинающих

       

Тело документа


Тело документа 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


Содержание раздела