Dez ferramentas e um comando que diz qual delas está faltando

Uma ferramenta faltando raramente dá erro. Dá um resultado vazio.

Já aconteceu na nossa casa. Um passo da publicação rodava dentro de um contêiner que não tinha o pdfinfo. O passo que contava as páginas do PDF simplesmente sumia, sem aviso. O livro saía sem a informação, e ninguém via.

Por isso o ambiente de produção de livro merece uma conferência própria. Neste artigo você instala o compilador, o editor e as ferramentas de prova. No fim, roda um script que lista o que está presente, com a versão, e o que falta.

Dois ambientes, não um

A produção de um miolo usa dois grupos de ferramentas, e eles não precisam morar no mesmo lugar.

Compilar. O que transforma o texto em PDF: o compilador Typst e as fontes do livro.

Provar. O que mede o PDF depois de pronto: o poppler (pdfinfo, pdftotext, pdffonts, pdftoppm), o Ghostscript, o qpdf, a biblioteca Python pikepdf, e, para capa e conversões, o potrace, o ImageMagick e o Pandoc.

No nosso serviço, que roda em um contêiner, só o primeiro grupo existe. As provas rodam na máquina de trabalho, fora do contêiner. Foi essa separação, e o esquecimento dela, que gerou o problema do pdfinfo ausente. A regra é simples. Todo passo que mede um arquivo roda onde as ferramentas de prova estão.

Passo 1: o compilador

O site do Typst indica estes caminhos de instalação:

Para fixar uma versão, baixe o binário da página de lançamentos do projeto: o comando cargo install instala a mais recente. A versão que usamos está na matriz de versões. Confirme com:

typst --version

O Typst tem licença Apache-2.0, segundo o repositório oficial, e é gratuito.

Passo 2: o editor

Você pode escrever o .typ em qualquer editor de texto. A extensão Tinymist, para o VS Code, acrescenta visualização do PDF ao lado do texto, ajuda de sintaxe e compilação ao salvar. Ela também tem licença Apache-2.0. A instalação é pela aba de extensões do editor, ou pelo arquivo .vsix das versões publicadas no repositório dela.

A alternativa é o aplicativo web do Typst, que dispensa instalação. O plano gratuito tem 200 MB e 100 arquivos por projeto, segundo o site. Nele, você envia as suas fontes para o projeto. Há uma limitação que não conseguimos confirmar. A documentação consultada descreve as entradas por linha de comando (--input) só para o compilador local. Ela não diz se o aplicativo web as aceita.

Passo 3: as ferramentas de prova

No Ubuntu ou Debian, estes são os pacotes que usamos:

sudo apt install poppler-utils ghostscript qpdf potrace imagemagick pandoc
python3 -m pip install pikepdf numpy pillow

No macOS, o Homebrew costuma ter fórmulas com os mesmos nomes (poppler, ghostscript, qpdf, potrace, imagemagick, pandoc): confirme com brew search. No Windows, a rota mais curta é usar o WSL com Ubuntu e repetir os comandos acima. Não testamos o Windows direto, então não prometemos que cada ferramenta tenha instalador equivalente.

Passo 4: o script que confere o ambiente

Este script verifica cada ferramenta, imprime a versão e lista as fontes que o Typst enxerga:

#!/bin/bash
# Confere o ambiente de produção de miolo: ferramentas, versões e um compile de teste.
ok=0; falta=0
for c in typst pdfinfo pdftotext pdffonts pdftoppm gs qpdf potrace convert pandoc; do
  if command -v "$c" >/dev/null 2>&1; then ok=$((ok+1)); printf "OK     %-10s" "$c"
    case $c in typst|pandoc|gs|qpdf|potrace) "$c" --version 2>&1 | head -1;; pdfinfo|pdftotext) "$c" -v 2>&1 | head -1;; convert) convert -version | head -1;; *) echo;; esac
  else falta=$((falta+1)); echo "FALTA  $c"; fi
done
python3 - <<'PY'
import importlib
for m in ("pikepdf", "numpy", "PIL"):
    try:
        mod = importlib.import_module(m); print("OK     python:%-8s %s" % (m, getattr(mod, "__version__", "?")))
    except Exception as e:
        print("FALTA  python:%s" % m)
PY
echo "fontes que o Typst enxerga (use --font-path para somar uma pasta):"; typst fonts 2>/dev/null | head -5
echo "ferramentas presentes: $ok | ausentes: $falta"

No nosso servidor, a saída listou as dez ferramentas, com versões iguais às da matriz. Listou também as bibliotecas Python pikepdf, numpy e Pillow. Em uma máquina nova, cada FALTA é uma instalação a fazer, antes de qualquer PDF.

O que cada ferramenta faz, e o que falha sem ela

Nenhuma das ausências dá erro de compilação. Esse é o ponto.

Passo 5: o teste de fumaça

Com tudo instalado, compile qualquer arquivo pequeno e meça:

typst compile livro.typ livro.pdf
pdfinfo livro.pdf

Se pdfinfo imprimir o tamanho da página, as duas pontas funcionam: compilar e provar. O arquivo mínimo para esse teste está no artigo Typst no lugar do InDesign.

Um detalhe que assusta, mas não é problema. O poppler pode imprimir Syntax Error: Suspects object is wrong type ao ler PDFs gerados pelo Typst. Nos nossos testes, a leitura seguiu normal.

O erro que custa caro

Confundir o ambiente que compila com o ambiente que prova. É o caso do contêiner. Outro erro parecido é confiar na versão que "deve estar instalada". Versão diferente muda resultado: em um teste nosso, duas versões do compilador deram o mesmo número de páginas e layout diferente em 71 de 158 páginas. A matriz existe para isso.

Quando NÃO usar este caminho

Se você só vai escrever e ler o livro na tela, sem imprimir, basta o compilador (ou o aplicativo web). As ferramentas de prova só entram quando há arquivo para gráfica.

Alternativa sem o nosso ambiente

Tudo neste artigo é do seu ambiente, e não do nosso. Se preferir não instalar nada, o aplicativo web cobre a escrita e a compilação. Para provar o PDF sem instalar nada, uma gráfica ou um serviço de preflight comercial pode ler o arquivo. Mas essa é uma segunda leitura, e não a sua.

O que o Claude faz hoje, e como fazer sem ele

Hoje o Claude instala e confere o ambiente da máquina de trabalho e relata o que falta. Sem ele, o script do passo 4 faz exatamente essa conferência.

Onde entra na operação

É o passo zero da esteira, antes do primeiro arquivo. O desenho completo está em Como produzimos o miolo de um livro profissional sem InDesign. A escolha das fontes, que também se instala, é o assunto de fontes para livro.

Versões usadas neste artigo: veja a matriz de versões.