Markdown e YAML, due formati semplici per testi e dati

21 Aug 2017

Se la memoria non mi inganna, le mie prime esperienze con un computer prevedevano l’uso di Word su un computer con MS-DOS.
Purtroppo l’umanità ha perso ogni traccia delle mie prime fatiche letterarie, sta di fatto che dai primi anni Novanta e per circa un ventennio è stato per me del tutto naturale affidarmi a un programma WYSIWYG quando dovevo scrivere testi, dai primissimi tentativi come scrittore di fantascienza, alle tesine per l’Università.

Prologo

Per capire come e perché abbandonare Word & co., vivendo molto più felici, proseguite la lettura.
Se invece il prologo vi spaventa potete saltarlo senza vergogna, ma vi perdete un po’ di ciccia.

WYSIWYG?!

what you see is (all!) you get¹

L’acronimo sta per «What you see is what you get» e racchiude, parlando di editor di testo, tutta la stirpe di Microsoft Word, Writer di LibreOffice/Open Office e un po’ tutti quei programmi che vengono più appropriatamente chiamati word processor. L’acronimo descrive con efficacia la modalità con cui il programma ci consente di visualizzare a schermo il risultato finale, man mano che procediamo alla composizione (del testo).

Se l’approccio WYSIWYG sembra proprio una bella idea, nel tempo ha sollevato più di una perplessità. Seppur datato, credo che un breve pamphlet polemico di Allin Cottrell spieghi molto bene i punti più problematici: l’approccio dei moderni word processor è «stupido e inefficiente» perché sintetizzando²

• distrae molto l’autore dall’obiettivo – la scrittura del testo – spingendolo alla microgestione dell’aspetto finale, e infatti…
• distoglie e diseduca l’autore al riconoscimento della struttura del testo e al significato di quella struttura.

È una regola ormai fondamentale in altri ambiti come il web, ma non riesce ancora a farsi strada nella scrittura di testi: l’aspetto dovrebbe essere gestito separatamente dal contenuto, lasciando all’autore solo la stesura del testo e della sua struttura, per occuparsi dell’aspetto solo in fase di stampa (che sia PDF, cartacea o altro).

Se il titoletto di una sezione deve apparire in grassetto ci accontenteremo sempre più facilmente di apporre il grassetto ai titoletti, man mano che scriviamo, anziché marcare tutti i titoletti con lo stile appropriato. Non solo l’operazione è gravemente inefficiente (se decidiamo di cambiare i titoletti dal grassetto a un corpo più grande, per esempio), ma esposta a molti errori. Inoltre più in generale non avremo modo di sfruttare la struttura per cose come la generazione automatica di un indice o una esportazione in HTML.

Altro punto importante dei word processor è che tendono a salvare i testi in formati variamente proprietari e scarsamente compatibili tra loro. Se all’epoca della scrittura del pamphlet le cose erano certamente peggiori, ciò non toglie che è decisamente preferibile poter aprire i propri testi a prescindere dal programma con cui li si è creati, programma che potrebbe smettere di esistere nei prossimi decenni.

Go plain text

La soluzione a questi problemi è la transizione dai word processor ai text editor; l’editor di testi consente di focalizzarci su ciò che dobbiamo scrivere – non sull’aspetto finale – e il file creato sarà leggibile direttamente, senza rischi di incompatibilità o di future obsolescenze.

L’uso di un editor di testo non implica una perdita di funzionalità: strumenti essenziali come il conteggio delle parole o il correttore ortografico sono parte integrante di ogni editor di testo minimamente credibile (e no, se usate il blocco note di Windows sappiate che è una fregatura).

La disponibilità di editor di testo è enorme e – a parte Windows – ogni sistema operativo ne offre già uno. Non saprei suggerirne, mi limito a dire che mi sto trovando molto bene con Atom, disponibile per Windows, Mac OS e Linux. Se vi confondono le troppe opzioni e l’interfaccia differente dal solito, su Windows si può anche provare Notepad++, su Mac penso possa andare bene anche TextEdit, presente di default, che però credo includa anche una serie di caratteristiche da word processor.

Nel passaggio da Word a un editor di testo scompaiono però un sacco pulsanti per fare cose utili, come i corsivi, grassetti, i titoli, le note a piè pagina o i link…
La soluzione che propone Cottrell è abbastanza radicale ma probabilmente per il 1999 era assai ragionevole: utilizzare file di testo semplice inserendo, nel testo, struttura e stili tramite delle marcature in un linguaggio specifico per la composizione tipografica: TeX.

Tralasciamo per il momento TeX e i suoi derivati perché fortunatamente nel frattempo è nato un linguaggio di marcatura molto semplice, pulito e leggibile: Markdown.

Markdown

Markdown³ nasce nel 2004 dal lavoro di John Gruber (e con il contributo di Aaron Swartz). È un linguaggio di marcatura, ossia consente di descrivere porzioni di testo sulla base di notazioni standard. A differenza di buona parte dei linguaggi di marcatura – come nell’esempio seguente l’HTML – il Markdown è semplice da usare:

<p>Questo è un paragrafo con <em>una porzione in corsivo</em> e <strong>una in grassetto</strong>.</p>

In Markdown è sufficiente scrivere:

Questo è un paragrafo con _una porzione in corsivo_ e **una in grassetto**.

È evidentemente una soluzione più facile da leggere, più rapida da scrivere e più semplice da usare (quindi anche con meno rischi di errori). Inoltre Markdown è nato per essere facilmente convertito in HTML e, nelle sue estensioni successive, è arrivato a includere note a piè pagina, tabelle e altro.

Per una panoramica sintetica di ciò che possiamo chiamare «il Markdown standard» la raccomandazione è quella di visitare l’help di Commonmark.org, che offre un agile specchietto con sintassi e risultato, nonché un tutorial chiaro e completo.

L’ecosistema di applicazioni che negli anni si è sviluppato intorno a Markdown fa in modo che possa essere utilizzato per una grande varietà di testi: diffusione e semplicità fanno sì che molti finiscano per usarlo senza nemmeno rendersene conto.
Personalmente lo uso per praticamente ogni testo: prendere appunti, realizzare slide, scrivere in questo blog e in forum ma anche per scrivere testi più complessi, guide e documentazione.

E i metadati: YAML

I metadati di un testo sono importanti, soprattutto per testi complessi: il titolo, l’autore, una data, magari qualche riferimento come le parole chiave, informazioni sul copyright, un link a una fonte originale o addirittura abstract e informazioni sugli autori.

Di norma buona parte di queste informazioni non appaiono all’interno del nostro testo ma abbiamo ottimi motivi per volerne ugualmente almeno qualcuna; in particolare i metadati:

• identificano il testo che stiamo vedendo
• possono aiutarci a capire se sia di nostro interesse
• aiutano a ricostruirne l’origine
• tra qualche decennio ringrazieremo il tempo speso ad averli inseriti
• vogliamo che accompagnino il testo, non che siano salvati altrove, altrimenti diventano scomodi o si perdono proprio

Esiste un linguaggio di marcatura che è standard in questi utilizzi, ma purtroppo è semplice da usare per un calcolatore, non così semplice da usare per un umano: l’eXtensible Markup Language, XML per gli amici,⁴ è infatti altamente intollerante agli errori e piuttosto complesso nella sua scrittura in assenza di editor dedicati.

Una alternativa sempre più diffusa – e come per Markdown & co. non così nuova: 2001 – è lo YAML (l’acronimo sarebbe ricorsivo: YAML Ain’t Markup Language, per ribadire non solo che parliamo di cose nerd, ma anche il fatto che è focalizzato sui dati, non sui testi). A dispetto del sito internet un tantino brutale, YAML ha come priorità uno la leggibilità da parte degli umani, ed è semplice da usare; inoltre è facilmente integrabile nel proprio file in Markdown, semplicemente anteponendolo al resto del testo usando --- come separatori:

---
title: "Il titolo del mio testo"
description: |
  Una descrizione del mio testo, non tanto breve, al punto che
  la faccio apparire su più righe in questo modo
tags: [ "varie", "tag", "descrivono", "il mio testo" ]
# questa riga inizia per cancelletto, quindi è un semplice commento
date: "2017-08-21"

# questo testo ha più autori, elenchiamoli
author:
  - Niccolò Copernico
  - Galileo Galilei
---

Lorem Ipsum, qui inizia il mio testo in Markdown.  

Quanto sopra è solo un esempio neanche troppo elementare, mentre sono possibili strutturazioni più complesse; inoltre l’interpretazione dei metadati – a parte la lettura a occhio nudo – può variare a seconda dello scopo, del programma in uso e anche delle nostre esigenze.

Conclusioni

La transizione non è stata immediata, ma dopo quasi vent’anni a scrivere testi esclusivamente su word processing – con email, testi su forum e wiki a far da eccezione – ormai sono giunto al punto che gestisco tutti i miei testi su file semplici (plain text) e scritti in Markdown + YAML.

Questo vale sia per i semplici appunti, sia per il seguente post sul sito, sia per scrivere la documentazione dei miei progetti. Per loro natura Markdown e YAML si adattano bene a vari contesti e sono facili da interpretare e convertire, pertanto – ne parlerò – ritengo siano una soluzione vincente anche per ambiti più impegnativi, quali ad esempio le pubblicazioni accademiche.

La focalizzazione su testo, struttura e dati consente infine di avere materiale adeguatamente strutturato e riutilizzabile, lasciando a un secondo passaggio l’eventuale applicazione di stili e l’esportazione nei formati desiderati, siano essi HTML, PDF, ebook in formato ePub o una bella stampa cartacea con copertina rigida:

l’impaginazione, di qualità ed efficiente (quindi ripetibile), deve essere tenuta distinta e dipende anche dalla destinazione finale.

Un possibile «come» lo vedremo a breve.⁵