Lettera22 - ver. 2019.12

Guida per lo scrittore

Tutorial per la realizzazione di contenuti con il software 'Lettera22'

di Claudio Tortorelli

Pubblicato il 12/12/2019 - Ultima revisione il 08/12/2020 - Revisione n. 87

Torna a www.claudiotortorelli.it -- Revisione precedente



Abstract

Guida per la realizzazione di contenuti con Lettera22

Indice

Introduzione
1 Parte prima: si comincia
   1.1 Presentazioni
   1.2 Avvio
   1.3 Ciao Mondo!
2 Parte seconda: l'interfaccia
   2.1 Notepad++
   2.1.1 Altre funzionalità integrate
   2.2 Il workspace
   2.3 La console e il log
3 Parte terza: configurazione
   3.1 Il file di configurazione
   3.2 Opzioni di base
   3.3 Opzioni avanzate
   3.3.1 Accesso allo spazio FTP
   3.3.2 Firma PEC
   3.3.3 Solo per esperti
4 Parte quarta: flusso di gestione del documento
   4.1 Organizzazione delle cartelle di lavoro
   4.2 Creazione di un nuovo documento
   4.2.1 Note sul nome del file
   4.3 Le opzioni del documento
   4.4 I tag
   4.4.1 Intestazione, titolo e il sottotitolo
   4.4.2 Autore
   4.4.3 Categoria di documento
   4.4.4 Luogo e data di creazione
   4.4.5 Altre date
   4.4.6 Numero di revisioni
   4.4.7 Sommario
   4.4.8 Abstract e introduzione
   4.4.9 Dedica
   4.4.10 Processabilità
   4.4.11 Pubblicazione
   4.4.12 Inizio del documento
   4.5 Parsing
   4.6 Compilazione
   4.7 Link
   4.8 L'indice generale
   4.9 Revisioni di un documento
   4.10 In pratica...
5 Parte quinta: lo stile e la sintassi del documento
   5.1 Stile dei documenti e degli elementi del testo
   5.1.1 Carattere
   5.1.2 Grassetto, italico e link
   5.1.3 Layout
   5.1.4 Colori
   5.2 La sintassi
   5.2.1 Struttura del documento (capitoli, sezioni, paragrafi, ecc.)
   5.2.2 Elementi del testo
   5.2.2.1 Citazioni
   5.2.2.2 Liste
   5.2.2.3 Interruzioni di linea
   5.2.2.4 Immagini
   5.2.2.5 Allegati
   5.2.2.6 Riferimenti bibliografici
6 Parte sesta: approfondimenti
   6.1 Lavorare offline
   6.2 Rinominare un documento
   6.3 Eliminare un documento
   6.4 Condividere i documenti tra due postazioni di lavoro
   6.5 Collaborazione di più autori allo stesso sito
   6.6 Eseguire il backup dei documenti e del software
   6.7 Creare un documento multilingua
   6.8 Verifica della firma dell'indice
   6.9 Recupero di una certa versione di un documento (hash)
   6.10 Stampa di un HTML compilato con Lettera22
   6.11 Applicare gli aggiornamenti di Lettera22
Bibliografia

Introduzione

La presente guida descrive tutte le funzionalità supportate da Lettera22 2019.12. Si analizza la configurazione dell'applicazione, il flusso di sviluppo, revisione e pubblicazione di un documento.


1 Parte prima: si comincia

[indice]

Introduzione allo strumento e verifiche iniziali.

1.1 Presentazioni

[indice]

Quando si apprende l'uso di un nuovo strumento occorrono anzitutto un po' di pazienza e di comprensione. Se non si è ben disposti, facilmente si possono fraintendere gli scopi e le potenzialità di ciò che si ha davanti. Diciamo subito che se si ha fretta di realizzare o non si è disposti a scendere a qualche compromesso, Lettera22 non fa per voi.

Viceversa di seguito sarete introdotti all'uso di questo software, che potrebbe rivelarsi piacevolmente diverso da tutti gli altri strumenti digitali per la scrittura. Almeno questo vale per me che l'ho ideato e curato.

Lettera22 non è un normale software di videoscrittura: è volutamente "spartano" e vincola lo scrittore ad una gestione "rigorosa" del documento (senza esagerare...). Trae ispirazione dal tradizionale flusso di sviluppo software, dove il documento subisce un processo di trasformazione che lo porta da testo originale (raw) ad artefatto finale, in analogia all'elaborazione del codice sorgente che diviene binario compilato.

Se chi affronta questa guida non ha idea di cosa sia Lettera22 si consiglia una rapida lettura della pagina di FAQ, che fornisce anche le motivazioni "filosofiche" a supporto delle scelte tecniche (quando presenti).

In sintesi...

1.2 Avvio

[indice]

L'installazione di Lettera22 avviene scaricando da QUI l'ultima versione rilasciata. Una volta decompresso l'archivio, l'interfaccia del software si avvia tramite l'eseguibile batch run.bat che si trova all'interno della cartella scompattata.

1.3 Ciao Mondo!

[indice]

Lettera22 può considerarsi un "compilatore di documenti" per cui, da prassi informatica, occorre cominciare con un Hello World! che abbia il duplice scopo di illustrare le funzionalità di base e verificare il corretto funzionamento del software.

...il risultato non è sicuramente molto significativo, ma ora si può cominciare.

2 Parte seconda: l'interfaccia

[indice]

Descrizione dell'editor incluso in Lettera22.

2.1 Notepad++

[indice]

Lettera22 non richiederebbe una specifica interfaccia utente, essendo composto da un insieme di tool da linea di comando (in gergo CLI), combinati tramite script batch. Un qualunque editor di testi in grado di produrre file .txt (banalmente il famoso "blocco note" di Windows) sarebbe sufficiente per procedere nella realizzazione degli elaborati.

Al fine di rendere Lettera22 "pronto all'uso", è inclusa nel pacchetto una versione "embedded e portable" di Notepad++ [1]. Notepad++ è un editor molto versatile ed efficace, ideale per integrare nuove funzionalità tramite script e plugin.

Supporta nativamente molte caratteristiche, quali ad esempio

...e molto altro.

A queste funzionalità di base si aggiungono decine e decine di caratteristiche aggiuntive, installabili separatamente come plugin sviluppati da terzi. Tra questi stati quindi selezionati e già inclusi i plugin

Inoltre Notepad++ è già configurato per mostrare gli elementi utili allo sviluppo dei testi con Lettera22: console, workspace, stile, preferenze.

Anche se non è necessario modificare la configurazione di Notepad++, è possibile farlo tramite la voce di menù Configurazione.

2.1.1 Altre funzionalità integrate

[indice]

Notepad++ integra l'accesso diretto ai tool di Lettera22, rendendo più semplice e rapido il loro utilizzo. Sotto il menù Macro sono presenti una serie di voci ("parse", "compile", ...)

che corrispondono alle icone incluse nella barra degli strumenti

(soffermandosi con il cursore del mouse sull'icona, appare il nome completo del relativo comando).

Il significato di ciascun comando viene descritto in seguito.

2.2 Il workspace

[indice]

In workspace è la suddivisione logica (opzionale) che è possibile attribuire ai documenti. Si può ad esempio suddividere i propri scritti in categorie, senza per questo creare le corrispondenti cartelle sul disco:

Tramite click con il tasto destro del mouse è possibile aggiungere o rimuovere file e cartelle nel workspace, caricarne e salvarne lo stato.

Nota: nel workspace possono essere inclusi file esterni alla cartella textworks, che non saranno però processati da Lettera22.

2.3 La console e il log

[indice]

Lettera22 mostra in basso una finestra Console che fornisce il dettaglio delle operazioni eseguite. Nella console viene riportato anche il log dell'applicativo, che viene salvato su file all'interno della cartella [lettera22 root]\bin\lettera22\log. La console consente anche attività interattive, come ad esempio l'inserimento del nome del file durante la creazione di un documento: è a tutti gli effetti un prompt attraverso il quale è possibile avviare operazioni, in modo simile a quanto avviene in software come Autocad.

Il log al momento non ha livelli configurabili: vi vengono annotati eventi di qualunque natura (errore, avviso, informazione).

3 Parte terza: configurazione

[indice]

Come mettere a punto Lettera22: le impostazioni globali.

3.1 Il file di configurazione

[indice]

Prima di cominciare a scrivere è bene verificare le opzioni globali di Lettera22. Il file delle opzioni è nella cartella [lettera22 root]\bin\lettera22\options.txt e può essere aperto cliccando su questa icona

Nel file delle opzioni il carattere '#' rende la riga un commento. Tutte le opzioni sono espresse nella forma [chiave valore], dove il valore può essere una stringa, un intero o un booleano ("true" o "false").

Ogni opzione è preceduta da un commento che ne spiega sinteticamente il significato e mostra un possibile esempio.

Nota: il file delle opzioni non è crittato (non ha protezioni) e può contenere delle password. E' essenziale per la sicurezza del proprio lavoro che tali password siano "robuste" e non vengano condivise. Si ricorda che normalmente una buona password ha

  1. almeno 8 caratteri
  2. maiuscole, minuscole, numeri
  3. almeno 1 carattere speciale ('&', '$', ecc.)

3.2 Opzioni di base

[indice]

Nella sezione "parametri del sito", si trovano le opzioni che definiscono l'indice dei contenuti e che dovrebbero essere completate, a prescindere dall'effettiva pubblicazione sul web. In particolare sono presenti il titolo e il sottotitolo, e le altre informazioni che appaiono nell'intestazione dell'indice.

L'opzione ABSTRACT_ONLY, se impostata a "true", consente di generare un indice che punta a documenti contenenti il solo abstract (quando presente). Il MAIN_URL è invece l'URL completo del sito che dovrebbe ospitare l'indice dei contenuti (es. https://www.claudiotortorelli.it).

3.3 Opzioni avanzate

[indice]

Tutte le opzioni che seguono sono opzionali e specifiche per la pubblicazione online dei contenuti.

3.3.1 Accesso allo spazio FTP

[indice]

Nella sezione "accesso via FTP" sono da inserire i dati per l'accesso al proprio spazio FTP, così come sono stati forniti dal provider dell'hosting web (ad esempio https://www.aruba.it/home.aspx).

3.3.2 Firma PEC

[indice]

Lettera22 non include al momento uno specifico tool di firma/marca digitale, atto a proteggere i dati generati e pubblicati anche in sede legale [2]. E' però presente un meccanismo che potrebbe essere equiparato al tradizionale sistema di auto-invio di raccomandate postali. Configurando un account di posta PEC il software provvede ad auto inviarsi l'hash SHA-256 [3] dell'indice, il quale a sua volta contiene l'hash SHA-256 dei documenti collegati. L'hash cambia completamente al modificarsi di un solo carattere di un documento, per cui

Disponendo dei dati SMTP e POP3 della PEC è quindi possibile abilitare questa funzionalità (SIGN_INDEX a "true"). Anche in questo caso i dati di configurazione sono forniti dal provider della PEC.

3.3.3 Solo per esperti

[indice]

Nella sezione "solo per esperti" sono presenti opzioni che determinano la modalità di gestione dei file nelle cartelle predefinite, nella gestione dei documenti e dell'indice autogenerato. La descrizione e la configurazione di queste opzioni esula dagli scopi di questa guida: si consiglia di non modificare tali opzioni a meno di specifiche necessità.

4 Parte quarta: flusso di gestione del documento

[indice]

Descrizione del flusso di lavoro: dal testo "raw" alla pubblicazione dell'artefatto finale.

4.1 Organizzazione delle cartelle di lavoro

[indice]

Lo stato di elaborazione dei documenti in Lettera22 passa attraverso tre fasi principali, nell'ordine:

  1. il parsing
  2. la compilazione
  3. il link

Ad ogni fase corrisponde uno specifico tool e una cartella che conterrà i documenti nel relativo stato di elaborazione:

Tutte le cartelle sono a loro volta incluse in una cartella "base" dei documenti, la docRoot appunto.

4.2 Creazione di un nuovo documento

[indice]

Come mostrato nell'Hello World!, la creazione di un documento consiste nel copiare e contestualmente rinominare il file template nella cartella textWorks, operazione automaticamente eseguita tramite l'apposita icona

4.2.1 Note sul nome del file

[indice]

La scelta del nome del file è particolarmente importante per una serie di motivi:

[4]

Per questo sono consigliati nomi

4.3 Le opzioni del documento

[indice]

Una volta che il nuovo documento è stato creato, la prima cosa da fare è verificare e personalizzare le sue opzioni. All'interno dell'intestazione (header) del template, ogni riga che inizia con il carattere '#' è considerata un commento e viene ignorata dal parser. Oltre ai commenti, che rammentano sinteticamente la sintassi supportata da Lettera22, l'intestazione contiene i tag di opzione.

E' quindi possibile abilitare o disabilitare una certa opzione semplicemente inserendo o rimuovendo il carattere iniziale di commento. Quando una caratteristica è disabilitata, verrà utilizzata la relativa impostazione di default.

4.4 I tag

[indice]

Ad ogni opzione ammessa corrisponde un tag, o parola chiave, delimitata da parentesi quadre. Dopo ogni tag è ammesso solo testo semplice: non è possibile inserire ad esempio un elemento complesso, come quelli descritti nel capitolo 5. Al momento Lettera22 supporta i seguenti tag, il cui ordine non è rilevante, se non per [start] che serve a chiudere l'intestazione:

Dopo [start] comincia il documento vero e proprio (body).

4.4.1 Intestazione, titolo e il sottotitolo

[indice]

I tre tag [header], [title] e [subtitle] definiscono rispettivamente intestazione, titolo e sottotitolo del documento.

Normalmente sono tutti elementi presenti e contribuiscono all'indicizzazione del testo da parte dei motori di ricerca. Il titolo dovrebbe essere abbastanza sintetico (appare anche nell'indice generale), mentre il sottotitolo è normalmente più descrittivo.

4.4.2 Autore

[indice]

Il tag [author] riporta l'autore o gli autori del testo

4.4.3 Categoria di documento

[indice]

La categorizzazione non è visibile nel documento stesso, ma solo nella tabella dell'indice generale. La categoria definita dopo il tag [category] aiuta a ricercare i documenti dividendoli secondo un determinato criterio (es. "poesia", "saggio", ...).

4.4.4 Luogo e data di creazione

[indice]

Anche il luogo può essere opzionalmente indicato tramite il tag [place], quando questo è ritenuto utile per completare le informazioni di un documento (es. una pagina di diario).

La data di creazione, il cui formato è libero, consiste nella prima rappresentazione (anche cartacea) del documento, a prescindere dalla sua pubblicazione con Lettera22.

4.4.5 Altre date

[indice]

Oltre alla data di creazione, i tag [showPublishDate] e [showRebuildDate] consentono rispettivamente di mostrare la data di prima pubblicazione (online) e di ultima rebuild. Tali riferimenti sono automaticamente mantenuti dal software per cui è sufficiente de-commentarli.

4.4.6 Numero di revisioni

[indice]

Per mostrare il numero di revisioni (rebuild) eseguite sul documento, occorre de-commentare il tag [showRevision]

4.4.7 Sommario

[indice]

Per generare e visualizzare il sommario dei titoli di capitolo, sezione e paragrafo, costituito da link ipertestuali ancorati ad elementi interni del documento, occorre commentare il tag [noSummary]. Altrimenti nessun sommario sarà automaticamente generato.

Il tag [showUnitNumber] invece abilita la numerazione automatica degli elementi della struttura del documento, quindi anche degli elementi del sommario.

4.4.8 Abstract e introduzione

[indice]

L'abstract [abstract] e l'introduzione [introduction] sono due elementi accessori che consentono una rapida identificazione degli argomenti trattati. L'abstract in particolare viene visualizzato anche nell'indice dei contenuti.

4.4.9 Dedica

[indice]

Il tag [dedication] abilita la dedica del documento.

4.4.10 Processabilità

[indice]

Se [noProcess] non è commentato, il documento non verrà "compilato" localmente verso HTML e nella console apparirà la seguente indicazione

4.4.11 Pubblicazione

[indice]

Se [noGlobal] non è commentato, il documento sarà ignorato in fase di link (pubblicazione), ovvero non verrà copiato verso il webserver che ospita il sito.

4.4.12 Inizio del documento

[indice]

Dal tag [start] in poi, Lettera22 ignora ogni ulteriore tag incontrato e considera l'intestazione conclusa.

4.5 Parsing

[indice]

La fase di parsing è eseguita dal modulo parser di Lettera22 e trasforma i file .txt, contenenti i tag e la sintassi prevista, in file metadoc .xml. Il metadoc è un file "intermedio": è la rappresentazione elaborata del contenuto, in cui ogni impostazione del documento (gestita nell'intestazione), e ogni caratteristica di stile, formato e struttura (inclusa nel corpo del testo), sono riclassificate in oggetti standard. I metadoc non sono fruibili da un lettore come documento finale, ma sono propedeutici alla successiva compilazione in formati rappresentabili.

Per eseguire il parsing di un documento specifico, aperto nell'editor, è sufficiente premere l'icona

che provvede a salvare lo stato corrente del documento e ad aggiornare o creare il metadoc.

Nota: ogni metadoc è contenuto nella stessa cartella del rispettivo file .txt (cartella "textworks") e ha lo stesso nome ma estensione .xml.

Accanto, la seguente icona

esegue il salvataggio e il parsing di tutti i file di testo inclusi nella cartella "textworks".

Nota: il parsing, come anche la compilazione in seguito, sono eseguiti da Lettara22 solamente se il documento è stato modificato nel frattempo. Vengono quindi ignorati e non aggiornati tutti i documenti il cui stato è consistente con l'ultima revisione.

L'icona

è una scorciatoia che consente di eseguire contestualmente parsing e compilazione per il documento corrente (operazione piuttosto frequente durante l'elaborazione di un testo).

4.6 Compilazione

[indice]

La compilazione è la fase successiva al parsing e consiste nel fornire una veste grafica al metadoc, traducendolo in un file finale. Al momento il tool compiler consente di produrre solamente file HTML. I file prodotti dal compiler sono utilizzabili per la lettura o per la stampa e hanno come principale caratteristica l'autoconsistenza: ogni file non fa riferimento a risorse esterne e dunque è "portabile", semplicemente eseguendone una copia tra contesti diversi. Nel caso dell'HTML ad esempio questo vuol dire che ogni file include il font utilizzato e le immagini. Una conseguenza negativa di questo approccio è la duplicazione di elementi condivisi tra più testi.

I file compilati sono generati e aggiornati all'interno della cartella pre_publish, con stesso nome del file txt ma estensione diversa (es. HTML).

Questa icona esegue la compilazione del metadoc del documento corrente

mentre questa

esegue la compilazione in batch di tutti i metadoc che risultano modificati all'interno della cartella "textworks".

4.7 Link

[indice]

L'ultima fase nel flusso di sviluppo del documento è il link, eseguita dal tool linker.

Durante il link

Se il parsing e la compilazione sono operazioni eseguibili "offline", per portare a termine il link è generalmente richiesta una connessione attiva ad Internet ed aver completato la configurazione delle opzioni relative allo spazio FTP e alla PEC (si vedano le "opzioni avanzate"). Tra le tre operazioni di base, il link è quella più "opzionale", in quanto le stesse operazioni riguardanti la pubblicazione dei documenti potrebbero essere eseguite con altri tool di sincronizzazione.

Per richiedere il link del documento corrente si clicca la seguente icona

Quella a fianco esegue la stessa operazione ma forza l'operazione di link anche se non sono state eseguite modifiche al documento (utile per imporre la sovrascrittura del documento e il contestuale aggiornamento dell'indice).

Infine l'icona

esegue il link forzato per tutti i documenti pubblicabili (che non siano cioè bloccati dai tag [noProcess] o [noGlobal]) a prescindere dal loro stato di modifica (aggiornamento forzato globale).

4.8 L'indice generale

[indice]

L'indice generale dei contenuti rappresenta lo stato di tutti i documenti pubblicati ed è generato in completa autonomia dal linker (salvo le informazioni contenute nel titolo e definite nelle opzioni globali).

E' pensato per essere la pagina iniziale del sito, dovrà quindi contenere titoli significativi. Fornisce funzionalità base di ricerca, sempre nell'ottica di non utilizzare alcun database: cliccando sulle intestazioni della tabella nella quale sono elencati i documenti, i contenuti saranno riordinati in modo crescente o decrescente, secondo i valori della colonna selezionata. L'ordine predefinito dei contenuti è però quello decrescente rispetto alla data di ultima revisione, ovvero i documenti aggiornati più di recente saranno visualizzati in cima all'elenco.

Al momento l'indice cataloga i documenti pubblicati tramite le seguenti colonne:

L'ultima colonna serve a garantire la consistenza di ogni contenuto collegato all'indice.

4.9 Revisioni di un documento

[indice]

Ogni documento ha delle revisioni, perché in Lettera22 è prevista un'elaborazione continuata nel tempo. La gerarchia delle pagine del sito pubblicato diviene quindi la seguente

in cui si nota che il punto di accesso principale è l'indice, attraverso il quale si accede all'ultima revisione del documento. Ogni revisione di documento consente di accedere alla precedente revisione pubblicata (se esistente), a ritroso fino alla prima revisione. E' da notare come il numero di revisioni non coincida necessariamente con il numero di documenti pubblicati: ogni attività di ricompilazione produce una nuova revisione, ma solo le revisioni pubblicate sono visitabili tramite il link, per cui nel risalire le revisioni si potrà passare dalla numero 23 alla numero 12, se le versioni intermedie non sono mai state pubblicate.

Nota: essendo intenzionalmente escluse da Lettera22 tecnologie database, tutte le relazioni sono costituite staticamente da hyperlink HTML.

4.10 In pratica...

[indice]

Quando si lavora ad un solo documento per volta, sono quasi sempre sufficienti le seguenti due icone per procedere nello sviluppo

ovvero l'esecuzione del parsing-compile che "rinfresca" il metadoc ed esegue una ricompilazione dello stesso e il link, quando si ritiene il documento pronto per la pubblicazione.

Le operazioni "forzate" sono necessarie solamente quando si vuol ripetere l'operazione senza applicare alcuna modifica al documento.

5 Parte quinta: lo stile e la sintassi del documento

[indice]

Di quali elementi si compone il testo e come sono definiti nella sintassi di Lettera22.

5.1 Stile dei documenti e degli elementi del testo

[indice]

Lo stile (carattere, sfondo, dimensioni, margini, ecc.) è definito staticamente nel CSS [5] incluso in ogni documento e nell'indice dei contenuti. Lettera22 non supporta variazioni allo stile de nessuna componente. Questa rigidità privilegia l'uniformità e la coerenza stilistica, e solleva lo scrittore dalla necessità di ridefinire esplicitamente uno stile per i propri contenuti. Non sono inoltre previste variazioni neppure nel caso di accesso al documento tramite dispositivi specifici (es. tablet o smartphone).

Tutti gli elementi descritti in questo capitolo sono esemplificati nel documento Tutte le funzionalità di stile.

5.1.1 Carattere

[indice]

Il font predefinito è il Computer Modern Serif [6], incluso in ogni documento. La scelta è caduta su questo specifico font perché largamente utilizzato per la realizzazione di documenti scientifici e non (ad esempio in LaTeX), esplicitamente studiato per essere leggibile. La dimensione del carattere del corpo del testo è 18px. Dimensioni diverse sono possibili per i titoli dell'intestazione e degli altri elementi della struttura del testo (i capitoli, o le sezioni ad esempio). I link ipertestuali che rimandano ad allegati sono evidenziati (caso unico) tramite il font "Courier New".

5.1.2 Grassetto, italico e link

[indice]

Le uniche proprietà attribuibili al testo sono il grassetto e l'italico che hanno la stessa sintassi dei corrispondenti tag HTML (< b>...< /b> per il grassetto, < i>...< /i> per l'italico). Il sottolineato è riservato per evidenziare i link ipertestuali.

5.1.3 Layout

[indice]

Tutto il testo viene suddiviso in paragrafi con allineamento giustificato. Ogni paragrafo comincia con un'indentazione e viene separato del paragrafo precedente da un'interlinea doppia rispetto a quella definita tra le normali righe del testo. La larghezza massima di ogni riga è 500px (il testo si sviluppa in un'unica colonna). Ogni riga conterrà quindi al più 66 caratteri (all'interno dell'intervallo che prescrive 50-75 caratteri per riga per rendere più scorrevole la lettura).

5.1.4 Colori

[indice]

Lo sfondo di ogni pagina (sia di documento che dell'indice) è lo #faf9f1, un bianco "caldo", che ricorda il colore della carta. Per migliorare il contrasto, il testo è sempre di colore nero.

5.2 La sintassi

[indice]

In questo capitolo si descrive la sintassi ammessa da Lettera22. Tutte le feature sono inoltre riassunte nei commenti dell'intestazione di ogni documento:

5.2.1 Struttura del documento (capitoli, sezioni, paragrafi, ecc.)

[indice]

Ogni documento, dal tag [start] in poi, è suddiviso in capitoli, sotto capitoli, ecc., ovvero avrà necessariamente una struttura. Per rendere la struttura veloce da realizzare e facile da leggere si utilizza l'indentazione con la tabulazione.

Ogni volta che il testo di una riga comincia con quattro punti (::), il parser converte tale testo in un elemento di struttura (titolo) tanto più "piccolo" quanto più l'elemento è annidato (indentato). Ogni tabulazione in più rispetto all'elemento di struttura precedente determina l'apertura di una sotto struttura (es. capitolo 1, sotto capitolo 1.1). Viceversa ogni volta che '::' viene utilizzato allo stesso livello di indentazione (o ad un livello inferiore), si chiude l'elemento precedente e se ne apre uno nuovo.

es.

Ogni elemento di struttura supporta delle opzioni

Per applicare tali opzioni ad un elemento di struttura occorre post-porre l'opzione al testo

es.

Il testo nelle righe successive ad un elemento di struttura si considera facente parte di quell'elemento e quindi, per coerenza, mantiene il medesimo livello di indentazione. Si ricorda che gli elementi di struttura possono essere automaticamente numerati se il tag delle opzioni del documento [showUnitNumber] non è commentato.

Ogni "a capo" viene interpretato come la chiusura di un paragrafo e l'apertura di quello seguente. La presenza di più linee vuote viene ignorata e considerata come la chiusura del paragrafo.

5.2.2 Elementi del testo

[indice]

Oltre al testo semplice possono essere rappresentati nel corpo del documento anche alcuni elementi complessi.

5.2.2.1 Citazioni

[indice]

La citazione è utilizzata per evidenziare un testo tramite apici.

es.

5.2.2.2 Liste

[indice]

Le liste supportate sono di due tipi: ordinate (ogni punto è numerato, in numeri romani),

o non ordinate (ogni punto è "anonimo")

Attenzione: all'interno di lista non è possibile includere altri elementi. Non si può per esempio rappresentare una citazione nel terzo elemento di una lista.

5.2.2.3 Interruzioni di linea

[indice]

A volte si rende necessario interrompere una linea (andare a capo), senza chiudere il paragrafo. Andare a capo con "invio" infatti chiude il paragrafo e ne apre un altro, con relativa indentazione automatica della prima riga. Per interrompere solo la riga è sufficiente porre una doppia barra verticale (
) tra una parola e l'altra, senza andare effettivamente a capo nel testo.

es.

5.2.2.4 Immagini

[indice]

L'inserimento di immagini è realizzato tramite la seguente sintassi

dove il percorso dell'immagine è relativo al file txt all'interno della cartella "textworks".

Sono supportate jpg, gif e png. L'immagine viene inclusa nel file di destinazione in fase di compilazione. Ogni immagine viene rappresentata centrata e con la larghezza massima di 500 px (la colonna del testo), mentre l'altezza viene ridimensionata proporzionalmente.

Attenzione: è richiesto che il tag di immagine sia contenuto in una riga senza altro testo prima e dopo per essere ben interpretato.

5.2.2.5 Allegati

[indice]

Con sintassi simile alle immagini è possibile riferirsi agli allegati del documento.

es.

Attenzione: il file allegato NON viene incluso nel documento e NON viene copiato automaticamente sullo spazio remoto dal linker. Questo significa che gli allegati dovranno essere caricati manualmente sullo spazio Web del sito dove sono pubblicate le pagine (es. tramite un client FTP come FileZilla). Il percorso relativo del file allegato deve essere coerente con il file system remoto: per essere scaricabile, il file docs.zip dovrà essere in copiato in una sottocartella (in questo caso "attachments") appositamente creata dentro la cartella dove si trova il documento che vi fa riferimento.

Essendo l'allegato un link, nel percorso è necessario l'uso del carattere "slash" (/) e non del "backslash" (\), dato che il primo è il separatore valido per gli indirizzi Web.

Il testo che appare dopo la "pipe" (|) (es. ...|documenti allegati]) è quello che invece sarà visualizzato nel documento, come testo del link.

L'allegato sarà sempre aperto in una nuova pagina web, senza mai "sostituire" il documento principale.

5.2.2.6 Riferimenti bibliografici

[indice]

Per concludere, la seguente sintassi descrive un riferimento bibliografico

dove il testo che segue i due punti sarà riportato in calce al documento, con una numerazione progressiva automaticamente aggiornata. Nel punto in cui il riferimento viene inserito apparirà il numero della nota (es. [2]), che costituisce un link interno al documento.

6 Parte sesta: approfondimenti

[indice]

6.1 Lavorare offline

[indice]

Lettera22, per il solo lavoro di scrittura e generazione degli artefatti, non richiede la presenza di una connessione Internet attiva. I tool di parsing e compilazione, lavorano esclusivamente all'interno della cartella "textworks". L'attività di link inoltre può procedere fino alla generazione automatica (locale al PC) dell'indice dei contenuti, e si interromperà nel momento in cui viene verificata l'impossibilità di raggiungere lo spazio remoto del sito.

6.2 Rinominare un documento

[indice]

Al momento per rinominare un documento è necessario eseguire l'operazione manualmente sul nome dei file

che si trovano nella cartella "textworks" mentre i file

con il vecchio nome che si trovano nella cartella "pre_published" e "published", potranno essere eliminati e rigenerati.

Si ricorda che il nome del file è l'identificativo di base di ogni documento e di conseguenza dovrà essere sempre modificato in modo coerente tra i file txt e xml: in caso contrario Lettera22 non sarà in grado di ricostruire il legame tra il file raw e il metadoc e il documento sarà considerato "nuovo".

6.3 Eliminare un documento

[indice]

L'eliminazione di un documento dovrà avvenire in modo simile al cambio di nome: occorrerà cercare ed eliminare manualmente ogni file locale dalle cartelle "textworks", "pre_published" e "published". Sarà inoltre necessario eseguire un nuovo link dei documenti pubblicati (all_link globale) in modo da aggiornare l'indice senza il documento eliminato. Il file html online, anche se non più nell'indice, sarà però ancora disponibile sul web server, quindi occorrerà accedere allo spazio web ed eliminarlo manualmente anche da li.

Purtroppo al momento non è possibile eliminare le revisioni di un documento rimosso.

6.4 Condividere i documenti tra due postazioni di lavoro

[indice]

Lettera22 non supporta l'elaborazione concorrente dello stesso documento. Se lo stesso documento viene elaborato da due postazioni separate, la seconda versione sovrascriverà la prima senza eseguire alcuna "fusione".

La maniera più semplice per cui uno stesso autore possa lavorare in postazioni diverse, è copiare la cartella di Lettera22 in una chiavetta USB (pen drive) da portare fisicamente tra più PC.

Si ricorda che tali archivi di massa, sono molto meno affidabili e performanti rispetto agli hard disk. Si consiglia quindi di eseguire con una certa frequenza una copia di backup del contenuto della chiavetta.

6.5 Collaborazione di più autori allo stesso sito

[indice]

Lettera22 supporta la collaborazione di diversi autori allo stesso sito. I documenti dei diversi autori confluiranno nello stesso indice ma ogni autore dovrà condividere le opzioni necessarie alla pubblicazione online dei contenuti nella sua copia di Lettera22.

6.6 Eseguire il backup dei documenti e del software

[indice]

Essendo Lettera22 un software portabile, la miglior soluzione per i backup periodici è quella di eseguire manualmente la copia in altra locazione (possibilmente sicura e offline) dell'intera cartella Lettera22 (o per lo meno della cartella "docRoot"). Per automatizzare la cosa è anche possibile utilizzare dei software di sincronizzazione, che eseguono la stessa operazione ma in modo più efficiente (per esempio creando dei backup incrementali, in cui solo i file effettivamente modificati sono aggiornati nel backup). Per questa modalità di backup si consiglia il tool gratuito FreeFileSynch.

6.7 Creare un documento multilingua

[indice]

Non è supportata la modalità multilingua, cioè non è presente al momento alcun meccanismo che consenta di eseguire e rappresentare una traduzione di un testo interna al documento. E' quindi necessario creare una nuova versione del documento nella lingua prescelta (le versioni non saranno però collegate).

6.8 Verifica della firma dell'indice

[indice]

Come detto ogni indice pubblicato può essere firmato tramite PEC. L'oggetto della PEC sarà l'hash dell'indice pubblicato, ovvero il codice alfanumerico che ne descrive il contenuto. Nella cartella "docRoot/history" sono archiviate tutte le firme (file datiCert xml) e tutti i relativi indici. Per validare la firma occorre verificare la corrispondenza tra l'hash contenuto nel file daticert e il corrispondente index html, facendone calcolare l'hash SHA256 ad uno dei tanti tool disponibili online.

6.9 Recupero di una certa versione di un documento (hash)

[indice]

Per recuperare una versione di un documento, ad una certa data occorre:

6.10 Stampa di un HTML compilato con Lettera22

[indice]

Per stampare un artefatto generato da Lettera22, la cosa più semplice è aprire il file html con Word o Libre Office. Essendo il documento consistente (non facendo uso di risorse esterne), l'impaginazione e la struttura dovrebbero essere già pronte per la stampa, a meno di modifiche minimali.

6.11 Applicare gli aggiornamenti di Lettera22

[indice]

Lettera22 al momento non include alcuna facilitazione per l'applicazione di aggiornamenti a versioni successive. Essendo però ben separate le cartelle del software ("bin") e dei documenti ("docRoot"), si consiglia di procedere nel seguente modo:

  1. eseguire un backup generale;
  2. rinominare la cartella "bin" in "_bin";
  3. estrarre dall'archivio con la versione aggiornata la sola cartella "bin", e copiarla all'interno di Lettera22;
  4. verificare l'avvio del software e il corretto funzionamento;
  5. eliminare la cartella "_bin";

Nota: le modifiche eventualmente apportate all'editor Notepad++ (es. configurazione personalizzata) saranno azzerate da questa operazione.


Bibliografia

[1] Notepad++, maggiori info su https://notepad-plus-plus.org/
[2] La firma digitale è lo strumento software crittografico che consente di attribuire in modo incontrovertibile la proprietà di un'informazione, https://it.wikipedia.org/wiki/Firma_digitale
[3] L'hash è la stringa alfanumerica che descrive il contenuto di un documento, https://it.wikipedia.org/wiki/Secure_Hash_Algorithm
[4] Approfondimento su SEO, https://it.wikipedia.org/wiki/Ottimizzazione_per_i_motori_di_ricerca
[5] CSS, Cascading Style Sheet, è la sintassi utilizzata per definire lo stile dei documenti di Lettera22 https://it.wikipedia.org/wiki/CSS
[6] Computer Modern, https://it.wikipedia.org/wiki/Computer_Modern, il font predefinito in Lettera22


[indice]