Convertitore online gratuito da ASCIIDOC a ORG

Che cos'è il formato ASCIIDOC

AsciiDoc è un formato di markup in testo semplice per la documentazione tecnica, i manuali, i file README, i libri e i siti web. I file utilizzano comunemente le estensioni .adoc o .asciidoc e vengono creati con Asciidoctor, il processore AsciiDoc originale, sistemi di documentazione come Antora o qualsiasi editor di testo.

AsciiDoc supporta titoli gerarchici, attributi, riferimenti incrociati, tabelle, avvisi, elenchi di codice sorgente, immagini, inclusioni, condizionali ed estensioni per blocchi. La sua sintassi è più espressiva rispetto al markup leggero di base, ma diverse di queste funzionalità non hanno un equivalente diretto in Org.

Che cos'è il formato ORG

Org è un formato di markup in testo semplice associato alla modalità Org di Emacs. I file Org utilizzano l'estensione .org e combinano titoli strutturati con stati TODO, tag, proprietà, tabelle, blocchi di codice sorgente, link, citazioni, pianificazione e dati dell'agenda.

Org è utile quando il documento convertito deve essere modificato in Emacs, interrogato con l'agenda di Org o con strumenti di ricerca, esportato in HTML o PDF oppure gestito come parte di un progetto di programmazione alfabetica. La sintassi dei titoli utilizza gli asterischi, i blocchi di codice sorgente utilizzano #+BEGIN_SRC e #+END_SRC e i link utilizzano la notazione tra parentesi quadre tipica di Org.

Come convertire effettivamente ASCIIDOC in ORG

Il workflow desktop più affidabile consiste nell'utilizzare Asciidoctor seguito da Pandoc. Asciidoctor risolve la sintassi e le inclusioni di AsciiDoc, mentre Pandoc converte la struttura DocBook risultante in Org.

1. Installa Asciidoctor e Pandoc utilizzando i pacchetti appropriati per il tuo sistema operativo.
2. Dalla directory che contiene il file sorgente, genera DocBook e passalo a Pandoc tramite una pipe:

asciidoctor -b docbook5 -o - input.adoc | pandoc -f docbook -t org -o output.org

Il comando legge input.adoc, scrive l'output DocBook di Asciidoctor sullo standard output e salva il risultato Org come output.org. Sostituisci i nomi dei file secondo necessità; utilizza la stessa directory di lavoro quando il documento contiene percorsi relativi per immagini o inclusioni.

Per un workflow in più fasi, salva il file intermedio in modo da poterlo esaminare:

asciidoctor -b docbook5 -o intermediate.xml input.adoc
pandoc -f docbook -t org intermediate.xml -o output.org

Apri output.org in Emacs e verifica i livelli dei titoli, i link, i nomi dei linguaggi del codice sorgente, le tabelle, i percorsi delle immagini e tutti i metadati Org che devono essere aggiunti manualmente. Per una conversione senza installazione, utilizza il convertitore gratuito su 101convert.com e scarica il file .org risultante.

Limitazioni relative a qualità e compatibilità

I contenuti strutturali vengono generalmente convertiti correttamente, ma gli attributi AsciiDoc, le sezioni condizionali, i ruoli personalizzati, i blocchi passthrough, le estensioni per diagrammi e le macro specifiche del processore possono essere omessi o ridotti a testo ordinario. Asciidoctor espande le inclusioni standard durante il primo comando, ma i file inclusi devono essere disponibili e referenziati con percorsi relativi utilizzabili.

Gli avvisi e i blocchi stilizzati di AsciiDoc potrebbero non corrispondere a costrutti Org nativi; esaminali dopo la conversione. Le tabelle possono richiedere un allineamento o una riscrittura manuale e i riferimenti alle immagini continuano a dipendere dai file delle risorse originali. DocBook è una rappresentazione intermedia, quindi lo stile di AsciiDoc e il comportamento specifico del backend non vengono preservati esattamente.

Se il sorgente utilizza estensioni Asciidoctor personalizzate, converti prima un campione rappresentativo e confronta il file Org generato con l'originale prima di elaborare un insieme più ampio di documenti.