O epubcheck é o validador de conformidade canônico do EPUB, mantido pelo DAISY Consortium e pela comunidade do W3C. Ele lê seu arquivo contra a especificação EPUB e reporta cada desvio como um ERROR ou um WARNING, cada um etiquetado com um código curto como RSC-005. Os códigos parecem crípticos, mas quase todos são mecânicos: um arquivo que falta, um atributo no lugar errado ou um recurso que não deveria estar ali.
Este guia percorre as famílias de erro que você realmente vai encontrar, o que causa cada uma e sua correção típica. A regra de ouro: resolva primeiro cada linha de ERROR — os erros quebram a conformidade e podem impedir que os leitores abram o livro — e depois trabalhe as linhas de WARNING. A Origami usa o mesmo motor do epubcheck, explica cada achado em linguagem simples e coloca os bloqueadores no topo para que você saiba exatamente o que mexer primeiro.
Erros de esquema: RSC-005
O RSC-005 é o erro mais comum e o que mais assusta. Significa que um arquivo falhou na validação de esquema contra a spec — o XML está bem formado, mas algo nele não é permitido onde você o colocou. Causas frequentes: um atributo que não corresponde a um elemento, um elemento aninhado dentro de outro que não pode contê-lo, um valor fora da lista permitida ou uma propriedade indevida em um itemref do spine.
O texto depois do código é a instrução real — leia-o literalmente. Uma mensagem como “attribute X not allowed here” diz com precisão qual atributo remover ou mover. As correções quase sempre são locais: apague o atributo problemático, reaninhe o elemento ou corrija o valor. Corrija um, execute de novo, e um número surpreendente de linhas RSC-005 costuma se reduzir a uma única causa repetida entre os capítulos.
Recursos que faltam e recursos remotos
O RSC-007 e o RSC-001 significam que o epubcheck seguiu uma referência — uma folha de estilos, imagem, fonte ou uma entrada do spine — e não encontrou o destino dentro do contêiner. A causa quase sempre é uma divergência de caminho ou de maiúsculas: um href aponta para images/Cover.jpg mas o arquivo é images/cover.jpg, ou um arquivo foi renomeado e sua referência não. Os caminhos de EPUB diferenciam maiúsculas; corrija o caminho ou restaure o arquivo que falta.
O RSC-006 marca um recurso remoto — uma URL que aponta para fora do EPUB. A spec só permite referências remotas para um conjunto reduzido de mídias, como áudio e vídeo; todo o resto, incluídas imagens, fontes e folhas de estilo, deve ir empacotado dentro do contêiner. A correção é baixar o recurso, adicioná-lo ao manifest e reapontar a referência para a cópia local.
O documento de pacote: erros OPF
Os erros OPF-* vêm do documento de pacote .opf — o manifest, os metadados e o spine. Os mais frequentes: um arquivo que existe no contêiner mas não está declarado no manifest (ou está declarado mas falta), um spine que referencia um id sem item correspondente no manifest, ou metadados Dublin Core obrigatórios ausentes ou mal formados, como um dc:identifier, dc:title ou dc:language faltante.
Trate o OPF como a fonte da verdade: cada arquivo de conteúdo deve aparecer uma vez no manifest com o media type correto, e cada itemref do spine deve apontar para um id de manifest existente. Adicione a declaração que falta, corrija o media type ou forneça o valor de metadado obrigatório, e a cascata de erros derivados costuma se resolver com isso.
Marcação, navegação e empacotamento
Os erros HTM-* significam que o próprio XHTML está mal formado ou usa algo que a spec não permite — uma tag sem fechar, um namespace não declarado ou uma construção obsoleta. Como o conteúdo EPUB é XHTML, deve ser XML bem formado: cada tag fechada, cada atributo entre aspas. Os erros de NCX e navegação apontam para o sumário — um link quebrado no documento nav, ou um descompasso entre o nav e a ordem do spine.
Os erros PKG-* têm a ver com como o ZIP é montado. O clássico: o arquivo mimetype deve ser a primeira entrada do arquivo e estar guardado sem compressão, sem bytes extras. Se sua ferramenta de compressão o comprimiu ou reordenou as entradas, o epubcheck reclama antes mesmo de ler o conteúdo. Reempacote com o mimetype primeiro e sem compressão — a maioria das ferramentas de exportação de EPUB faz isso sozinha, então isso costuma significar evitar um re-zip manual.
A solução, passo a passo
-
1
Valide e leia o relatório em bruto
Passe seu EPUB pelo epubcheck 5.x e capture a saída completa. Cada linha traz um código, uma severidade e uma localização de arquivo e linha — esse trio é o seu mapa até o ponto exato que precisa ser alterado. Não adivinhe; o relatório já nomeia o arquivo.
-
2
Ordene por severidade, primeiro os bloqueadores
Separe os erros dos warnings. Os erros quebram a conformidade e podem impedir que os leitores abram o livro, então resolva cada um antes de tocar em um único warning. Os warnings são de aviso e podem esperar até que os erros desapareçam.
-
3
Corrija por família, do contêiner para dentro
Agrupe os achados — esquema, recursos, documento de pacote, marcação — e comece pelo contêiner: primeiro mimetype e empacotamento, depois o OPF, e por fim os arquivos de conteúdo. Corrigir uma causa raiz costuma resolver várias linhas de uma vez.
-
4
Valide de novo até o relatório ficar limpo
Execute o epubcheck de novo após cada rodada de correções. Os códigos se encadeiam, então uma correção pode resolver ou revelar outras. Repita até não restar nenhum erro, e então decida quais warnings vale a pena limpar para seus leitores.