Guida completa per l'utilizzo di AsciiDoc in Linux

Breve:questa guida dettagliata discute i vantaggi dell'utilizzo di AsciiDoc e mostra come installare e utilizzare AsciiDoc in Linux.

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

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

Se ho fatto quella storia, è perché in qualche modo il ciclo si è chiuso. Epistole era un word processor dell'era delle console di testo. Per quanto mi ricordo, c'erano i menu e puoi usare il mouse per selezionare il testo, ma la maggior parte della formattazione è stata eseguita aggiungendo tag non intrusivi nel testo. Proprio come si fa con AsciiDoc. Naturalmente, non è stato 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'uso dei formati di testo per la scrittura:primo, 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. E d'altra parte, puoi in qualche modo ottenere un certo livello di separazione utilizzando modelli e fogli di stile con gli editor WYSIWYG. Sono d'accordo. Ma trovo ancora problemi di presentazione invadenti con gli strumenti della GUI. Mentre, quando usi i formati di testo, puoi concentrarti solo sul contenuto senza che lo stile del carattere o la linea della vedova ti disturbino nella scrittura. Ma forse sono solo io? Tuttavia, non riesco a contare il numero di volte in cui ho smesso di scrivere solo per risolvere qualche piccolo problema di stile e ho perso la mia ispirazione quando sono tornato al testo. Se non sei d'accordo o hai un'esperienza diversa, non esitare a contraddirmi utilizzando la sezione commenti qui sotto!

Ad ogni modo, il mio secondo argomento sarà meno soggetto a interpretazioni personali:i documenti basati su formati testuali sono altamente interoperabili . Non solo puoi modificarli con qualsiasi editor di testo su qualsiasi piattaforma, ma puoi facilmente gestire 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 fare un esempio concreto, quando si utilizza un formato testuale come AsciiDoc, ho bisogno di un solo comando per produrre mailing altamente personalizzato da un documento master, mentre lo stesso lavoro utilizzando un editor WYSIWYG avrebbe richiesto un uso intelligente dei "campi" e passando attraverso diverse schermate della procedura guidata.

Cos'è AsciiDoc?

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

Anche se tale definizione potrebbe sembrare astratta, si tratta di qualcosa di semplice:alcune parole chiave o caratteri nel tuo documento hanno un significato speciale che cambierà il rendering del documento. Questo è esattamente lo stesso concetto dei tag in HTML. Ma una differenza fondamentale con AsciiDoc è la proprietà del documento di origine di rimanere facilmente leggibile dall'uomo.

Controlla il nostro repository GitHub per confrontare come lo stesso output può essere prodotto utilizzando alcuni formati di file di testo comuni:(idea della pagina di manuale del caffè per gentile concessione di http://www.linuxjournal.com/article/1158)

• coffee.man usa il venerabile troff processore (basato sul programma RUNOFF del 1964). È usato principalmente oggi per scrivere pagine man. Puoi provarlo dopo aver scaricato il coffee.* file digitando man ./coffee.man al prompt dei comandi.
• coffee.tex utilizza LaTeX sintassi (1985) per ottenere per lo più lo stesso risultato ma per un output PDF. LaTeX è un programma di composizione particolarmente adatto per pubblicazioni scientifiche grazie alla sua capacità di formattare in modo corretto formule e tabelle matematiche. Puoi produrre il PDF dal sorgente LaTeX usando pdflatex coffee.tex
• coffee.html utilizza 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 che hai visto il risultato, apri quei quattro file usando il tuo editor di testo preferito (nano, vim, SublimeText, gedit, Atom, ...) e confronta i sorgenti:ci sono grandi possibilità che tu sia d'accordo che i sorgenti AsciiDoc siano più facili da leggere — e probabilmente anche per scrivere.

Come installare AsciiDoc in Linux?

AsciiDoc è relativamente complesso da installare a causa delle numerose dipendenze. Intendo complesso se vuoi installarlo dai sorgenti. Per la maggior parte di noi, utilizzare 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 di AsciiDoc. Per ora, tutto ciò di cui hai bisogno ora è un po' di pazienza, dal momento che, almeno sul mio sistema Debian minimo, l'installazione di AsciiDoc richiede 360 ​​MB per essere scaricata (principalmente a causa della dipendenza da LaTeX). Il che, 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 dall'uomo . Quindi, puoi scrivere i tuoi documenti usando l'editor di testo di tua scelta. Ci sono anche editor di testo dedicati. Ma non ne parlerò qui, semplicemente perché non li uso. Ma se ne stai utilizzando uno, non esitare a condividere il tuo feedback utilizzando 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 utilizzerai praticamente in qualsiasi documento. Dal semplice esempio di comando "caffè" citato sopra, potresti vedere:

• titoli in AsciiDoc sono identificati sottostanti con === o --- (a seconda del livello del titolo),
• grassetto gli intervalli di caratteri vengono scritti tra gli inizi,
• e corsivo tra i trattini bassi.

Quelle sono convenzioni piuttosto comuni che risalgono probabilmente all'era della posta elettronica pre-HTML. Inoltre, potresti aver bisogno di altri due costrutti comuni, non illustrati nel mio esempio precedente:collegamenti ipertestuali e immagini inclusione, la cui sintassi è abbastanza autoesplicativa.

// HyperText links
link:http://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog]

// Inline Images
image:https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

// Block Images
image::https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

Ma la sintassi AsciiDoc è molto più ricca di così. Se vuoi di più, posso indicarti quel simpatico cheatsheet di AsciiDoc:http://powerman.name/doc/asciidoc

Come eseguire il rendering dell'output finale?

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

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

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

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 del successivo, a volte si parla di una toolchain .

Anche se spiego qui alcuni dettagli interni di lavoro, devi capire che la maggior parte di ciò ti sarà nascosto. A meno che non sia necessario installare inizialmente gli strumenti o se si desidera perfezionare alcuni passaggi del processo.

In pratica?

Per l'output HTML, hai solo bisogno di asciidoc attrezzo. Per toolchain più complicati, ti incoraggio a utilizzare a2x strumento (parte della distribuzione AsciiDoc) che attiverà i processori necessari in 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à principale di asciidoc rimane lo strumento per trasformare il documento AsciiDoc nel formato DocBook intermedio. DocBook è un formato basato su XML comunemente utilizzato (ma non limitato alla) 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 passaggio successivo della trasformazione. Per questo, qualunque sia il formato di output, il documento intermedio DocBook viene elaborato tramite un processore XSLT per produrre direttamente l'output (ad es. XHTML) o un altro formato intermedio.

Questo è il caso quando si genera un documento PDF in cui il documento DocBook verrà (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à quella 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 che non è necessario per un formato "stream" come HTML.

dblatex o fop?

Poiché ci sono due backend PDF, la solita domanda è "Qual è il migliore?" Qualcosa a cui non posso rispondere per te.

Entrambi i processori hanno pro e contro. E alla fine, la scelta sarà un compromesso tra le tue esigenze e i tuoi gusti. Quindi ti incoraggio a dedicare del tempo a provarli entrambi prima di scegliere il backend che utilizzerai. Se segui il percorso LaTeX, dblatex sarà il back-end utilizzato per produrre il PDF. Mentre sarà 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, ovviamente, tu non sia soddisfatto dell'output predefinito!

Come personalizzare l'output di AsciiDoc?

AsciiDoc in HTML

Fuori dagli schemi, AsciiDoc produce documenti piuttosto carini. Ma prima o poi sarai tu a personalizzarne l'aspetto.

Le modifiche esatte dipenderanno dal back-end che utilizzi. Per l'output HTML, la maggior parte delle modifiche può essere eseguita 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 custom.css file:

h2 {
    color: red;
}

Ed elabora 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

Puoi anche apportare modifiche a un livello più preciso allegando un ruolo attribuire a un elemento. Questo si tradurrà in una classe attributo nell'HTML generato.

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

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

Quindi aggiungi la seguente regola a custom.css file:

.summary {
    font-style: italic;
}

Rigenera 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 poiché il testo di partenza rimarrà identico. Eventualmente utilizzando lo stesso attributo role di cui sopra per identificare le parti che necessitano di un trattamento speciale.

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

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

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

Poiché l'adeguamento del margine è un requisito piuttosto comune, potresti anche voler dare un'occhiata a questo:http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Se i nomi dei parametri sono in qualche modo coerenti tra i due backend, gli argomenti della riga di comando usati per passare quei valori ai backend differiscono tra dblatex e fop . Quindi, ricontrolla prima la tua sintassi se apparentemente non funziona. Ma ad essere onesti, mentre scrivevo questo articolo non sono riuscito a creare il body.font.family parametro funziona con dblatex back-end. Dal momento che di solito uso fop , forse mi sono perso qualcosa? Se hai più indizi a riguardo, sarò più che felice di leggere i tuoi suggerimenti nella sezione commenti alla fine di questo articolo!

Vale la pena menzionare l'uso di caratteri non standard, anche con fop –richiede un po' di lavoro extra. Ma è abbastanza ben documentato sul sito Web di Apache:https://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 utili se hai solo bisogno di regolare 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 permette di scrivere trasformazioni arbitrarie da un documento XML a... qualcos'altro. XML o meno.

Ad esempio, dovrai estendere o modificare il foglio di stile XSL di DocBook per produrre il codice XSL-FO per i nuovi stili che potresti desiderare. E se usi dblatex backend, ciò potrebbe richiedere la modifica del corrispondente foglio di stile XSLT da DocBook a LaTeX. In quest'ultimo caso potresti anche aver bisogno di usare un pacchetto LaTeX personalizzato. Ma non mi concentrerò su questo dato 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, condividi i tuoi suggerimenti e trucchi nella sezione commenti!

Anche concentrandoti solo su fop , Non ho davvero lo spazio qui per dettagliare l'intera procedura. Quindi, ti mostrerò solo le modifiche che potresti utilizzare per ottenere un risultato simile a quello ottenuto con poche righe CSS nell'output HTML sopra. Ovvero:titoli delle sezioni in rosso e un riepilogo paragrafo in corsivo.

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

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:exsl="http://exslt.org/common" exclude-result-prefixes="exsl"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<!-- Import the default DocBook stylesheet for XSL-FO -->
<xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl" />

<!--
    DocBook XSL defines many attribute sets you can
    use to control the output elements
-->
<xsl:attribute-set name="section.title.level1.properties">
    <xsl:attribute name="color">#FF0000</xsl:attribute>
</xsl:attribute-set>

<!--
    For fine-grained changes, you will need to write
    or override XSLT templates just like I did it below
    for 'summary' simpara (paragraphs)
-->
<xsl:template match="simpara[@role='summary']">
  <!-- Capture inherited result -->
  <xsl:variable name="baseresult">
    <xsl:apply-imports/>
  </xsl:variable>

  <!-- Customize the result -->
  <xsl:for-each select="exsl:node-set($baseresult)/node()">
    <xsl:copy>
      <xsl:copy-of select="@*"/>
      <xsl:attribute name="font-style">italic</xsl:attribute>
      <xsl:copy-of select="node()"/>
    </xsl:copy>
  </xsl:for-each>
</xsl:template>


</xsl:stylesheet>

Quindi, devi richiedere a2x utilizzare quel foglio di stile XSL personalizzato per produrre l'output anziché quello predefinito utilizzando il --xsl-file opzione:

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

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

Ma non mentirò, alcune modifiche apparentemente semplici nell'output del documento potrebbero richiedere di dedicare un bel po' di tempo a cercare nei manuali DocBook XML e XSL-FO, esaminare i sorgenti dei fogli di stile ed eseguire un paio di test prima di ottenere finalmente ciò che desideri .

La mia opinione

Scrivere documenti utilizzando un formato di testo ha enormi vantaggi. E se devi pubblicare in HTML, non ci sono molte ragioni per non utilizzando AsciiDoc. La sintassi è pulita e ordinata, l'elaborazione è semplice e la modifica della presentazione, se necessario, richiede principalmente competenze CSS facili da acquisire.

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

Se devi pubblicare in PDF, i vantaggi rimangono gli stessi per lo scrittore. Le cose saranno sicuramente più difficili se è necessario modificare in profondità il layout predefinito. In un ambiente aziendale, ciò significa probabilmente assumere un documento progettato in modo esperto con XSLT per produrre l'insieme di fogli di stile che si adattano al tuo marchio o ai tuoi requisiti tecnici, o che qualcuno nel team acquisisca tali competenze. Ma una volta fatto, sarà un piacere scrivere testo con AsciiDoc. E vedere quegli 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 citarne alcuni. Anche se basato su concetti risalenti agli albori dell'informatica, l'ecosistema del formato di testo leggibile dall'uomo è piuttosto ricco. Probabilmente più ricco era solo 20 anni fa. A riprova, molti moderni generatori di siti Web statici si basano su di essi. Sfortunatamente, questo è fuori dallo scopo di questo articolo. Quindi, facci sapere se vuoi saperne di più!