This page is also available in english

Introduzione

Marcare il testo

Un marcatore è un segno convenzionale per indicare la formattazione.

I linguaggi di marcatura leggeri usano espressioni codificate abbastanza semplici da essere utilizzabili durante la fase creativa di scrittura.

In altre parole sono un linguaggio con regole semplici per descrivere la rappresentazione del testo da cui creare documenti strutturati che saranno utilizzabili su più supporti.

Esempio di scrittura con marcatori

# Capitolo primo
  bla bla bla

# Capitolo secondo 
  bla bla *bla in grassetto*

Una caratteristica importante è che la lettura del testo crudo non presenta difficoltà.

Markdown e CommonMark

Markdown è il linguaggio di marcatura inventato da Aaron Swartz e John Gruber. Nato per pubblicare in HTML, presenta delle limitazioni per altri formati di pubblicazione. CommonMark è il dialetto che si propone di superare queste limitazioni e di uniformare le convenzioni. Alla buona: Markdown è il formato stretto creato nel 2004, CommonMark è il Markdown esteso grazie alla conversione con Pandoc. Un testo scritto in CommonMark può essere convertito in un formato di pubblicazione come HTML, PDF, EPUB o LaTeX.

Questo testo è stato scritto in Markdown esteso e convertito con Pandoc. Per la sua eventuale utilità se ne consiglia la lettura nel formato crudo in CommonMark e il confronto con la pagina convertita in HTML o in PDF.

Usare un editore di testo

Per scrivere e inserire i marcatori liberamente è necessario usare un editore di testo che sappia scrivere, salvare, riscrivere e stampare e che non conosca la formattazione1, di quella si occupa lo scrittore usando i marcatori.

Qualunque editore di testo va bene a patto che scriva e salvi in formato puro testo (TXT). Ad esempio Gedit, il quale è anche in grado di visualizzare la struttura logica del testo evidenziando i marcatori.

Quando viene data al documento una desinenza che dichiara il formato, l'editore potrà riconoscerlo automagicamente: la desinenza .md significa Markdown.

Esempio: questo documento si chiama: commonmark-buona.md

Sintassi

Capitoli

Un Capitolo è rappresentato da una riga preceduta da un cancelletto.

Se ne possono usare fino a sei: #, ##, ###, eccetera2.

Esempio:

# Titolo
## Capitolo
### Sottocapitolo

Paragrafi

Per andare a capo (punto e a capo), mettere due spazi a fine riga.

Ecco come funzionano le pillole:
gialla e rossa, nella fossa.
Bianca e viola, qui si vola.

Per rappresentare un paragrafo, lasciare una linea vuota.

Attributi del testo

Per creare attributi al testo si usa spesso l'asterisco.

Italico

Una parola tra asterischi è in italico

*italico*

Grassetto

Una parola (o frase) tra due asterischi è grassetto

**grassetto**

Barrato

Una parola tra quattro tilde è barrata3

~~barrata~~

Vengono considerati quattro tipi di link: automatico, allineato, di riferimento e interno alla pagina.

Un indirizzo web (URL) tra parentesi acute verrà automaticamente visualizzato.

<URL>

https://stackoverflow.com/editing-help

La sintassi del link allineato è: nome tra parentesi quadre e URL tra parentesi tonde.

[nome](url)

Esempio: markdown announce page

Il link di riferimento è composto da due parti dove l'una rimanda all'altra.

Il link di riferimento esplicito usa solo parentesi quadre, si riferisce a un nome che viene espresso più avanti, ad esempio a fine pagina.

[riferimento][nome]

e

[nome]:url

Esempio: 12121 la pagina del markdown

Il link di riferimento implicito omette il nome.

[riferimento][]

e

[riferimento]:url

Per rappresentare un link a una sezione del documento, lo si può puntare a un capitolo.

vai alla sezione [Sintassi](#sintassi)

vai alla sezione Sintassi

L'inserimento delle immagini usa la stessa sintassi dei link, ma preceduta da un punto esclamativo.

![nome](immagine.png)

Per accompagnare il link a una descrizione metterla tra virgolette dopo l'URL.

[nome](url "descrizione")

Il link allineato è più veloce da inserire scrivendo, ma rende la lettura del testo crudo più faticosa, mentre il link di riferimento scorre meglio.

Questo esempio mostra un link allineato con descrizione che punta alla parola Markdown sull'enciclopedia libera. Va benissimo per la pubblicazione sul web, ma leggere il testo crudo non è comodo, soprattutto se i link fossero molti.

Questo link di riferimento implicito con descrizione invece scorre benissimo: punta alla parola Markdown sull'enciclopedia libera. La leggibilità è ottima in quanto il riferimento compare a fine pagina o paragrafo e non ostacola la lettura.

Rappresentare il Codice

Per rappresentare del codice è possibile usare un blocco di testo con quattro spazi (o una Tab) a inizio riga.

blocco di testo
rappresentato come codice

È possibile anche mettere la parola o frase tra accenti a sinistra (backtick).

`codice`

Esempio: questa frase viene rappresentata come codice.

Blockquotes

Per rappresentare un blocco di testo che risulti separato dal resto usare una parentesi acuta > a inizio riga.

Esempio:

> blocco di testo separato dal resto

Risulta:

blocco di testo separato dal resto

Elenchi

Per rappresentare una lista non numerata usare un asterisco a inizio riga.

Esempio:

* latte
* caffé
* miele

Risulta:

Lasciando delle righe in mezzo si creano paragrafi multipli.

Per rappresentare una lista numerata usare i numeri:

  1. cartine
  2. tabacco
  3. filtri

Non è necessario che la numerazione sia progressiva, ma è consigliabile.

Note a pié pagina

Le note a piede pagina sono in due parti, si rappresentano usando un accento circonflesso ^ tra parentesi quadre.

[^nota]

e

[^nota]: riferimento

Questa è una nota4

Pubblicazione

Impaginazione

Informazioni bibliografiche

Titolo autore e data possono essere rappresentati con questa sintassi all'inizio del testo

% Titolo
% Autore
% Data

Interruzione di pagina

Per rappresentare un'interruzione di pagina5 si può utilizzare:

\newpage

Conversione

Una volta scritto il documento, è possibile convertirlo in un formato di pubblicazione. In questo contesto viene usato il convertitore di documenti libero e a sorgente aperta Pandoc, alcuni esempi:6

Installare Pandoc e Citeproc:

apt-get install pandoc pandoc-citeproc

Convertire da Markdown in HTML:

pandoc -s articolo.md -o articolo.html

Convertire da Markdown in PDF:

pandoc tesina.md -o tesina.pdf

Convertire da Markdown a EPUB:

pandoc -f markdown libro.md -t epub -o libro.epub

Convertire da Markdown in LaTeX:

pandoc -f markdown saggio.md -t latex -o saggio.tex

Citazioni

Inserire una citazione

È sempre una buona idea scrivere da qualche parte, a grandi caratteri che ispirano fiducia, le parole: NON FATEVI PRENDERE DAL PANICO (vedi Douglas 1980, 1:5).

La sintassi per inserire una citazione estraendola da un file bibliografico: (id)entificativo del file bibliografico preceduto da una chiocciola tra parentesi quadre, separate (se le citazioni sono più d'una) da punto e virgola.

Esempio:

[@id]

Esempio citazione:

[vedi @dougadams, pp. 21-22]

Esempio doppia citazione:

[considera @dougadams79, pp. 21-22 ; ma anche @tumembete85, pp. 42]

Si possono usare anche le citazioni allineate:

@manzoni ha scritto che

Creare un documento in LaTeX o PDF con bibliografia

Una volta aggiunte al testo le citazioni, si potrà convertire il file da Markdown nel formato desiderato usando Pandoc e l'estensione pandoc-citeproc.

Esempio: il file in formato BibTeX biblio.bib contiene le seguenti righe:

@book{dougadams:ggpa,
    author = {Douglas, Adams},
    title = {Guida galattica per gli autostoppisti},
    series = {Urania},
    volume = {1},
    publisher = {Mondadori},
    address = {Milano},
    year = {1980}
    }

Convertire un testo da Markdown a LaTeX specificando il file bibliografico esterno:

pandoc --bibliography=biblio.bib saggio.md -o saggio.tex

Convertire un testo da Markdown a PDF con indice:

pandoc --bibliography=biblio.bib --toc -s saggio.md -o saggio.pdf

Lo stesso comando con estensione .epub produrrà l'effetto desiderato. (generare un EPUB).

L'opzione standalone -s produce un documento indipendente;
L'opzione --toc genera l'indice dei contenuti;
L'opzione -N numera i capitoli;
L'opzione -H, ad esempio: -H head.css, può essere usata per inserire un link a un file css nel header HTML.

Quando non si specifica lo stile di citazione con l'opzione --csl Pandoc usa il Chicago Manual of Style.

Pandoc usa unicode UTF-8. Consultare il manuale di Pandoc per altre opzioni.

Le citazioni vengono riportate automaticamente alla fine del documento, dunque l'ultimo capitolo farà bene a chiamarsi: Bibliografia.

# Bibliografia

Utilizzare un editore di testo avanzato

Emacs

Usare Emacs per scrivere in Markdown

GNU Emacs è un libero editore di testo che associa i comandi a sequenze di tasti; usa diversi modi per comportarsi diversamente7 a seconda di quello che si sta scrivendo. In questo contesto viene usato GNU Emacs 24.4.1

markdown-mode.el

Il modo di Emacs per scrivere Markdown si chiama markdown-mode.el il quale utilizza alcune convenzioni di org-mode portate al Markdown.

Una volta scaricato markdown-mode e inserito nel path di Emacs, solitamente ~/.emacs.d/lisp/ è comodo segnalare a Emacs di aprire ogni file con desinenza .md direttamente in markdown-mode, aggiungendo queste righe al ~/.emacs

; attivare il percorso
    (setq load-path (cons "~/.emacs.d/lisp/" load-path))

; attivare il markdown-mode per i file.md
    (autoload 'markdown-mode "markdown-mode" "Major mode for editing Markdown files" t)
        (add-to-list 'auto-mode-alist '("\\.md\\'" . markdown-mode))

Integrazione di markdown-mode.el con Pandoc

Convertire da Markdown in altro formato da Emacs usando Pandoc

(defun convert-markdown-to (newtype)
(interactive "sOutput[html|html5|rtf|pdf|mediawiki|latex|..]: ")
    (let ((current-document (buffer-file-name))
        (temp-filename (concat "./output." newtype)))
            (with-temp-file temp-filename
                (call-process-shell-command (concat "pandoc -s -f markdown -t " newtype)
                    nil t nil current-document))

Il comando convert-markdown-to convertirà il file che viene editato nel formato prescelto: ad esempio HTML, HTML5, PDF, MediaWiki, LaTeX. Il file chiamato output.[xxx] verrà salvato nella stessa directory.

Attibuire una chiave da tastiera al comando convert-markdown-to

(browse-url temp-filename)))
    (eval-after-load "markdown-mode"
        '(define-key markdown-mode-map (kbd "C-c C-c c") 'convert-markdown-to))

Vim8

Usare Vim per scrivere in Markdown

Vim (o Vi IMproved) è un libero editore di testo avanzato comunemente installato su sistemi operativi Unix-like, come Linux, MacOSX e BSD. In questo contesto viene usato Vim 7.4 o successive.

Vim offre una perfetta integrazione con Pandoc tramite l'installazione di un plugin chiamato vim-pandoc.

Installazione di vim-pandoc

L'installazione di questo plugin avviene tramite l'uso di uno dei seguenti gestori di pacchetti per Vim: pathogen, Vundle o NeoBundle. Quello consigliato da questa guida è Vundle il quale richiede l'inserimento delle seguenti righe nel file di configurazione di Vim, comunemente: ~/.vimrc:

Plugin 'vim-pandoc/vim-pandoc'
Plugin 'vim-pandoc/vim-pandoc-syntax'

Una volta avviato Vim, eseguire il comando per procedere allo scaricamento e l'installazione del plugin:

:PluginInstall

Utilizzo di vim-pandoc

Tramite questo plugin, Vim assiste la scrittura di documenti in Markdown. In aggiunta, supporta la creazione di pagine HTML, documenti PDF, TeX e ogni altro formato supportato dal programma Pandoc.

Per convertire il documento che si sta editando in HTML, eseguire il comando:

:Pandoc

Rimandiamo alla documentazione ufficiale del plugin per maggiori dettagli.

la Navigazione fuorilinea

Editare un testo con un programma di videoscrittura permette di usare la tecnica del copia e incolla e di applicare il montaggio non lineare alla scrittura. Usare un editore di testo avanzato come Emacs o Vim permette inoltre di accedere alla funzionalità chiamata navigazione fuorilinea. Con la navigazione fuorilinea si effettua un passaggio da micro a macro, con la possibilità di visualizzare una mappa del testo da editare e di usare il copia e incolla su interi capitoli.

Navigazione Fuorilinea è una funzionalità presente negli editori di testo strutturali che utilizzano la modalità outline, a scomparsa o con pannello laterale. Può causare dadaismo.

Esempio:

La prima immagine mostra questo testo durante la scrittura

la seconda immagine mostra lo stesso testo collassato in modalità navigazione fuorilinea a scomparsa.

Compendio

# capitoli     *italico*      **grassetto**     `codice`
elenco:        * * * *        1. 2. 3. 4.
link:          [nome](url)
link ref:      [ref][]        [ref]:url 
nota:          [^nota][]      [^nota]:cosa
immagine:      ![nome](immagine.png)
citazione:     [vedi @eco, pp. 42]
breakpage:     \newpage

Emacs markdown-mode keybind:
Folding outline navigation: Shift-Tab
Vai a predecente/prossimo capitolo: C-c C-p, C-c C-n
Converte e offre anteprima HTML nel browser via Pandoc: C-c C-c c
Elenca i comandi da tastiera disponibili: C-c C-h

Pagina sintassi Markdown
Pandoc user guide
Pandoc citerproc homepage
Emacs tutorial
Vim tutorial
GNU/Linux Debian
BunsenLabs Linux

Bibliografia

Douglas, Adams. 1980. Guida Galattica Per Gli Autostoppisti. Vol. 1. Urania. Milano: Mondadori.

  1. I documenti scritti in un linguaggio di marcatura come HTML vengono solitamente fruiti con la formattazione che gli viene restituita da un navigatore, ma restano documenti in semplice testo.↩

  2. Ci sono anche altri metodi per creare gli headers, si possono usare quelli che si preferiscono, solo non è il caso di mischiarli tra loro.↩

  3. Esistono altri tipi di attributi, come superscript, tag e spoiler, oltre le tabelle e anche le funzioni matematiche, che non verranno descritti qui.↩

  4. Il riferimento può essere messo essere posto ovunque e comparirà al piede della pagina.

    Il riferimento alla nota può anche continuare in un blocco di testo.↩

  5. l'interruzione di pagina non viene resa in HTML↩

  6. È stata utilizzata BunsenLabs, distribuzione Linux basata su Debian 8.↩

  7. Perché c'è differenza tra programmare in Python o scrivere una sceneggiatura.↩

  8. Contributo di Andrea Marchesini↩

Home

Commenti? Kudos? Consigli? Vaffa? Grazie!
@DanieleSalvini