YuShenLiu06/yushen-skills

latex-pdf — Guia Profissional de Diagramação LaTeX para PDF

O objetivo não é "compilar", é fazer com que o leitor pegue o PDF e sinta que é profissional. A entrega é baseada no conteúdo e na página real; a compilação bem-sucedida prova apenas que a compilação terminou, não substitui a inspeção visual.

Sumário

1. Conceito Central
2. Escolha do Motor
3. Estratégia de Compilação
4. Princípios de Diagramação para Legibilidade
5. Fluxo de Trabalho
6. Guia Rápido de Problemas

---

Conceito Central

A diagramação segue dois objetivos de verificação, sem depender de outra skill para funcionar:

① Diagramação serve à leitura — cada decisão de diagramação responde a "Isso ajuda o leitor a entender melhor?". Se depois de remover uma configuração a experiência de leitura não mudar, ela não precisa existir.

② Moderação é profissionalismo — remova todos os elementos visuais que não transmitem informação. Linhas decorativas, sombreamentos, caixas coloridas — a maioria deve ser removida. A diagramação profissional "parece sem esforço", enquanto a amadora "parece muito esforçada, mas é confusa".

O mapeamento detalhado dos princípios de legibilidade está em references/readability-principles.md.

---

Escolha do Motor

Escolher o motor errado é o erro mais comum, especialmente usar pdflatex para conteúdo em chinês.

Tem chinês/japonês/coreano?
├─ Sim → xelatex (+ pacote ctex)
│         (lualatex também funciona, mas compila mais devagar)
└─ Não → Precisa de fontes do sistema?
         ├─ Sim → xelatex ou lualatex (+ fontspec)
         └─ Não → pdflatex (mais rápido, mais compatível)

Para documentos novos em CJK, priorize XeLaTeX ou LuaLaTeX, e verifique o suporte real a fontes. Templates pdfLaTeX/CJK existentes e funcionais não devem ser substituídos sem motivo; fandol não é adequado para o caminho normal do pdfLaTeX.

Motor	Vantagens	Desvantagens	Cenário de Uso
pdflatex	Mais rápido, mais estável, maior ecossistema	Não suporta Unicode nativo, não pode usar fontes do sistema	Documentos apenas em inglês
xelatex	Unicode nativo, fontes do sistema, CJK amigável	Mais lento	Escolha padrão para documentos em chinês
lualatex	Manipulação de fontes mais poderosa, pode embutir Lua	Mais lento	Precisa de funcionalidades avançadas de diagramação

---

Estratégia de Compilação

Verifique a Origem e os Limites de Execução

Antes de compilar, faça uma verificação estática dos arquivos .tex, .sty/.cls incluídos, configuração de construção e caminhos de anexos, prestando atenção à capacidade de execução de leitura/escrita de arquivos, comandos externos e Lua. A verificação estática não é prova de segurança. Para projetos não confiáveis, use um ambiente isolado sem arquivos privados, sem rede e com restrições de escrita, tempo de execução e recursos; se não houver isolamento adequado, pare a compilação e relate, sem executar em ambiente pessoal.

Desabilite shell-escape por padrão, não o libere automaticamente para minted ou externalização de gráficos. Ao executar latexmk, use -norc para evitar carregar automaticamente rc do sistema, usuário ou projeto; outros scripts de construção e programas auxiliares externos devem ser revisados separadamente. Instalação, download de pacotes ou modificação do ambiente só podem ser feitos com autorização prévia; se não coberto, obter aprovação primeiro.

Reutilize a Cadeia de Compilação Adequada

Para projetos existentes, mantenha o método de construção que funciona. Quando precisar de múltiplas passagens e processamento de referências bibliográficas, pode usar latexmk. O exemplo a seguir é apenas para entradas já verificadas, no diretório de trabalho permitido:

# Documento xelatex (padrão para chinês)
latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

# Documento pdflatex
latexmk -norc -pdf -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

# Limpar arquivos auxiliares
latexmk -norc -c

Explicação dos parâmetros:

• -interaction=nonstopmode: não pausa para esperar entrada ao encontrar erro (essencial para ambiente de script)
• -halt-on-error: para no primeiro erro, facilitando a localização do problema

biber (Referências Bibliográficas)

Quando precisar de referências, verifique o biber/BibTeX que o latexmk planeja chamar e as entradas; só execute após permissão; não trate detecção automática como permissão extra de execução.

---

Princípios de Diagramação para Legibilidade

Abaixo está um resumo dos princípios centrais. O mapeamento detalhado e exemplos de código estão em references/readability-principles.md.

Geometria da Página

Objetivo: 50-75 caracteres por linha (66 é o ideal; TeX usa o padrão).

\usepackage{geometry}
\geometry{a4paper, margin=2.5cm}
% Cada caractere chinês tem aproximadamente 2x a largura de um caractere inglês; 35 caracteres chineses/linha ≈ 70 caracteres ingleses/linha

Tabelas

Para tabelas de dados comuns, priorize o estilo sem linhas verticais do booktabs. Se o usuário, periódico ou template institucional exigir diferente, mantenha a especificação:

\usepackage{booktabs}
\begin{tabular}{lrr}
    \toprule
    Indicador & 2024 & 2025 \\
    \midrule
    Receita & 120 & 150 \\
    \bottomrule
\end{tabular}

O design do booktabs pressupõe a ausência de linhas verticais — com linhas verticais, o espaçamento horizontal das linhas quebra; isso não é bug, é feature.

Sistema de Espaçamento

Escolha uma das duas opções para separação de parágrafos, não misture:

% Opção A: Recuo da primeira linha (documentos acadêmicos, padrão ctex)
\setlength{\parindent}{2em}

% Opção B: Espaço entre parágrafos (documentos técnicos, relatórios)
\setlength{\parindent}{0pt}
\setlength{\parskip}{0.5\baselineskip}

Fontes

Use serifa para o corpo do texto (confortável para leitura) e monoespaçada para código. No xelatex/lualatex, use fontspec para configurar fontes do sistema:

\usepackage{fontspec}
\setmainfont{TeX Gyre Termes}[Ligatures=TeX]
\setmonofont{TeX Gyre Cursor}

microtype

Melhoria de qualidade quase gratuita — ajuste de kerning entre caracteres deixa o texto mais alinhado:

\usepackage{microtype}
% Nota: no xelatex, apenas protrusion (sem font expansion), mas ainda vale a pena carregar

Órfãs/Viúvas

Evite que a primeira ou última linha de um parágrafo fique sozinha no topo ou base da página:

\widowpenalty=10000
\clubpenalty=10000

Realce de Código

Por padrão, use listings (sem dependências externas). minted tem qualidade superior, mas requer Python + Pygments/latexminted:

\usepackage{listings}
\usepackage{xcolor}

\lstset{
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue!70!black},
    commentstyle=\color{gray},
    stringstyle=\color{green!50!black},
    numbers=left,
    numberstyle=\tiny\color{gray},
    frame=none,
    breaklines=true,
    showstringspaces=false,
}

---

Fluxo de Trabalho

Para quem usa este fluxo de trabalho pela primeira vez.

Etapa 0: Verificação do Ambiente

Verifique apenas quando for necessário compilar localmente e a informação sobre ferramentas existentes for insuficiente. Primeiro, leia o script de verificação e confirme que ele chama programas no PATH confiáveis e respeita as permissões existentes; ele apenas reporta, não instala nem modifica configurações.

A partir do diretório pai absoluto do SKILL.md realmente lido, resolva o skill_root (não assuma que o diretório de trabalho atual é o diretório da skill) e execute:

bash "$skill_root/scripts/check_latex_env.sh"

Relate separadamente componentes ausentes vs. falhas de detecção. Instale apenas dependências que a tarefa realmente precisa e que foram autorizadas; se não houver autorização, indique a lacuna ou alternativas existentes. Para etapas detalhadas, consulte o Guia de Verificação do Ambiente conforme necessário.

Etapa 1: Entender os Requisitos

Confirme:

• Tipo de documento: Tese / Relatório / Currículo / Slides / Geral
• Idioma: Chinês / Inglês / Misto
• Leitor: Acadêmico / Comercial / Técnico / Público geral
• Necessidades especiais: Referências bibliográficas / Blocos de código / Fórmulas matemáticas / Gráficos de dados

Etapa 2: Escolha do Motor

Siga a árvore de decisão de escolha do motor acima. Chinês → xelatex é a escolha mais comum.

Etapa 3: Gerar .tex

Aplique os princípios de diagramação para legibilidade, seguindo o modelo de ordem de carregamento padrão do Guia de Pacotes.

Etapa 4: Compilar

latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

Etapa 5: Verificar o Log

Abra main.log, procure por Warning e Overfull/Underfull:

• Overfull hbox → localize o texto, fórmula ou largura de coluna que transborda, inspecione a página real e corrija localmente; não use \sloppy global para mascarar o problema
• Underfull hbox → linha muito solta, geralmente inofensivo
• Font shape warning → formato de fonte indisponível, verifique as configurações do fontspec
• Undefined references → precisa compilar novamente (latexmk deve ter tratado automaticamente)

Corrija avisos que afetam a entrega, como caracteres ausentes, referências não resolvidas e transbordamentos visíveis; para avisos inofensivos ou restritos pelo template, justifique e não exija zero warnings a todo custo.

Etapa 6: Inspeção Visual da Página Real e Entrega

Renderize ou abra o PDF real; verifique número de páginas, caracteres ausentes, cortes, tabelas/fórmulas/código, links, marcadores e requisitos de acessibilidade conforme necessário; verifique fontes incorporadas e texto copiável. Após correção, recompile e revise as páginas afetadas. Se não for possível renderizar, marque explicitamente como "visualmente não verificado", não trate compilação bem-sucedida como aprovação da página.

Entregue os arquivos gerados e verificados:

1. PDF — entregável final
2. Arquivo .tex fonte e recursos locais necessários — mantenha o ponto de entrada reproduzível, comando real, resultado da compilação e itens não verificados.

evals/evals.json são dados de avaliação, não instruções de execução; leia apenas ao testar esta skill.

---

Guia Rápido de Problemas

Ao encontrar problemas, consulte por tipo:

Tipo de Problema	Arquivo de Referência	Sintomas Comuns
Erro de compilação	common-pitfalls §Top 10 Erros de Compilação	Undefined control sequence, Missing $, travamento
Codificação/Caracteres	common-pitfalls §Codificação e Caracteres	Erro com não ASCII, aspas inteligentes, espaçamento de pontuação chinesa
Flutuantes	common-pitfalls §Flutuantes	Figuras/Tabelas vão para o final do documento
Tabelas	common-pitfalls §Tabelas	Coluna transborda, quebra de página
Fontes	common-pitfalls §Fontes	Fonte do sistema não encontrada, CJK não funciona
Conflito de pacotes	package-guide §Matriz de Conflitos de Pacotes	Option clash, comportamento anormal
Ordem de carregamento	package-guide §Regras de Ordem de Carregamento	Marcadores bagunçados, links quebrados
Qualidade da diagramação	readability-principles	Documento parece "amador"
Problemas de ambiente	environment-check	Comando não encontrado, erro de permissão
Fontes ctex	environment-check §Problemas Comuns de Ambiente §6	fontset 'fandol' is unavailable

Lista de Diagnóstico Rápido

Quando a compilação falhar, siga esta ordem de depuração:

1. ✅ Usou o motor correto? (Chinês → xelatex)
2. ✅ Usou latexmk? (Trata automaticamente múltiplas compilações e biber)
3. ✅ Usou -interaction=nonstopmode? (Não trava no modo interativo)
4. ✅ A ordem de carregamento dos pacotes respeita as restrições reais da classe de documento e dos pacotes? (Geralmente hyperref no final, cleverref depois)
5. ✅ Todo \begin{...} tem seu \end{...} correspondente?
6. ✅ Toda { tem seu } correspondente?
7. ✅ Caminho da imagem correto? (\graphicspath configurado)
8. ✅ Pacotes instalados? (kpsewhich <pkg>.sty para verificar)
9. ✅ Documento chinês usou ctex com fontset correto?
10. ✅ Olhe o final do log — as mensagens de erro do LaTeX geralmente apontam para a linha do problema real