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


Ошибки форматирования

Помимо ошибок в содержимом документации, вы можете допустить в Texinfo еще два вида ошибок: ошибки в @-командах и ошибки в структуре нод и глав.

В Emacs есть два способа для нахождения ошибок в @-командах и два для ошибок в структуре.

Для нахождения ошибок в @-командах вы можете запустить TeX или команду форматирования области в той области, где возникла проблема; на самом деле вы можете запускать эти команды для каждой области по мере написания.

Для нахождения ошибок в структуре нод или глав, вы можете использовать команду C-c C-s (texinfo-show-structure) и другие команды пакета occur, а также команду M-x Info-validate.

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

Если есть возможность, применяйте команды обновления для создания и вставки указателей и меню. Они предотвращают появление многих ошибок. Потом используйте makeinfo (или ее проявления в режиме Texinfo, makeinfo-region и makeinfo-buffer) для форматирования вашего файла и проверки наличия других ошибок. Это наилучший способ работы с Texinfo. Однако, если вы не можете использовать makeinfo, или ваши ошибки слишком загадочны, вы можете применить инструменты, описанные в данном приложении.

Поиск ошибок при форматировании для Info

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

Но вероятнее всего вы читаете этот раздел, потому что по какой-либо причине не можете использовать команду makeinfo-region; поэтому в дальнейшем полагается, что вы пользуетесь командой texinfo-format-region.

Если вы допустили ошибку в @-команде, texinfo-format-region останавливается на этом месте или после него и выводит сообщение об ошибке. Чтобы увидеть, в каком месте буфера допущена ошибка, переключитесь в буфер `*Info Region*'; курсор будет находиться в позиции после места ошибки. Кроме того, текст после того места, где допущена (или, точнее, была обнаружена) ошибка, не будет отформатирован.

Например, если вы случайно завершите меню командой @end menus с `s' в конце, вместо @end menu, вы увидите сообщение об ошибке, говорящее:

@end menus is not handled by texinfo

Курсор остановится в той точке буфера, где допущена ошибка или немного после. Буфер будет выглядеть так:

---------- Buffer: *Info Region* ----------
* Menu:

* Using texinfo-show-structure::  How to use
                                  `texinfo-show-structure'
                                  to catch mistakes.
* Running Info-Validate::         How to check for
                                  unreferenced nodes.
@end menus
-!-
---------- Buffer: *Info Region* ----------

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

(@xref{Поиск ошибок, для подробной информации.)

В этом случае texinfo-format-region находит, что пропущена закрывающая фигурная скобка, но выводит сообщение, сообщающее о несбалансированных круглых, а не фигурных скобках. Это происходит, потому что форматирующая команда ищет непарные фигурные скобки, как если бы они были круглыми.

Иногда texinfo-format-region не может обнаружить ошибку. Например, во фрагменте ниже, закрывающая фигурная скобка поменялась местами с закрывающей круглой скобкой:

(@xref{Поиск ошибок), для подробной информации.}

Форматирование дает:

(*Note для подробной информации.: Поиск ошибок)

Единственный способ заметить эту ошибку -- понять, что ссылка должна выглядеть так:

(*Note Поиск ошибок::, для подробной информации.)

Кстати, если вы читаете эту ноду в Info и введете f RET (Info-follow-reference), то получите такое сообщение об ошибке:

Невозможно найти ноду: "Поиск ошибок) Единственный ...

Это происходит, потому что Info воспринимает пример с ошибкой как первую перекрестную ссылку в этой ноде, и, если вы нажмете RET сразу после ввода команды Info f, попытается перейти к указанной ноде. Если вы введете f catch TAB RET, Info завершит имя ноды правильно написанного примера и перенесет вас к ноде `Поиск ошибок'. (Если вы попробуете так сделать, вы сможете вернуться из ноды `Поиск ошибок', нажав l (Info-last).)

Поиск ошибок при форматировании с TeX

Вы также можете найти ошибки при форматировании с помощью TeX.

Как правило, вам стоит сделать это после того, как вы прогнали texinfo-format-buffer (или лучше makeinfo-buffer) на том же файле, потому что иногда texinfo-format-buffer выводит более полезные сообщения об ошибках, чем TeX. (See section Поиск ошибок при форматировании для Info, для подробной информации.)

Например, TeX был запущен для Texinfo-файла, часть которого приведена здесь:

---------- Buffer: texinfo.texi ----------
name of the Texinfo file as an extension.  The
@samp{??} are `wildcards' that cause the shell to
substitute all the raw index files.  (@xref{sorting
indices, for more information about sorting
indices.)@refill
---------- Buffer: texinfo.texi ----------

(В перекрестной ссылке нет закрывающей фигурной скобки.) TeX выдает следующий вывод и останавливается:

---------- Buffer: *tex-shell* ----------
Runaway argument?
{sorting indices, for more information about sorting
indices.) @refill @ETC.
! Paragraph ended before @xref was complete.
<to be read again>
                   @par
l.27

?
---------- Buffer: *tex-shell* ----------

В данном случае TeX выдает точное и понятное сообщение об ошибке:

Абзац закончился до завершения @xref.

`@par' -- это внутренняя команда TeX, не относящаяся к Texinfo. `l.27' означает, что TeX обнаружил ошибку в строке 27 Texinfo-файла. `?' служит приглашением для ввода, которое TeX использует в таких случаях.

К сожалению, сообщения TeX не всегда настолько полезны, и вам нужно быть по-настоящему Шерлоком Холмсом, чтобы понять, что за неприятность произошла.

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

  1. Вы можете сказать TeX продолжать выполнение и игнорировать эту ошибку, введя в ответ на приглашение `?' символ RET.
  2. Вы можете сказать TeX продолжать выполнение и игнорировать все ошибки, насколько возможно, введя в ответ на приглашение `?' символы r RET. Часто это лучшее, что можно сделать. Однако, помните: одна ошибка может привести к каскаду дополнительных сообщений об ошибках, так как ее последствия сказываются до конца файла. Чтобы остановить TeX, когда он выводит такую лавину сообщений об ошибках, нажмите C-c (или C-c C-c, если вы запустили оболочку из Emacs).
  3. Вы можете сказать TeX остановить работу, введя в ответ на приглашение `?' символы x RET.

Если вы запускаете TeX из Emacs, вы должны переключиться в буфер оболочки и перейти к строке, в которой TeX печатает `?' в качестве приглашения для ввода.

Иногда TeX может отформатировать файл, не выдавая сообщений об ошибках, даже если ошибки есть. Обычно это случается, если команда не была завершена, но TeX смог продолжить обработку. Например, если вы не завершите простой перечень командой @end itemize, TeX запишет DVI-файл, который вы сможете распечатать. Единственным сообщением об ошибке, которое выведет TeX, будет несколько загадочный комментарий

(@end occurred inside a group at level 1)
(команда @end встречена внутри группы на уровне 1)

Однако, если вы распечатаете DVI-файл, то обнаружите, что во всем тексте файла после перечня сделан отступ, как будто этот текст является частью последнего пункта перечня. Этим сообщением об ошибке TeX хотел сказать, что ожидал найти команду @end где-нибудь в файле; но он не может определить, где она действительно была нужна.

Другой источник пресловутых труднонаходимых ошибок -- это пропущенная команда @end group. Если вы когда-нибудь окажетесь поставленными в тупик непонятными ошибками, поищите первым делом пропущенные команды @end group.

Если в Texinfo-файле пропущены строки заголовка, TeX может остановиться в начале работы и вывести что-то похожее на приведенное ниже. Символ `*' означает, что TeX ждет ввода.

This is TeX, Version 3.14159 (Web2c 7.0)
(test.texinfo [1])
*

В таком случае просто напечатайте \end RET после звездочки. Потом напишите в Texinfo-файле строки заголовка и запустите TeX снова. (Обратите внимание, вы должны использовать обратную косую черту, `\'. TeX использует `\' вместо `@'; а при этих обстоятельствах вы работаете непосредственно с TeX, а не с Texinfo.)

Использование texinfo-show-structure

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

В GNU Emacs в режиме Texinfo, команда texinfo-show-structure перечисляет все строки, начинающиеся @-командами, определяющими структуру: @chapter, @section, @appendix и так далее. Если задан аргумент (C-u в качестве числового аргумента, при интерактивном вызове), эта команда показывает также строки @node. В режиме Texinfo команда texinfo-show-structure по умолчанию привязана к ключу C-c C-s.

Строки выводятся в буфер, называемый буфером `*Occur*', с отступами по уровню иерархии. Например, вот часть полученного при запуске texinfo-show-structure в данном руководстве:

 13 lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
 in buffer texinfo-06.texi.
    3:@chapter Ноды
   26:	 @heading Два способа
   59:	 @section Иллюстрация нод и меню
  167:	 @section Команда @code{@@node}
  222:	     @subheading Выбор имен нод и указателей
  245:	     @subsection Как писать строку @code{@@node}
  294:	     @subsection Советы по написанию строки @code{@@node}
  ...

Здесь написано, что строки 59, 222 и 245 файла `texinfo-06.texi' начинаются командами @section, @subheading и @subsection, соответственно. Если вы переместите курсор в окно `*Occur*', вы можете поместить курсор на одной из этих строк и перейти к соответствующему месту Texinfo-файла с помощью команды C-c C-c (occur-mode-goto-occurrence). See section `Using Occur' in Руководство по GNU Emacs, для получения подробной информации о команде occur-mode-goto-occurrence.

Первая строка в окне `*Occur*' описывает регулярное выражение, заданное в переменной texinfo-heading-pattern. Это регулярное выражение -- тот образец, по которому производит поиск команда texinfo-show-structure. See section `Using Regular Expressions' in Руководство по GNU Emacs, для получения подробной информации.

Когда вы вызываете команду texinfo-show-structure, Emacs отобразит структуру всего буфера. Если вы хотите посмотреть структуру только части буфера, например одной главы, используйте команду C-x n n (narrow-to-region) для пометки области. (See section `Narrowing' in Руководство по GNU Emacs.) Так был получен пример выше@transnote{При переводе руководство было разбито на несколько файлов по главам, поэтому не было необходимости использовать этот метод.}. (Чтобы снова увидеть весь буфер, используйте C-x n w (widen).)

Если вы вызовете texinfo-show-structure с числовым аргументом, напечатав C-u C-c C-s, будут перечислены строки, начинающиеся с @node, а так же строки, начинающиеся @-командами @chapter, @section и подобными.

Вы можете вспомнить структуру Texinfo-файла, взглянув на список в окне `*Occur*'; и если вы неправильно назвали ноду или пропустили раздел, то сможете исправить ошибку.

Использование occur

Иногда команда texinfo-show-structure выдает слишком много информации. Вероятно, вы хотите вспомнить общую структуру Texinfo-файла, и вам не нужен слишком детальный список, выдаваемый командой texinfo-show-structure. в таком случае вы можете непосредственно использовать команду occur. Для этого напечатайте

M-x occur

и затем в ответ на приглашение напечатайте регулярное выражение, образец для поиска. (See section `Regular Expressions' in Руководство по GNU Emacs.) Команда occur начинает работу от текущей позиции курсора до конца буфера. Если вы хотите запустить occur для буфера целиком, поместите курсор в начале буфера.

Например, чтобы увидеть все строки, содержащие слово `@chapter', просто напечатайте `@chapter'. Вы получите список всех глав. Также будут перечислены все предложения со словом `@chapter' в середине строки.

Если вы хотите увидеть только строки, начинающиеся словом `@chapter', напечатайте на запрос occur `^@chapter'. Если вы хотите увидеть все строки, заканчивающиеся определенным словом или фразой, завершите последнее слово символом `$', например `поиск ошибок$'. Это может быть полезно, если вы хотите увидеть все ноды, являющиеся частью одной и той же главы или раздела, и, следовательно, имеющие один и тот же указатель `Up'.

See section `Using Occur' in Руководство по GNU Emacs, для большей информации.

Поиск неправильных ссылок на ноды

Вы можете использовать команду Info-validate для проверки, ссылаются ли `Next', `Previous', `Up' или другие указатели на ноды. Эта команда проверяет, что каждый указатель ссылается на существующую ноду. Команда Info-validate работает только с Info-файлами, но не с Texinfo-файлами.

Программа makeinfo проверяет указатели автоматически, так что вам не придется применять команду Info-validate, если вы используете makeinfo. Вам понадобится применять Info-validate, если вы не можете запустить makeinfo и вместо этого должны создавать Info-файл, используя texinfo-format-region или texinfo-format-buffer, или если вы пишите Info-файл с нуля.

Запуск Info-validate

Чтобы использовать Info-validate, обратитесь к Info-файлу, который вы хотите проверить и напечатайте:

M-x Info-validate

Обратите внимание, в команде Info-validate должна стоять заглавная буква `I'. Вы также должны создать таблицу тегов перед запуском Info-validate. See section Создание тегов в файле.

Если файл написан правильно, вы получите сообщение "File appears valid". Однако, если есть указатель, ссылающийся на несуществующую ноду, в буфер `*problems in info file*' будет выведено сообщение об ошибке.

Например, Info-validate была запущена в тестовом файле, содержащем только первую ноду данного руководства. Одно из сообщений говорит:

In node "Обзор", invalid Next: Режим Texinfo

Это значит, что нода, называемая `Обзор', содержит указатель `Next', который ни на что не ссылается (что верно в данном случае, так как в этом тестовом файле есть только одна нода).

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

In node "Режим Texinfo", should have Previous: Обзор

Это происходит, потому что каждому указателю `Next' должен соответствовать указатель `Previous' (в ноде, на которую указывает `Next'), ссылающийся назад.

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

Info-validate требует наличия таблицы тегов и не работает с разбитыми файлами. (Команда texinfo-format-buffer автоматически разбивает большие файлы.) Чтобы использовать Info-validate с большим файлом, вы должны запустить texinfo-format-buffer с аргументом, чтобы она не разбивала Info-файл; и вы должны создать для этого неразбитого файла таблицу тегов.

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

Вы можете запустить Info-validate только для одного Info-файла, имеющего таблицу тегов. Эта команда не работает с косвенными подфайлами, созданными при разбиении главного файла. Если у вас есть большой файл (длиннее 70000 байт или около этого), вам нужно запускать команды texinfo-format-buffer или makeinfo-buffer таким образом, чтобы они не создавали косвенных подфайлов. Вам также нужно будет создать для Info-файла таблицу тегов. После того, как вы это сделали, вы можете запускать Info-validate и искать неправильные ссылки на ноды.

Первый шаг -- создание неразбитого Info-файла. Чтобы запретить texinfo-format-buffer разбивать Texinfo-файл на меньшие Info-файлы, задайте команде M-x texinfo-format-buffer аргумент:

C-u M-x texinfo-format-buffer

или, иначе

C-u C-c C-e C-b

Если вы сделаете так, Texinfo не будет разбивать файл и создавать для него таблицу тегов.

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

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

M-x Info-tagify

(Обратите внимание на заглавную букву `I' в Info-tagify.) Это создаст Info-файл с таблицей тегов, который вы сможете проверить.

Третий шаг -- проверить Info-файл:

M-x Info-validate

(Обратите внимание на заглавную букву `I' в Info-validate.) Кратко, шаги таковы:

C-u M-x texinfo-format-buffer
M-x Info-tagify
M-x Info-validate

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

Разбивание файла вручную

Вам стоит разбивать большие файлы или предоставлять командам texinfo-format-buffer или makeinfo-buffer делать это для вас автоматически. (Обычно вы будете предоставлять эту работу одной из команд форматирования. See section Создание Info-файла.)

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

Info-файлы разбиваются для экономии памяти. Работая с меньшими файлами, Emacs не должен создавать большие буферы для хранения информации.

Если в Info-файле более 30 нод, вам стоит также создать для него таблицу тегов. See section Запуск Info-validate, для получения информации о методе создания таблицы тегов. (Опять же, таблицы тегов обычно создаются автоматически командой форматирования; вам нужно создавать таблицу тегов самим, только если вы пишите файл вручную. Скорее всего, вам придется это делать для большого неразбитого файла, в котором вы хотите запустить Info-validate.)

Обратитесь к Info-файлу, который вы хотите разбить и снабдить таблицей тегов, и напечатайте две команды:

M-x Info-tagify
M-x Info-split

(Обратите внимание, буква `I' в `Info' -- заглавная.)

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

Главный файл продолжает работать в качестве Info-файла, но содержит лишь таблицу тегов и каталог подфайлов.


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