Re: [Hackmeeting] Questua per le slides | la scrittura strut…

43r0 wrote:
>Chi ha tenuto un talk e non ha lasciato le slides le può mandare a
>hackmeeting2016@??? o anche qui in lista - please in questo
>thread - poi verranno caricate sul sito.
>
>Nei prossimi giorni taglieremo anche gli audio dei talks che sono stati
>strimmati su icecast, va bene caricarli su http://www.arkiwi.org/ ? Chi
>mi da un paio di dritte? A qualcun@ scoccia?
>
>DAIDAIDAI

in allegato il file di testo in markdown del talk sulla scrittura
strutturata, dal quale ricavare in autonomia il Pdf o una slide.

ciao

~ d


% Scrivere e pubblicare in CommonMark alla buona
% dan [chiocciola] autistici [punto] org
% 16 marzo 2016

\newpage

# 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
formattazione[^nonsa], 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

[^nonsa]: 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.

# Sintassi

## Capitoli

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

Se ne possono usare fino a sei: #, ##, ###, eccetera[^h].

    Esempio:

    # Titolo
    ## Capitolo
    ### Sottocapitolo

[^h]: Ci sono anche altri metodi per creare gli headers, si possono usare quelli
    che si preferiscono, solo non è il caso di mischiarli tra loro.

## 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 è ~~barrata~~ [^al]

`~~barrata~~`

[^al]: Esistono altri tipi di attributi, come superscript, tag e spoiler, oltre
    le tabelle e anche le funzioni matematiche, che non verranno descritti qui.

## Links

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

### Link automatico

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

`<URL>`

<https://stackoverflow.com/editing-help>

### Link allineato

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

`[nome](url)`

Esempio: [markdown announce page](http://www.aaronsw.com/weblog/001189)

### Link di riferimento

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

#### Link di riferimento esplicito

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][markdown page] la pagina del markdown

[markdown page]: https://daringfireball.net/projects/markdown/ "markdown page"

#### Link di riferimento implicito

Il link di riferimento implicito omette il nome.

`[riferimento][]`

e

`[riferimento]:url`

### Link interno alla pagina

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](#sintassi)

### Link a un'immagine

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

``

### Utilizzo dei link

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](https://it.wikipedia.org/wiki/Markdown "Markdown è un
linguaggio di markup con una sintassi del testo semplice") 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.

[alla parola Markdown]: https://it.wikipedia.org/wiki/Markdown "Markdown è un linguaggio di markup con una sintassi del testo semplice"

## 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:

* latte
* caffé
* miele

Lasciando delle righe in mezzo si creano paragrafi multipli.

Per rappresentare una lista numerata usare i numeri:

1. cartine
3. tabacco
2. 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 nota [^nota]

[^nota]: 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.

# 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 pagina[^ip] si può utilizzare:

`\newpage`

[^ip]: l'interruzione di pagina non viene resa in HTML

## 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:[^deb]

[^deb]: È stata utilizzata BunsenLabs, distribuzione Linux basata su Debian 8.

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 @dougadams:ggpa, pp. 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`

\newpage

# 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 diversamente[^e] a seconda di quello che
si sta scrivendo. In questo contesto viene usato GNU Emacs 24.4.1

[^e]: Perché c'è differenza tra programmare in Python o scrivere una sceneggiatura.

#### 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))

## Vim[^b]

### 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](https://github.com/vim-pandoc/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](https://github.com/gmarik/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.

[^b]: Contributo di Baku

\newpage

# 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.

\newpage

# 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`

Per pubblicare questo file sono stati usati i seguenti comandi:

    pandoc --bibliography=biblio.bib --toc -s commonmark-buona.md -o commonmark-buona.html
    pandoc --bibliography=biblio.bib --toc -s commonmark-buona.md -o commonmark-buona.pdf

al file HTML è stato poi aggiunto un css in testa

    <link rel="stylesheet" type="text/css" href="un.css" />

nota: per convertire un CV è stato usato questo comando. Possa tu non averne mai bisogno.

    pandoc -V geometry:"top=3cm, bottom=1.5cm, left=3cm, right=1cm" cv.md -o cv.pdf

[Pagina sintassi Markdown](https://daringfireball.net/projects/markdown/syntax)
[Pandoc user guide](http://pandoc.org/README.html)
[Pandoc citerproc homepage](https://github.com/jgm/pandoc-citeproc)
[Emacs tutorial](http://www2.lib.uchicago.edu/keith/tcl-course/emacs-tutorial.html
"Emacs tutorial in inglese de l'Università di Chicago")
[Vim tutorial](http://vim.wikia.com/wiki/Tutorial "Vim tutorial in english")
[GNU/Linux Debian](https://www.debian.org/index.it.html "il sistema operativo
libero Debian")
[BunsenLabs Linux](https://www.bunsenlabs.org/ "una distribuzione Linux leggera
basata su Debian")

[crudo in CommonMark]: commonmark-buona.md
[convertita in HTML]: commonmark-buona.html
[o in PDF]: commonmark-buona.pdf
[Gedit]: https://wiki.gnome.org/Apps/Gedit "Gedit è un editore di testo"
[Pandoc]: http://pandoc.org/README.html "Pandoc, il convertitore di documenti universale"
[markdown-mode.el]: https://www.emacswiki.org/emacs/MarkdownMode "Pagina wiki del markdown-mode"
[markdown-mode]: http://jblevins.org/projects/markdown-mode/ "Emacs Markdown Mode"

# Bibliografia