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


Перекрестные ссылки

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

Часто, хоть и не всегда, печатный документ нужно разрабатывать так, чтобы его можно было читать последовательно. Людей утомляет пролистывать вперед и назад, чтобы найти информацию, которая должна быть предоставлена им по мере необходимости.

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

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

В Info, перекрестная ссылка выражается в виде вхождения, по которому вы можете перейти с помощью команды Info `f'. (See Info file `@external{info', node `Help-Adv'}.)

Различные команды, работающие с перекрестными ссылками, используют ноды (или маркеры, see section @anchor: Определение произвольных назначений для ссылок) для определения позиции, на которую указывает ссылка. Это очевидно в Info, где перекрестная ссылка переносит вас к указанной позиции. TeX также использует ноды для определения назначения перекрестной ссылки, но его действия не столь очевидны. Когда TeX генерирует DVI-файл, он записывает номер страницы каждой ноды и использует эти номера при создании перекрестных ссылок. Таким образом, если вы пишете руководство, предназначенное только для печати, и которое не будет использоваться интерактивно, вы тем не менее должны писать строки @node для указания мест, на которые вы будете делать перекрестные ссылки.

Различные команды для перекрестных ссылок

Существует четыре команды для перекрестных ссылок:

@xref
Используется для начала предложения в печатном руководстве, говорящего `Смотрите ...', или перекрестной ссылки Info, говорящей `*Note имя: нода.'.
@ref
Используется внутри или, чаще, в конце предложения; то же, что и @xref для Info; в печатном руководстве дает только перекрестную ссылку без предшествующего слова `Смотрите'.
@pxref
Используется внутри круглых скобок для создания ссылки, подходящей и для Info-файла, и для печатной книги. В печатном руководстве начинается со слова `смотрите' со строчной буквы. (`p' означает `parenthesis', то есть `круглые скобки'.)
@inforef
Используется для создания ссылки на Info-файл, для которого нет печатного руководства.

(Команда @cite используется для создания ссылок на книги и руководства, для которых нет соответствующего Info-файла, и, следовательно, нет ноды, на которую можно сослаться. See section @cite{ссылка}.)

Части перекрестных ссылок

Команда, создающая перекрестную ссылку, требует только один аргумент, имя ноды, на которую указывает ссылка. Но эта команда может содержать до четырех дополнительных аргументов. Используя эти аргументы, вы можете предоставить имя ссылки для Info, описание темы или название раздела для печатного вывода или название другого печатного руководства.

Вот простой пример перекрестной ссылки:

@xref{имя ноды}.

что дает

*Note Имя ноды::.

и

Смотрите Раздел nnn [имя ноды], стр. ppp.

Вот пример полной перекрестной ссылки из пяти частей:

@xref{имя ноды, имя перекрестной ссылки, тема, имя-Info-файла,
печатное руководство}, для подробной информации.

что дает

*Note имя перекрестной ссылки: (имя-Info-файла)имя ноды,
для подробной информации.

в Info и

Смотрите раздел "тема" в печатном руководстве, для подробной информации.

в печатной книге.

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

  1. Имя ноды или маркера (обязательно). Это позиция, к которой вас переносит перекрестная ссылка. В печатном документе, позиция ноды предоставляет ссылку на страницу только в пределах того же документа.
  2. Имя перекрестной ссылки для Info, если оно должно отличаться от имени ноды. Если вы включаете этот аргумент, он становится первой частью перекрестной ссылки. Обычно его опускают.
  3. Описание темы или название раздела. Часто это заголовок раздела. Он используется в качестве имени ссылки в печатном руководстве. Если этот аргумент опущен, используется имя ноды.
  4. Имя Info-файла, на который указывает ссылка, если он отличен от текущего файла. Вам не нужно включать в имя файла какие-либо суффиксы `.info', так как программы чтения Info попытаются добавить его автоматически.
  5. Название печатного руководства из другого Texinfo-файла.

Шаблон полной перекрестной ссылки с пять аргументами выглядит так:

@xref{имя-ноды, имя-перекрестной-ссылки,
тема-или-раздел, имя-info-файла,
название-печатного-руководства}.

Перекрестные ссылки с одним, двумя, четырьмя и пятью аргументами описаны отдельно после @xref.

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

Вы можете написать в абзаце команду, создающую перекрестную ссылку, но помните, как Info и TeX форматируют вывод каждой из них: пишите @xref в начале предложения; пишите @pxref только внутри круглых скобок и так далее.

Команда @xref

Команда @xref создает перекрестную ссылку в начале предложения. Команды форматирования для Info преобразуют ее в перекрестную ссылку Info, которую может использовать команда Info `f' для перенесения вас непосредственно к другой ноде. Команды набора TeX превращают ее в ссылку на страницу или на другую книгу или руководство.

Чаще всего перекрестная ссылка Info выглядит так:

*Note имя-ноды::.

или так

*Note имя-перекрестной-ссылки: имя-ноды.

В TeX перекрестная ссылка выглядит так:

Смотрите раздел номер-раздела [имя-ноды], стр. страница.

или так

Смотрите раздел номер-раздела [название-или-тема], стр. страница.

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

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

@xref должна ссылаться на ноду Info по имени. Используйте @node для определения ноды (see section Как писать строку @node).

После @xref идут несколько аргументов в фигурных скобках, разделенные запятыми. Пробельные символы перед запятыми и после них игнорируются.

Перекрестная ссылка требует только имя ноды; но она может содержать до четырех дополнительных аргументов. Каждый из этих вариантов производит перекрестные ссылки, выглядящие несколько по-разному.

Пожалуйста, обратите внимание: запятые разделяют аргументы в перекрестной ссылке; избегайте включения их в названия разделов или другие части, чтобы программы форматирования не приняли их за разделители.

@xref с одним аргументом

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

Например,

@xref{Тропические бури}.

дает

*Note Тропические бури::.

и

Смотрите раздел 3.1 [Тропические бури], стр. 24.

(Заметьте, что в этом примере после закрывающей фигурной скобки стоит точка.)

Вы можете написать после перекрестной ссылки дополняющую фразу, как здесь:

@xref{Тропические бури}, для подробной информации.

что дает

*Note Тропические бури::, для подробной информации.

и

Смотрите раздел 3.1 [Тропические бури], стр. 24, для подробной информации.

(Заметьте, что в этом примере после закрывающей фигурной скобки написана запятая, а после дополняющей фразы стоит точка.)

@xref с двумя аргументами

Если заданы два аргумента, второй используется как имя перекрестной ссылки в Info, тогда как первый так же является именем ноды, на которую указывает эта ссылка.

Шаблон выглядит так:

@xref{имя-ноды, имя-перекрестной-ссылки}.

Например,

@xref{Электрические эффекты, Молния}.

дает:

*Note Молния: Электрические эффекты.

и

Смотрите раздел 5.2 [Электрические эффекты], стр. 57.

(Заметьте, что в этом примере после закрывающей фигурной скобки стоит точка, и что печатается имя ноды, а не имя перекрестной ссылки.)

Вы можете написать после перекрестной ссылки дополняющую фразу, как здесь:

@xref{Электрические эффекты, Молния}, для подробной информации.

что дает

*Note Молния: Электрические эффекты, для подробной информации.

и

Смотрите раздел 5.2 [Электрические эффекты], стр. 57, для подробной информации.

(Заметьте, что в этом примере после закрывающей фигурной скобки написана запятая, а после дополняющей фразы стоит точка.)

@xref с тремя аргументами

Третий аргумент замещает имя ноды в выводе TeX. Третий аргумент должен быть названием раздела в печатном выводе или объявлять тему, обсуждаемую в этом разделе. Часто вам стоит писать название с заглавной буквы, чтобы его было легче читать напечатанным. Используйте третий аргумент, когда имя ноды не подходит по синтаксису или по смыслу.

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

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

Шаблон выглядит так:

@xref{имя-ноды, имя-перекрестной-ссылки,
название-или-тема}.

Например,

@xref{Электрические эффекты, Молния, Гром и молния},
для деталей.

дает

*Note Молния: Электрические эффекты, для деталей.

и

Смотрите раздел 5.2 [Гром и молния], стр. 57, для деталей.

Если третий аргумент задан, а второй пуст, то третий служит и для того, и для другого. (Заметьте, как две последовательные запятые помечают пустой второй аргумент.)

@xref{Электрические эффекты, , Гром и молния}, для деталей.

дает

*Note Гром и молния: Электрические эффекты, для деталей.

и

Смотрите раздел 5.2 [Гром и молния], стр. 57, для деталей.

Фактически, часто лучше всего писать перекрестные ссылки лишь с одним аргументом, если имя ноды и название раздела совпадают, или с первым и третьим аргументами, если имя ноды и название раздела различны.

Вот несколько примеров из The GNU Awk User's Guide:

@xref{Sample Program}.
@xref{Glossary}.
@xref{Case-sensitivity, ,Case-sensitivity in Matching}.
@xref{Close Output, , Closing Output Files and Pipes},
   for more information.
@xref{Regexp, , Regular Expressions as Patterns}.

@xref с четырьмя и пятью аргументами

Четвертый аргумент в перекрестной ссылке задает имя другого Info-файла, отличного от файла, где появляется ссылка, а пятый аргумент задает название для печатного руководства.

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

Шаблон таков:

@xref{имя-ноды, имя-перекрестной-ссылки,
название-или-тема, имя-info-файла,
название-печатного-руководства}.

Например,

@xref{Электрические эффекты, Молния, Гром и молния, погода,
Введение в метеорологию}, для деталей.

дает

*Note Молния: (погода)Электрические эффекты, для деталей.

Имя Info-файла заключается в круглые скобки и предшествует имени ноды.

В печатном руководстве эта ссылка выглядит так:

Смотрите раздел "Гром и молния" в книге Введение в метеорологию, для деталей.

Название печатного руководства набирается курсивом; в ссылке нет номера страницы, так как TeX не может знать, на какую страницу она указывает, если это ссылка на другое руководство.

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

Шаблон выглядит так:

@xref{имя-ноды, , название-или-тема, имя-info-файла,
название-печатного-руководства}, для деталей.

что дает

*Note название-или-тема: (имя-info-файла)имя-ноды,
для деталей.

и

Смотрите раздел название-или-тема в книге название-печатного-руководства, для деталей.

Например,

@xref{Электрические эффекты, , Гром и молния,
погода, Введение в метеорологию}, для деталей.

дает

*Note Гром и молния: (погода)Электрические эффекты,
для деталей.

и

Смотрите раздел "Гром и молния" в книге Введение в метеорологию, для деталей.

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

Именование ноды Top

В перекрестной ссылке вы всегда должны называть ноду. Это значит, что для ссылки на все руководство вы должны обозначить ноду `Top', написав ее в качестве первого аргумента команды @xref. (Это отличается от способа, которым вы пишите пункты меню; смотрите section Ссылки на другие Info-файлы.) В то же время, чтобы предоставить осмысленную тему или название для перекрестной ссылки (вместо слова `Top'), вы должны написать подходящий третий аргумент для команды @xref.

Таким образом, чтобы создать перекрестную ссылку на Руководство по GNU Make, напишите:

@xref{Top, , Обзор, make, Руководство по GNU Make}.

что дает

*Note Обзор: (make)Top.

и

Смотрите раздел "Обзор" в книге Руководство по GNU Make.

`Top' в этом примере является именем первой ноды, а `Обзор' --- названием первого раздела этого руководства.

@ref

@ref практически та же команда, что и @xref, за исключением того, что она не пишет `смотрите' в печатном выводе, а пишет только саму ссылку. Поэтому она удобна в последней части предложения.

Например,

Для получения большей информации смотрите @ref{Ураганы}.

дает

Для получения большей информации смотрите *Note Ураганы::.

и

Для получения большей информации смотрите раздел 8.2 [Ураганы], стр. 123.

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

Например,

Морские волны описаны в @ref{Ураганы}.

дает

Морские волны описаны в разделе 6.7 [Ураганы], стр. 72.

в печатном документе, и следующее в Info:

Морские волны описаны в *Note Ураганы::.

Осторожно: Вы должны ставить точку, запятую или правую круглую скобку сразу после команды @ref с двумя или более аргументами. Иначе Info не найдет конец перекрестной ссылки и попытка перейти по ссылке завершится неуспехом. В качестве общего правила, вы должны писать точку или запятую после каждой команды @ref. Это смотрится лучше всего как в печатном выводе, так и в Info.

@pxref

Команда для перекрестных ссылок в круглых скобках, @pxref, почти эквивалентна @xref, но вы можете использовать ее только внутри круглых скобок, и вы не ставите запятую или точку после закрывающей фигурной скобки команды. Эта команда отличается от @xref с двух сторон:

  1. TeX набирает ссылку для печатного руководства со словом `смотрите' со строчной буквы, а не с заглавной.
  2. Команды форматирования Info автоматически завершают ссылку двоеточием или точкой.

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

@pxref разработана так, чтобы вывод выглядел правильно как в напечатанном виде, так и в Info-файле. В печатном руководстве после перекрестной ссылки в круглых скобках не должна стоять запятая или точка; такая пунктуация неправильна. Но в Info-файле, после перекрестной ссылки должна идти подходящая пунктуация, чтобы Info могла распознать конец ссылки. @pxref избавляет вас от необходимости использования сложных методов поставить ограничитель в одной форме и не ставить в другой.

С одним аргументом, перекрестная ссылка в круглых скобках выглядит так:

... бури причиняют наводнения (@pxref{Ураганы}) ...

что дает

... бури причиняют наводнения (*Note Ураганы::) ...

и

... бури причиняют наводнения (смотрите раздел 6.7 [Ураганы], стр. 72) ...

С двумя аргументами, перекрестная ссылка в круглых скобках выглядит так:

... (@pxref{имя-ноды, имя-перекрестной-ссылки})
...

что дает

... (*Note имя-перекрестной-ссылки: имя-ноды.) ...

и

... (смотрите раздел nnn [имя-ноды], стр. ppp) ...

@pxref можно передать до пяти аргументов, в точности, как и @xref (see section Команда @xref).

Пожалуйста, обратите внимание: Используйте @pxref только для перекрестных ссылок в круглых скобках. Не пытайтесь использовать @pxref в качестве дополнения в предложении. Это будет смотреться плохо либо в Info-файле, либо в печатном выводе, либо и там, и там.

Также, перекрестные ссылки в круглых скобках смотрятся лучше всего в конце предложения. Хотя вы можете написать их в середине предложения, такое расположение нарушит течение текста.

@inforef

@inforef используется для перекрестных ссылок на Info-файлы, для которых нет печатных руководств. Даже в печатном руководстве @inforef создает ссылку, направляющую пользователя к Info-файлу.

Эта команда принимает два или три аргумента в следующем порядке:

  1. Имя ноды.
  2. Имя перекрестной ссылки (необязательно).
  3. Имя Info-файла.

Разделяйте аргументы запятыми, как и в @xref. Также, вы должны завершить ссылку запятой или точкой после `}', как вы делаете для @xref.

Шаблон таков:

@inforef{имя-ноды, имя-перекрестной-ссылки,
имя-info-файла},

Таким образом,

@inforef{Эксперт, Продвинутые команды Info, info},
для дальнейшей информации.

дает

*Note Продвинутые команды Info: (info)Эксперт,
для дальнейшей информации.

и

Смотрите Info-файл `info', нода `Эксперт', для дальнейшей информации.

Аналогично,

@inforef{Эксперт, , info}, для дальнейшей информации.

дает

*Note (info)Эксперт::, для дальнейшей информации.

и

Смотрите Info-файл `info', нода `Эксперт', для дальнейшей информации.

Обратной к @inforef является команда @cite, которая используется для ссылки на печатное произведение, не существующее в форме Info. See section @cite{ссылка}.

@uref{url[, отображаемый-текст]}

@uref производит ссылку на унифицированный указатель ресурса (url). Она принимает один обязательный аргумент, собственно url, и два необязательных, которые определяют отображаемый текст. При выводе в HTML @uref создает ссылку, по которой можно проследовать.

Второй аргумент, если он задан, -- это отображаемый текст (по умолчанию это сам url); при выводе в Info или DVI показывается также и url.

С другой стороны, третий аргумент, если он задан, -- это тоже отображаемый текст, но тогда url не выводится в любом формате. Это полезно, если текст сам по себе дает хорошую ссылку, как в man-странице. Если задан третий аргумент, то второй игнорируется.

Вот простая форма с одним аргументом, где url является и назначением, и текстом ссылки:

Официальный ftp-сайт GNU --- это @uref{ftp://ftp.gnu.org/gnu}.

дает:

Официальный ftp-сайт GNU --- это ftp://ftp.gnu.org/gnu.

Вот пример формы с двумя аргументами:

Официальный
@uref{ftp://ftp.gnu.org/pub/gnu, ftp-сайт GNU}
содержит программы и тексты.

дает

Официальный ftp-сайт GNU содержит
программы и тексты.

то есть, в Info это выглядит так:

Официальный ftp-сайт GNU (ftp://ftp.gnu.org/gnu) содержит
программы и тексты.

а в HTML так:

Официальный <a href="ftp://ftp.gnu.org/gnu">ftp-сайт GNU</a>
содержит программы и тексты.

Пример формы с третьим аргументом:

Программа @uref{http://example.org/man.cgi/1/ls,,ls(1)} ...

дает это:

Программа http://example.org/man.cgi/1/ls ...

и в HTML:

Программа <a href="http://example.org/man.cgi/1/ls">ls(1)</a>  ...

Чтобы просто обозначить url, не создавая ссылки, по которой можно перейти, используйте команду @url (see section @url{унифицированный-указатель-ресурса}).

Некоторые предпочитают писать url в недвусмысленном формате:

<URL:http://машина/путь>

Если хотите, вы можете использовать такую форму во входном файле. Мы не считаем необходимым загромождать вывод дополнительными `<URL:' и `>', так как все программы, пытающиеся обнаруживать url в тексте, должны находить их без `<URL:', если они хотят быть полезными.


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