A estrutura do documento: síntese e desafios

Resumo

Esta aula encerra a terceira unidade do curso, dedicada à estrutura do documento. Reconstrói a cadeia de decisões e mecanismos que vai da classe do documento ao preâmbulo próprio, assinalando em cada elo que princípio se usa e em que aula se estabelece; situa o que foi alcançado em relação ao plano do curso e precisa que questões, apenas antecipadas, ficam para as unidades seguintes; repete em sua avaliação de saída as habilidades da avaliação de entrada; e termina com seis desafios, de dificuldade superior à dos problemas das aulas, que exigem combinar várias delas para planejar uma tese a partir de suas normas, prever a numeração e as remissões de um livro e diagnosticar documentos divididos que falham ou que mentem.

Objetivos de aprendizagem

Reconstruir a ordem das decisões e dos mecanismos da unidade, identificando o princípio em que se apoia cada um.
Explicar como a numeração, o sumário, as remissões e a compilação parcial dependem dos arquivos auxiliares.
Distinguir o que a unidade estabeleceu do que apenas antecipou e que as unidades seguintes desenvolverão.
Diagnosticar documentos divididos em vários arquivos que falham, ou que compilam com números falsos, ordenando as correções.
Planejar a classe, a página, as partes, as remissões e os arquivos de uma tese a partir das normas que ela deve cumprir.

O que a unidade alcançou

A unidade propôs-se dar ao documento uma arquitetura cujos números, sumário e remissões continuem verdadeiros através de todas as suas mudanças. O propósito foi cumprido apoiando-se no que a introdução declarou sabido das unidades anteriores: as passagens da compilação, a divisão entre o preâmbulo e o corpo, e a marcação lógica. Com isso, o caminho percorrido pode ser lido como uma só cadeia em cinco trechos.

Classes de documento e página

A aula sobre as classes de documento e a página estabeleceu que a classe decide que divisões existem, o que faz \maketitle, se há resumo e se as páginas pares se distinguem das ímpares; disso deduziu um critério para escolher entre article, report e book segundo a estrutura e a impressão, e apresentou as classes do KOMA-Script, com a opção es-noquoting que sua combinação com o espanhol exige na versão do TeX Live destes exemplos. Percorreu as opções da classe, explicou por que as margens dependem do comprimento da linha e como fixá-las com o geometry, e terminou com os estilos de página, que algumas instruções da classe impõem por conta própria.

Seções, sumário e apêndices

A aula sobre as seções, o sumário e os apêndices compôs os dados do título e o resumo, ordenou os níveis de divisão e estabeleceu que dois contadores independentes, secnumdepth e tocdepth, decidem o que se numera e o que entra no sumário. Explicou que o sumário se compõe com o que a passagem anterior anotou, sem advertência quando fica desatualizado; que \appendix muda a numeração do que vem depois dele; e que um livro tem três partes, com duas numerações de página, cuja ordem não é indiferente.

Referências cruzadas

A aula sobre as referências cruzadas estabeleceu o princípio do qual depende toda remissão: um rótulo registra o último número atribuído antes dele, dentro de seu ambiente. Dele deduziu onde vai o rótulo em cada elemento, por que um rótulo antes da legenda de uma figura remete à seção e por que uma seção sem número não tem número próprio ao qual remeter. Mostrou que, depois de uma mudança, uma só compilação imprime os números anteriores com toda a aparência de correção, e apresentou o hyperref, que deve ser carregado no final dos pacotes, e o cleveref, que vem depois dele e que, com a opção brazilian, abrevia “fig.” e “eq.” se não se lhe pede o contrário.

Documentos longos

A aula sobre os documentos longos repartiu um documento num arquivo principal e em peças sem preâmbulo. Distinguiu \input, uma substituição literal, de \include, que abre página, escreve um arquivo auxiliar próprio e admite \includeonly, cuja numeração depende dos auxiliares de uma compilação completa anterior. Estabeleceu que os caminhos se escrevem a partir da pasta do arquivo principal, que no Texmaker se declara o documento mestre, e percorreu os erros próprios dos documentos divididos, entre eles dois silenciosos: a peça que não se encontra com \include e a peça com preâmbulo, cujo \end{document} termina a tese.

Macros e preâmbulo próprio

A aula sobre as macros e o preâmbulo próprio converteu em método a marcação lógica: \newcommand com argumentos e com um opcional, a proteção que impede redefinir um nome ocupado, o espaço que se perde depois de um comando sem argumentos, \NewDocumentCommand, os ambientes próprios, cujos argumentos só existem na abertura, e o preâmbulo levado a um arquivo ou a um pacote, que não deve impor a classe, o idioma nem a posição do hyperref.

A figura seguinte reúne os cinco trechos numa só cadeia. Cada nó da coluna é uma decisão ou um mecanismo, numerado segundo a ordem em que se apoiam uns nos outros e unido por um arco aos elos anteriores que usa; ao redor flutuam os apoios, isto é, os princípios aos quais a cadeia recorre uma e outra vez, cada um unido por um traço firme aos elos que se apoiam nele e por um pontilhado ao elo onde se estabelece, salvo os que se estabeleceram em unidades anteriores, que se desenham como anéis. Ao clicar num apoio destacam-se todos os elos que o usam, e cada elo remete à aula em que se estuda.

Apoios da cadeia

APassagens. O motor anota nos arquivos auxiliares os números, os títulos e as páginas numa passagem, e os usa na seguinte. Estabelece-se na primeira unidade. Admitido sem demonstração nesta unidade.
BPreâmbulo e corpo. O preâmbulo configura e carrega os pacotes, e o corpo compõe; o que só define ou guarda pode ir em ambos. Estabelece-se na primeira unidade. Admitido sem demonstração nesta unidade.
CConteúdo e forma. O autor declara o que é cada coisa, e uma decisão tomada em outro lugar fixa como se vê. Estabelece-se nas unidades anteriores. Admitido sem demonstração nesta unidade.
DA classe decide. A classe do documento decide que divisões existem, o que compõe o título, se há resumo, como se repartem as páginas e que estilo impõem suas instruções. Estabelecido em: 1. Três classes padrão.
EO que um rótulo registra. Um rótulo registra o último número atribuído antes dele, dentro de seu ambiente, sem saber a que está unido. Estabelecido em: 11. Rótulos e referências.
FOrdem de carregamento. Os pacotes são carregados na ordem em que são lidos, e um posterior pode desfazer o que fez um anterior: o hyperref vai no final, e o cleveref depois dele. Estabelecido em: 13. Links.
GO arquivo principal. Compila-se sempre o arquivo principal; as peças são fragmentos de seu corpo, sem preâmbulo, e seus caminhos se escrevem a partir da pasta do principal. Estabelecido em: 16. A instrução include.

Trecho 1 Classes de documento e página
- Escolher a classe pela estrutura e pela impressão do documento.
- Declarar as opções da classe e prever seu efeito.
- Fixar as margens com o geometry sem alongar a linha em excesso.
- Prever e mudar os estilos de página, os cabeçalhos e os rodapés.
1. Três classes padrão. article não tem capítulos; report os tem, com título e resumo em páginas próprias; book imprime frente e verso e não tem resumo.
  Apoia-se em: B (Preâmbulo e corpo). Demonstrado em: Classes de documento e página.
2. KOMA-Script. scrartcl, scrreprt e scrbook correspondem às padrão com decisões europeias; com o babel em espanhol exigem, nesta versão, a opção es-noquoting.
  Usa: 1. Três classes padrão. Apoia-se em: C (Conteúdo e forma). Demonstrado em: Classes de documento e página.
3. Opções da classe. Papel, corpo da letra, uma ou duas faces, folha de rosto, início dos capítulos e rascunho declaram-se na primeira linha.
  Usa: 1. Três classes padrão. Apoia-se em: D (A classe decide). Demonstrado em: Classes de documento e página.
4. Margens. O geometry calcula a página a partir de umas poucas medidas; a largura da mancha fixa o comprimento da linha, que é o que o leitor padece.
  Usa: 3. Opções da classe. Apoia-se em: B (Preâmbulo e corpo). Demonstrado em: Classes de documento e página.
5. Estilos de página. O estilo decide cabeçalhos e rodapés; \maketitle e \chapter impõem o estilo plain à sua página, e o fancyhdr ou o scrlayer-scrpage compõem estilos próprios.
  Usa: 1. Três classes padrão, 4. Margens. Apoia-se em: D (A classe decide). Demonstrado em: Classes de documento e página.
Trecho 2 Seções, sumário e apêndices
- Compor o título e o resumo segundo a classe.
- Escolher o nível de divisão e prever a numeração e o sumário.
- Produzir o sumário e as listas, sabendo de que passagem dependem.
- Ordenar os apêndices e as partes de um livro.
1. Título e resumo. \title, \author e \date guardam, \maketitle compõe; o ambiente abstract existe em article e report, não em book.
  Usa: 1. Três classes padrão. Apoia-se em: D (A classe decide), B (Preâmbulo e corpo). Demonstrado em: Seções, sumário e apêndices.
2. Níveis de divisão. Sete níveis, da parte ao subparágrafo; o capítulo só existe em report e book, e a hierarquia não se escolhe pelo tamanho do título.
  Usa: 1. Três classes padrão. Apoia-se em: D (A classe decide). Demonstrado em: Seções, sumário e apêndices.
3. Numeração e sumário. secnumdepth decide que níveis se numeram e tocdepth quais entram no sumário; a forma com asterisco não numera nem consome número.
  Usa: 7. Níveis de divisão. Apoia-se em: C (Conteúdo e forma). Demonstrado em: Seções, sumário e apêndices.
4. Sumário e listas. O sumário compõe o que a passagem anterior anotou no arquivo .toc, e não adverte quando fica desatualizado.
  Usa: 7. Níveis de divisão, 8. Numeração e sumário. Apoia-se em: A (Passagens). Demonstrado em: Seções, sumário e apêndices.
5. Apêndices e partes do livro. \appendix muda a numeração do que vem depois; em book, as páginas preliminares, o corpo e as finais têm duas numerações, e os apêndices vêm antes de \backmatter.
  Usa: 7. Níveis de divisão, 5. Estilos de página. Apoia-se em: D (A classe decide). Demonstrado em: Seções, sumário e apêndices.
Trecho 3 Referências cruzadas
- Situar e nomear os rótulos.
- Prever o que imprime uma referência depois de uma ou duas passagens.
- Carregar o hyperref e o cleveref em sua ordem.
- Remeter com o nome e o número, ou com o título.
1. Rótulos e referências. \label marca um lugar, \ref e \pageref escrevem seu número e sua página, com duas passagens.
  Usa: 7. Níveis de divisão. Apoia-se em: A (Passagens). Demonstrado em: Referências cruzadas.
2. Onde vai o rótulo. Depois da instrução que atribui o número e dentro do mesmo ambiente: depois de \section, depois de \caption; com um prefixo que diga o que designa.
  Usa: 11. Rótulos e referências. Apoia-se em: E (O que um rótulo registra). Demonstrado em: Referências cruzadas.
3. Links. O hyperref converte as referências, o sumário e as notas em links e as seções em marcadores, e é carregado no final dos pacotes.
  Usa: 11. Rótulos e referências, 9. Sumário e listas. Apoia-se em: B (Preâmbulo e corpo). Demonstrado em: Referências cruzadas.
4. Referências com nome. O cleveref escreve o nome e o número, com a opção brazilian “seção”, “fig.” e “eq.”, ajustável com a opção noabbrev ou com \crefname; o nameref remete pelo título.
  Usa: 13. Links, 12. Onde vai o rótulo. Apoia-se em: E (O que um rótulo registra), F (Ordem de carregamento). Demonstrado em: Referências cruzadas.
Trecho 4 Documentos longos
- Escolher entre \input e \include para cada peça.
- Prever o que \includeonly conserva.
- Organizar as pastas e declarar o documento mestre.
- Reconhecer os erros, ruidosos e silenciosos, dos documentos divididos.
1. A instrução input. \input insere um arquivo como se seu texto estivesse escrito em seu lugar, sem cortar a página nem criar auxiliares.
  Apoia-se em: B (Preâmbulo e corpo). Demonstrado em: Documentos longos.
2. A instrução include. \include abre página antes e depois, escreve um auxiliar próprio por peça e não pode ser aninhado.
  Usa: 15. A instrução input, 7. Níveis de divisão. Apoia-se em: A (Passagens). Demonstrado em: Documentos longos.
3. Compilação parcial. \includeonly compõe só as peças escolhidas e numera as demais com seus auxiliares, que devem vir de uma compilação completa posterior à sua última mudança.
  Usa: 16. A instrução include, 11. Rótulos e referências. Apoia-se em: A (Passagens). Demonstrado em: Documentos longos.
4. Pastas e documento mestre. Um arquivo principal na raiz, peças em pastas, caminhos a partir do principal, nomes simples, e no Texmaker o principal como documento mestre.
  Usa: 16. A instrução include. Apoia-se em: G (O arquivo principal). Demonstrado em: Documentos longos.
5. Erros dos documentos divididos. Um \input sem arquivo detém a compilação; um \include sem arquivo só anota “No file”; uma peça com preâmbulo termina a tese em seu \end{document}.
  Usa: 16. A instrução include, 18. Pastas e documento mestre. Apoia-se em: G (O arquivo principal), B (Preâmbulo e corpo). Demonstrado em: Documentos longos.
Trecho 5 Macros e preâmbulo próprio
- Definir comandos com argumentos e um opcional.
- Distinguir definir, redefinir e prover, e evitar o espaço perdido.
- Definir ambientes próprios.
- Reunir o preâmbulo num arquivo ou num pacote.
1. Comandos próprios. \newcommand define um comando com até nove argumentos, o primeiro opcional com seu valor por omissão; nomeia uma função que se repete.
  Apoia-se em: C (Conteúdo e forma). Demonstrado em: Macros e preâmbulo próprio.
2. Nomes ocupados e espaços. \newcommand rejeita um nome existente e \renewcommand um inexistente; um comando sem argumentos consome o espaço que o segue.
  Usa: 20. Comandos próprios. Apoia-se em: B (Preâmbulo e corpo). Demonstrado em: Macros e preâmbulo próprio.
3. Ambientes próprios. \newenvironment define abertura e fechamento; seus argumentos só existem na abertura, e \NewDocumentEnvironment os admite também no fechamento.
  Usa: 20. Comandos próprios. Apoia-se em: C (Conteúdo e forma). Demonstrado em: Macros e preâmbulo próprio.
4. Preâmbulo próprio. O preâmbulo é levado a um arquivo lido com \input ou a um pacote .sty, que não impõe a classe, o idioma nem a posição do hyperref.
  Usa: 20. Comandos próprios, 21. Nomes ocupados e espaços, 15. A instrução input, 13. Links. Apoia-se em: F (Ordem de carregamento), C (Conteúdo e forma). Demonstrado em: Macros e preâmbulo próprio.

Rumo à matemática. A cadeia se detém onde a arquitetura está completa e falta preenchê-la: as equações e os teoremas numerados, que serão remetidos com os rótulos desta unidade, são o objeto da seguinte.