====== Wiki: mantenere la documentazione in modo efficace ======

{{wiki_logo.jpg |}}
 L'**aggiornamento della documentazione** prodotta e' uno degli aspetti piu' critici del lavoro collaborativo 
a causa della difficolta'  nell'immissione dei dati e nel coordinamento tra i diversi autori,  con il rischio di 
avere una documentazione incompleta, obsoleta o contraddittoria.  \\
**Wiki** e' un strumento di GroupWare per creare e mantenere documenti web dinamici 
in modo semplice ed efficace usando un Web Browser.
La stessa pagina Web utilizzata per la consultazione ne consente la modifica, che puo' essere 
realizzata da diverse persone.  
\\


**La modifica** avviene tipicamente con un meta-linguaggio (Markap Language), semplice da utilizzare, che verra' tradotto in HTML.  Ad esempio la modifica della parte iniziale di questo tutorial avviene utilizzando una finestra di editing ed una sintassi del tipo:


| {{  wiki.png  | Esempio di Editing }} |


**Il lavoro di gruppo** e' gestito grazie al blocco che un autore 
esercita su di un documento o di una sua parte al momento della modifica; il Wiki inoltre gestisce in modo semplice ed automatico le diverse revisioni dei documenti, consentendo rapidamente, con la funzionalita' "Differenze", di individuare le modifiche apportate ed eventualmente provvedere al ripristino di revisioni precedenti.

| {{  wiki_diff.png  |  Differenze}} |

L'**autenticazione** degli utenti viene stabilita dall'amministratore che, a seconda dell'utilizzo, puo' attivare  l'autoregistrazione, oppure utilizzare una infrasruttura di backend come puo' essere Ldap o PKI. In questo caso e' possibile creare policy di autorizzazione per singoli utenti o gruppi, applicate a singole pagine o a gruppi di documenti, i NameSpace, differenziando l'accesso in lettura e modifica 

**L'ambito di utilizzo** prevalente e' quindi quello di una collaborazione ad 
un progetto comune, in cui il wiki rappresenta lo strumento condiviso per la documentazione.


Esistono piu' di **100 diverse implementazioni** (http://www.wikimatrix.org/),  con diverse caratteristiche specifiche.
[[wp>Mediawiki]] e' il Wiki più noto a causa del suo impiego nell'applicazione che ha reso popolare lo strumento Wiki: l'Enciclopedia [[wp>Wikipedia]].\\
Un'altro Wiki molto diffuso per la sua semplicita' e' [[doku>wiki:dokuwiki | Dokuwiki]]. Dokuwiki e' stato adottato dalla Commissione Calcolo e Reti dell'INFN  come Wiki  Centrale di riferimento per l'Ente: http://wiki.infn.it.\\

Nella seconda parte del tutorial  vedremo quanto sia facile creare ed aggiornare documentazione utilizzando DokuWiki. 
 

====== DokuWiki Tutorial ======



==== Navigazione ====
Un sito Dokuwiki contiene un insieme di documenti identificati da un nome ed eventualmente preceduto da un Namespace.

| {{  roberto.alfieri:wiki-naming.png?400 | Naming  }} |

In questo esempio roberto.alfieri e' il Namespace e wiki-tutorial e' il nome.
I NameSpace possono essere  organizzati all'interno di una infrastruttura gerarchica per poter gestire  in modo strutturato l'insieme dei documenti.  Ad esempio **roberto.alfieri:priv:documento_riservato** ha due livelli di NameSpace. 
L'amministratore puo' attribuire policy di accesso specifiche per ogni NameSpace o singola pagina.\\




==== Policy di Accesso ====

L'accesso al Wiki può avvenire in modo anonimo o autenticato. Gli utenti autenticati possono appartenere a uno o piu' gruppi.  
Per l'autenticazione l'amministatore puo' utilizzare un sistema interno di autoregistrazione o puo' utilizzare una eventuale infrastruttura di Autenticazione preesistente (e.g. LDAP). 
I permessi di accesso (lettura/modifica) ai NameSpace o ai singoli documenti vengono attibuiti dall'amministratore agli utenti, ai gruppi, a qualunque utente autenticato (@user) o agli utenti non autenticati (@ALL),  mediante le ACL (Access Control List). 

| {{ http://wiki.splitbrain.org/_media/wiki:acladmin.png?400 }} |

L'indirizzo URL di  un documento Dokuwiki del tipo  **namespace:mydoc** si compone nel seguente modo:
   http://server/dokuwiki/doku?id=namespace:mydoc
Un semplice modo per **creare una nuova pagina** consiste nel generare un URL di un documento che non esiste: dokuwiki presentera' una pagina per la sua creazione con il nome indicato nell'URL, ammesso che l'utente abbia i permessi necessari.

==== Editing ====

Se l'utente e' abilitato alla modifica, sul documento appaiono diversi pulsanti "Modifica" che  consentono di entrare nell'editor dell'intero documento o solo di una sezione, acquisendone l'accesso esclusivo. L'editing avviene con un meta-linguaggio piu' semplice e piu' rapido da inserire rispetto all'HTML. 
Comunque ad un primo livello di utilizzo il documento puo' essere editato senza conoscere il meta-linguaggio, ma semplicemente utilizzando i "Pulsanti ad Accesso Rapido" disponibili sopra l'area di Editing.

| {{  wiki.png  | Area di Editing con Pulsanti ad Accesso Rapido  }} |

Esistono inoltre Plugins  che consentono l'editing WYSISYG ([[doku>plugin:wysiwyg]]).

La sintassi Dokuwiki e' molto semplice e ben documentata: [[http://wiki.splitbrain.org/wiki:it:syntax | Syntax ]].\\
Il pulsante "Mostra Pagina" di un documento esistente ci consente di imparare rapidamente "per esempi".










==== Sintassi ====

=== Testo Formattato ===

La seguente tabella riassume, a titolo di esempio, i principali elementi per la **formattazione del testo**, confrontandoli con l'HTML: 

^    Dokuwiki    ^  HTML   ^  Risultato    ^
|  <nowiki>**bold**</nowiki>   |   <b>bold</b>      |     **bold**    |
|   <nowiki>//italic//</nowiki>   |  <i>italic</i>  |   //italic//        |
|  <nowiki>__sottolineato__</nowiki>  |  <u>sottolineato</u>    |  __sottolineato__  |
|  <nowiki>\\</nowiki>  |  <br>    |  A CAPO  |
|  RIGA VUOTA  |    <p>  </p>        |  NUOVO PARAGRAFO  |
| <nowiki>log<sub>2</sub></nowiki> |  <nowiki>log<sub>2</sub></nowiki>    |  log<sub>2</sub>  |
| <nowiki>3<sup>2</sup></nowiki> |     <nowiki>3<sup>2</sup></nowiki>      |  3<sup>2</sup>  |



Se l'amministatore dell'installazione lo consente, e' comunque possibile inserire direttamente parti del documento scritte in **HTML**. Ad esempio:

<nowiki><html><font color="red">ROSSO</font></html></nowiki> diventa: <html><font color="red">ROSSO</font></html>



=== Testo non formattato ===

In alcuni casi e' utile visualizzare **testo senza formattazione** (righe di codice, caratteri speciali, parole chiave, ..).\\
L'interprete Dokuwiki puo' essere disbilitato delimitando il testo senza formattazione con il  tag <nowiki><nowiki></nowiki>, come ad esempio **<nowiki><nowiki>//italic//</nowiki><nowiki></nowiki></nowiki>**

Il testo non formattato puo' essere incluso in specifici riquadri:

  Due spazi all'inizio della riga disabilitano l'interprete per i caratteri dell'intera riga.

Si puo' creare un'area di testo non formattato delimitandola con i tag <nowiki> <code> </code></nowiki>.
Grazie al supporto di [[http://qbnz.com/highlighter/ | GeSHi]] (Generic Syntax Highlighter) il tag <nowiki> <code> </nowiki> può evidenziare codice sorgente in modo da renderlo più facile da leggere. Il seguente esempio e' delimitato da <nowiki> <code java> </code> </nowiki>:
<code java>
class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); //Visualizza la stringa.
    }
}
</code>

=== Intestazioni ===

Se esistono piu' di 3 intestazioni (di livello 1, 2 o 3) **l'indice** del documento viene generato automaticamente in un opportuno riquadro della pagina.\\
 L'indice automatico puo' essere disabilitato includendo la stringa <nowiki>~~NOTOC~~</nowiki> nel documento.\\
Le intestazioni dal livello 1 al livello 5 si creano così:


^    Dokuwiki  ^ Risultato ^
|  <nowiki>======Intestazione 1=======</nowiki>  |  <html><font size="5">Intestazione 1</font></html>  |
|  <nowiki>=====Intestazione 2=====</nowiki>     |  <html><font size="4">Intestazione 2</font></html>  |
|  <nowiki>====Intestazione 3====</nowiki>       |  <html><font size="3">Intestazione 3</font></html>  |
|  <nowiki>===Intestazione 4===</nowiki>         |  <html><font size="2">Intestazione 4</font></html>  |
|  <nowiki>==Intestazione 5==</nowiki>           |  <html><font size="1">Intestazione 5</font></html>  |


=== Liste ===

Dokuwiki supporta liste ordinate e non-ordinate. Per creare un elemento di una lista bisogna indentare il testo con due spazi e usare un asterisco (*) per le liste non ordinate oppure un trattino (-) per quelle ordinate.\\
Per creare sottolivelli di liste basta aggiungere altre coppie di spazi  iniziali.
<code>
   * Primo elemento 
   * Secondo elemento 
     * Terzo elemento
</code>
   * Primo elemento 
   * Secondo elemento 
     * Terzo elemento
   
=== Link ===

I **link** possono essere riferiti a collegamenti esterni o ad altre pagine interne di Dokuwiki. E' previsto il supporto per le principali applicazioni di documentazione Web (Wikipedia, Google, ..). Gli indirizzi e-mail possono essere oscurati per proteggerli dallo Spam. Esempi:


^    Dokuwiki  ^  Risultato  ^
|<nowiki>http://www.google.com </nowiki>  | http://www.google.com |
|<nowiki>[[ http://www.google.com | google]] </nowiki>  | [[http://www.google.com | google]] |
|<nowiki>[[andi@splitbrain.org | Andi ]]</nowiki>  | [[andi@splitbrain.org| Andi]] |
|<nowiki> [[wp>DokuWiki]] </nowiki>  | [[wp>DokuWiki]] |
|<nowiki> [[google>DokuWiki]] </nowiki>  | [[google>DokuWiki]] |
|<nowiki> [[doku>wiki:plugins]] </nowiki>  | [[doku>wiki:plugins]] |


=== Immagini===

Le **immagini** possono essere interne o esterne.
Le immagini interne sono caricate con lo strumento di Upload.\\
Per attivare la **finestra di Upload** bisogna entrare nell'editor e selezionare il pulsante per inserire immagini.

| {{roberto.alfieri:bottone-upload.png|Bottone di Upload}} |


 L'upload e' possibile per un insieme di tipi di file [[doku>wiki:mime]].\\
Le immagini possono essere incluse nel documento inserendo il nome tra doppie graffe con diverse opzioni possibili, quali:


^    Dokuwiki  ^ Risultato ^
|<nowiki> {{  namespace:dokuwiki-128.png}}   </nowiki>         |allineata a destra |
|<nowiki>{{namespace:dokuwiki-128.png  }}    </nowiki>         |allineata a sinistra |
|<nowiki>{{  namespace:dokuwiki-128.png  }}  </nowiki>         |centro |
|<nowiki>{{ namespace:dokuwiki-128.png?200x50 }}  </nowiki>     |ridimensionata |
|<nowiki>{{ namespace:dokuwiki-128.png | didascalia }}</nowiki> |con didascalia |
|<nowiki>{{http://de3.php.net/images/php.gif?200x50}} </nowiki> |immagine esterna |


Se si specifica il nome di un file (esterno o interno) che non è un'immagine (gif, jpeg, png), allora esso sarà visualizzato come collegamento.

=== Tabelle ===
Una tabella si puo' creare semplicemente delimitando gli elementi delle righe con il carattere | (pipe).
Piu' Pipe adiacenti fondono gli elementi delle riga (ColSpan). Esempio:

  | Riga1 Colonna1 | Riga1 Colonna2 | Riga1 Colonna 3 |
  | Riga2 Colonna1 | Riga2 Colonna2 | Riga2 Colonna 3 |
  | Riga3 Colonna1 | Riga3 Colonna2 e Colonna 3 ||

| Riga1 Colonna1 | Riga1 Colonna2 | Riga1 Colonna 3 | xxxx
| Riga2 Colonna1 | Riga2 Colonna2 | Riga2 Colonna 3 |
| Riga3 Colonna1 | Riga3 Colonna2 e Colonna 3 ||

Il carattere ^ al posto di | attibuisce il significato di **intestazione** all'elemento che segue.
Inoltre per allineare il testo di una cella basta aggiungere 2 spazi a destra e/o a sinistra:

  ^  Colonna1^ Colonna2  ^Colonna3  |
  | Riga1 Colonna1 | Riga1 Colonna2 | Riga1 Colonna 3 |
  | Riga2 Colonna1 | Riga2 Colonna2 | Riga2 Colonna 3 |
  | Riga3 Colonna1 | Riga3 Colonna2 | Riga3 Colonna 3 |

^     Colonna1^  Colonna2  ^Colonna3  |
| Riga1 Colonna1 | Riga1 Colonna2 | Riga1 Colonna 3 |
| Riga2 Colonna1 | Riga2 Colonna2 | Riga2 Colonna 3 |
| Riga3 Colonna1 | Riga3 Colonna2 | Riga3 Colonna 3 |















====== DokuWiki a Fisica ======

Al Dipartimento di Fisica e' attivo un server [[http://www.fis.unipr.it/dokuwiki/doku.php | Dokuwiki]] Dipartimentale \\
\\
Si autentica al Dominio Fisica. Sono quindi riconosciuti (con le stesse credenziali username/password della posta)
tutti gli utenti del Dipartimento. Ogni utente puo' avere un proprio NameSpace Personale  del tipo 
<nowiki> [[nome.cognome:documento]] </nowiki> leggibile da tutti e un Namespace <nowiki> [[nome.cognome:priv:documento]] </nowiki> 
visibile solo al proprietario.\\
Si possono creare anche NameSpace per Gruppi, con le stesse policy dei Namespace personali.


----
\\
[[roberto.alfieri@pr.infn.it | Roberto Alfieri]] --- 2008/07/08