Ler documentação técnica offline no iPad

A maioria das ferramentas de documentação exporta HTML estático. MkDocs, Sphinx, Docusaurus, Hugo, uma referência de API gerada: o resultado é uma pasta autónoma, concebida para funcionar sem ligação. É exatamente o que precisa num avião, na cave de um centro de dados ou num cliente cujo wifi recusa o seu portátil.

Falta abri-la no tablet que levou.

Porque o PDF não é a resposta

O reflexo é exportar a documentação para PDF. Funciona, e para um documento curto é muitas vezes a escolha certa. Mas uma documentação técnica perde muito na conversão.

• A navegação lateral desaparece, substituída por um deslocamento de várias centenas de páginas.
• As ligações entre secções tornam-se, na melhor das hipóteses, remissões de página, na pior texto morto.
• O realce de sintaxe e os blocos de código recolhíveis nem sempre sobrevivem.
• Cada atualização obriga a refazer a exportação.

Ora a exportação HTML já existe, e contém tudo isso.

Manter a documentação tal como foi gerada

O Pagira abre a pasta de exportação como o faria um navegador: a barra lateral, as ligações entre páginas, o realce do código. Consulta a documentação, não uma fotografia dela.

1. Copie a pasta de exportação para o Ficheiros ou para o iCloud Drive.
2. Abra-a com o Pagira.
3. Navegue como no site: a barra de ferramentas dá retroceder, avançar e recarregar.

iCloud Drive e a questão do offline

Uma documentação gerada pesa muitas vezes várias centenas de megabytes, imagens e tipos de letra incluídos. Colocada no iCloud Drive, descarrega enquanto lê, sem espera antes de a primeira página aparecer.

Antes de uma deslocação, descarregue uma cópia offline permanente. A transferência é retomável, portanto uma quebra não recomeça do início, e um aviso deixa claro o que continua consultável sem rede. Ver transmitir do iCloud Drive ou guardar offline.

Preparar as páginas de que vai precisar

Há o offline sofrido e o offline preparado. Se já sabe que secções vai consultar, guarde-as na lista de leitura antes de partir. Cada item é conservado como um instantâneo completo e não como um marcador, pelo que continua legível mesmo que a pasta de origem se mova. Ver a lista de leitura.

O caso das documentações mistas

Uma documentação de empresa mistura quase sempre páginas HTML e PDF: uma especificação, um esquema de arquitetura, um anexo contratual. Ambos abrem na mesma app, e uma ligação de uma página para um PDF abre ali mesmo.

Perguntas frequentes

E uma documentação de vários gigabytes?

A transmissão a partir do iCloud evita ter de descarregar tudo de uma vez. Para o offline completo, o limite é o espaço disponível no dispositivo.

A minha documentação é confidencial

Nada é enviado. Tudo é apresentado localmente, o que é justamente o argumento face a um serviço online de visualização de documentos.

Posso consultá-la também no iPhone?

Sim, uma só app cobre ambos, e os itens recentes permitem retomar um documento começado no outro dispositivo.

Como a abro a partir de outra ferramenta?

Pela folha de partilha, com Abrir com o Pagira, a partir do Ficheiros ou de qualquer app. Ver abrir a partir de qualquer lado.