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