Convertidor online gratuito de ASCIIDOC a DOCBOOK

Qué es el formato ASCIIDOC

AsciiDoc es un formato de marcado de texto plano para documentación técnica, manuales, archivos README, libros y documentación web. Los autores escriben archivos fuente legibles con extensiones como .adoc o .asciidoc, utilizando convenciones para encabezados, listas, advertencias, tablas, enlaces, imágenes, código fuente, atributos e inclusiones.

El software principal utilizado para crear y procesar documentos AsciiDoc es Asciidoctor, un conversor basado en Ruby con implementaciones para otros entornos de ejecución. El procesador antiguo asciidoc también admite el formato. Estos archivos se encuentran en repositorios de software, proyectos de documentación, flujos de trabajo de sitios estáticos y paquetes de código fuente.

Qué es el formato DOCBOOK

DocBook es un vocabulario XML para libros estructurados, manuales, artículos, páginas de referencia y otras publicaciones técnicas. Un archivo DocBook almacena elementos semánticos como <section>, <para>, <itemizedlist>, <programlisting> y <figure>, en lugar de un formato específico de presentación.

DocBook es útil cuando una herramienta de publicación XML, un sistema de gestión de contenido, un proceso de validación o un flujo de trabajo de archivado requiere un formato de origen estandarizado. El resultado DocBook puede transformarse con herramientas como publican, dblatex, FOP u hojas de estilo XSLT. DocBook 5 utiliza espacios de nombres XML y un esquema moderno; los flujos de trabajo antiguos pueden requerir resultados en DocBook 4.

Cómo convertir ASCIIDOC a DOCBOOK

Asciidoctor proporciona la conversión más directa. Instálelo mediante RubyGems y, a continuación, ejecute:

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

La opción -b docbook5 selecciona el resultado DocBook 5, -o manual.xml establece el nombre del archivo de destino y manual.adoc es el archivo de origen. Para escribir el resultado junto al archivo de origen con un nombre derivado automáticamente, utilice:

asciidoctor -b docbook5 manual.adoc

Para un proyecto completo cuyo origen incluya otros archivos, ejecute el comando desde el directorio del proyecto y compruebe que las rutas relativas de inclusión y las rutas de las imágenes sean correctas. Asciidoctor resuelve los archivos incluidos durante la conversión, por lo que los archivos faltantes pueden producir errores o resultados incompletos. Los atributos pueden proporcionarse en la línea de comandos, por ejemplo:

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

Utilice -b docbook4 solo cuando la aplicación receptora no pueda procesar DocBook 5:

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

Para realizar una conversión sin instalar nada, el conversor integrado de 101convert.com puede convertir el archivo de forma gratuita. Descargue el XML resultante e inspecciónelo antes de importarlo en un flujo de trabajo de publicación.

Consideraciones de calidad y compatibilidad

El resultado es una conversión estructural, no una copia visual de un documento renderizado. Los atributos de AsciiDoc, los roles personalizados, las extensiones, las macros, el HTML incrustado, los diagramas y los tipos de bloques no compatibles pueden requerir ajustes manuales o una extensión de Asciidoctor. Normalmente, las imágenes se referencian mediante una ruta en lugar de incrustarse en el XML, por lo que debe copiar el directorio de imágenes y conservar las ubicaciones relativas esperadas por el procesador de DocBook.

Valide el resultado con el esquema requerido por la siguiente herramienta. Los documentos DocBook 5 utilizan un espacio de nombres, mientras que los documentos DocBook 4 utilizan una declaración y convenciones de elementos diferentes. Compruebe también los listados de código, las tablas, las advertencias, las referencias cruzadas, las notas al pie y los archivos incluidos, ya que el comportamiento específico del backend puede diferir del renderizado original de AsciiDoc.