Exemplo mínimo
Origem: Tex-Br, a enciclopédia livre.
Para aumentar suas chances de ter uma boa resposta ao postar na lista de discussão, em muitos casos é de grande auxílio fornecer um exemplo mínimo que ilustre o problema. Nessa página será explicado o que é um exemplo mínimo, e como obtê-lo.
Conteúdo |
O que é um exemplo mínimo?
Um exemplo mínimo é uma maneira de procurar e corrigir bugs, bem como de encontrar a causa de um determinado comportamento. Exemplos mínimos devem ser tão pequenos e simples quanto possível, porém completos, isto é, devem ter a estrutura básica de um documento LaTeX e poderem ser compilados do jeito em que estão, mas não devem ter nenhum pacote nem código que não seja necessário para exemplicar o problema.
Um exemplo mínimo deve ser completo e funcional,
- para que não seja acidentalmente omitida informação importante no diagnosticar do problema;
- para que a pessoa que vai testá-lo possa apenas copiar e colar o código para experimentá-lo.
Um exemplo mínimo deve ser pequeno,
- para que pessoas que vão tentar ajudar no problema não tenham que se preocupar com longos trechos desnecessários de código;
- porque isso vai diminuir o número de possíveis causas do comportamento indesejado;
- porque exemplos curtos são mais apropriados para postar em listas públicas de discussão;
- porque muitos problemas, como chaves faltando, sintaxe incorreta, opções inválidas, etc., serão facilmente encontrados durante a elaboração do exemplo;
- porque documentos curtos não vão fazer com que alguém se perca no que está acontecendo.
Mesmo iniciantes não devem ter problemas para criar exemplos mínimos, uma vez que apenas é necessário um pouco de paciência e bom senso. Em muitos casos, você vai encontrar a causa do problema no decorrer da elaboração do exemplo, eliminando a necessidade de postar na lista.
Como construir um exemplo mínimo
Há duas maneiras básicas de construir um exemplo mínimo, construindo um documento a partir da estrutura básica e adicionando conteúdo até que o problema apareça, ou cortando partes do documento até que sobre apenas o mínimo necessário para demonstrar o problema.
Construindo um novo documento
Nesse procedimento, começamos com um documento básico do LaTeX, algo como
\documentclass{...}
\begin{document}
\end{document}
e adicionamos conteúdo de forma a tentar demonstrar o problema.
A primeira coisa a fazer é adicionar um pouco do texto ao redor de onde ocorre o erro. Nem sempre é fácil identificar exatamente onde está a causa do erro, no entanto.
Além disso, às vezes um problema em uma parte do documento causa um erro em uma outra parte. Por exemplo, pode ser acusado um erro no índice devido a um problema num título de seção, ou na lista de figuras por causa de um \caption. Nestes casos, inclua o título da seção ou \caption (provavelmente será necessário o ambiente figure ou table ao redor dela, mas a figura ou tabela não é necessária).
Se o erro aparece, você tem o que é necessário. Se não, tente adicionar pacotes. O ideal é um arquivo que carregue apenas um pacote, mas você pode observar que às vezes o erro só ocorre se dois pacotes forem carregados junto, ou mesmo que só ocorre se o pacote A for carregado antes do B, mas não depois.
Cortando partes desnecessárias
Neste procedimento, iniciamos com o documento original e vamos eliminando partes dele até que o erro não ocorra mais. Sabemos então que o erro está na última parte removida.
Em primeiro lugar, faça um backup do documento original, faça suas alterações na cópia. Você não vai querer ter a surpresa de descobrir que apagou 99% de sua dissertação.
Se o documento consiste de vários arquivos (inseridos com \input ou \include), em primeiro lugar identifique qual o arquivo que causa o problema: comente todas as linhas e vá descomentando uma de cada vez, para localizar qual deles é o culpado.
Feito isso (ou se o documento for constituído de um único arquivo), é necessário identificar qual parte dele é responsável pelo erro. Para isso, podemos fazer uma busca binária. Insira \end{document} aproximadamente no meio do arquivo. Se o erro ocorrer, então a causa dele está na primeira metade do documento (antes do \end{document}), então tudo após a linha inserida pode ser apagado. Se o erro não ocorrer, ele está depois do \end{document} inserido, então apague tudo que estiver antes. Repita agora o procedimento colocando o \end{document} no meio da parte restante.
Executando esse processo algumas vezes, será possível encolher o documento original para apenas um pequeno trecho que mostre o erro.
