Conversor online gratuito de ASCIIDOC para DOCBOOK

O que é o formato ASCIIDOC

AsciiDoc é um formato de markup em texto simples para documentação técnica, manuais, arquivos README, livros e documentação web. Os autores escrevem arquivos de origem legíveis com extensões como .adoc ou .asciidoc, usando convenções para títulos, listas, admonições, tabelas, links, imagens, código-fonte, atributos e inclusões.

O principal software usado para criar e processar documentos AsciiDoc é o Asciidoctor, um conversor baseado em Ruby com implementações para outros runtimes. O processador asciidoc antigo também oferece suporte ao formato. Esses arquivos são encontrados em repositórios de software, projetos de documentação, fluxos de trabalho de sites estáticos e pacotes de código-fonte.

O que é o formato DOCBOOK

DocBook é um vocabulário XML para livros, manuais, artigos, páginas de referência e outras publicações técnicas estruturadas. Um arquivo DocBook armazena elementos semânticos como <section>, <para>, <itemizedlist>, <programlisting> e <figure>, em vez de formatação específica de apresentação.

DocBook é útil quando uma ferramenta de publicação XML, um sistema de gerenciamento de conteúdo, um processo de validação ou um fluxo de arquivamento exige um formato de origem padronizado. A saída DocBook pode ser transformada com ferramentas como publican, dblatex, FOP ou folhas de estilo XSLT. O DocBook 5 usa namespaces XML e um schema moderno; fluxos de trabalho mais antigos podem exigir saída DocBook 4.

Como converter ASCIIDOC para DOCBOOK

Asciidoctor oferece a conversão mais direta. Instale-o por meio do RubyGems e execute:

gem install asciidoctor
asciidoctor -b docbook5 -o manual.xml manual.adoc

A opção -b docbook5 seleciona a saída DocBook 5, -o manual.xml define o nome do arquivo de destino e manual.adoc é o arquivo de origem. Para gravar o resultado ao lado da fonte com um nome derivado automaticamente, use:

asciidoctor -b docbook5 manual.adoc

Para um projeto completo cuja fonte inclui outros arquivos, execute o comando no diretório do projeto e verifique se os caminhos relativos de inclusão e os caminhos das imagens estão corretos. O Asciidoctor resolve os arquivos incluídos durante a conversão, portanto arquivos ausentes podem produzir erros ou uma saída incompleta. Atributos podem ser fornecidos na linha de comando, por exemplo:

asciidoctor -b docbook5 -a toc -a source-highlighter=highlight.js -o manual.xml manual.adoc

Use -b docbook4 somente quando o aplicativo receptor não puder processar DocBook 5:

asciidoctor -b docbook4 -o manual.xml manual.adoc

Para uma conversão sem instalação, o conversor integrado do 101convert.com pode converter o arquivo gratuitamente. Baixe o XML resultante e inspecione-o antes de importá-lo para um fluxo de trabalho de publicação.

Considerações sobre qualidade e compatibilidade

A saída é uma conversão estrutural, não uma cópia visual de um documento renderizado. Atributos do AsciiDoc, roles personalizados, extensões, macros, HTML incorporado, diagramas e tipos de bloco sem suporte podem exigir ajustes manuais ou uma extensão do Asciidoctor. Normalmente, as imagens são referenciadas por caminho em vez de incorporadas ao XML; portanto, copie o diretório de imagens e preserve os locais relativos esperados pelo processador DocBook.

Valide o resultado em relação ao schema exigido pela próxima ferramenta. Documentos DocBook 5 usam um namespace, enquanto documentos DocBook 4 usam uma declaração e convenções de elementos diferentes. Verifique também listagens de código, tabelas, admonições, referências cruzadas, notas de rodapé e arquivos incluídos, pois o comportamento específico do backend pode diferir da renderização original do AsciiDoc.