Convertitore online gratuito da ASCIIDOC a DOCBOOK

Cos'è il formato ASCIIDOC

AsciiDoc è un formato di markup in testo semplice per la documentazione tecnica, i manuali, i file README, i libri e la documentazione web. Gli autori scrivono file sorgente leggibili con estensioni come .adoc o .asciidoc, utilizzando convenzioni per titoli, elenchi, avvisi, tabelle, collegamenti, immagini, codice sorgente, attributi e inclusioni.

Il software principale utilizzato per creare ed elaborare documenti AsciiDoc è Asciidoctor, un convertitore basato su Ruby con implementazioni per altri runtime. Anche il processore asciidoc meno recente supporta questo formato. Questi file sono presenti in repository software, progetti di documentazione, workflow per siti statici e pacchetti sorgente.

Cos'è il formato DOCBOOK

DocBook è un vocabolario XML per libri strutturati, manuali, articoli, pagine di riferimento e altre pubblicazioni tecniche. Un file DocBook memorizza elementi semantici come <section>, <para>, <itemizedlist>, <programlisting> e <figure>, invece di formattazione specifica della presentazione.

DocBook è utile quando uno strumento di pubblicazione XML, un sistema di gestione dei contenuti, un processo di convalida o un workflow di archiviazione richiede un formato sorgente standardizzato. L'output DocBook può essere trasformato con strumenti come publican, dblatex, FOP o fogli di stile XSLT. DocBook 5 utilizza namespace XML e uno schema moderno; i workflow meno recenti potrebbero richiedere un output DocBook 4.

Come convertire ASCIIDOC in DOCBOOK

Asciidoctor offre la conversione più diretta. Installarlo tramite RubyGems, quindi eseguire:

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

L'opzione -b docbook5 seleziona l'output DocBook 5, -o manual.xml imposta il nome del file di destinazione e manual.adoc è il file sorgente. Per scrivere il risultato accanto al sorgente con un nome derivato automaticamente, utilizzare:

asciidoctor -b docbook5 manual.adoc

Per un progetto completo il cui sorgente include altri file, eseguire il comando dalla directory del progetto e verificare che i percorsi relativi delle inclusioni e delle immagini siano corretti. Asciidoctor risolve i file inclusi durante la conversione, quindi i file mancanti possono produrre errori o un output incompleto. Gli attributi possono essere forniti dalla riga di comando, ad esempio:

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

Utilizzare -b docbook4 solo quando l'applicazione ricevente non è in grado di elaborare DocBook 5:

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

Per una conversione senza installazione, il convertitore integrato di 101convert.com può convertire il file gratuitamente. Scaricare l'XML risultante e ispezionarlo prima di importarlo in un workflow di pubblicazione.

Considerazioni sulla qualità e sulla compatibilità

L'output è una conversione strutturale, non una copia visiva di un documento renderizzato. Gli attributi AsciiDoc, i ruoli personalizzati, le estensioni, le macro, l'HTML incorporato, i diagrammi e i tipi di blocco non supportati potrebbero richiedere modifiche manuali o un'estensione Asciidoctor. Le immagini vengono normalmente referenziate tramite percorso anziché incorporate nell'XML, quindi copiare la directory delle immagini e mantenere le posizioni relative previste dal processore DocBook.

Convalidare il risultato rispetto allo schema richiesto dallo strumento successivo. I documenti DocBook 5 utilizzano un namespace, mentre i documenti DocBook 4 utilizzano una dichiarazione e convenzioni per gli elementi differenti. Verificare inoltre gli elenchi di codice, le tabelle, gli avvisi, i riferimenti incrociati, le note a piè di pagina e i file inclusi, poiché il comportamento specifico del backend può differire dal rendering AsciiDoc originale.