Convertitore online gratuito da AD a DOCBOOK

Che cos'è il formato AD

Nella categoria File di testo, AD identifica generalmente un file sorgente AsciiDoc. I file AsciiDoc contengono markup in testo semplice per titoli, elenchi, tabelle, collegamenti, immagini, admonition, codice sorgente e metadati del documento; la stessa sintassi viene comunemente memorizzata anche con le estensioni .adoc o .asciidoc.

I file con estensione .ad vengono creati o modificati con i processor AsciiDoc, Asciidoctor e i normali editor di testo. La sola estensione non garantisce il processor o la versione della sintassi esatti, quindi controlla le prime righe per individuare attributi come :doctype:, :toc: o direttive include prima della conversione.

Che cos'è il formato DOCBOOK

DocBook è un vocabolario XML per la documentazione tecnica strutturata. Rappresenta elementi del documento come capitoli, sezioni, paragrafi, procedure, tabelle, citazioni, elenchi di programmi e riferimenti incrociati indipendentemente dal layout di pagina finale.

DocBook è adatto quando una pipeline di publishing utilizza strumenti come xsltproc, Jing, Saxon o stylesheet DocBook per produrre HTML, PDF, EPUB o pagine man. La sua struttura XML facilita inoltre la convalida, l'indicizzazione e le successive trasformazioni di formato rispetto al lavoro con markup orientato alla presentazione.

Come convertire AD in DOCBOOK

Asciidoctor è lo strumento di conversione desktop più diretto perché legge AsciiDoc e include un backend DocBook.

1. Installa Asciidoctor utilizzando il package manager del tuo sistema operativo o la Ruby gem, quindi verificalo con asciidoctor --version.
2. Inserisci il file sorgente e tutte le immagini, i file inclusi o i file degli attributi referenziati nei percorsi relativi previsti.
3. Esegui asciidoctor -b docbook5 -o output.xml input.ad. L'opzione -b docbook5 seleziona DocBook 5 XML, mentre -o imposta il nome del file di output.
4. Per un workflow DocBook 4, usa asciidoctor -b docbook -o output.xml input.ad se il backend è disponibile nella versione installata.
5. Convalida il risultato con lo schema DocBook o con il comando di convalida richiesto dal tuo sistema di publishing. Apri output.xml in un editor compatibile con XML per verificare include non risolti, percorsi delle immagini non validi e attributi malformati.

Per una conversione grafica senza installare software, carica il file AD su 101convert.com, seleziona DOCBOOK come formato di destinazione e scarica l'XML generato. Questa soluzione è adatta per un file occasionale quando il sorgente utilizza funzionalità AsciiDoc standard e non dipende da file include locali.

Considerazioni sulla qualità e sulla compatibilità

Il markup AsciiDoc non viene mappato perfettamente in DocBook quando il sorgente utilizza estensioni personalizzate, attributi specifici del backend, blocchi passthrough, macro o script incorporati. Dopo la conversione, controlla admonition, tabelle, callout, note a piè di pagina, riferimenti incrociati ed elenchi di codice sorgente.

Le immagini relative e le direttive include:: richiedono l'accesso alla struttura di directory originale; un convertitore che riceve solo il file principale potrebbe omettere tali risorse o lasciare riferimenti non risolti. L'output DocBook è XML, non un PDF o una pagina web finiti, quindi applica lo stylesheet DocBook appropriato o lo strumento di publishing successivo.