baip/skills

Anotações de aula acessíveis a partir de originais manuscritos e digitados

A entrega é um arquivo Markdown por documento, mais um script de desenho de figuras por documento. Um PDF etiquetado e um site são gerados a partir deles pelo conjunto de ferramentas aqui incluído. O Markdown é a única fonte: as correções vão no .md, nunca no .tex ou HTML gerado.

                     ┌─ mkweb.py   → Sphinx + MyST + MathJax → site/
Markdown (*.md) ─────┤
                     └─ md2tex.py  → <class>.cls → lualatex  → PDF junto ao .md

Um projeto se parece com isto:

md2tex.py buildtex.py mkweb.py checkweb.py package.py contents.py   scripts de compilação, executados da raiz
<class>.cls  contents.yaml  CONVENCOES.md  BUILD.md
src/                 aulas: NN_Nome.md, com NN_Nome.tex e .pdf junto a cada um
2026/                tarefas e provas de uma oferta, mesma organização
figures/             fig_<doc>_<NN>_<nome>.svg, e os PDFs feitos a partir deles
scripts/figures_audit.py
scripts/figures/     figlib.py, make_figures_<doc>.py, helpers de dados
originals/  work/    os originais e imagens de página, não versionados

O que está incluído

Caminho	Uso
scripts/init_project.py	criar um novo projeto, ou --update-toolkit em um existente
scripts/render_pages.py	renderizar as páginas de um original (e recortes ampliados) para lê-las
scripts/contact_sheet.py	renderizar figuras SVG alteradas em um único PNG para inspeção e envio
scripts/notation_lint.py	sinalizar compromissos de notação: limites por extenso, anotações descritas, subscritos achatados, letras fora da matemática, blocos alt ruins, glifos que faltam na fonte do PDF
assets/toolkit/	os scripts de compilação e notes.cls, colocados em um projeto pelo init_project.py
assets/templates/	contents.yaml, um exemplo de aula e script de desenho, .gitignore, package.json
references/transcribing.md	leitura de originais, peculiaridades do OneNote, aulas e tarefas, verificações de pré-entrega
references/figures.md	como desenhar figuras que sobrevivem à revisão
references/notation-pass.md	revisar documentos existentes para notação real, sozinho ou com ajudantes paralelos
references/review-and-delivery.md	rodadas de revisão, git, trabalho através de uma ponte de arquivos, publicação
references/conventions.md, references/building.md	tornam-se os CONVENCOES.md e BUILD.md do projeto

0. Configurar ou encontrar o projeto

1. Procure por um projeto existente: contents.yaml, md2tex.py, um *.cls, CONVENCOES.md, BUILD.md. Se estiver lá, leia seu CONVENCOES.md e BUILD.md primeiro e siga-os onde diferirem desta skill, pois eles registram decisões que o autor tomou. Verifique também os commits recentes do próprio projeto: o autor frequentemente revisa documentos manualmente, e essas revisões são o estilo atual da casa (redação do frontmatter, o que os fechamentos mantêm).

2. Caso contrário, crie um:

   python3 <skill>/scripts/init_project.py <pasta> \
       --title "QUI 101 — Química Geral" --short "QUI 101" \
       --class qui101 --author "…" --copyright "…"
   

   Compile o exemplo de aula uma vez para confirmar que a máquina está configurada (BUILD.md lista as instalações), depois remova-o de contents.yaml, src/, scripts/figures/ e figures/.

3. Pergunte o que não puder inferir, em uma rodada: nome do curso e código curto, quais documentos vêm primeiro, onde os originais e o projeto estão (uploads, uma pasta no computador do autor, um repositório git), se deve compilar o PDF e o site em cada rodada, e quem faz push. A menos que instruído em contrário, faça commit localmente e nunca faça push.

4. Instruções permanentes valem para cada rodada posterior até serem revogadas ("não compile", "farei push sozinho").

1. Ler os originais

A extração de texto retorna apenas texto digitado. Escrita à mão e esboços são tinta, então renderize as páginas e leia-as como imagens, ampliando qualquer coisa pequena:

python3 <skill>/scripts/render_pages.py originals/03.pdf work/03
python3 <skill>/scripts/render_pages.py originals/03.pdf work/03 --zoom 5 0.1 0.2 0.9 0.5

Leia references/transcribing.md antes do primeiro documento.

2. Transcrever

Siga o CONVENCOES.md do projeto. As regras mais importantes:

• Onde colocar. Uma aula vai em src/NN_Nome.md; tarefas e provas vão na pasta do ano (2026/tarefa03_solucao.md). Adicione cada uma ao contents.yaml com checked: false. Apenas o autor define como true, o que a publica no site.
• Frontmatter. title, docheading (o único h1), lang, runningfoot, description (" Anotações de aula de <Tópico>: <tópicos>."), subtitle ("<título do curso>."). Os cabeçalhos do corpo começam em ## e nunca pulam um nível. Sem nota "Sobre esta transcrição" e sem marcadores de limite de página: o autor os remove, então não os adicione.
• Soluções de tarefas. Transcreva apenas as soluções, sob ## Problema N e ### Parte (a): <o que encontra>. Quando o autor fornecer o conjunto de problemas (como .tex ou .pdf), use-o para entender as soluções e para a notação, não como texto para converter.
• Matemática: a notação do original, corretamente tipografada. LaTeX em $…$, e $$…$$ dentro de ::: eq. Somas, produtos e integrais carregam seus limites; matrizes e determinantes são tipografados; letras de script são \mathcal{}; índices corridos em itálico, rótulos em redondo; subscritos realmente aninhados (x_{j}, nunca x\, j); palavras em \text{}; sem \left( \right) em volta de uma fração simples a menos que desenhado; \, apenas após uma vírgula em uma lista de subscritos, entre frações adjacentes e antes de um diferencial; {} após um \underbrace seguido por um operador; \exp(…) para um expoente que carrega uma fração.
• Anotações manuais tornam-se notação (\cancel, \underbrace{…}_{0}, chaves rotuladas, \overset{…}{=}, \boxed, barras de avaliação), e tal equação recebe uma forma falada: ::: {.eq alt="…"} contendo exatamente uma equação de exibição, com uma frase simples nomeando as marcas (sem LaTeX, sem aspas duplas). Equações comuns não recebem alt: o MathML do MathJax permite que um leitor navegue por elas.
• A fonte de texto do PDF não possui alguns símbolos (⋮, ①, π, ′, ≪, ≫). Escreva-os como matemática ($\vdots$), e "estado 1" para números circulados. A compilação falha em qualquer caractere ausente.
• Tabelas: apenas tabelas pipe, com uma linha de cabeçalho, sem regras. Coloque uma figura antes de uma tabela longa, nunca imediatamente depois. Mantenha as tabelas estreitas o suficiente para a página (a compilação avisa quando uma é muito larga).
• Blocos: ::: eq, ::: problem, ::: keep, ::: flush, ::: quote, ::: note. Não existe [H].
• Erros no original são transcritos como escritos e sinalizados nas notas de fechamento com a evidência, nunca corrigidos silenciosamente. Quando o autor disser para corrigir um, corrija-o.
• Notas de fechamento (## Notas sobre alterações feitas para acessibilidade) contêm apenas o que o autor precisa verificar ou decidir: possíveis erros, leituras incertas, adições. Sem texto genérico.

Execute python3 <skill>/scripts/notation_lint.py <doc>.md antes de compilar: seus erros devem ser corrigidos, seus avisos verificados contra o original.

3. Redesenhar cada figura

Cada esboço se torna um SVG desenhado por scripts/figures/make_figures_<doc>.py com base em figlib.py, nomeado fig_<doc>_<NN>_<nome>.svg, referenciado do Markdown relativo a si mesmo como ![**Título.** Descrição longa.](../figures/fig_….svg){#fig-<doc>-<NN> width=NNN alt="…"} e citado como [](#fig-<doc>-<NN>). Nunca escreva um número de figura manualmente. Leia references/figures.md antes de desenhar. Em resumo: calcule curvas a partir de equações, centralize-as no gráfico, inicie e termine setas nos objetos, mantenha os rótulos próximos e claros das linhas (place_label em gráficos densos), desenhe acentos e números circulados em vez de digitá-los, dimensione o viewBox para o desenho e atualize a legenda sempre que o desenho mudar.

4. Compilar e verificar

python3 scripts/figures/make_figures_<NN>.py
python3 md2tex.py <nome>                  # ex.: 09_Misturas ou tarefa03_solucao
python3 buildtex.py <nome>                # 12 verificações, mais um aviso de largura excessiva
python3 mkweb.py && python3 checkweb.py   # 9 verificações por página, erros MathJax incluídos
python3 scripts/figures_audit.py
python3 <skill>/scripts/contact_sheet.py work/sheet.png figures/fig_<doc>_*.svg

• Veja a saída. Veja a folha de contato de cada figura alterada e renderize as páginas do PDF que contêm equações, tabelas e figuras alteradas. Envie a folha para o autor.
• Um documento retido com checked: false não está no site. Para testar sua página, compile o site em uma cópia temporária com ele definido como true.
• A verificação 11 ("texto alternativo da fórmula não é LaTeX bruto") falha no TeX Live mais antigo que o tagpdf 1.0. Se falhar na máquina que faz os PDFs publicados, diga isso em vez de ocultá-lo.
• Se o autor disse para não compilar, não escreva a saída da compilação em sua pasta. Uma cópia temporária em outro lugar é aceitável para verificar uma alteração arriscada.
• As verificações são necessárias, não suficientes. Recomende PAC 2024 nos PDFs e uma auditoria WCAG do site antes da publicação.

5. Rodadas de revisão e revisões em lote

Leia references/review-and-delivery.md. Em resumo: sincronize com os arquivos atuais do autor primeiro, faça uma tarefa por marcador mais uma tarefa de verificação, cruze cada ponto com o original, responda perguntas separadamente das edições (não mude nada para uma pergunta até o autor decidir), corrija convenções de todo o projeto no toolkit e no CONVENCOES.md, e relate em uma linha por item.

Quando o autor pedir a mesma revisão em muitos documentos (por exemplo "faça 05-10 corresponder ao que fiz em 01-04"), leia references/notation-pass.md: estude a própria revisão do autor como modelo, faça as partes mecânicas com um script e distribua o trabalho por equação para ajudantes paralelos, dois ou três documentos cada, com um resumo escrito.

6. Entrega

• Edite na máquina do autor quando o projeto estiver lá. Regere os SVGs executando o script de desenho lá, em vez de copiá-los, já que pontes de arquivo podem reescrever imagens em trânsito. Confirme por checksum ao copiar.
• Faça commit com a identidade do próprio autor e uma mensagem listando os itens. Nunca faça push a menos que solicitado, e recuse hooks que peçam para você fazer.
• Se a conexão com o computador do autor cair, faça commit em seu próprio clone e entregue um bundle git (git bundle create x.bundle <cabeça-deles>..main) que eles possam puxar, ou aplique-o quando a conexão retornar.
• python3 package.py compila um arquivo de todo o projeto a partir de contents.yaml, e se recusa enquanto scripts/figures_audit.py falhar.
• Para dar a um projeto um toolkit mais novo: python3 <skill>/scripts/init_project.py <pasta> --update-toolkit.