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


Создание и установка Info-файлов

Эта глава рассказывает, как создать и установить Info-файлы. See section Info-файлы, для получения общих сведений о самом формате этих файлов.

Создание Info-файла

makeinfo -- это программа, преобразующая Texinfo-файл в Info-файл, файл на HTML, или простой текст.

texinfo-format-region и texinfo-format-buffer -- это функции GNU Emacs, преобразующие Texinfo в Info.

Информацию об установке Info-файла в систему Info смотрите в see section Установка Info-файла.

Преимущества makeinfo

Утилита makeinfo создает Info-файл из исходного Texinfo-файла быстрее любой форматирующей команды Emacs и предоставляет лучшие сообщения об ошибках. Мы рекомендуем применять ее. makeinfo --- это программа на Си, независимая от Emacs. Вы не должны запускать Emacs, чтобы использовать makeinfo, что означает, что вы можете использовать makeinfo на машинах, слишком маленьких, чтобы запустить Emacs. Вы можете запустить makeinfo любым из трех таких способов: из оболочки операционной системы, из оболочки внутри Emacs или напечатав команды C-c C-m C-r или C-c C-m C-b в режиме Texinfo в Emacs.

Команды texinfo-format-region и texinfo-format-buffer полезны, если вы не можете запустить makeinfo. Кроме того, при некоторых обстоятельствах они форматируют небольшие области или буферы быстрее, чем makeinfo.

Запуск makeinfo из оболочки

Чтобы создать Texinfo-файл из Info-файла, напечатайте makeinfo и имя Texinfo-файла. Таким образом, чтобы создать Info-файл для Bison, напечатайте в оболочке следующее:

makeinfo bison.texinfo

(Вы можете запустить оболочку в Emacs, напечатав M-x shell.)

Ключи для makeinfo

Команда makeinfo принимает несколько ключей. Чаще всего ключи применяются для задания колонки заполнения и стиля сносок. Каждый ключ командной строки -- это слово с предшествующими символами `--' или буква с предшествующим `-'. Вы можете использовать сокращения для длинных ключей, если они однозначны.

Например, вы можете использовать следующую команду для создания из файла `bison.texinfo' такого Info-файла, в котором каждая строка заполнена на 68 колонок:

makeinfo --fill-column=68 bison.texinfo

Вы можете последовательно написать два ключа или более, например так:

makeinfo --no-split --fill-column=70 ...

Это сохранит Info-файл целиком в виде, возможно, очень большого файла и установит колонку заполнения равной 70.

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

@option{-D переменная}
Делает переменную определенной. Это эквивалентно @set переменная в Texinfo-файле (see section @set, @clear и @value).
@option{--commands-in-node-names}
Разрешает использование @-команд в именах нод. Это не рекомендуется, поскольку, вероятно, никогда не будет реализовано в TeX. Это также сильно замедляет работу @command{makeinfo}. Кроме того, этот ключ игнорируется, если использован @option{--no-validate}. See section Проверка указателей, для дальнейших подробностей.
@option{--error-limit=предел}
@option{-e предел}
Устанавливает наибольшее число ошибок, о которых сообщит makeinfo перед выходом (в предположении, что продолжать бесполезно); по умолчанию 100.
@option{--fill-column=ширина}
@option{-f ширина}
Устанавливает наибольшее число колонок в строке; это правый край строки. Заполнение абзацев происходит по этой ширине. (Заполнение -- это процесс разбиения и слияния строк таким образом, чтобы они имели длину, меньшую или равную числу, заданному в качестве колонки заполнения. Строки разбиваются между словами.) Значение по умолчанию равно 72. Игнорируется с `--html'.
@option{--footnote-style=стиль}
@option{-s стиль}
Устанавливает стиль сносок равным стилю, `end' для сносок в конце ноды (по умолчанию) или `separate' для отдельных сносок. Значение, заданное этим ключом, перекрывает установленное в Texinfo-файле командой @footnotestyle (see section Сноски). Когда стиль сносок установлен в значение `separate', makeinfo создает новую ноду для сносок, находящихся в текущей ноде. Когда стиль сносок установлен в значение `end', makeinfo помещает сноски в конце текущей ноды. Игнорируется `--html'.
@option{--force}
@option{-F}
Обычно, если входной файл содержит ошибки, выходные файлы не создаются. С этим ключом, они сохраняются.
@option{--help}
@option{-h}
Напечатать сообщение об использовании, перечисляющее все доступные ключи, и завершить выполнение успешно.
@option{--html}
Создавать вывод в формате HTML, а не Info. See section Создание HTML.
@option{-I каталог}
Добавить каталог в конец списка каталогов для поиска файлов, включаемых командой @include. По умолчанию, makeinfo производит поиск только в текущем каталоге. Если каталог не задан, добавляется каталог `.', то есть текущий. Заметьте, что каталог может на самом деле быть списком нескольких каталогов, разделенных обычным символом-разделителем путей (`:' в Unix, `;' в MS-DOS/MS-Windows).
@option{--macro-expand=файл}
@option{-E файл}
Вывести исходный Texinfo-файл, раскрыв все макросы, в заданный файл. Обычно результаты раскрытия макросов используются внутри makeinfo и затем отбрасываются. Этот ключ используется программой @command{texi2dvi}, если у вас установлена старая версия `texinfo.tex', которая не поддерживет @macro.
@option{--no-headers}
Для вывода в формате Info, не включать меню и строки нод и писать на стандартный вывод (если не задан ключ @option{--output}). Это дает в результате ASCII-файл, который вы не можете читать в Info, так как он не содержит необходимых нод и меню. Прежде всего, он нужен, чтобы извлечь определенные фрагменты руководства в отдельные файлы, включаемые в пакет, такие, как файлы `INSTALL'. При выводе в формате HTML, если также задан `--no-split', не включать ссылки для навигации в начало каждой ноды. See section Создание HTML.
@option{--no-split}
Пропустить стадию разбиения в работе makeinfo. По умолчанию, большие выходные файлы (размером более 70 тысяч байт) разбиваются на меньшие подфайлы. При выводе в формате Info, размер каждого примерно 50 тысяч байт. При выводе в формате HTML, каждый файл содержит одну ноду (see section Создание HTML).
@option{--no-pointer-validate}
@option{--no-validate}
Пропустить стадию проверки указателей в работе makeinfo. Это можно сделать также командой @novalidate (see section Используйте TeX). Обычно после обработки Texinfo-файла производятся некоторые проверки соответствия, чтобы убедиться, что перекрестные ссылки разрешаются и прочее. See section Проверка указателей.
@option{--no-warn}
Подавить вывод предупреждений (но не сообщений об ошибках). Вы можете захотеть этого, если созданный вами файл содержит примеры перекрестных ссылок Texinfo, и ссылаемые ноды на самом деле не существуют.
@option{--number-sections}
Выводить номера глав, разделов и приложений как в печатном руководстве.
@option{--no-number-footnotes}
Подавить автоматическую нумерацию сносок. По умолчанию makeinfo последовательно нумерует все сноски в одной ноде, сбрасывая номер сноски на 1 в начале каждой ноды.
@option{--output=файл}
@option{-o файл}
Указывает, что вывод должен быть направлен в файл, а не в файл, заданный командой @setfilename в исходном Texinfo-файле (see section @setfilename). Если файл равен `-', вывод идет в стандартный вывод и подразумевается `--no-split'. При выводе в формате HTML, файл -- это имя выходного файла для первой ноды (see section Создание HTML).
@option{-P каталог}
Добавить каталог в начало списка каталогов для поиска файлов, включаемых командой @include. Если каталог не задан, добавляется каталог `.', то есть текущий. Смотрите `-I' для получения деталей.
@option{--paragraph-indent=отступ}
@option{-p отступ}
Устанавливает стиль отступов в абзацах равным отступу. Значение, заданное этим ключом, перекрывает установленное в Texinfo-файле командой @paragraphindent (see section Отступ в начале абзаца). Значение отступа интерпретируется следующим образом:
`asis'
Сохранять существующие отступы в начале абзацев.
`0' или `none'
Удалять существующие отступы.
число
Делать в каждом абзаце отступы, равные заданному числу пробелов.
@option{--reference-limit=предел}
@option{-r предел}
Устанавливает число ссылок на ноду, которое makeinfo будет делать, не выдавая предупреждения. Если нода содержит больше ссылок, чем это число, makeinfo создаст эти ссылки, но также выдаст предупреждение. Значение по умолчанию равно 1000.
@option{-U переменная}
Делает переменную неопределенной. Это эквивалентно @clear переменная в Texinfo-файле (see section @set, @clear и @value).
@option{--verbose}
Заставляет makeinfo выводить сообщения о том, что она делает. Обычно makeinfo выводит сообщения, только если есть ошибки или предупреждения.
@option{--version}
@option{-V}
Напечатать номер версии и завершить выполнение успешно.

Проверка указателей

Если вы не подавили проверку указателей с помощью ключа `--no-validate' или команды @novalidate в исходном файле (see section Используйте TeX), makeinfo сделает проверку конечного Info-файла. Как правило это означает проверку того, что все ноды, на которые вы ссылались, на самом деле существуют. Вот полный список проверок:

  1. Если указатели на ноды `Next', `Previous' или `Up' являются ссылками на ноды в текущем файле, но не внешними ссылками, такими, как на `(dir)', то ссылаемая нода должна существовать.
  2. В каждой ноде, если нода `Previous' отлична от ноды `Up', то нода, на которую указывает поле `Previous', должна содержать в поле `Next' указатель обратно на эту ноду.
  3. Каждая нода, за исключением `Top', должна иметь указатель `Up'.
  4. Нода, на которую ссылается указатель `Up' должна сама ссылаться на текущую ноду через пункт меню, за исключением случаев, когда нода, на которую ссылается `Up' имеет форму `(файл)'.
  5. Если в ноде указатель `Next' не тот же, что и указатель `Next' ноды `Up', то нода, на которую ссылается `Next' должна иметь указатель `Previous', ссылающийся обратно на текущую ноду. Это правило позволяет последней ноде в разделе ссылаться на на первую ноду следующей главы.
  6. На каждую ноду, за исключением `Top', должна быть ссылка по крайней мере из одной другой ноды, или через указатели `Previous' или `Next', или через меню или перекрестную ссылку.

Некоторые документы Texinfo могут не пройти фазу проверки, потому что в них команды вроде @value и @definfoenclose использовались в определениях нод и в перекрестных ссылках непоследовательно. Рассмотрим следующий пример:

@set nodename Node 1

@node @value{nodename}, Node 2, Top, Top

Это нода 1.

@node Node 2, , Node 1, Top

Это нода 2.

Эдесь на ноду "Node 1" ссылаются как по точному имени, так и через @value.

По умолчанию @command{makeinfo} терпит в таких случаях неуспех, поскольку имена нод не раскрываются полностью, пока не будут записаны в выходной файл. Вы должны всегда стараться ссылаться на ноды последовательно; скажем, в примере выше во второй строка @node следует также использовать @value. Если однако, по какой-либо причине вы должны ссылаться на имена нод непоследовательно, и @command{makeinfo} не подтверждает правильность этого файла, вы можете использовать ключ @option{--commands-in-node-names}, чтобы принудить @command{makeinfo} производить ресурсоемкое раскрытие всех имен нод, которые она находит в документе. Это, однако, может заметно замедлить работу программы; для больших файлов, таких как the Jargon file, было зафиксировано двукратное увеличение времени преобразования.

Поддержка @-команд в директивах @node не обладает достаточной общностью, чтобы ей можно было свободно пользоваться. Например, если приведенный выше пример переопределит бы где-то в документе nodename, то makeinfo не сможет преобразовать ее, даже если вызвать с ключом @option{--commands-in-node-names}.

@option{--commands-in-node-names} не имеет действия, если задан ключ @option{--no-validate}.

Запуск makeinfo из Emacs

Вы можете запустить makeinfo из режима Texinfo в GNU Emacs, используя команду makeinfo-region или makeinfo-buffer. В режиме Texinfo, эти команды по умолчанию привязаны к C-c C-m C-r и C-c C-m C-b.

C-c C-m C-r
M-x makeinfo-region
Форматировать текущую область для Info.
C-c C-m C-b
M-x makeinfo-buffer
Форматировать текущий буфер для Info.

Когда вы вызываете makeinfo-region или makeinfo-buffer, Emacs запрашивает имя файла, предлагая по умолчанию имя текущего файла. Вы можете, если хотите, отредактировать в минибуфере имя файла по умолчанию, перед нажатием RET и началом процесса makeinfo.

Команды Emacs makeinfo-region и makeinfo-buffer запускают программу makeinfo во временном буфере оболочки. Если makeinfo находит ошибки, Emacs отображает сообщения об ошибках в этом временном буфере.

Вы можете произвести грамматический разбор сообщений об ошибках, напечатав C-x ` (next-error). Это заставляет Emacs перевести курсор на ту строку в исходном Texinfo-файле, которая, по мнению makeinfo вызывает ошибку. See section `Running make or Compilers Generally' in Руководство по GNU Emacs, для подробной информации об использовании команды next-error.

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

C-c C-m C-k
M-x makeinfo-kill-job
Уничтожить запущенный в данный момент процесс makeinfo, созданный makeinfo-region или makeinfo-buffer.
C-c C-m C-l
M-x makeinfo-recenter-output-buffer
Показать в буфере оболочки makeinfo самые последние строки вывода.

(Обратите внимание, аналогичные команды для уничтожения и центрирования процесса TeX -- это C-c C-t C-k и C-c C-t C-l. See section Форматирование и печать в режиме Texinfo.)

Вы можете задать ключи для makeinfo, установив переменную makeinfo-options с помощью команд M-x edit-options или M-x set-variable, или установив эту переменную в вашем файле инициализации `.emacs'.

Например, вы можете написать в вашем файле `.emacs' следующее:

(setq makeinfo-options
      "--paragraph-indent=0 --no-split
       --fill-column=70 --verbose")

Дальнейшую информацию смотрите в section Ключи для makeinfo, а также "Editing Variable Values," "Examining and Setting Variables," и "Init File" в Руководстве по GNU Emacs.

Команды texinfo-format...

В режиме Texinfo GNU Emacs вы можете отформатировать Texinfo-файл или его часть с помощью команды texinfo-format-region. Она форматирует текущую область и выводит форматированный текст во временный буфер, называемый `*Info Region*'.

Аналогично, вы можете отформатировать буфер с помощью команды texinfo-format-buffer. Она делает новый буфер и выводит в него Info-файл. Вызов C-x C-s сохранит этот Info-файл под именем, заданным строкой @setfilename, которая должна быть недалеко от начала Texinfo-файла.

C-c C-e C-r
texinfo-format-region
Форматировать текущую область для Info.
C-c C-e C-b
texinfo-format-buffer
Форматировать текущий буфер для Info.

Команды texinfo-format-region и texinfo-format-buffer обеспечивают некоторую проверку ошибок, а другие функции могут предоставить вам дальнейшую помощь в нахождении ошибок форматирования. Эти процедуры описаны в приложении; смотрите section Ошибки форматирования. Однако программа makeinfo часто работает быстрее и предоставляет лучшую проверку ошибок (see section Запуск makeinfo из Emacs).

Пакетное форматирование

Вы можете отформатировать Texinfo-файлы для Info, используя batch-texinfo-format и пакетный режим Emacs. Вы можете запустить Emacs в пакетном режиме из оболочки, в том числе из оболочки внутри Emacs. (See section `Command Line Switches and Arguments' in Руководство по GNU Emacs.)

Вот команда оболочки для форматирования всех файлов в текущем каталоге, оканчивающихся на `.texinfo':

emacs --batch --funcall batch-texinfo-format *.texinfo

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

Запускайте batch-texinfo-format только в пакетном режиме Emacs, как показано; эта команда не интерактивна. Она уничтожает Emacs после завершения.

batch-texinfo-format удобна, если у вас нет makeinfo, и вы хотите отформатировать несколько Texinfo-файлов одновременно. Когда вы используете пакетный режим, вы создаете новый процесс Emacs. Это высвобождает ваш текущий Emacs, так что вы можете продолжать в нем работать. (Когда вы запускаете texinfo-format-region или texinfo-format-buffer, вы не можете использовать Emacs ни для чего больше, пока команда не закончит работу.)

Создание тегов и разбиение файлов

Если Texinfo-файл содержит более 30000 байт, texinfo-format-buffer автоматически создает таблицу тегов для его Info-файла; makeinfo всегда создает таблицу тегов. С таблицей тегов Info может переходить к другим нодам быстрее, чем без нее.

Кроме того, если Texinfo-файл содержит более примерно 70000 байт, texinfo-format-buffer и makeinfo разбивают большой Info-файл на меньшие косвенные подфайлы примерно по 50000 байт в каждом. Большие файлы разбиваются на меньшие, чтобы Emacs не должен был делать большие буферы для хранения большого Info-файла целиком; вместо этого Emacs выделяет памяти чтобы как раз хватило для маленького, отсоединенного файла, нужного в данный момент. Таким способом Emacs избегает ненужной траты памяти, когда вы запускаете Info. (До того, как было реализовано разбиение, Info-файлы всегда делались короткими, а для создания единого, большого печатного руководства из меньших Info-файлов были разработаны включаемые файлы. See section Включаемые файлы, для подробной информации. Включаемые файлы до сих пор используются для очень больших документов, таких как The Emacs Lisp Reference Manual, в котором каждая глава -- это отдельный файл.)

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

Отсоединенные файлы имеют имена, образованные добавлением `-1', `-2', `-3' и так далее к имени файла, заданного командой @setfilename. Укороченная версия первоначального файла так же имеет имя, заданное @setfilename.

На одной стадии написания оригинала этого документа, к примеру, Info-файл был сохранен как `test-texinfo', и этот файл выглядел следующим образом:

Info file: test-texinfo,    -*-Text-*-
produced by texinfo-format-buffer
from file: new-texinfo-manual.texinfo

^_
Indirect:
test-texinfo-1: 102
test-texinfo-2: 50422
test-texinfo-3: 101300
^_^L
Tag table:
(Indirect)
Node: overview^?104
Node: info file^?1271
Node: printed manual^?4853
Node: conventions^?6855
...

(Но в `test-texinfo' было гораздо больше нод, чем показано здесь.) Каждый из отсоединенных, косвенных файлов, `test-texinfo-1', `test-texinfo-2' и `test-texinfo-3', перечислен в этом файле после строки, в которой написано `Indirect:'. Таблица тегов помещена после строки `Tag table:'.

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

Если вы используете для создания Info-файлов texinfo-format-buffer, вы, возможно, захотите запустить команду Info-validate. (Команда makeinfo сама по себе делает хорошие проверки, вам не нужно применять Info-validate.) Однако, вы не можете запустить команду проверки нод M-x Info-validate в косвенных файлах. Для получения информации о том, как предотвратить разбиение файла и как проверить структуру нод, смотрите section Запуск Info-validate.

Создание HTML

Как альтернативу обычному выводу в формате Info, вы можете использовать ключ `--html' для создания вывода в формате HTML для установки на Web-сайте (к примеру). В данном выпуске makeinfo производит монолитный HTML-файл; разбиение по главам или нодам не поддерживается. Мы надеемся в скором времени реализовать эту возможность.

Выходному HTML-файлу дается имя в соответствии с @setfilename, но расширение `.info' заменяется на `.html'.

Входной текст Texinfo, помеченный командой @ifhtml, будет давать вывод, только если задан ключ `--html'. Входной текст, помеченный @html, передается на выход буквально (с подавлением обычного преобразования входных символов `<', `>' и `&', имеющих особое значение в HTML).

Ключ `--footnote-style' на данный момент игнорируется при выводе HTML; для сносок делаются гиперсвязи на конец выходного файла.

Создаваемый HTML главным образом соответствует стандарту (то есть HTML 2.0, RFC1866). Исключение в том, что из команды @multitable создаются таблицы HTML 3.2, но так, чтобы они как можно лучше отображались броузерами без поддержки таблиц. Пожалуйста, сообщайте о выводе, полученном от makeinfo без сообщений об ошибок, но нарушающем HTML 3.2 DTD как об ошибке программы.

В начало нод, как при выводе в Info, вставляются панели навигации. Это можно предотвратить, используя ключ @option{--no-headers} вместе с @option{--no-split}. Элементы заголовка <link> могут поддерживать перемещение, как в Info, с броузерами, реализующими эту возможность HTML 1.0, такими как Lynx и Emacs W3. Все же вы обычно теряете возможность поиска регулярных выражений и вхождений именного указателя во многих файлах, предоставляемую программами чтения Info. Вместо этого, когда возможно, из команд Texinfo создаются гиперсвязи. Команды `@xref', ссылающиеся на другие документы, создаются в предположении, что они также доступны в форме HTML, и к имени Info-файла в `@xref' добавляется `.html'. Предположительно, часто это не будет работать.

Установка Info-файла

Info-файлы обычно хранятся в каталоге `info'. Вы можете читать Info-файлы с помощью отдельной программы Info или программой чтения, встроенной в Emacs. (See Info file `info', node `Top', введение в Info.)

Файл-каталог `dir'

Чтобы Info могла работать, в каталоге `info' должен быть файл, служащий каталогом верхнего уровня системы Info. По соглашению, этот файл называется `dir'. (Вы можете узнать местоположение этого файла, нажав в Emacs C-h i, чтобы войти в Info, и затем C-x C-f, чтобы увидеть полный путь к каталогу `info'.)

Файл `dir' сам по себе является Info-файлом. В нем содержится меню верхнего уровня для всех Info-файлов в системе. Это меню выглядит следующим образом:

* Menu:

* Info:    (info).     Система просмотра документации.
* Emacs:   (emacs).    Расширяемый, самодокументированный
                       текстовый редактор.
* Texinfo: (texinfo).  Создание печатного руководства с
                       помощью TeX или Info-файла из
                       одного исходного файла.
...

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

Таким образом, пункт `Info' указывает на первую ноду файла `info', а пункт `Emacs' -- на первую ноду файла `emacs'.

В каждом Info-файле, указатель `Вверх' (`Up') первой ноды ссылается на файл dir. Например, строка первой ноды руководства по Emacs выглядит в Info так:

File: emacs  Node: Top, Up: (DIR), Next: Distrib

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

Включение нового Info-файла

Чтобы включить новый Info-файл в систему, вы должны написать пункт меню и добавить его в файл `dir' в каталоге `info'. Например, если вы добавляете документацию для GDB, вам следует написать такой новый пункт:

* GDB: (gdb).           Отладчик C на уровне исходного кода.

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

Имя Info-файла обычно имеет расширение `.info'. Значит, Info-файл для GDB мог бы называться `gdb' или `gdb.info'. Программы чтения Info автоматически пробуют имена файлов и с расширением `.info'(12), и без него; поэтому лучше избегать написания лишнего текста и не писать в пункте меню `.info' явно. Например, в пункте меню GDB в качестве имени файла нужно использовать `gdb', а не `gdb.info'.

Info-файлы в других каталогах

Если Info-файл не находится в каталоге `info', есть три способа указать его местоположение:

  1. Написать полный путь в файле `dir' во второй части пункта меню.
  2. Если вы пользуетесь Emacs, включить имя файла во второй файл `dir' в его каталоге; и потом добавить имя этого каталога в переменную Info-directory-list в вашем собственном или локальном для вашей машины файле инициализации. Эта переменная сообщает Emacs где искать файлы `dir' (эти файлы должны обязательно называться `dir'). Emacs объединяет файлы с именем `dir' из каждого из перечисленных каталогов. (В Emacs версии 18, вы можете записать в переменную Info-directory имя только одного каталога.)
  3. Указать имя каталога Info в переменной среды @env{INFOPATH} в вашем файле инициализации `.profile' или `.cshrc'. (Info-файлы, чье местоположение задается таким способом, сможете найти только вы и те, кто так же установил эту переменную.)

Например, чтобы достичь тестового файла в каталоге `/home/bob/info/', вы можете добавить подобный пункт в меню стандартного файла `dir':

* Тест: (/home/bob/info/info-test).  Тестовый файл Боба.

В данном случае абсолютное имя файла `info-test' написано в качестве второй части пункта меню.

Или вы можете написать такую команду в вашем файле `.emacs':

(require 'info)
(setq Info-directory-list
      (cons (expand-file-name "/home/bob/info") Info-directory-list))

Она велит Emacs объединить файл `dir' из каталога `/home/bob/info' с системным файлом `dir'. Info перечислит файл `/home/bob/info/info-test' как пункт меню файла `/home/bob/info/dir'. Emacs производит объединение, только когда M-x info запущена первый раз, так что если вы хотите установить Info-directory-list в сессии Emacs, где вы уже запускали info, вы должны выполнить (setq Info-dir-contents nil), чтобы принудить Emacs заново составить файл `dir'.

И наконец, вы можете сообщить Info путь поиска, установив переменную среды @env{INFOPATH} в файле инициализации вашей оболочки, таком как `.cshrc', `.profile' или `autoexec.bat'. Если вы пользуетесь оболочкой, совместимой с Bourne shell, такой как sh или bash, вам нужно установить переменную среды @env{INFOPATH} в файле инициализации `.profile'; но если вы пользуетесь csh или tcsh, вы должны установить эту переменную в файле `.cshrc'. В системах MS-DOS/MS-Windows, вы должны установить @env{INFOPATH} в вашем файле `autoexec.bat' или в Реестре. Каждый тип командного интерпретатора используют различный синтаксис.

Как обычно, `.' обозначает текущий каталог. Emacs использует переменную среды @env{INFOPATH} для инициализации значения переменной Emacs Info-directory-list. Самостоятельная программа чтения Info сливает все файлы, называемые `dir', во всех каталогах, перечисленных в переменной среды @env{INFOPATH}, в одно меню, представляемое вам в ноде, называемой `(dir)Top'.

Какое бы значение вы не установили для @env{INFOPATH}, если его последним символом является двоеточие(14), оно замещается путем по умолчанию (задаваемым при компиляции). Это дает вам возможность дополнять путь по умолчанию, избавляя вас от необходимости перечислять все стандартные каталоги. Например (с использованием синтаксиса sh):

INFOPATH=/local/info:
export INFOPATH

приводит к поиску сначала в `/local/info', а потом в стандартных каталогах. Двойные двоеточия или двоеточия в начале не рассматриваются особо.

Когда вы создаете свой собственный файл `dir' для использования с Info-directory-list или @env{INFOPATH}, проще всего начать с копирования существующего файла `dir' и замены всего текста после `* Menu:' вашими желаемыми пунктами. При таком способе сохранится пунктуация и специальные символы CTRL-_, которые необходимы для Info.

Установка файлов-каталогов Info

При установке в вашу систему Info-файла, вы можете использовать программу install-info для обновления файла-каталога Info `dir'. Обычно install-info запускается make-файлом пакета сразу после копирования Info-файла в подходящее для установки место.

Чтобы Info-файл мог работать с install-info, вы должны использовать команды @dircategory и @direntry в исходном Texinfo-файле. Используйте @direntry...@end direntry для задания пунктов меню, добавляемых в файл-каталог Info, и @dircategory для задания той части каталога Info, в который их следует поместить. Вот как эти команды используются в данном руководстве:

@dircategory Система документации Texinfo
@direntry
* Texinfo: (texinfo).           Формат документации GNU.
* install-info: (texinfo)Вызов install-info. ...
...
@end direntry

Это дает в Info-файле следующее:

INFO-DIR-SECTION Система документации Texinfo
START-INFO-DIR-ENTRY
* Texinfo: (texinfo).           Формат документации GNU.
* install-info: (texinfo)Вызов install-info. ...
...
END-INFO-DIR-ENTRY

Программа install-info видит эти строки в Info-файле и так узнает, что нужно делать.

Всегда пишите команды @direntry и @dircategory недалеко от начала Texinfo-файла, до первой команды @node. Если вы напишете их после, install-info не заметит их.

Если вы используете @dircategory в исходном Texinfo-файле более одного раза, каждое применение задает `текущую' категорию; все последующие команды @direntry будут добавлять новый пункт к этой категории.

Вот несколько рекомендуемых категорий @dircategory: `GNU packages', `GNU programming tools', `GNU programming documentation', `GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual utilities'. Идея состоит в том, чтобы включать ноду `вызов' для каждой устанавливаемой пакетом программы в категории `Individual utilities', а вхождение для руководства целиком -- в другой подходящей категории.

Вызов install-info

Программа install-info вставляет вхождения меню из Info-файла в файл `dir', каталог верхнего уровня системы Info (объяснения, как работает файл `dir', смотрите в предыдущих разделах). Чаще всего она запускается в процессе установки программного обеспечения или при составлении каталога всех руководств в системе. Обзор использования:

install-info [ключ]... [info-файл [dir-файл]]

Если не заданы info-файл или dir-файл, то должны быть заданы ключи (описанные ниже), определяющие их. Для них нет значений по умолчанию, определяемых на стадии компиляции, и стандартный ввод не используется. install-info за один запуск может считать только один info-файл и записать один dir-файл.

Если dir-файл (будучи задан) не существует, install-info создает его, если возможно (без вхождений).

Если какой-нибудь входной файл сжат с помощью gzip (see section `Invoking gzip' in Gzip), install-info автоматически распаковывает его для чтения. А если сжат dir-файл, install-info также автоматически оставляет его сжатым после записи всех изменений. Если не существует сам dir-файл, install-info пытается открыть `dir-file.gz'.

Ключи:

--delete
Удалить из dir-файла вхождения для info-файла. Имя файла во вхождениях в dir-файле должно совпадать с info-файлом (за исключением допустимого суффикса `.info' в любом из них). Не вставлять новых вхождений.
--dir-file=имя
-d имя
Задает имя файла-каталога Info. Это эквивалентно использованию аргумента dir-файл.
--entry=текст
-e текст
Вставить текст в качестве вхождения в каталог Info; текст должен иметь вид пункта меню Info плюс одна или более дополнительных строк, начинающихся с пробельных символов. Если вы зададите более одного вхождения, все они будут добавлены. Если вы не зададите вхождений, они будут определены из самого Info-файла.
--help
-h
Показать сообщение об использовании, перечисляющее основные способы использования и все доступные ключи, и завершить выполнение успешно.
--info-file=файл
-i файл
Задает Info-файл, который нужно установить в каталог. Это эквивалентно использованию аргумента info-файл.
--info-dir=кат
-D кат
Задает каталог с файлом `dir'. Эквивалентно `--dir-file=dir/dir'.
--item=текст
Синоним `--entry=текст'. Вхождение в каталог Info на самом деле является пунктом меню.
--quiet
Подавить вывод предупреждений.
--remove
-r
Синоним `--delete'.
--section=разд
-s разд
Поместить вхождения этого файла в раздел разд каталога. Если вы зададите более одного раздела, все вхождения будут добавлены в каждый из разделов. Если вы не зададите разделов, они будут определены из самого info-файла.
--version
-V
Показать информацию о версии и завершить выполнение успешно.


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