Conversor online gratuito de AD para RST

RST é exigido por sistemas de documentação como Sphinx e Docutils, enquanto um arquivo AD pode ser um documento de texto simples mais antigo ou uma exportação de texto específica de um aplicativo. Convertê-lo torna o conteúdo legível utilizável em documentação baseada em RST, controle de versão e compilações de sites estáticos.

O que é o formato AD

AD não é um formato de texto padronizado único. A extensão é usada por diferentes ferramentas de documentação legadas, aplicativos personalizados e programas de exportação de texto simples. O programa que cria o arquivo determina se ele contém parágrafos comuns, registros estruturados, marcação, tabelas ou comandos específicos do aplicativo.

Abra o arquivo primeiro em um editor de texto. Se ele contiver texto legível e títulos, listas ou marcações reconhecíveis, geralmente poderá ser adaptado para RST. Se contiver dados binários ou caracteres de controle ilegíveis, identifique o aplicativo original e exporte o conteúdo desse programa para texto simples, HTML ou outro formato documentado antes da conversão.

O que é o formato RST

RST, ou reStructuredText, é um formato de marcação leve usado por Docutils, Sphinx e projetos de documentação em Python. Ele representa títulos com sublinhados, listas com indentação, links com destinos explícitos, código literal com indentação e diretivas como .. note::.

RST continua legível como texto simples e funciona bem com Git, revisão de código, compilações automatizadas de documentação, referências cruzadas, tabelas e saída HTML ou PDF gerada. Ele é preferível quando o sistema de destino aceita especificamente reStructuredText, em vez de Markdown ou HTML.

Como converter efetivamente AD para RST

1. Faça um backup do arquivo source.ad original.
2. Abra-o em um editor compatível com UTF-8, como Visual Studio Code, Notepad++ ou outro editor de texto simples. Confirme a codificação de caracteres e remova os cabeçalhos do aplicativo que não façam parte do documento.
3. Identifique a estrutura do AD: linhas de título, parágrafos, listas, tabelas, links, seções de código e imagens incorporadas. Não existe um analisador AD universal, portanto a sintaxe de origem deve ser interpretada antes de ser mapeada para RST.
4. Reescreva os títulos usando um caractere de sublinhado cujo comprimento corresponda ao do título. Por exemplo:
   Installation ============ Install the package with:: pip install package-name
5. Converta listas simples para marcadores RST, como * item ou #. numbered item. Indente as linhas de continuação de forma consistente.
6. Substitua links, campos e diretivas específicos do AD pelos equivalentes em RST. Use .. image:: filename.png para imagens e .. code-block:: python para código com destaque de sintaxe.
7. Salve o resultado como output.rst usando a codificação UTF-8.
8. Compile ou valide o resultado com Docutils ou Sphinx. Um projeto Sphinx pode ser verificado com sphinx-build -b html . _build/html; erros de conversão e diretivas malformadas aparecerão na saída da compilação.

Para um arquivo AD simples contendo parágrafos comuns, o conversor integrado do 101convert.com pode converter o arquivo online gratuitamente, sem instalar software. Revise o RST gerado depois, pois a conversão automática não consegue inferir de forma confiável marcações AD específicas de aplicativos.

Se o arquivo AD for, na verdade, conteúdo semelhante a Markdown, o Pandoc poderá realizar a conversão da sintaxe depois que o formato de entrada for confirmado: pandoc source.ad -f markdown -t rst -o output.rst. Não use -f markdown apenas porque a extensão é .ad; isso está correto somente quando o conteúdo do arquivo segue a sintaxe Markdown.

Limitações de qualidade e compatibilidade

Parágrafos simples e listas básicas geralmente são transferidos com pouca perda. Níveis de título, listas aninhadas, tabelas, formatação em linha, âncoras, imagens e comandos AD personalizados exigem verificação manual, pois o RST os expressa de maneira diferente.

O RST trata a indentação como sintaxe. Um espaço colocado incorretamente pode alterar uma lista, um bloco literal ou uma diretiva, e uma tabela poderá falhar na compilação se os separadores de coluna forem inconsistentes. Verifique caracteres não ASCII, caminhos relativos de imagens, links externos, notas de rodapé e quaisquer metadados AD após a conversão.

Renomear .ad para .rst não converte o conteúdo. Isso altera apenas o nome do arquivo e pode fazer com que Docutils ou Sphinx relatem erros de análise.