Guida completa per l'utilizzo di AsciiDoc in Linux

Breve: Questa guida dettagliata illustra i vantaggi dell'uso di AsciiDoc e mostra come installare e utilizzare AsciiDoc in Linux.

Nel corso degli anni ho usato molti strumenti diversi per scrivere articoli, rapporti o documentazione. Penso che tutto sia iniziato per me con Epistole di Luc Barthelet su Apple IIc dall'editore francese Version Soft. Poi sono passato agli strumenti della GUI con l'eccellente Microsoft Word 5 per Apple Macintosh, poi il meno convincente (per me) StarOffice su Sparc Solaris, che era già noto come OpenOffice quando passai definitivamente a Linux. Tutti questi strumenti erano veramente processori di parole.

Ma non sono mai stato veramente convinto dagli editor WYSIWYG. Così ho studiato molti diversi formati di testo più o meno leggibili dall'uomo: troff, HTML, RTF, TeX / LaTeX, XML e infine AsciiDoc, che è lo strumento che utilizzo maggiormente oggi. In effetti, lo sto usando proprio ora per scrivere questo articolo!

Se ho fatto quella storia, era perché in qualche modo il ciclo è chiuso. Epistole era un word-processor dell'era della console di testo. Per quanto mi ricordo, c'erano dei menu e puoi usare il mouse per selezionare il testo - ma la maggior parte della formattazione è stata fatta aggiungendo tag non intrusivi nel testo. Proprio come è fatto con AsciiDoc. Certo, non era il primo software a farlo. Ma è stato il primo che ho usato!

Perché AsciiDoc (o qualsiasi altro formato di file di testo)?

Vedo due vantaggi nell'utilizzo dei formati di testo per la scrittura: in primo luogo, c'è una netta separazione tra il contenuto e la presentazione. Questo argomento è aperto alla discussione poiché alcuni formati di testo come TeX o HTML richiedono una buona disciplina per aderire a tale separazione. D'altra parte, in qualche modo è possibile raggiungere un certo livello di separazione utilizzando modelli e fogli di stile con gli editor WYSIWYG. Sono d'accordo. Ma trovo ancora problemi di presentazione intrusivi con gli strumenti della GUI. Considerando che, quando si utilizzano i formati di testo, è possibile concentrarsi sul contenuto solo senza lo stile del carattere o la linea della vedova che vi disturba nella scrittura. Ma forse sono solo io? Tuttavia, non riesco a contare il numero di volte in cui ho interrotto la mia scrittura solo per risolvere un problema di stile secondario - e avendo perso la mia ispirazione quando sono tornato al testo. Se non sei d'accordo o hai un'esperienza diversa, non esitare a contraddirmi usando la sezione commenti qui sotto!

Ad ogni modo, la mia seconda argomentazione sarà meno soggetta all'interpretazione personale: i documenti basati su formati di testo sono altamente interoperabili . Non solo è possibile modificarli con qualsiasi editor di testo su qualsiasi piattaforma, ma è possibile gestire facilmente le revisioni del testo con uno strumento come git o SVN o automatizzare la modifica del testo utilizzando strumenti comuni come sed, AWK, Perl e così via. Per dare un esempio concreto, quando si utilizza un formato basato su testo come AsciiDoc, ho solo bisogno di un comando per produrre mailing altamente personalizzato da un documento master, mentre lo stesso lavoro con un editor WYSIWYG avrebbe richiesto un uso intelligente dei "campi" e passando attraverso diversi schermi wizard.

Cos'è AsciiDoc?

A rigor di termini, AsciiDoc è un formato di file. Definisce costrutti sintattici che aiuteranno un processore a comprendere la semantica delle varie parti del testo. Solitamente per produrre un output ben formattato.

Anche se questa definizione potrebbe sembrare astratta, questa è una cosa semplice: alcune parole chiave o caratteri nel tuo documento hanno un significato speciale che cambierà il rendering del documento. Questo è lo stesso concetto dei tag in HTML. Ma una delle principali differenze con AsciiDoc è la proprietà del documento sorgente di rimanere facilmente leggibile.

Controlla il nostro repository GitHub per confrontare come è possibile produrre lo stesso output usando pochi formati di file di testo comuni: (idea per la manpage del caffè per gentile concessione di //www.linuxjournal.com/article/1158)

  • coffee.man usa il venerabile processore troff (basato sul programma RUNOFF del 1964). Oggi è usato principalmente per scrivere pagine man. Puoi provarlo dopo aver scaricato i file coffee.* Digitando man ./coffee.man al prompt dei comandi.
  • coffee.tex usa la sintassi LaTeX (1985) per ottenere lo stesso risultato, ma per un output PDF. LaTeX è un programma di composizione tipografica particolarmente adatto per pubblicazioni scientifiche grazie alla sua capacità di formattare in modo gradevole formule e tabelle matematiche. È possibile produrre il PDF dalla sorgente LaTeX utilizzando pdflatex coffee.tex
  • coffee.html sta utilizzando il formato HTML (1991) per descrivere la pagina. Puoi aprire direttamente quel file con il tuo browser web preferito per vedere il risultato.
  • coffee.adoc, infine, utilizza la sintassi AsciiDoc (2002). Puoi produrre sia HTML che PDF da quel file:
 asciidoc coffee.adoc # HTML output a2x --format pdf ./coffee.adoc # PDF output (dblatex) a2x --fop --format pdf ./coffee.adoc # PDF output (Apache FOP) 

Ora hai visto il risultato, apri questi quattro file usando il tuo editor di testo preferito (nano, vim, SublimeText, gedit, Atom, ...) e confronta le fonti: ci sono grandi possibilità che tu sia d'accordo che le fonti di AsciiDoc siano più facili da leggere - e probabilmente anche a scrivere.

Come installare AsciiDoc in Linux?

AsciiDoc è relativamente complesso da installare a causa delle numerose dipendenze. Intendo complesso se si desidera installarlo da fonti. Per la maggior parte di noi, usare il nostro gestore di pacchetti è probabilmente il modo migliore:

 apt-get install asciidoc fop 

o il seguente comando:

 yum install acsiidoc fop 

(fop è richiesto solo se hai bisogno del backend Apache FOP per la generazione di PDF - questo è il backend PDF che uso io stesso)

Maggiori dettagli sull'installazione possono essere trovati sul sito ufficiale AsciiDoc. Per ora, tutto ciò che serve ora è un po 'di pazienza, dal momento che, almeno sul mio sistema Debian minimo, l'installazione di AsciiDoc richiede il download di 360 MB (principalmente a causa della dipendenza da LaTeX). Quale, a seconda della larghezza di banda di Internet, potrebbe darti un sacco di tempo per leggere il resto di questo articolo.

Tutorial AsciiDoc: Come scrivere in AsciiDoc?

L'ho detto più volte, AsciiDoc è un formato di file di testo leggibile. Quindi, puoi scrivere i tuoi documenti usando l'editor di testo che preferisci. Ci sono persino editor di testo dedicati. Ma di questo non parlerò qui semplicemente perché non li uso. Ma se ne stai utilizzando uno, non esitare a condividere il tuo feedback usando la sezione commenti alla fine di questo articolo.

Non ho intenzione di creare un altro tutorial sulla sintassi di AsciiDoc qui: ce ne sono molti già disponibili sul web. Quindi menzionerò solo i costrutti sintattici di base che userete praticamente in qualsiasi documento. Dal semplice esempio di comando "caffè" citato sopra, potresti vedere:

  • i titoli in AsciiDoc sono identificati dal loro sottostante con === o --- (a seconda del livello del titolo),
  • le campate in grassetto sono scritte tra le partenze,
  • e corsivo tra i caratteri di sottolineatura.

Si tratta di convenzioni piuttosto comuni che risalgono probabilmente all'era dell'email pre-HTML. Inoltre, potrebbero essere necessari altri due costrutti comuni, non illustrati nel mio esempio precedente: collegamenti ipertestuali e inclusione di immagini, la cui sintassi è piuttosto auto-esplicativa.

 // HyperText links link://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog] // Inline Images image://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo] // Block Images image:://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo] 

Ma la sintassi di AsciiDoc è molto più ricca di quella. Se vuoi di più, posso indicarti quel bel cheatheet AsciiDoc: //powerman.name/doc/asciidoc

Come rendere l'output finale?

Presumo che tu abbia già scritto del testo seguendo il formato AsciiDoc. Se questo non è il caso, puoi scaricare qui alcuni file di esempio copiati direttamente dalla documentazione di AsciiDoc:

 # Download the AsciiDoc User Guide source document BASE="//raw.githubusercontent.com/itsfoss/asciidoc-intro/master" wget "${BASE}"/{asciidoc.txt, customers.csv} 

Poiché AsciiDoc è leggibile, puoi inviare il testo sorgente di AsciiDoc direttamente a qualcuno via e-mail e il destinatario sarà in grado di leggere quel messaggio senza ulteriori indugi. Ma potresti voler fornire un output più piacevolmente formattato. Ad esempio come HTML per la pubblicazione sul Web (proprio come l'ho fatto per questo articolo). O come PDF per l'utilizzo di stampa o display.

In tutti i casi, è necessario un processore . In effetti, sotto il cofano, avrai bisogno di diversi processori. Perché il tuo documento AsciiDoc verrà trasformato in vari formati intermedi prima di produrre l'output finale. Poiché vengono utilizzati diversi strumenti, l'output di uno è l'input di quello successivo, a volte parliamo di una toolchain .

Anche se spiego qui alcuni dettagli di lavoro interiori, devi capire che la maggior parte di questo sarà nascosta a te. A meno che non sia necessario installare inizialmente gli strumenti o se si desidera ottimizzare alcuni passaggi del processo.

In pratica?

Per l'output HTML, è necessario solo lo strumento asciidoc . Per toolchain più complicati, ti incoraggio a utilizzare lo strumento a2x (parte della distribuzione AsciiDoc) che attiverà i processori necessari nell'ordine:

 # All examples are based on the AsciiDoc User Guide source document # HTML output asciidoc asciidoc.txt firefox asciidoc.html # XHTML output a2x --format=xhtml asciidoc.txt # PDF output (LaTeX processor) a2x --format=pdf asciidoc.txt # PDF output (FOP processor) a2x --fop --format=pdf asciidoc.txt 

Anche se può produrre direttamente un output HTML, la funzionalità di base dello strumento asciidoc rimane quella di trasformare il documento AsciiDoc nel formato intermedio del DocBook. DocBook è un formato basato su XML comunemente usato per (ma non limitato a) la pubblicazione di documentazione tecnica. DocBook è un formato semantico. Ciò significa che descrive il contenuto del tuo documento. Ma non la sua presentazione. Quindi la formattazione sarà il prossimo passo della trasformazione. Per questo, qualunque sia il formato di output, il documento intermedio di DocBook viene elaborato tramite un processore XSLT per produrre direttamente l'output (ad esempio XHTML) o un altro formato intermedio.

Questo è il caso in cui si genera un documento PDF in cui il documento DocBook sarà (a proprio piacimento) convertito come rappresentazione intermedia LaTeX o come XSL-FO (un linguaggio basato su XML per la descrizione della pagina). Infine, uno strumento dedicato convertirà la rappresentazione in PDF.

I passaggi aggiuntivi per le generazioni di PDF sono in particolare giustificati dal fatto che la toolchain deve gestire l'impaginazione per l'output PDF. Qualcosa non è necessario per un formato "stream" come HTML.

dblatex o fop?

Dato che ci sono due backend PDF, la solita domanda è "Qual è il migliore?" Qualcosa che non posso rispondere per te.

Entrambi i processori hanno vantaggi e svantaggi. E alla fine, la scelta sarà un compromesso tra i tuoi bisogni e i tuoi gusti. Quindi ti incoraggio a prenderti il ​​tempo di provare entrambi prima di scegliere il back-end che userete. Se segui il percorso LaTeX, dblatex sarà il back-end utilizzato per produrre il PDF. Mentre sarà preferibile utilizzare Apache FOP se preferisci utilizzare il formato intermedio XSL-FO. Quindi non dimenticare di dare un'occhiata alla documentazione di questi strumenti per vedere quanto sarà facile personalizzare l'output in base alle tue esigenze. A meno che, naturalmente, non si sia soddisfatti dell'output predefinito!

Come personalizzare l'output di AsciiDoc?

AsciiDoc in HTML

Fuori dagli schemi, AsciiDoc produce documenti molto carini. Ma prima o poi avrai cosa personalizzare il loro aspetto.

Le esatte modifiche dipenderanno dal backend che usi. Per l'output HTML, la maggior parte delle modifiche può essere effettuata cambiando il foglio di stile CSS associato al documento.

Ad esempio, supponiamo di voler visualizzare tutte le intestazioni di sezione in rosso, potrei creare il seguente file custom.css :

 h2 { color: red; } 

Ed elaborare il documento usando il comando leggermente modificato:

 # Set the 'stylesheet' attribute to # the absolute path to our custom CSS file asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt 

È anche possibile apportare modifiche ad un livello più elevato allegando un attributo role a un elemento. Questo si tradurrà in un attributo di classe nell'HTML generato.

Ad esempio, prova a modificare il nostro documento di test per aggiungere l'attributo role al primo paragrafo del testo:

 [role="summary"] AsciiDoc is a text document format .... 

Quindi aggiungi la seguente regola al file custom.css :

 .summary { font-style: italic; } 

Ricreare il documento:

 asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt 

  1. et voilà: il primo paragrafo è ora visualizzato in corsivo. Con un po 'di creatività, un po' di pazienza e un paio di tutorial CSS, dovresti essere in grado di personalizzare il tuo documento a tuo piacimento.

AsciiDoc in PDF

La personalizzazione dell'output PDF è un po 'più complessa. Non dal punto di vista dell'autore dal momento che il testo di origine rimarrà identico. Alla fine usando lo stesso attributo di ruolo come sopra per identificare le parti che necessitano di un trattamento speciale.

Ma non puoi più usare i CSS per definire la formattazione per l'output PDF. Per le impostazioni più comuni, ci sono dei parametri che puoi impostare dalla riga di comando. Alcuni parametri possono essere utilizzati sia con dblatex che con i backend fop, altri sono specifici per ciascun backend.

Per l'elenco dei parametri supportati da dblatex, vedi //dblatex.sourceforge.net/doc/manual/sec-params.html

Per l'elenco dei parametri di DocBook XSL, vedi //docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

Poiché la regolazione del margine è un requisito piuttosto comune, puoi anche dare un'occhiata a questo: //docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Se i nomi dei parametri sono alquanto coerenti tra i due backend, gli argomenti della riga di comando utilizzati per passare quei valori ai backend differiscono tra dblatex e fop . Quindi, controlla prima la tua sintassi se, apparentemente, questo non funziona. Ma ad essere onesti, mentre scrivevo questo articolo non ero in grado di far funzionare il parametro body.font.family con il backend dblatex . Dato che di solito uso il fop, forse mi sono perso qualcosa? Se hai più indizi su questo, sarò più che felice di leggere i tuoi suggerimenti nella sezione commenti alla fine di questo articolo!

Vale la pena menzionare l'utilizzo di caratteri non standard, anche con il fop, è necessario un lavoro extra. Ma è abbastanza ben documentato sul sito web di Apache: //xmlgraphics.apache.org/fop/trunk/fonts.html#bulk

 # XSL-FO/FOP a2x -v --format pdf \ --fop \ --xsltproc-opts='--stringparam page.margin.inner 10cm' \ --xsltproc-opts='--stringparam body.font.family Helvetica' \ --xsltproc-opts='--stringparam body.font.size 8pt' \ asciidoc.txt # dblatex # (body.font.family _should_ work, but, apparently, it isn't ?!?) a2x -v --format pdf \ --dblatex-opts='--param page.margin.inner=10cm' \ --dblatex-opts='--stringparam body.font.family Helvetica' \ asciidoc.txt 

Impostazione a grana fine per la generazione di PDF

I parametri globali sono belli se hai solo bisogno di modificare alcune impostazioni predefinite. Ma se vuoi mettere a punto il documento (o cambiare completamente il layout) avrai bisogno di qualche sforzo in più.

Al centro dell'elaborazione di DocBook c'è XSLT. XSLT è un linguaggio informatico, espresso in notazione XML, che consente di scrivere trasformazioni arbitrarie da un documento XML a ... qualcos'altro. XML o no.

Ad esempio, sarà necessario estendere o modificare il foglio di stile XSL di DocBook per produrre il codice XSL-FO per i nuovi stili desiderati. E se si utilizza il back - end dblatex, potrebbe essere necessario modificare il foglio di stile XSLT DocBook-to-LaTeX corrispondente. In quest'ultimo caso potrebbe essere necessario utilizzare un pacchetto LaTeX personalizzato. Ma non mi concentrerò su ciò dal momento che dblatex non è il backend che uso io stesso. Posso solo indicarti la documentazione ufficiale se vuoi saperne di più. Ma ancora una volta, se hai familiarità con questo, per favore condividi i tuoi consigli e trucchi nella sezione commenti!

Anche se mi concentro solo su FOP, non ho davvero la stanza qui per dettagliare l'intera procedura. Quindi, ti mostrerò semplicemente le modifiche che potresti utilizzare per ottenere un risultato simile a quello ottenuto con poche righe CSS nell'output HTML sopra. Cioè: titoli di sezione in rosso e un paragrafo di riepilogo in corsivo.

Il trucco che uso qui è creare un nuovo foglio di stile XSLT, importando il foglio di stile originale di DocBook, ma sostituendo gli insiemi di attributi o il modello per gli elementi che vogliamo modificare:

  #FF0000 italic 

Quindi, devi richiedere a2x di usare quel foglio di stile XSL personalizzato per produrre l'output piuttosto che quello predefinito usando l'opzione --xsl-file :

 a2x -v --format pdf \ --fop \ --xsl-file=./custom.xsl \ asciidoc.txt 

Con un po 'di familiarità con XSLT, i suggerimenti forniti qui e alcune domande sul tuo motore di ricerca preferito, penso che dovresti essere in grado di iniziare a personalizzare l'output XSL-FO.

Ma non mentirò, alcuni cambiamenti apparentemente semplici nell'output del documento potrebbero richiedere di passare un po 'di tempo a cercare tra i manuali DocBook XML e XSL-FO, esaminare le fonti dei fogli di stile e eseguire un paio di test prima di ottenere finalmente quello che vuoi .

La mia opinione

Scrivere documenti usando un formato di testo ha enormi vantaggi. E se hai bisogno di pubblicare in HTML, non ci sono molte ragioni per non usare AsciiDoc. La sintassi è pulita e ordinata, l'elaborazione è semplice e, se necessario, la modifica della presentazione richiede per lo più l'acquisizione di competenze CSS.

E anche se non si utilizza direttamente l'output HTML, l'HTML può essere usato oggi come un formato di interscambio con molte applicazioni WYSIWYG. Ad esempio, questo è stato fatto qui: ho copiato l'output HTML di questo articolo nell'area di edizione di WordPress, conservando così tutta la formattazione, senza dover digitare nulla direttamente in WordPress.

Se è necessario pubblicare in PDF, i vantaggi rimangono gli stessi per lo scrittore. Le cose saranno sicuramente più difficili se è necessario modificare il layout predefinito in profondità. In un ambiente aziendale, questo probabilmente significa assumere un documento progettato con XSLT per produrre l'insieme di fogli di stile che soddisferanno i requisiti tecnici o di branding o che qualcuno nel team acquisisca tali competenze. Ma una volta fatto sarà un piacere scrivere un testo con AsciiDoc. E vedere questi scritti convertiti automaticamente in bellissime pagine HTML o documenti PDF!

Infine, se trovi AsciiDoc troppo semplicistico o troppo complesso, puoi dare un'occhiata ad altri formati di file con obiettivi simili: Markdown, Textile, reStructuredText o AsciiDoctor per nominarne alcuni. Anche se basato su concetti che risalgono ai primi anni dell'informatica, l'ecosistema in formato testo leggibile dall'uomo è piuttosto ricco. Probabilmente più ricco era solo 20 anni fa. Come prova, molti generatori di siti Web statici moderni si basano su di essi. Sfortunatamente, questo è fuori dallo scopo di questo articolo. Quindi, facci sapere se vuoi saperne di più!

Raccomandato

8 consigli e trucchi Vim che ti renderanno un utente Pro
2019
Unity Editor è ora ufficialmente disponibile per Linux
2019
5 migliori software di gestione foto di Linux
2019