Convertidor online gratuito de AD a RST

RST es necesario para sistemas de documentación como Sphinx y Docutils, mientras que un archivo AD puede ser un documento de texto sin formato antiguo o una exportación de texto específica de una aplicación. Convertirlo hace que el contenido legible pueda utilizarse en documentación basada en RST, sistemas de control de versiones y compilaciones de sitios estáticos.

Qué es el formato AD

AD no es un formato de texto estandarizado único. La extensión es utilizada por distintas herramientas de documentación antiguas, aplicaciones personalizadas y programas de exportación de texto sin formato. El programa que crea el archivo determina si este contiene párrafos normales, registros estructurados, marcado, tablas o comandos específicos de la aplicación.

Abra primero el archivo en un editor de texto. Si contiene texto legible y títulos, listas o marcado reconocibles, normalmente puede adaptarse a RST. Si contiene datos binarios o caracteres de control ilegibles, identifique la aplicación original y exporte el archivo desde ese programa a texto sin formato, HTML u otro formato documentado antes de convertirlo.

Qué es el formato RST

RST, o reStructuredText, es un formato de marcado ligero utilizado por Docutils, Sphinx y proyectos de documentación de Python. Representa los títulos mediante subrayados, las listas mediante sangría, los enlaces mediante destinos explícitos, el código literal mediante sangría y las directivas, como .. note::.

RST sigue siendo legible como texto sin formato y funciona bien con Git, las revisiones de código, las compilaciones automatizadas de documentación, las referencias cruzadas, las tablas y la generación de archivos HTML o PDF. Es preferible cuando el sistema de destino acepta específicamente reStructuredText en lugar de Markdown o HTML.

Cómo convertir realmente AD a RST

1. Cree una copia de seguridad del archivo original source.ad.
2. Ábralo en un editor compatible con UTF-8, como Visual Studio Code, Notepad++ u otro editor de texto sin formato. Confirme la codificación de caracteres y elimine los encabezados de la aplicación que no formen parte del documento.
3. Identifique la estructura de AD: líneas de título, párrafos, listas, tablas, enlaces, secciones de código e imágenes incrustadas. No existe un analizador universal de AD, por lo que la sintaxis de origen debe interpretarse antes de poder asignarla a RST.
4. Reescriba los títulos utilizando un carácter de subrayado cuya longitud coincida con la del título. Por ejemplo:
   Installation ============ Install the package with:: pip install package-name
5. Convierta las listas simples a marcadores de RST, como * item o #. numbered item. Indente las líneas de continuación de forma coherente.
6. Reemplace los enlaces, campos y directivas específicos de AD por equivalentes de RST. Utilice .. image:: filename.png para las imágenes y .. code-block:: python para el código con resaltado de sintaxis.
7. Guarde el resultado como output.rst utilizando la codificación UTF-8.
8. Compile o valide el resultado con Docutils o Sphinx. Un proyecto de Sphinx puede comprobarse con sphinx-build -b html . _build/html; los errores de conversión y las directivas con formato incorrecto aparecerán en la salida de compilación.

Para un archivo AD simple que contenga párrafos normales, el convertidor integrado de 101convert.com puede convertir el archivo en línea de forma gratuita y sin instalar software. Revise el RST generado posteriormente, ya que la conversión automática no puede inferir de forma fiable el marcado AD específico de una aplicación.

Si el archivo AD contiene en realidad contenido similar a Markdown, Pandoc puede realizar la conversión de sintaxis después de confirmar el formato de entrada: pandoc source.ad -f markdown -t rst -o output.rst. No utilice -f markdown simplemente porque la extensión sea .ad; solo es correcto cuando el contenido del archivo sigue la sintaxis de Markdown.

Limitaciones de calidad y compatibilidad

Los párrafos normales y las listas básicas suelen transferirse con poca pérdida. Los niveles de título, las listas anidadas, las tablas, el formato en línea, los anclajes, las imágenes y los comandos personalizados de AD requieren una revisión manual, ya que RST los expresa de forma diferente.

RST trata la sangría como sintaxis. Un espacio colocado incorrectamente puede cambiar una lista, un bloque literal o una directiva, y una tabla puede no compilarse si los separadores de sus columnas no son coherentes. Compruebe los caracteres que no sean ASCII, las rutas relativas de las imágenes, los enlaces externos, las notas al pie y cualquier metadato de AD después de la conversión.

Cambiar el nombre de .ad a .rst no convierte el contenido. Solo cambia el nombre del archivo y puede hacer que Docutils o Sphinx informen de errores de análisis.