Перейти к содержимому
Topos Uranos
Русский

Компиляция и исправление ошибок

Краткое содержание

Этот урок учит уверенно компилировать документ и исправлять то, что не получается. В нём объясняется, что компиляция выполняется за несколько проходов, почему перекрёстным ссылкам и оглавлению нужен второй проход и как latexmk сам повторяет проходы, в Texmaker и в терминале. Урок учит читать журнал компиляции: где он находится, как читается ошибка со строкой, начинающейся с восклицательного знака, с номером строки и с контекстом, разрезанным надвое, и чем ошибка отличается от предупреждения и от сообщения о переполненном боксе. Разбираются самые частые ошибки с их настоящими сообщениями, режимы взаимодействия движка и стратегия отладки: сначала прочитать первую ошибку, делить исходный текст пополам, свести задачу к минимальному примеру, удалить вспомогательные файлы и поискать текст сообщения. В конце рассматриваются предупреждения, на которые стоит обращать внимание.

Цели обучения

  1. Объяснять, почему документу с перекрёстными ссылками или оглавлением нужно больше одного прохода, и компилировать его с помощью latexmk.
  2. Читать ошибку в журнале и находить её сообщение, строку, в которой движок её обнаружил, и точное место в этой строке.
  3. Узнавать самые частые ошибки по их сообщению и связывать каждую с её вероятными причинами.
  4. Находить настоящую причину ошибки, когда она не в указанной строке, читая сначала первую ошибку и деля исходный текст пополам.
  5. Отличать предупреждения, требующие исправления, от тех, которые можно не учитывать.

Что делает компиляция

Движок читает исходный текст только один раз, от начала до конца, и вёрстает каждую страницу по мере продвижения. У такого однократного чтения есть следствие: когда на второй странице встречается ссылка на пятый раздел или когда оглавление на первой странице должно перечислить разделы, которые ещё не прочитаны, движок ещё не может знать, какой номер или какая страница им соответствует. Решение LaTeX состоит в том, чтобы работать в несколько проходов. На каждом проходе он записывает в файл .aux номер и страницу каждой метки (тех, что ставятся командой \label), а в файл .toc заголовки разделов; на следующем проходе он в начале читает эти файлы и использует записанное. Отсюда следует, что при первой компиляции ссылки выглядят как два вопросительных знака, а оглавление выходит пустым, и что достаточно скомпилировать ещё раз, чтобы всё заполнилось. Если изменение сдвигает номера, может понадобиться третий проход; библиография, как будет показано в посвящённом ей разделе курса, добавляет между проходами ещё одну программу, Biber.

Считать проходы вручную утомительно, и легко что-нибудь забыть. Для этого существует latexmk, программа, входящая в дистрибутивы: она запускает движок, изучает журнал и вспомогательные файлы и повторяет проходы или вызывает Biber, пока ничего не перестанет меняться. Её ключ -lualatex указывает использовать LuaLaTeX, а ключ -c удаляет вспомогательные файлы, сохраняя PDF.

Примерlatexmk в терминале

Первая команда компилирует thesis.tex движком LuaLaTeX столько раз, сколько нужно; вторая удаляет вспомогательные файлы.

Терминал
$ latexmk -lualatex thesis.tex$ latexmk -c thesis.tex

В Texmaker одна из предопределённых последовательностей быстрой сборки использует latexmk (LatexMk + View PDF); в списке команд окна настроек команду latexmk заменяют на latexmk -lualatex -synctex=1 -interaction=nonstopmode %.tex, чтобы она использовала LuaLaTeX и сохраняла синхронизацию с PDF.