Go to the first, previous, next, last section, table of contents.


Включаемые файлы

Когда TeX или команда форматирования Info встречают в Texinfo-файле команду @include, они обрабатывают содержимое указанного командой файла и включают его в создаваемый DVI- или Info-файл. Вхождения именных указателей из включаемых файлов вносятся в именные указатели выходного файла.

Включаемые файлы позволяют вам держать большой документ в виде удобных небольших частей.

Как использовать включаемые файлы

Чтобы включить в Texinfo-файл другой файл, напишите команду @include в начале строки, и за ней имя включаемого файла на той же строке. Например:

@include buffers.texi

Включаемый файл должен быть просто сегментом текста, который вы предполагаете вставить как есть в общий или внешний Texinfo-файл; он не должен содержать стандартные начальную и завершающую части Texinfo-файла. В особенности, вы не должны начинать включаемый файл строкой `\input texinfo'; если вы сделаете так, эта фраза вставится во внешний файл буквально. Аналогично, вы не должны завершать включаемый файл командой @bye; текст после @bye не форматируется.

Раньше в начале каждого включаемого файла нужно было обязательно писать строку @setfilename, но теперь не нужно. Теперь не имеет значения, написали ли вы такую строку или нет. Если строка @setfilename существует во включаемом файле, она игнорируется.

По соглашению, включаемый файл начинается строкой @node, за которой следует строка @chapter. Каждый включаемый файл -- это одна глава. Это облегчает использование обычных команд создания и обновления нод и меню внутри включаемого файла. Однако, простые команды Emacs для создания и обновления нод и меню не работают со множественными Texinfo-файлами. То есть вы не можете использовать эти команды для заполнения указателей `Next', `Previous' и `Up' в строке @node, которая начинает включаемый файл. Также вы не можете использовать обычные команды для создания главного меню полного файла. Вы либо должны заполнить меню и указатели `Next', `Previous' и `Up' вручную, либо использовать команду режима Texinfo для GNU Emacs, texinfo-multiple-files-update, разработанную для @include-файлов.

texinfo-multiple-files-update

Режим Texinfo в GNU Emacs предоставляет команду texinfo-multiple-files-update. Эта команда создает или обновляет во включаемом файле указатели `Next', `Previous' и `Up', а также во внешнем или общем Texinfo-файле; и создает или обновляет главное меню во внешнем файле. В зависимости от того, вызвали ли вы ее с необязательными аргументами, эта команда обновляет либо только указатели в первой строке @node включаемого файла, либо все указатели:

M-x texinfo-multiple-files-update
Вызванная без аргументов:
C-u M-x texinfo-multiple-files-update
Вызванная с C-u в качестве префиксного аргумента:
C-u 8 M-x texinfo-multiple-files-update
Вызванная с числовым префиксным аргументом, например C-u 8:

Обратите внимание на применение префиксного аргумента при интерактивном использовании: с обычным префиксным аргументом, просто C-u, команда texinfo-multiple-files-update вставляет главное меню; с числовым префиксным аргументом, таким как C-u 8, эта команда обновляет все указатели и меню во всех файлах и затем вставляет главное меню.

Требования для включаемых файлов

Если вы планируете использовать команду texinfo-multiple-files-update, то внешний Texinfo-файл, перечисляющий включаемые файлы, не должен содержать ничего, кроме начальной и завершающей частей Texinfo-файла и нескольких команд @include для включаемых файлов. Он не должен включать даже именных указателей, которые должны быть перечислены в отдельном включаемом файле.

Кроме того, каждый включаемый файл должен содержать ровно одну ноду верхнего уровня (обычно это @chapter или эквивалент), и эта ноды должна быть первой нодой во включаемом файле. Более того, все эти нод верхнего уровня из каждого включаемого файла должны быть на одном иерархическом уровне в общей структуре. Обычно все они являются нодами @chapter, @appendix или @unnumbered. Таким образом, каждый включаемый файл содержит одну и только одну ноду с главой или эквивалентного уровня.

Внешний файл должен содержать только одну ноду, ноду `Top'. Он не должен содержать никаких нод кроме одной ноды `Top'. Команда texinfo-multiple-files-update не будет их обрабатывать.

Пример файла с @include

Вот пример законченного внешнего Texinfo-файла с @include-файлами внутри, до запуска texinfo-multiple-files-update, которая вставила бы главное меню:

\input texinfo @c -*-texinfo-*-
@setfilename  include-example.info
@settitle Include Example

@setchapternewpage odd
@titlepage
@sp 12
@center @titlefont{Include Example}
@sp 2
@center by Whom Ever

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998 Free Software Foundation, Inc.
@end titlepage

@ifinfo
@node Top, First, , (dir)
@top Master Menu
@end ifinfo

@include foo.texinfo
@include bar.texinfo
@include concept-index.texinfo

@summarycontents
@contents

@bye

Включаемый файл, например `foo.texinfo', может выглядеть так:

@node First, Second, , Top
@chapter First Chapter

Contents of first chapter ...

Полное содержание `concept-index.texinfo' может выглядеть так:

@node Concept Index
@unnumbered Concept Index

@printindex cp

Внешний исходный Texinfo-файл для The GNU Emacs Lisp Reference Manual называется `elisp.texi'. Этот внешний файл содержит главное меню из 417 пунктов и список из 41 включаемого файла.

История развития включаемых файлов

Когда Info была первоначально создана, было принято делать много небольших Info-файлов на одну тему. Каждый Info-файл форматировался из отдельного исходного Texinfo-файла. Этот обычай был предназначен для того, чтобы в Emacs не нужно было создавать большой буфер для хранения большого Info-файла целиком, когда кто-то хотел получить информацию; вместо этого Emacs выделял ровно столько памяти, сколько нужно для маленького Info-файла, содержащего нужную информацию. Таким образом Emacs избегал лишнего расхода памяти.

Ссылки из одного файла в другой делались путем указания и имени файла, и имени ноды. (See section Ссылки на другие Info-файлы. Также смотрите section @xref с четырьмя и пятью аргументами.)

Включение файлов было разработано преимущественно как способ создания единого, большого печатного руководства из нескольких меньших Info-файлов. В печатном руководстве все ссылки были внутри одного документа, так что TeX мог автоматически определить для них номера страниц. Команды форматирования Info использовали включаемые файлы лишь для создания объединенных именных указателей; каждый отдельный Texinfo-файл нужно было форматировать для Info индивидуально. (Каждый из них, следовательно, должен был содержать свою строку @setfilename.)

Однако, так как большие Info-файлы теперь автоматически разбиваются, больше нет необходимости сохранять их маленькими.

Теперь множественные Texinfo-файлы используются преимущественно для больших документов, таких как The GNU Emacs Lisp Reference Manual и для проектов, в которых несколько человек одновременно пишут разные разделы документа.

Кроме того, команды форматирования для Info были расширены для работы с командой @include так, чтобы создавать единый большой Info-файл, который разбивается при необходимости на меньшие файлы. Это означает, что вы можете писать меню и перекрестные ссылки не обращаясь к различным Texinfo-файлам.


Go to the first, previous, next, last section, table of contents.