Compilação condicional e “comentários”

Embora o LaTeX (ou qualquer outro pacote derivado do TeX) não seja exatamente como um compilador, as pessoas regularmente querem fazer coisas de compilador com ele. As necessidades mais comuns são ‘compilação’ condicional e ‘comentários de bloco’, e vários meios específicos do LaTeX para esse fim estão disponíveis.

Os simples \newcommand{\gobble}[1]{} e \iffalse ... \fi não são satisfatórios (como uma solução geral) para comentários, uma vez que a matéria que está sendo pulada é, mesmo assim, lida pelo TeX, nem sempre como seria de se esperar. A leitura impõe restrições ao que você pode pular; isso pode não ser um problema no trabalho de hoje, mas poderia voltar para te morder amanhã. Para um exemplo de surpresas que podem vir a te morder, considere o seguinte exemplo (derivado de experiência real de usuário):

\iffalse % ignoring this bit
ignorando este trecho, considere o que acontece se nós \verb+\iftrue+ -- a surprise
\fi
O \iftrue é lido pelo TeX , fazendo com que ele ignore o comando \verb; então, o \iffalse não é terminado pelo \fi que vem a seguir. Além disso, \gobble é bastante ineficiente em consumir qualquer coisa não trivial, já que toda a matéria a ser ignorada é copiada para a pilha de argumentos antes de ser ignorada. Se sua exigência é para um documento do qual capítulos inteiros (ou coisa parecida) estão faltando, considere o sistema \include/\includeonly do LaTeX. Se você usar o ‘\include’ para incluir seus arquivos (em vez de \input  — veja O que está acontecendo em meus comandos \include?), o LaTeX grava macro traços do que está acontecendo no final de cada capítulo no arquivo aux ; usando o \includeonly, você pode dar ao LaTeX uma lista exaustiva dos arquivos necessários. Arquivos que não forem incluídos por \include são ignorados por inteiro, mas o processamento do documento continua como se eles estivessem lá, e os números de página, nota de rodapé e outros não são afetados. Observe que você pode escolher quais seções deseja incluir interativamente, usando o pacote askinclude.

Uma variante do mecanismo \includeonly é oferecido pelo pacote stampinclude , que tira proveito do comando \pdffilemoddate do PDFTeX. Quando um arquivo incluído por \include é processado em um documento LaTeX, um arquivo aux é criado para guardar dados como intervalos de números de páginas e numeração de capítulos/seções. Quando o \stampinclude é incluído em um documento, ele compara os tempos de modificação do sistema de arquivos de cada arquivo com seus aux correspondentes; o arquivo só é compilado “nessa corrida” do documento se ele for mais recente que o aux correspondente. O pacote requer um PDFTeX atual e também será executado em LuaTeX se o pacote pdftexcmds estiver disponível (o pdftexcmds emula os comandos PDFTeX necessários usando lua. Fora essa exigência, o stampinclude é um objeto de baixa manutenção; inclua-o em seu documento e ele, silenciosamente, fará o trabalho dele. Quando você quiser uma versão final do seu documento, exclua todos os arquivos aux, e o stampinclude não vai interferir.)

O inverso pode ser feito usando o pacote excludeonly : isso permite que você exclua (uma lista de) arquivos incluídos por \include de seu documento, por meio de um comando \excludeonly.

Se você quiser selecionar páginas específicas do seu documento, use o pacote pagesel , de Heiko Oberdiek, ou o selectp. Você pode fazer algo semelhante com um documento PDF existente (que você pode ter compilado usando pdflatex), usando o pacote pdfpages. O trabalho é então feito com um documento parecido com:

\documentclass{article}
\usepackage[final]{pdfpages}
\begin{document}
\includepdf[pages=30-40]{yoursource.pdf}
\end{document}
(Para incluir todo o documento, você escreve
\includepdf[pages=-]{yoursource.pdf}
omitindo as páginas inicial e final no argumento opcional.)

Se você quiser recursos flexíveis para incluir ou excluir pequenas partes de um arquivo, considere os pacotes comment, version ou optional.

O pacote comment permite que você especifique áreas de um documento a serem incluídas ou excluídas; isso se faz no preâmbulo do arquivo. O comando \includecomment{version-name} declara um ambiente version-name cujo conteúdo será incluído em seu documento, enquanto o \excludecomment{version-name} define um ambiente cujo conteúdo será excluído do documento. O pacote usa um método de exclusão que é bastante robusto e pode lidar com grupos de texto mal formados (por exemplo, com chaves ou comandos \if desbalanceados).

(Estas FAQs empregam o pacote comment para alterar o layout entre a versão impressa (duas colunas) e a versão em PDF para navegação; existem as opções narrowversion e wideversion para cada uma das versões do arquivo.)

O version oferece recursos semelhantes ao comment.sty (isto é, comandos \includeversion e \excludeversion); é muito mais “leve”, mas é menos robusto (e, em particular, não consegue lidar com áreas muito grandes de texto sendo incluídas/excluídas).

Um desenvolvimento significativo do versioné confusamente chamado versions (ou seja, apenas um plural do nome do pacote antigo). O Versions adiciona um comando \markversion{version-name} , que define um ambiente que imprime o texto incluído, com uma nítida marca impressa em torno dele.

O optional define um comando \opt; seu primeiro argumento é um ‘indicador de inclusão’, e seu segundo argumento é o texto a ser incluído ou excluído. O texto a ser incluído ou excluído deve ser bem formado (nenhuma incongruência) e não deve ser muito grande — se um grande corpo de texto for necessário, deve-se usar \input no argumento. A documentação (no próprio arquivo do pacote) informa como declarar quais seções devem ser incluídas: isso pode ser feito no preâmbulo do documento, mas a documentação também sugere maneiras pelas quais isso pode ser feito na linha de comando que invoca o LaTeX, ou interativamente.

E, não menos importante nesse estilo de compilação condicional, o verbatim (que deve estar disponível em qualquer distribuição) define um ambiente comment, que permite que o usuário dedicado do editor do texto de origem suprima trechos de um arquivo de origem LaTeX. A classe memoir oferece o mesmo ambiente.

Uma variação interessante é o pacote xcomment . Ele define um ambiente cujo corpo é excluído, além dos ambientes nomeados em seu argumento. Então, por exemplo:

\begin{xcomment}{figure,table}
  This text is not included
  \begin{figure}
    This figure is included
  \end{figure}
  This is not included, either
  \begin{table}
    This table also included
  \end{table}
  ...
\end{xcomment}

O pacote tagging oferece outro conjunto de sintaxe, que permite ao usuário aplicar “tags” a trechos de texto, e incluir e excluir o texto marcado, de acordo com as tags. Por exemplo, o usuário pode ‘usar’ texto marcado com algumas tags e ‘tirar’ texto marcado com outras:

\usetag{}
\droptag{}
(as listas de tags consistem em palavras únicas separadas por vírgula). E existem comandos
\tagged{}{}
que reproduzem o texto apenas se a ‹lista de tags› contiver pelo menos uma tag listada no comando \usetag, e
\untagged{}{}
que reproduzem o texto apenas se a ‹lista de tags› não contiver qualquer tag listada no comando \droptag.

Outros comandos oferecem uma configuração se-então-senão e especificam ambientes taggedblock e untaggedblock.

Outro aspecto valioso do problema é coberto pelo pacote extract. O pacote permite que se produza uma “cópia parcial” de um documento existente: o pacote foi desenvolvido para permitir a produção de um “livro de exemplos” a partir de um conjunto de anotações de palestras. A documentação do pacote mostra o seguinte uso:

\usepackage[
  active,
  generate=foobar,
  extract-env={figure,table},
  extract-cmd={chapter,section}
]{extract}
o que fará com que o pacote produza um arquivo foobar.tex contendo todos os ambientes figure e table, e os comandos \chapter e \section do documento que estiver sendo processado. O novo arquivo foobar.tex é gerado no decorrer de uma execução comum no documento “mestre”. O pacote fornece um bom número de outros recursos, incluindo intervalos (numéricos ou rotulados) de ambientes para extrair, e um ambiente extract , que você pode usar para criar documentos extract , que você pode usar para criar documentos LaTeX prontos para execução com coisas que você extraiu.
askinclude.sty
Distributed as part of oberdiek
comment.sty
comment
excludeonly.sty
excludeonly
extract.sty
extract
memoir.cls
memoir
optional.sty
optional
pagesel.sty
Distributed as part of oberdiek
pdfpages.sty
pdfpages
selectp.sty
selectp
stampinclude.sty
Distributed as part of oberdiek
tagging.sty
tagging
verbatim.sty
Distributed as part of 2etools
version.sty
version
versions.sty
versions
xcomment.sty
xcomment

This answer last edited: 2014-06-09


Do you have any question? Ask on: latex.net.br - we love qood questions!