Ensinando LaTeX para o Emacs

Este post faz parte de uma série de textos sobre LaTeX e sobre a ideia de tratar documentos como código. Ao longo dos anos, acabei montando um workflow para escrever documentos técnicos, artigos, relatórios e apresentações baseado em LaTeX, Emacs, latexmk e Git, e esta série é basicamente uma tentativa de organizar e documentar esse processo.

A ideia não é ensinar LaTeX do zero, mas sim discutir o ambiente de trabalho ao redor dele: editores, compilação automática, organização de projetos, templates e versionamento. Cada post da série aborda uma parte desse sistema.

Introdução

No último post, criamos uma configuração inicial para o Emacs, que pega o comportamento padrão dele e deixa um pouco mais próximo das nossas necessidades. Modularizamos a configuração, ajustamos o funcionamento do sistema de pacotes, configuramos a interface de usuário e acertamos detalhes nesse nível. Agora, as configurações que fizermos serão módulos adicionais que vamos ativando dentro do init.el, conforme formos construindo o esquema todo. No futuro, caso surja mais alguma configuração que queiramos, podemos só adicionar outro módulo. Isso vai deixar essa configuração mais fácil de navegar e gerenciar.

Nosso objetivo nesta série é montar um fluxo de trabalho para LaTeX, centrado no Emacs. Vamos usá-lo para editar, revisar, compilar, visualizar o PDF, e controlar as mudanças feitas ao texto. Neste post, vamos cuidar da parte mais importante disso tudo: a configuração do Emacs especificamente para arquivos LaTeX.

O Gerente Regional: AUCTeX

O AUCTeX é um pacote que estende o Emacs com suporte avançado a TeX e LaTeX. Mais do que isso, ele transforma o editor em um ambiente que entende a estrutura do documento — comandos, ambientes, arquivos incluídos, referências e o próprio fluxo de compilação.

Um pouco de história

Não seria um post meu se eu não entrasse nessa tangente: um pouco de história.

O AUCTeX surgiu no início dos anos 90, a partir de um conjunto de macros criadas por estudantes da Universidade de Aalborg, na Dinamarca. Essas macros eram reunidas em um pacote chamado tex-mode.el, que eventualmente foi renomeado e passou a se chamar AUCTeX. “AUC” veio originalmente de “Aalborg University Center”, mas eventualmente foi rebatizado como “Advanced Unified Comprehensive”.

É possível argumentar que, tendo sido desenvolvido desde meados dos anos 1980, o AUCTeX foi pioneiro na implementação de ferramentas de produtividade que viriam a ser consideradas essenciais em qualquer IDE que valha alguma coisa. Ele implementa desde coisas mais simples como macros de entrada e “snippets” para ambientes, equações, comandos de seção e assim por diante, até coisas mais complexas como visualização de equações diretamente no editor, visualização do resultado final (com correlação via SyncTeX), auto-completar para referências e citações, navegação pela estrutura (pular para a próxima seção, por exemplo), e assim por diante.

O que vamos cobrir aqui está longe de ser toda a capacidade do AUCTeX; eu recomendo fortemente uma leitura do manual para ver quais habilidades dele se encaixam com o seu estilo de escrita.

Configurando o AUCTeX

Começamos assim:

(use-package tex
  :ensure auctex
  :defer t

Esse início faz algumas tarefas básicas:

• Carrega o pacote tex, que é o núcleo de tudo (ele faz parte do AUCTeX).
• O uso de use-package, juntamente com a opção :ensure auctex, organiza a declaração do pacote e garante que o auctex está instalado.
• A opção :defer t faz com que o AUCTeX não seja carregado imediatamente, mas só quando for necessário. Assim, se formos editar algum arquivo que não tem nada a ver com LaTeX, ele não vai gastar tempo no carregamento nem ocupar espaço na memória.

Ganchos

O passo seguinte é definir “ganchos”, isto é, gatilhos que fazem o Emacs realizar alguma coisa quando uma condição é satisfeita:

:hook ((LaTeX-mode . LaTeX-math-mode)
       (LaTeX-mode . turn-on-reftex)
       (LaTeX-mode . visual-line-mode)
       (LaTeX-mode . outline-minor-mode)
       (LaTeX-mode . TeX-source-correlate-mode)
       (LaTeX-mode . (lambda ()
		       (setq-local TeX-command-default "LatexMk"))))

Esses ganchos estão todos vinculados ao LaTeX-mode, isto é, quando o Emacs identifica que estamos abrindo um arquivo LaTeX, ele executa essas instruções para configurar o ambiente. Vamos a elas:

• LaTeX-math-mode: Esse modo facilita a inserção de comandos matemáticos. Como documentos em LaTeX frequentemente envolvem fórmulas e símbolos, faz sentido ativá-lo por padrão.
• turn-on-reftex: Ativa o RefTeX junto com o AUCTeX. Isso é importante porque os dois se complementam: o AUCTeX entende a estrutura geral do documento, enquanto o RefTeX cuida das conexões internas, como referências e citações (vamos mexer com a configuração do RefTeX mais adiante).
• visual-line-mode: Esse modo faz quebra visual de linha sem inserir quebras reais no arquivo. Para texto corrido, isso é muito mais confortável do que trabalhar com linhas longas escapando horizontalmente pela tela.
• outline-minor-mode: Ativa uma forma leve de navegação estrutural, permitindo expandir, recolher e percorrer seções do documento.
• TeX-source-correlate-mode: Ativa o mecanismo de correlação entre o código-fonte e o PDF, que será usado pelo SyncTeX (também vamos ver isso mais adiante).
• TeX-command-default "LatexMk": O AUCTeX é bem capaz de se virar para decidir se precisa rodar alguma parte do “toolkit” para processar o documento: latex, xelatex, biber e assim por diante. Mas, em vez disso, vamos deixar que o LaTeXMk tome conta disso. Configurando o LatexMk adequadamente, podemos deixar que ele decida quantas vezes e quais comandos rodar para atingir o PDF final. O AUCTeX não tem esse nível de controle, e de fato hoje em dia ele espera que isso seja feito pelo LatexMk. Podemos então cuidar dessa configuração separadamente, mantendo a lógica pesada fora do editor e concentrada no .latexmkrc, onde ela pode ser mantida de forma mais limpa.

Comportamento do pacote

Agora, configuramos algumas opções do pacote:

:config
(setq TeX-auto-save t
      TeX-parse-self t
      TeX-save-query nil
      TeX-PDF-mode t
      TeX-engine 'xetex
      TeX-source-correlate-mode t
      TeX-source-correlate-method 'synctex
      TeX-source-correlate-start-server t)

• TeX-auto-save t e TeX-parse-self t: Essas duas opções são muito importantes. Elas fazem o AUCTeX analisar o documento e salvar informações sobre ele. É isso que permite ao Emacs conhecer labels, ambientes, seções, macros e outros elementos estruturais.
• TeX-save-query nil: Essa opção evita que o Emacs fique perguntando toda hora se deve salvar antes de compilar. Em um workflow real, isso só atrapalha.
• TeX-PDF-mode t: Indica que o objetivo da compilação é gerar PDF, e não formatos mais antigos como DVI.
• TeX-engine 'xetex: Aqui definimos o motor tipográfico padrão como XeTeX. Isso combina com um workflow moderno, baseado em Unicode e em fontes do sistema.

Em seguida, acionamos o modo de correlação (linhas 7 a 9 do bloco acima). Esses comandos montam a estrutura do SyncTeX para que seja possível relacionar partes do código com partes do PDF; assim, podemos clicar numa parte do PDF e ir direto para a parte do .tex que gera aquilo, ou selecionar uma parte do fonte e visualizar o resultado no PDF.

Visualização de PDF

Já que falamos do SyncTeX, aproveitamos e configuramos a visualização de PDF:

(setq TeX-view-program-selection '((output-pdf "PDF Tools")))
(setq TeX-view-program-list '(("PDF Tools" TeX-pdf-tools-sync-view)))

(add-hook 'TeX-after-compilation-finished-functions
          #'TeX-revert-document-buffer)

A configuração de PDF na verdade está em outro módulo; mas como esta parte tem a ver com o AUCTeX, deixamos ela aqui. Configuramos duas opções:

• Se o output é um PDF, usar o pdf-tools;
• Ativar a opção de sincronização do PDF Tools (outro motivo para essas opções estarem aqui, já que a configuração do modo de correlação está neste módulo também).

Também adicionamos mais um gancho: quando a compilação terminar de rodar, atualizamos o PDF que estiver aberto na visualização. Assim o resultado já aparece sozinho, e não precisamos ficar recarregando o arquivo toda vez (quando estamos montando algumas coisas em LaTeX isso pode ficar bem cansativo).

Documento mestre e sub-arquivos

Aqui só temos uma linha de configuração:

(setq-default TeX-master nil)

Em projetos pequenos isso não faz tanta diferença. Mas, quando o documento começa a ficar grande o suficiente para que cada parte dele fique em um arquivo diferente (por exemplo, dividir um relatório entre intro.tex, metodo.tex, resultados.tex e conclusao.tex), é importante saber qual é o arquivo principal, isto é, aquele que contém o preâmbulo, bem como os comandos para incluir todas essas partes. Definindo essa variável como nil, forçamos o AUCTeX a perguntar qual é o arquivo principal. Assim, quando fazemos alguma alteração e mandamos a compilação rodar, ele já sabe o que fazer em vez de tentar compilar o arquivo errado e acabar encontrando um monte de erros.

Chamando o LatexMk

Finalmente, vamos configurar o comando a ser usado na hora da compilação. Já definimos, lá em cima, que esse comando se chama “LatexMk”, mas por padrão o Emacs não sabe do que se trata. Então, vamos dizer a ele:

(add-to-list 'TeX-command-list
             '("LatexMk"
               "latexmk -cd %s"
               TeX-run-TeX nil t
               :help "Run latexmk, following .latexmkrc"))

Essa linha adiciona um comando à “lista” chamada TeX-command-list, chamado “LatexMk”, que roda a linha:

latexmk -cd %s

A opção -cd faz com que o latexmk rode no diretório-raiz do projeto, o que é bastante útil especialmente quando temos vários sub-arquivos (que podem estar em sub-diretórios). No lugar de %s, o Emacs/AUCTeX passa para o comando o nome do documento mestre.

Autocompletar no AUCTeX

Por último, vamos finalizar a configuração do AUCTeX chamando outro pacote:

(use-package company-auctex
  :after (company tex)
  :config
  (company-auctex-init))

O company-mode é a forma de autocompletar usada no Emacs. Ele fornece as ferramentas para que tenhamos sugestões para completar enquanto digitamos (ele é o que o IntelliSense gostaria de ser). Ele busca entre as palavras usadas no texto para sugerir complementos em vários lugares, mas ele também tem módulos para sugerir palavras específicas de diversas linguagens – inclusive o LaTeX.

O que estamos fazendo nessa parte da configuração é garantir que tanto o company quanto o tex (o pacote principal do AUCTeX) estejam carregados. Daí, ele carrega o módulo company-auctex, que tem justamente os padrões de complemento para LaTeX. Ao ser inicializado, ele se integra ao AUCTeX e começa a oferecer sugestões conforme vamos escrevendo.

O Assistente (do) Gerente Regional: RefTeX

Mais história

O RefTeX é relativamente mais novo que o AUCTeX. Ele surgiu para responder a um problema que fugia do domínio do AUCTeX: gerenciar referências, rótulos e citações. O AUCTeX lida com esse tipo de coisa, mas não gerencia; e, em documentos mais longos, começa a ficar complicado lidar com isso pois o número de itens começa a ficar muito grande. Por isso, fica difícil lembrar como referenciar cada item que precisamos ao longo do texto.

O RefTeX também começou como uma extensão e, com o tempo, se tornou parte integral de distribuições padrão do Emacs. Essas duas ferramentas são o “núcleo duro” da abordagem do Emacs para LaTeX. Isso porque a ideia dele não é substituir o AUCTeX, mas sim se integrar a ele. O AUCTeX cuida da estrutura do documento, enquanto o RefTeX usa essa estrutura para facilitar o uso de referências.

Configuração

A configuração do RefTeX é bem simples, já que não tem muito segredo aqui:

;; Configuração do RefTeX
(use-package reftex
  :defer t
  :hook (LaTeX-mode . turn-on-reftex)
  :config
  (setq reftex-plug-into-AUCTeX t
        reftex-save-parse-info t
        reftex-cite-prompt-optional-args t)

  ;; Formatos de citação para BibLaTeX
  (setq reftex-cite-format
        '((?c . "\\cite{%l}")
          (?p . "\\parencite{%l}")
          (?t . "\\textcite{%l}")
          (?f . "\\footcite{%l}")
          (?s . "\\supercite{%l}")
          (?a . "\\autocite{%l}"))))

Começamos carregando o pacote, com use-package, quando necessário. Também o vinculamos com um gancho no LaTeX-mode, para o Emacs saber quando carregar o pacote.

Definindo a variável reftex-plug-into-AUCTeX, acionamos a integração do RefTeX com o AUCTeX. Por extensão, ele também vai alimentar o company, através do AUCTeX, que faz esse meio de campo. Essa integração também nos proporciona navegação pelo documento, gerenciamento de referências, além do contexto das sugestões.

reftex-save-parse-info instrui o RefTeX a salvar as informações de parsing do documento, facilitando o carregamento nas próximas vezes que carregarmos esse arquivo. Assim ele não precisa ficar refazendo o trabalho toda vez e o sistema todo fica mais ágil.

Finalmente, a opção reftex-cite-prompt-optional-args habilita que o Emacs peça ao usuário informações adicionais sobre citações, como números de páginas, prefixos e sufixos.

Formatos de citação

Finalmente, onde o RefTeX brilha: citações. Vamos usar BibLaTeX e Biber, e pra isso precisamos “ensinar” o RefTeX a criar os diferentes tipos de citação. É isso que fazemos da linha 10 em diante: criamos os atalhos para os diferentes tipos de citação que o RefTeX é capaz de criar.

O papel do RefTex

Enquanto o AUCTeX fornece a estrutura do documento, o RefTeX contribui com a camada de inteligência para conexões do texto:

• Referências cruzadas
• Etiquetas
• Citações
• Navegação pelo texto

E como todos esses pacotes conversam entre si, eles trabalham em conjunto, oferecendo uma experiência consistente para a edição do documento.

O Workflow

Neste momento, temos nossa primeira versão de um ambiente bem arrumado para composição de documentos em LaTeX. Isso permite que montemos uma sequência ações que vão compor o fluxo de trabalho no qual vamos fazer isso.

Abrir o documento

Você abre um arquivo .tex, e o Emacs entra automaticamente em LaTeX-mode.

A partir desse momento, várias coisas já estão ativas sem nenhuma ação adicional:

• AUCTeX entende a estrutura do documento;
• RefTeX está pronto para lidar com referências e citações;
• autocompletar contextual está disponível;
• navegação por seções está habilitada;
• SyncTeX já está preparado para sincronizar com o PDF.

Nada disso precisa ser ativado manualmente — o ambiente já está configurado para esse contexto.

Escrever

Ao escrever o documento, o editor passa a oferecer suporte constante, mas discreto:

• comandos LaTeX são sugeridos automaticamente;
• ambientes podem ser inseridos com ajuda do AUCTeX;
• símbolos matemáticos ficam mais acessíveis;
• o texto é exibido com quebra visual adequada (visual-line-mode);
• a estrutura do documento pode ser explorada via outline-minor-mode.

O importante aqui é que o editor não “briga” com o texto. Ele ajuda, mas não atrapalha.

Referenciar e citar

Quando entram labels, referências e citações, o RefTeX assume um papel central.

Em vez de lembrar nomes de labels ou chaves de bibliografia, você passa a selecionar:

• labels existentes no documento;
• entradas do arquivo .bib;
• formato de citação adequado ao contexto.

Isso reduz bastante o atrito ao escrever e praticamente elimina erros de digitação nesse tipo de coisa.

Compilar

Na hora de compilar, o fluxo é simples:

• o AUCTeX aciona o comando padrão (LatexMk);
• o latexmk executa a lógica de build definida no .latexmkrc;
• dependências, bibliografia e recompilações são resolvidas automaticamente.

O Emacs não precisa saber como compilar — ele apenas dispara o processo correto.

Essa separação é uma das decisões mais importantes do workflow.

Ver o resultado

Depois da compilação:

• o PDF é aberto (ou já está aberto) dentro do Emacs;
• o buffer é atualizado automaticamente;
• a sincronização entre código e PDF está disponível.

Com o SyncTeX, podemos:

• ir do código para o ponto correspondente no PDF;
• clicar no PDF e voltar para o trecho correspondente no .tex.

Isso fecha o ciclo de escrita e revisão.

Conclusão

Agora temos o Emacs com uma configuração inicial que o transforma em um ambiente que já é otimizado para LaTeX.

Com o AUCTeX, o editor passa a entender a estrutura do documento. Com o RefTeX, ele entende as conexões internas — referências, citações e navegação. Com o company-mode e o company-auctex, o processo de escrita se torna mais fluido e menos repetitivo. E, com a integração com latexmk e pdf-tools, o ciclo completo de edição, compilação e visualização acontece dentro de um único ambiente.

A ideia é que possamos permanecer dentro do mesmo ambiente durante todo o processo, isto é, o ciclo de escrita do documento acontece completamente dentro do Emacs. Assim não é necessário ficar alternando as janelas, indo para o prompt para compilar o LaTeX, depois abrir um visualizador de PDF, procurar “na raça” o que queremos ajustar no fonte, e seguir nesse ciclo, alternando entre diferentes programas, o que gera mais desgaste. Temos um ambiente consistente que deixa o processo todo mais conveniente, e por evitar essa alternância de interfaces, facilita na manutenção do foco – um bônus preciosíssimo pra cérebros com canais dopaminérgicos deficientes.

No próximo post, passamos ao complemento externo que trabalha por trás da cortina para que esse ciclo seja, de fato, constante: a configuração do LatexMk.