Español
English
中文 (中国)
العربية
हिन्दी
Русский
Français
Deutsch
Ελληνικά
Italiano
日本語
한국어
LatineResumo
Esta aula abre a primeira unidade do curso, dedicada aos primeiros passos com LaTeX. Explica para que serve a unidade: levar quem nunca usou LaTeX até o ponto de escrever, compilar e corrigir por conta própria um documento breve; apresenta suas quatro aulas e o fio que as une, desde a ideia de composição tipográfica até a leitura dos erros; precisa o pouco que se dá por sabido, que é o manejo de arquivos e pastas em um computador; formula o problema que a unidade resolve, o de passar de um arquivo vazio a um documento composto e, quando algo falha, da mensagem do motor à sua causa; e mostra que esse mesmo ciclo serve tanto a um relatório de laboratório quanto a um ensaio de filosofia ou a uma edição de um texto latino.
Objetivos de aprendizagem
- Descrever a sequência de conteúdos da unidade e explicar o que cada aula traz à seguinte.
- Reconhecer os conhecimentos prévios que a unidade supõe e preparar o computador para ela, em particular a visibilidade das extensões dos arquivos.
- Explicar, com um exemplo, por que um documento de LaTeX pode não produzir resultado e por que o erro nem sempre é apontado onde está.
- Reconhecer em outras disciplinas e nas unidades seguintes o ciclo de escrever, compilar e corrigir que a unidade constrói.
Avaliação de entrada
Antes de percorrer a unidade, convém medir o ponto de partida. Esta avaliação é uma autoavaliação: não recebe nota, e seu único propósito é orientar o estudo. Suas oito perguntas tratam, de duas em duas e em ordem, das quatro aulas da unidade; quem nunca usou LaTeX não deve esperar acertá-las, e isso não importa: cada resposta, certa ou não, explica o ponto e indica a aula que o trata. As mesmas habilidades voltam a ser medidas no final, na aula de síntese; como esta é a primeira unidade do curso, não há perguntas sobre unidades anteriores.
Antes de começar a unidade, meça seu ponto de partida. É uma autoavaliação breve: não recebe nota e seu resultado fica guardado apenas no seu navegador.
Pergunta 1Uma pesquisadora escreve em português um artigo que cita passagens em grego politônico, e a revista exige uma fonte OpenType que ela tem instalada no computador. Com que motor convém compilá-lo, segundo o critério deste curso?
Sua rapidez não compensa o que ele não faz: o pdfLaTeX não carrega diretamente as fontes OpenType do sistema, e uma letra grega escrita em Unicode interrompe sua compilação se não se preparam codificações e fontes especiais.Entendem o mesmo LaTeX, mas diferem no modo como leem o texto e nas fontes que podem usar; o fontspec, que carrega a fonte do sistema, exige XeLaTeX ou LuaLaTeX.O Texmaker é o editor, não um motor: nele se escreve a fonte, e ele chama o motor que vem com a distribuição instalada. A pergunta é qual desses motores ele deve chamar.O LuaLaTeX escreve o grego diretamente, com seus acentos e espíritos, e carrega a fonte exigida com\setmainfont. O XeLaTeX também serviria; o curso adota o LuaLaTeX para que todos os seus documentos sejam compilados do mesmo modo.Revisar: O que é o LaTeX
Pergunta 2O que imprime a linha
Foram aprovados 70% dos estudantes.escrita tal como está no corpo de um documento?O sinal de porcentagem é um dos caracteres que o LaTeX reserva: escrito tal como está, não se imprime, mas faz alguma coisa.Um comentário não é um erro; por isso esse descuido é perigoso: o motor descarta meia frase sem apontar nada, e isso só se percebe ao ler o resultado.O comentário não se limita ao sinal: abrange tudo o que segue até o fim da linha.O sinal de porcentagem inicia um comentário: o motor ignora tudo o que segue até o fim da linha, incluída a quebra de linha, e não avisa. Para imprimir o sinal, escreve-se\%.Revisar: O que é o LaTeX
Pergunta 3A pasta de uma tese contém
tese.tex,tese.aux,tese.log,tese.toc,tese.pdfemapa.png, uma figura que a tese inclui. Outra pessoa da coautoria compilará a tese no próprio computador. O que é o mínimo que ela deve receber?Os auxiliares são regenerados ao compilar e não lhe servem; um.auxalheio pode até arrastar referências desatualizadas até a compilação seguinte.A figura não é produzida pela compilação, mas usada por ela: semmapa.png, o motor para porque não encontra o arquivo.O sumário se obtém com uma segunda compilação, e a figura, que é sim indispensável, ficou de fora.Precisa exatamente do que o motor não pode produzir: o que o autor escreveu ou forneceu. Os demais arquivos, a compilação os regenera.Revisar: O ambiente de trabalho
Pergunta 4Um estudante corrige sua fonte e compila, mas o PDF que vê no visualizador não muda. O registro termina com a linha
Fatal error occurred, no output PDF file produced!. Que PDF ele está vendo?Isso ocorre quando o registro termina sem erros e o PDF da pasta tem a hora da última compilação; aqui o registro diz que não se produziu nenhum PDF.Se estivesse danificado, o visualizador não mostraria nada; mostra um documento completo e legível, só que antigo.Essa seria outra falha possível, mas o registro a descarta: diz que não se produziu nenhum PDF, de modo que não há um PDF novo.Um erro grave interrompeu a compilação antes de escrever o resultado; o PDF da pasta é o último produzido com sucesso, e o visualizador o mostra como se nada tivesse acontecido. É preciso corrigir o erro que o registro aponta.Revisar: O ambiente de trabalho
Pergunta 5No corpo de um documento, depois de vários parágrafos, o autor escreve
\usepackage{amsmath}. O que acontece ao compilar?Assim se comportam algumas declarações, como\setmainfont, que funcionam no corpo a partir do ponto em que são escritas; os pacotes, não.O motor não reordena a fonte: lê-a em ordem, e o que encontra fora de lugar aponta como erro.É verdade que não compõe texto, mas isso só permite colocá-lo antes do corpo; não o habilita a ir dentro dele.Ao chegar a\begin{document}encerra-se a configuração, e um pacote carregado depois poderia mudar decisões já aplicadas; por isso os pacotes só são carregados no preâmbulo.Revisar: Anatomia de um documento
Pergunta 6No corpo de um documento aparece, escrita tal como está, a frase
Salve o arquivo como relatorio_final.tex.O que acontece ao compilar?O sublinhado é um dos dez caracteres reservados: escrito tal como está, não se imprime.Isso faz o sinal de porcentagem, que inicia um comentário; o sublinhado tem outra função, a dos índices inferiores.O motor tenta algo parecido, mas só depois de apontar o erro, quando insere por conta própria o cifrão que julga faltar; o resultado não é o pretendido.O sublinhado escreve índices inferiores dentro das fórmulas; no texto, o motor supõe que falta abrir uma fórmula e o aponta. Para imprimi-lo, escreve-se\_.Revisar: Anatomia de um documento
Pergunta 7O registro de uma compilação contém o erro
! Undefined control sequence.e, abaixo, a linhal.7 \sectoin. O que isso indica?Uma instrução não definida pode dever-se a um pacote que não foi carregado; mas\sectionnão precisa de nenhum, e a instrução que o registro mostra denuncia um erro de digitação em seu nome.A indicaçãol.7remete à fonte, que é o que se corrige; o registro só informa.O número é o de uma linha da fonte, não o de uma seção do documento.O erro nomeia a falha, uma instrução não definida; a indicaçãol.7dá o número de linha da fonte, e o texto que a segue termina justamente na instrução desconhecida.Revisar: Compilar e corrigir erros
Pergunta 8A compilação produz o PDF, mas o registro contém a linha
Overfull \hbox (3.21451pt too wide) in paragraph at lines 20--24. O que significa?Os erros começam com um ponto de exclamação; esta linha é uma advertência sobre a composição, e o PDF é válido.Os números são linhas da fonte, não páginas do PDF, e o que ultrapassa é uma linha de texto, não uma página.A extensão do parágrafo não importa: o problema é uma única linha que não pôde ser bem quebrada, e se resolve nela.O motor não encontrou um modo aceitável de quebrar alguma linha desse parágrafo, por exemplo por causa de uma palavra longa que não sabe hifenizar, e a deixou mais larga que a caixa de texto. O PDF foi produzido; convém olhar esse parágrafo nele e decidir se é preciso intervir.Revisar: Compilar e corrigir erros
Os conteúdos da unidade
Esta unidade serve ao primeiro dos objetivos do curso, produzir e compilar documentos, diagnosticando e corrigindo seus erros, e é a condição de todos os demais: compor textos em vários idiomas e escritas, estruturar documentos longos, escrever matemática e lógica, apresentar tabelas e figuras, gerenciar a bibliografia e escolher a classe adequada a cada gênero acadêmico supõem que o ciclo de escrever, compilar e corrigir já não oferece dificuldade. Sua meta é que quem nunca usou LaTeX possa, ao terminá-la, escrever um documento breve a partir de um arquivo vazio, compilá-lo com LuaLaTeX no Texmaker ou no Overleaf e, quando não compilar, encontrar e corrigir a causa por conta própria. Suas quatro aulas formam uma cadeia em que cada uma se apoia nas anteriores.
- O que é LaTeX. Explica a composição tipográfica, compara a linguagem de marcação com o processador de textos, conta a origem do TeX e do LaTeX e seu princípio de separar o conteúdo da forma, justifica a escolha do LuaLaTeX e mostra como uma fonte se converte em um PDF. Fixa o vocabulário de toda a unidade: fonte, motor, compilação, preâmbulo, corpo e registro.
- O ambiente de trabalho. Instala o que a primeira aula descreveu: uma distribuição de TeX, com seu gerenciador de pacotes, e o editor Texmaker, configurado para compilar com LuaLaTeX e salvar em UTF-8; apresenta o Overleaf como alternativa no navegador e explica que arquivos a compilação deixa e quais se conservam. Termina com dois documentos de teste que verificam a instalação.
- Anatomia de um documento. Decompõe a fonte em suas peças: o preâmbulo e o corpo, as instruções com seus argumentos, os grupos que limitam o alcance das declarações, os ambientes, os dez caracteres reservados, os comentários, os pacotes e a classe. Com ela, o documento mínimo da primeira aula deixa de ser uma receita e se converte em uma estrutura que se entende peça por peça.
- Compilar e corrigir erros. Ensina a ler o registro: distinguir os erros das advertências, localizar cada erro na fonte, reconhecer as mensagens mais frequentes e isolar a causa quando a mensagem não basta. Reúne o anterior, porque quase todo erro é a infração de uma regra da anatomia da fonte, e seu diagnóstico se apoia no ambiente de trabalho.
A unidade termina com a aula de síntese e desafios, que reúne o que foi alcançado em uma cadeia de conceitos e procedimentos, repete em sua avaliação de saída as habilidades da avaliação de entrada e propõe desafios que combinam várias aulas.
O que se dá por sabido
A unidade parte de quase nada. Não supõe ter usado LaTeX, nem saber programar, nem conhecimentos de matemática; tampouco supõe saber inglês, embora as mensagens do motor estejam nesse idioma, porque o curso explica cada uma das que apresenta. Supõe apenas o uso corrente de um computador: criar uma pasta, salvar um arquivo com um nome determinado e em uma pasta determinada, encontrá-lo depois, copiar, mover e apagar arquivos e instalar um programa, ou então dispor de um navegador e de uma conta no Overleaf.
Daí se segue uma única preparação prévia, que convém fazer antes da aula sobre o ambiente de trabalho. Um nome de arquivo consta de uma base e de uma extensão, a parte que segue o último ponto: em relatorio.tex, a base é relatorio e a extensão, tex. Ora, o Explorador de Arquivos do Windows e o Finder do macOS ocultam por padrão as extensões conhecidas, de modo que relatorio.tex e relatorio.pdf aparecem ambos como relatorio, e os arquivos auxiliares da compilação, que se distinguem apenas pela extensão, tornam-se indistinguíveis. Portanto, convém ativar a opção que mostra as extensões: no Windows, no menu Exibir do Explorador de Arquivos; no macOS, nos ajustes avançados do Finder. No Linux, os gerenciadores de arquivos as mostram por padrão.
O problema que a unidade resolve
Quem escreve em um processador de textos vê o resultado à medida que escreve. No LaTeX, entre a fonte e a página há um programa que lê a fonte ao pé da letra, e o resultado só aparece ao compilar. Isso coloca dois problemas, que são os da unidade. O primeiro é como se passa de um arquivo vazio a um documento composto: o que é preciso instalar, o que a fonte deve conter no mínimo e o que o motor faz com ela. O segundo é o que fazer quando o documento não sai, ou sai diferente do que se pretendia: o motor não mostra o erro sobre a página, mas o descreve no registro, em uma linguagem própria, e às vezes o aponta longe do lugar em que foi cometido. O exemplo seguinte mostra ambos os problemas em um documento de quinze linhas.
A fonte seguinte é um documento completo: declara a classe, carrega os pacotes (com a opção brazilian do babel; em Portugal, usa-se portuguese), guarda o título, o autor e uma data vazia e compõe duas seções. Compilada com LuaLaTeX, produz este resultado.
\documentclass{article}\usepackage{fontspec}\usepackage[brazilian]{babel}\title{Relatório de leitura}\author{Ana Souza}\date{}\begin{document}\maketitle\section{A pergunta}O texto examina uma \emph{hipótese} sobre 40\% dos casos.\section{A resposta}A resposta se apoia na seção anterior.\end{document}
Se na décima primeira linha se omite a chave que fecha o argumento de \emph, o motor não produz nenhum PDF, e o registro contém, entre outras, estas linhas.
Runaway argument?{hipótese sobre 40\% dos casos. \par \section {A resposta} A respost\ETC.! File ended while scanning use of \emph ....! ==> Fatal error occurred, no output PDF file produced!O erro não é apontado na décima primeira linha, mas no fim do arquivo: o motor continuou lendo o argumento de \emph através do parágrafo, da seção seguinte e de \end{document}, até que o arquivo terminou. Ora, o registro dá a pista que falta: a linha que segue «Runaway argument?» reproduz o argumento desgovernado desde o seu começo, e esse começo, a chave que precede «hipótese», é exatamente o lugar do erro. Ler assim o registro é o que ensina a aula sobre a compilação e a correção de erros; entender por que uma chave não fechada arrasta tudo o que segue é o que ensina a da anatomia de um documento.
A resposta da unidade a esses dois problemas tem, portanto, duas partes. Para o primeiro, um ambiente instalado e testado, e uma fonte cuja estrutura se entende peça por peça, de modo que nada nela é uma fórmula mágica. Para o segundo, um método: ler o registro desde o primeiro erro, situar o erro na fonte, reconhecer a regra que foi infringida e, se a mensagem não basta, isolar a causa desativando partes da fonte. Nenhuma das duas partes exige memorizar instruções; ambas exigem ler a fonte como o motor a lê.
A unidade nas disciplinas
O ciclo que a unidade ensina é o mesmo em todas as disciplinas, e o que muda de uma para outra é apenas o que se escreve. Um relatório de laboratório de química, um ensaio de filosofia com uma centena de notas de rodapé, um comentário de uma passagem de Cícero com o texto latino e sua tradução, um trabalho de economia com tabelas, uma tese de história com documentos de arquivo e um artigo de matemática com teoremas começam igual: uma pasta, um arquivo-fonte com seu preâmbulo e seu corpo, uma compilação e a leitura de seu registro. Do mesmo modo, os erros desta unidade, uma chave não fechada, um caractere reservado escrito tal como está, um pacote carregado fora de lugar, aparecem em qualquer desses documentos, sem distinção de disciplina.
Por isso, o que a unidade ensina é usado nos demais cursos do site. Os trabalhos e as anotações de Lógica Aristotélica ou de Fundamentos de Mecânica podem ser escritos em LaTeX desde a primeira semana; em Análise de Dados com R, os resultados de uma análise são incorporados a um documento composto; e em Programação em C++ I o ciclo é, no essencial, o mesmo: escreve-se uma fonte, um compilador a lê, e suas mensagens, que remetem a números de linha, são lidas com o método que esta unidade ensina.
Aonde conduz
Ao terminar a unidade, o documento mínimo será um ponto de partida conhecido, e as unidades seguintes construirão sobre ele. A segunda se ocupará do próprio texto: os idiomas e as escritas, entre elas o grego e o latim, as fontes, as notas de rodapé e as citações longas. A terceira, da estrutura dos documentos longos, com seus capítulos, seu sumário e suas referências internas, distribuídos em vários arquivos. A quarta, da escrita da matemática e da lógica com a notação correta; a quinta, das tabelas e das figuras; a sexta, da bibliografia e das convenções de citação de cada disciplina; e a sétima, das classes de documento adequadas a cada gênero acadêmico, das apresentações às cartas e aos pôsteres. Em todas elas, cada nova instrução será escrita, compilada e, quando falhar, corrigida com o que se aprendeu nesta.