Per formattare “al volo” il testo, esiste il markdown, un linguaggio che unisce il testo alla formattazione.
Lo si scrive velocemente, utilizzando quasi sempre solo la tastiera (senza dover andare al menu con il mouse).
E lo si rilegge anche molto bene, perché la formattazione non è invadente.
Vediamo 2 possibilità con software opensource:
L’istallazione, in entrambi i casi, è semplicissima: si scarica dal web (con wget) e si installa on gdebi. Attualmente la versione di remarkable è 1.87 (vedi https://remarkableapp.github.io/linux/download.html ) quindi:
wget https://remarkableapp.github.io/files/remarkable_1.87_all.deb
sudo gdebi remarkable_1.87_all.deb
Al volerlo installare, ubuntu lo descrive e chiede “vuoi installare i pacchetti sorgente”?
A free fully featured markdown editor.
Remarkable is a free fully featured markdown editor. It has a syntax
like Github flavoured markdown. With it you can write markdown and view
the changes as you make them in the live preview window. You can export
your files to a variety of formats. There are multiple styles available
along with extensive configuration options so you can set it up exactly
how you like.
Do you want to install the software package? [y/N]:
Stessa cosa con haroopad:
wget https://bitbucket.org/rhiokim/haroopad-download/downloads/haroopad-v0.13.1-x64.tar.gz
In caso di errori, per remarkable, eseguire:
user@A:~$ sudo pip install --upgrade beautifulsoup4
user@A:~$ sudo pip install --upgrade html5lib
La formattazione del testo
Vediamo come utilizzarlo in casi speciali (per l’utilizzo “ordinario”, grassetto, italico, rimandiamo a questa guida https://help.github.com/articles/basic-writing-and-formatting-syntax/#lists).
Ad esempio, per inserire una nota che non sia visibile nel testo finale, si utilizza la sintassi del commento in html, quindi:
<!– testo non visibile –>
Liste ordinate
Per non interromprere la continuitiá uno spazio ed indentate.
Resize image
Se vogliamo inserire un’immagine con una dimensione differente, in remarkable, non un funziona il fatto di aggiungere la dimensione dopo, come in altri formattatori, ma dobbiamo ricorrere all’html.
- no
- 
- si
- <img src=”/home/ca/git/manuales/impu.png” width=”80″ height=”60″>
Si può provare “al volo” il markdown alla pagina https://jonschlinkert.github.io/remarkable/demo/
Markdown On line
Come sfruttare in una pagina web tutte questi testi facilmente formattati con il markdown? Consigliamo di usare il pacchetto python chiamato mkdocs, che crea varie pagine web “coerenti” per mostrare i nostri testi.
L’istallazione è estremamente semplice (la vedremo alla fine) ed il lancio altrettanto: nella directory in cui abbimo il file delle impostazioni (mkdocs.yml) digitiamo mkdocs serve per far partire il server che mostrerá alla porta 8000 i testi.
Lasciamo per dopo l’installazione, vediamo prima come strutturare pagine coerenti, ad esempio, rilazionando, con dei collegamenti o link, fra di loro.
Collegamenti fra le diverse pagine dei testi markdown
Si creano con questa sintassi:
[testo che appare](nome_del_file)
Esempio
[007 login.md](007_Aceder.md)
[007 login](007_Aceder)
Notare come si possa mettere o omettere l’estensione .md. Non va messo docs, va bene un percorso relativo (cioè non funzionerebbe un link scritto così [007 docs/login.md](docs/007_Aceder.md) )
La struttura del menu
Si possono innestare le pagina, cosi da creare menu piu sintetici e leggibili, mettendo poi, nelle singole voci, maggiori informazioni.
Corrisponde a questi file e directory:
- Home.md
- Examples.md
- img/favicon.png
- Sub dir
- Sub dir/Sub page.md
- Sub dir/Sub dir 2
- Sub dir/Sub dir 2/Sub page 2.md
Per il solo fatto di strutturare un file markdown dentro una directory mkdocs la interpreta come un sub-voce del menu. Notate che la directory img non contiene md file e quindi non viene mostrata nel menu.
Testo delle voci del menu
Il testo che appare nel menu varia a seconda della posizione:
se si è nella pagina stessa, appare il testo del titolo principale, altrimenti il nome del file stesso.
Immagini
In mkdocs non funziona la definizione di un’immagine con tags html, dei tre modi, funziona solo il primo:
<img src="../imp.png" width="80" height="60">
<img src="../impu.png" >
Installazione e lancio
Supponendo nella vostra macchina già sia installato python, vanno bene le versioni 2.7, 3.3, 3.4, 3.5 e pypy, mkdocs si installa con pip, tipocamente con permessi di sudo:
sudo pip install mkdocs
Lo si lancia, come detto, con serve:
user@PC_A:~/git/manuales/mia_directory_con_file_yml$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
WARNING - The page "subitem21.md" contained a hyperlink to "007_Aceder.md" which is not listed in the "pages" configuration.
[I 171124 07:11:36 server:283] Serving on http://127.0.0.1:8000
[I 171124 07:11:36 handlers:60] Start watching changes
[I 171124 07:11:36 handlers:62] Start detecting changes
Se il file yml non fosse presente, ce lo ricorda e si blocca (non sapendo mkdocs che fare).
user@PC_A:~$ mkdocs serve
INFO - Building documentation...
Config file ‘/home/user/mkdocs.yml’ does not exist.
user@PC_A:~$
Un interessante opzione la dà la specifica –dev-addr, permette di lanciare il manuale mkdocs in un’altra porta rispetto alla 8000, presa di default, cosí da avere, ad esempio in locale, più di un manuale aperto.
user@PC:~/$ mkdocs serve --dev-addr=localhost:8002