Convertitore online gratuito da ASCIIDOC a EPUB

I lettori di ebook e i sistemi di pubblicazione richiedono comunemente EPUB anziché un file sorgente AsciiDoc. La conversione del sorgente mantiene titoli, paragrafi, elenchi, collegamenti, immagini e altri contenuti strutturati in un formato a flusso variabile che i lettori possono aprire su telefoni, tablet e dispositivi ebook dedicati.

Cos'è il formato ASCIIDOC

AsciiDoc è un formato di markup in testo semplice per documenti strutturati come libri, manuali, documentazione software, articoli e file README. Gli autori scrivono titoli, elenchi, tabelle, collegamenti, blocchi di codice, attributi, riferimenti incrociati e avvisi utilizzando una sintassi testuale leggibile invece di modificare un documento binario.

Le estensioni dei sorgenti più comuni includono .adoc, .asciidoc e .asc. Asciidoctor e Asciidoc utilizzano questi file per generare documenti HTML, PDF, man page ed EPUB. Gli sviluppatori li incontrano generalmente nei repository di documentazione, nei progetti per siti statici, nei progetti basati su Git e nei sistemi di compilazione della documentazione.

Cos'è il formato EPUB

EPUB è un pacchetto ebook basato su ZIP che contiene contenuti XHTML, fogli di stile CSS, metadati, file di navigazione e, facoltativamente, immagini, font e altre risorse. EPUB 3 supporta HTML semantico, layout adattivi, navigazione, audio o video e scrittura da destra a sinistra o verticale, quando il sistema di lettura supporta tali funzionalità.

A differenza di un PDF a pagina fissa, il contenuto EPUB si adatta alle dimensioni dello schermo, alle impostazioni del carattere e all'orientamento del dispositivo di lettura. È adatto alla distribuzione di documentazione o libri di ampio formato tramite lettori di ebook e biblioteche, nonché al controllo del risultato con applicazioni compatibili con EPUB.

Come convertire ASCIIDOC in EPUB

Utilizzare Asciidoctor EPUB3

Asciidoctor EPUB3 è la scelta più diretta perché comprende i costrutti specifici di AsciiDoc invece di trattare il sorgente come markup generico. Installare prima Ruby, se non è già disponibile, quindi installare il convertitore:

gem install asciidoctor-epub3

Dalla directory contenente il file sorgente, eseguire:

asciidoctor-epub3 book.adoc -o book.epub

Sostituire book.adoc con il nome effettivo del file. Il convertitore legge l'intestazione del documento, i file inclusi, le immagini referenziate, gli attributi e gli elementi strutturali, quindi scrive book.epub.

Per un progetto composto da più file, mantenere i sorgenti inclusi e le directory delle immagini nelle relative posizioni previste. Un comando tipico con una directory di lavoro personalizzata è:

asciidoctor-epub3 -D output book.adoc

Impostare i metadati del documento nell'intestazione AsciiDoc prima della conversione, ad esempio:

= Book title
Author Name <author@example.com>
:revnumber: 1.0
:description: A short description
:doctype: book
:toc:
:sectnums:

Utilizzare un attributo per le immagini come :imagesdir: images quando i percorsi delle immagini sono relativi a una directory comune. Verificare che ogni immagine referenziata esista e utilizzi un formato supportato dai sistemi di lettura di destinazione, generalmente JPEG, PNG o SVG.

Convertire senza installare software

È possibile convertire gratuitamente il file sul sito web 101convert.com quando installare Ruby o Asciidoctor non è pratico. Caricare il file AsciiDoc, scegliere EPUB come formato di output, avviare la conversione e scaricare l'ebook generato.

Utilizzare Pandoc come alternativa

Pandoc può convertire direttamente alcuni documenti AsciiDoc:

pandoc book.adoc -o book.epub

Utilizzare Pandoc per documenti relativamente semplici o quando fa già parte del flusso di lavoro di pubblicazione. In genere, Asciidoctor EPUB3 conserva in modo più affidabile gli attributi specifici di AsciiDoc, gli avvisi, le inclusioni e i riferimenti incrociati.

Qualità, compatibilità e limitazioni

EPUB è a flusso variabile, quindi le interruzioni di riga fisse, le posizioni esatte delle pagine e le istruzioni di layout in stile PDF non possono essere conservate in modo coerente. I numeri di pagina, la gestione delle righe isolate a inizio o fine pagina e l'andata a capo variano in base al sistema di lettura e alle impostazioni del carattere dell'utente.

Le estensioni AsciiDoc complesse, i convertitori personalizzati, i diagrammi incorporati, le macro non supportate e la formattazione esclusiva per PDF possono richiedere modifiche manuali. Generare i file dei diagrammi prima della conversione e utilizzare percorsi relativi per tutte le risorse locali.

Aprire il risultato in almeno un lettore EPUB e controllare l'indice, la gerarchia dei titoli, i collegamenti, i blocchi di codice, le tabelle, le immagini e i caratteri speciali. Per la convalida a livello di pacchetto, eseguire EPUBCheck:

epubcheck book.epub

Correggere le risorse mancanti, l'XHTML non valido, gli errori nei metadati e gli avvisi di navigazione prima di distribuire il file.