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


Ноды

Ноды -- это первичные сегменты Texinfo-файла. Сами по себе они не налагают иерархической или иной другой структуры на файл. Ноды содержат указатели на ноды, которые отсылают к другим нодам, и меню, являющиеся списками нод. Команды перемещения в Info могут привести вас к ноде по указателю на нее или к ноде, перечисленной в меню. Указатели на ноды и меню обеспечивают некую структуру в Info-файлах, как главы, разделы, подразделы и подобные фрагменты обеспечивают структуру в печатных книгах.

Два способа

Команды для нод и меню и команды описания структуры глав независимы друг от друга в техническом смысле:

Вы можете использовать указатели на ноды и меню, чтобы создать Info-файл с любой структурой, какой захотите; вы можете написать Texinfo-файл так, что его вывод в формате Info будет иметь другую структуру, нежели его печатный вывод. Однако, прктически все Texinfo-файлы наисаны так, что структура вывода в Info соответствует структуре печатного вывода. Делать иначе было бы неудобно и непонятно для читателя.

Обычно печатный вывод структурирован в виде древовидной иерархии, в которой главы являются более крупными членами, и от них ответвляются разделы. Аналогично, указатели на ноды и меню организуются так, чтобы создать совпадающую структуру при выводе в Info.

Иллюстрация нод и меню

Здесь приведена копия показанной ранее диаграммы, которая изображает Texinfo-файл с тремя главами, каждая из которых содержит три раздела.

"Корень" находится в вершине диаграммы, а "листья" внизу. Традиционно подобные диаграммы изображаются именно таким образом; они иллюстрируют дерево, направленное сверху вниз. По этой причине корневая нода называется `Top' (Первая), а указатели `Up' (Вверх) переносят вас ближе к корню.

                        Вершина
                           |
         -------------------------------------
        |                  |                  |
      Глава 1            Глава 2            Глава 3
        |                  |                  |
     --------           --------           --------
    |        |         |        |         |        |
  Раздел   Раздел    Раздел   Раздел    Раздел   Раздел
   1.1      1.2       2.1      2.2       3.1      3.2

Полная форма команды для начала Главы 2 выглядела бы так:

@node    Глава 2,   Глава 3, Глава 1,  Top
@comment node-name, next,    previous, up

Эта строка @node говорит, что данная нода называется "Глава 2", следующая нода называется "Глава 3", предыдущая нода называется "Глава 1", а верхняя нода называется "Top". Вы можете не писать все эти имена нод, если ваш документ организован иерархически (see section Создание указателей с помощью @command{makeinfo}), но связь между указателями сохраняется.

Пожалуйста, обратите внимание: `Next' ссылается на следующую ноду на том же иерархическом уровне руководства, не обязательно на следующую ноду в Texinfo-файле. В Texinfo-файле, последующие ноды могут находиться на более нижнем уровне: ноды уровня разделов чаще всего следуют за нодами уровня глав, для примера. Указатели `Next' и `Previous' ссылаются на ноды того же иерархического уровня. (Нода `Top' представляет исключение из этого правила. Так как нода `Top' является единственной нодой на своем уровне, то ее указатель `Next' ссылается на первую последующую ноду, которая почти всегда является главой или нодой уровня глав.)

Чтобы перейти к разделам 2.1 и 2.2, используя Info, вам понадобится меню внутри Главы 2. (See section Меню.) Вы должны написать меню непосредственно перед началом Раздела 2.1, как показано ниже:

    @menu
    * Разд. 2.1::    Описание этого раздела.
    * Разд. 2.2::
    @end menu

Напишите ноду для раздела 2.1 так:

    @node     Разд. 2.1, Разд. 2.2, Глава 2, Глава 2
    @comment  node-name, next,      previous,  up

В формате Info указатели `Next' и `Previous' обычно ведут к другим нодам того же уровня -- от главы к главе или от раздела к разделу (иногда, как показано, `Previous' ссылается на верхнюю ноду); указатель `Up', как правило, ведет к ноде верхнего уровня (ближе к первой ноде (`Top'); меню приводит к нодам более низкого уровня (ближе к `листьям'). (Перекрестная ссылка может указывать на ноду любого уровня; смотрите section Перекрестные ссылки.)

Обычно команда @node и команды описания структуры глав используются вместе, как и команды добавления вхождений в именные указатели. (Вы можете написать после строки @node строку комментария, который напомнит вам, какой указатель куда указывает.)

Ниже приведено начало главы данного руководства, озаглавленной "Завершение Texinfo-файла". Тут показана строка @node, за которой идет строка комментария, строка @chapter и затем строки для именных указателей.

@node Завершение файла, Структурирование, Начало файла, Top
@comment node-name, next, previous, up
@chapter Завершение Texinfo-файла
@cindex Завершение Texinfo-файла
@cindex Texinfo-файл, завершение
@cindex Файл, завершение

Команда @node

Нода -- это сегмент текста, начинающийся с команды @node и продолжающийся до следующей команды @node. Определение ноды отличается от определения главы или раздела. Глава может включать разделы, а раздел -- подразделы, но нода не может содержать подноды; текст ноды продолжается только до следующей команды @node в файле. Нода обычно содержит только одну команду для описания структуры глав, ту, что идет после строки @node. С другой стороны, в печатном выводе ноды применяются только для перекрестных ссылок, так что глава или раздел может содержать любое число нод. На самом деле, глава обычно включает несколько нод, по одной на каждый раздел, подраздел и подподраздел.

Чтобы создать ноду, напишите команду @node в начале строки и за ней четыре ее аргумента, разделенные запятыми, в конце той же строки. Первый аргумент обязателен: это имя данной ноды. Последующие аргументы --- это имена для указателей `Next', `Previous' и `Up', в таком порядке; они могут быть опущены, если ваш документ организован иерархически (see section Создание указателей с помощью @command{makeinfo}).

Вы можете вставлять пробелы перед каждым именем, если хотите. Вы должны писать имя ноды и имена указателей `Next', `Previous' и `Up' на одной строке, иначе программы форматирования не смогут их правильно обработать. (See Info file `info', node `Top', для получения подробной информации о нодах в Info.)

Обычно сразу после строки @node вы будете писать строку с одной из команд описания структуры глав -- например, строку @section или @subsection. (See section Типы команд описания структуры.)

Пожалуйста, обратите внимание: Команды обновления в режиме Texinfo для GNU Emacs работают только с такими Texinfo-файлами, в которых после строк @node написаны строки описания структуры глав. See section Требования для обновления.

TeX использует строки @node для определения имен перекрестных ссылок. Поэтому вы должны писать строки @node в Texinfo-файле, предназначенном для форматирования для печати, даже если вы не намереваетесь форматировать его для Info. (Перекрестные ссылки, такие как в конце этого предложения, создаются командой @xref и родственными с ней командами; смотрите section Перекрестные ссылки.)

Выбор имен нод и указателей

Имя ноды служит для ее идентификации. Указатели позволяют вам достичь других нод и состоят из имен этих нод.

Как правило, указатель `Up' содержит имя ноды, в меню которой упомянута данная нода. Указатель `Next' содержит имя ноды, следующей после данной в этом меню, а указатель `Previous' -- имя ноды, написанной в меню перед данной. Когда ноды `Previous' и `Up' совпадают, оба указателя ссылаются на одну ноду.

Обычно первой нодой Texinfo-файла является нода `Top', а ее указатели `Up' и `Previous' ссылаются на файл `dir', который содержит главное меню для всей системы Info.

Сама нода `Top' содержит главное или мастер-меню руководства. Также в ноду `Top' полезно включить краткое описание этого руководства. See section Первая нода, чтобы узнать, как писать первую ноду Texinfo-файла.

Даже если вы явно записываете все указатели, это не означает, что вы можете писать ноды в исходном Texinfo-файле в произвольном порядке! Так как TeX обрабатывает файл последовательно, не обращая внимания на указатели на ноды, вы должны писать ноды в том порядке, в каком вы желаете их видеть в печатном выводе.

Как писать строку @node

Простейший способ написать строку @node -- написать в начале строки команду @node и затем имя ноды, как показано здесь:

@node имя-ноды

Если вы пользуетесь GNU Emacs, вы можете использовать для вставки имен указателей команды обновления ноды, предоставляемые режимом Texinfo; или вы можете не заботиться об указателях в Texinfo-файле и предоставить программе @command{makeinfo} вставить их в создаваемый ей Info-файл. (See section Использование режима Texinfo, и section Создание указателей с помощью @command{makeinfo}.)

Или вы можете вставить указатели `Next', `Previous' и `Up' сами. Если вы делаете так, вы можете счесть полезным использовать команду режима Texinfo C-c C-c n. Эта команда вставляет строку `@node' и строку комментария, перечисляющего имена указателей на ноды в нужном порядке. Такая строка комментария особенно полезна, если вы не совсем освоились с Texinfo.

Шаблон для полной формы строки ноды с указателями `Next', `Previous' и `Up' выглядит следующим образом:

@node имя-ноды, следующая, предыдущая, вверх

Если вы хотите, то можете вообще не писать строки @node в первом наброске и затем использовать команду texinfo-insert-node-lines, которая создаст их за вас. Однако мы не рекомендуем такую практику. Лучше давать ноде имя тогда же, когда вы пишите ее текст, чтобы вы могли легко создавать перекрестные ссылки. Большое число перекрестных ссылок --- это особенно важная отличительная черта хорошего Info-файла.

После того, как вы вставили строку @node, вы должны сразу написать @-команду для главы или раздела и вставить имя этой главы. Потом (и это важно!) напишите несколько вхождений для именных указателей. Обычно вы сможете найти по крайней мере два, а часто даже четыре или пять способов сослаться на ноду из именного указателя. Используйте их все. Это позволит людям намного легче найти данную ноду.

Советы по написанию строки @node

Вот три рекомендации:

Требования для строки @node

Вот несколько требований, предъявляемых к строкам @node:

Первая нода

Первой нодой Texinfo-файлой, за исключением включаемых файлов (see section Включаемые файлы), является нода Top. Первая нода содержит главное меню документа и его краткий обзор. (see section Обзор в ноде Top).

Первая нода (которая должна называться `top' или `Top') должна содержать в качестве указателя `Up' имя ноды в другом файле, в котором есть меню, ведущее к данному файлу. Имя файла пишется в круглых скобках. Если файл должен быть установлен непосредственно в файл-каталог Info, пишите в качестве родителя первой ноды `(dir)'; это сокращение для `(dir)top', указывающее на первую ноду в файле `dir', которая содержит главное меню для всей системы Info. Например, в этом руководстве строка @node Top выглядит так:

@node Top, Копирование, , (dir)

(Вы можете использовать команды обновления Texinfo или утилиту @command{makeinfo}, чтобы вставить эти указатели автоматически.)

Не делайте `(dir)' `Предыдущей' нодой первой ноды, так как это приводит к непонятному для пользователей поведению программы: если вы находитесь в первой ноде и нажимаете клавишу DEL, чтобы вернуться назад, вы перейдете к середине какого-то другого вхождения файла `dir', не имеющего никакого отношения к тому, что вы читали.

See section Установка Info-файла, для большей информации об установке Info-файла в каталог `info'.

Команда @top

Специальная команда @top была создана для использования со строкой @node Top. Команда @top сообщает программе @command{makeinfo}, что здесь помещена первая нода файла. Она предоставляет сведения, необходимые @command{makeinfo}, чтобы автоматически вставлять указатели на ноды. Пишите команду @top в начале строки сразу после строки @node Top. На оставшейся части той же строки напишите заглавие.

В Info команда @top выводит на отдельной строке заголовок и строку звездочек под ним.

В TeX и texinfo-format-buffer, команда @top -- это просто синоним команды @unnumbered. Обе эти форматирующие программы не требуют наличия команды @top и не делают для нее ничего особеного. Если вы пользуетесь этими программами форматирования, то можете использовать после строки @node Top команды @chapter или @unnumbered. Вы также можете писать @chapter или @unnumbered при использовании команд обновления Texinfo для создания или обновления указателей и меню.

Обзор в ноде Top

Вы можете помочь читателям, написав в первой ноде обзор, после строки @top и перед главным меню. В Info этот обзор появится непосредственно перед главным меню. В печатном руководстве этот обзор появится на отдельной странице.

Если вы не хотите, чтобы в печатном руководстве обзор выводился на отдельной странице, вы можете заключить всю первую ноду, включая строки @node Top и @top или другие команды для разделов, между командами @ifinfo и @end ifinfo. Это предотвратит появление всего этого текста в печатном выводе. (see section Условно видимый текст). Вы можете повторить краткое описание из первой ноды внутри блока @iftex ... @end iftex в начале первой главы, для тех, кто читает печатное руководство. Это сберегает бумагу и может выглядеть красивее.

В обзоре вы должны написать номер версии программы, к которой относится это руководство. Это поможет читателю проследить, какое руководство написано для какой версии программы. Если руководство меняется чаще, чем сама программа, или независимо от нее, вы также должны включить номер редакции для руководства. (Титульный лист тоже должен содержать эти сведения: смотрите section @titlepage.)

Создание указателей с помощью @command{makeinfo}

Программа @command{makeinfo} умеет автоматически определять указатели на ноды для иерархически организованных файлов.

Если вы пользуетесь этой возможностью, вам не нужно писать указатели `Next', `Previous' и `Up' после имени ноды. Однако, вы должны писать команды для задания структуры разделов, такие как @chapter или @section, на строке, идущей сразу после укороченной строки @node (можно лишь написать строку комментария).

Кроме того, после строки @node в ноде `Top' вы должны написать строку, начинающуюся командой @top, чтобы обозначить первую ноду файла. See section @top.

Наконец, вы должны написать имя каждой ноды (кроме ноды `Top') в меню одним или несколькими иерархическими уровнями выше, чем уровень данной ноды.

Эта способность @command{makeinfo} вставлять указатели на ноды освобождает вас от необходимости создания и обновления меню и указателей вручную или с помощью команд режима Texinfo. (See section Обновление нод и меню.)

@anchor: Определение произвольных назначений для ссылок

Маркер -- это позиция в вашем документе, помеченная так, что на нее могут указывать перекрестные ссылки, в точности так же, как на ноды. Вы можете создать маркер, написав команду @anchor и задав ему метку в виде обычного аргумента в фигурных скобках. Например:

Это @anchor{х-место}место помечено.
...
@xref{х-место,,место}.

дает:

Это место помечено.
...
Смотрите [место], страница 1.

Как вы видите, команда @anchor сама не дает вывода. В этом примере определен маркер `х-место' непосредственно перед словом `место'. Вы можете сослаться на него позже с помощью команды @xref или другой команды для перекрестных ссылок, как показано. See section Перекрестные ссылки, подробности о командах для создания перекрестных ссылок.

Лучше всего помещать команды @anchor непосредственно перед позицией, на которую вы хотите сослаться; тогда при переходе к маркеру взгляд читателя будет перенесен к нужному фрагменту текста. Вы можете помещать команду @anchor на отдельной строке, если это послужит облегчению чтения исходного текста. Пробелы после команды @anchor всегда игнорируются.

Имена маркеров и нод не должны конфликтовать. Иногда маркеры и ноды имеют схожее значение; например, в самостоятельной программе Info, команда goto-node принимает в качестве аргумента как имя ноды, так и имя маркера. (See section `goto-node' in GNU Info.)


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