Il linguaggio Markdown

Il linguaggio Markdown è un linguaggio di markup progettato per avere una sintassi del testo semplice, al fine di semplificare la scrittura e permettere una facile conversione in altri formati.

Attualmente è il linguaggio più utilizzato per scrivere documentazione di programmi, wiki e note.

Anche se non si vede, questa stessa pagina è stata scritta in linguaggio Markdown, ed è stata poi convertita in HTML da un generatore di siti statici.

La tesi

La tesi di Andrea Catena ha portato alla realizzazione di un applicazione da terminale per la visualizzazione di file Markdown con la possibilità di utilizzare dei temi (o stili) preimpostati, e permettere la creazione di temi personalizzati.

L’applicazione è stata pubblicata come software opensource su GitHub con licenza GPLv3.

Obbiettivi

Gli obiettivi del progetto sono:

• La realizzazione di un visualizzatore per file in formato Markdown.
• L’utilizzo specifico da terminale Linux.
• La creazione di uno strumento funzionale ed altamente personalizzabile.

Per la realizzazione di questi obbiettivi è stato utilizzato il linguaggio di programmazione Python affiancato dalle seguenti librerie:

• Click per la gestione degli argomenti da riga di comando e aggiunta di funzioni per mezzo di decoratori.
• Mistletoe per quanto riguarda il parsing del file markdown.
• Ansiwrap per una migliore formattazione del testo.
• Prompt-toolkit per la visualizzazione interattiva del testo.

Requisiti

I requisiti prefissati sono stati:

• Una modalità interattiva con supporto per l’adattamento dinamico alla variazione della larghezza della finestra di visualizzazione. * La gestione di temi e stili di visualizzazione configurabili con file JSON.
• La possibilità di navigare i link tra i file in modalità interattiva.
• La possibilità di seguire dei link con apertura del browser nel caso di apertura di siti web oppure dell’apertura di file sul file system locale.
• La conseguente gestione della cronologia nell’apertura di file locali ed un wordwrap intelligente.

Temi e stili

Lo stile utilizzato per la visualizzazione del file Markdown permette di specificare gli attributi “visuali” del testo, così come si fa con i CSS per le pagine HTML. E’ possibile indicare i colori per il testo e lo sfondo, e alcuni altri aspetti di formattazione, come l’indentazione e i margini.

Gli stili tengono ovviamente in considerazione il fatto che il terminale ha limitate capacità grafiche, e quindi le possibilità di personalizzare lo stile sono anch’esse molto più limitate di quanto avviene, per esempio, per le pagine HTML.

Gli stili sono specificati tramite in JSON. Un estratto di un file di specifica dello stile è il seguente:

{
  "document": {
    "prefix": "",
    "suffix": "",
    "margin": 2
  },
  "paragraph": {
    "prefix": "",
    "suffix": "\n",
    "color": "",
    "background_color": "",
    "bold": false,
    "underline": false,
    "blink": false
  },
  "h1": {
    "prefix": "# ",
    "suffix": "\n",
    "color": "red",
    "background_color": "",
    "bold": "",
    "underline": false,
    "blink": false
  },
  ...

Questo formato è stato ispirato dal formato utilizzato dal programma glow, che con qualche limitazione rispetto ad mdt, punta anch’esso alla visualizzazione di file Markdown nel terminale.

Funzionalità implementate

Cercando di prendere spunto da programmi con obiettivi simili, come il già citato glow e mdv, si è puntato a sopperire ad alcune alle loro mancanze e sono ritenute utili per l’uso di uno strumento come quello predisposto.

Alcune di queste funzionalità sono le seguenti:

• La possibilità di scegliere uno tra i temi di default.
• La possibilità di scegliere un tema personalizzato.
• Il riepilogo di tutti i temi di default disponibili, per facilitarne la scelta.
• La modalità interattiva di visualizzazione del file.
• L’impostazione della larghezza di visualizzazione in modo manuale.
• L’impostazione del margine destro che il testo terrà di default durante la visualizzazione.

L’esecuzione del comando mdt senza alcun argomento permette di cominciare ad esplorare le funzionalità del programma:

$ mdt --help
Usage: mdt_parser.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  gallery  Shows a gallery with the available themes.
  show     Display the specified Markdown file.
  themes   Lists of available themes.

Esempi di output sono i seguenti:

Conclusione

In conclusione questo progetto è stato realizzato come strumento volto alla combinazione delle caratteristiche più interessanti di programmi analoghi ponendo particolare enfasi sulla semplicità di configurazione del tema/stile.