Questo documento raccoglie la sintassi di aWiki (Almost Wiki).
Per sapere cosa è un WIKI fare riferimento a: http://it.wikipedia.org/wiki/Wiki
Indice dei contenuti
aWiki è un sistema WIKI semplificato basato su testo, dove ogni articolo rappresenta una unità di contenuto oppure un indice che raccoglie riferimenti ad unità di contenuto. La chiave univoca che distingue un articolo dall'altro è il nome del file, generato automaticamente dal sistema e basato sul titolo dell'articolo. Il titolo dell'articolo è generato a partire dal LINK (vedi: #Link ad altri documenti).
In breve un link tipo: Nuovo articolo genera un contenuto dal titolo Nuovo articolo che a sua volta genera un file nuovo_articolo.txt dove è fisicamente contenuto il testo.
E' quindi estremamente importante scegliere con cura le parole da linkare, essendo consapevoli che:
La sintassi di aWiki è estremamente semplice, ma anche limitata rispetto ad altri WIKI e a HTML. La sintassi è stata studiata per essere il più chiara ed intuitiva possibile. Ha inoltre una curva di apprendimento molto alta.
Il miglior modo per imparare aWiki è confrontare un articolo con il suo sorgente, posizionati sul testo scelto e premi "EDIT". Un altro modo è abilitare la funzione di #debug.
Il concetto di ambiente è l'unico concetto da imparare. Un ambiente definisce uno spazio di formattazione ed è separato dagli altri da una e una sola riga vuota. Quindi: salta una riga e inizia a scrivere, esempio:
=== sono un titolo === sono un paragrafo un altro paragrafo + una lista + numerata == un altro titolo ==
Gli ambienti sono definiti nello specifico dal primo carattere a sinistra del documento, ad esempio un + indica l'inizio di una lista numerata, un = un titolo, dove non ci sono caratteri speciali inizia un paragrafo. aWiki dovrebbe essere in grado di correggere le righe vuote non necessarie. aWiki dovrebbe anche essere in grado di recuperare i titoli delle sezioni, ovvero è accettabile scrivere:
=== Titolo di sezione === Un paragrafo ==== Altro titolo ==== +lista numerata +lista numerata
Come detto un ambiente è definito da una riga vuota seguita dal testo. Un ambiente si distingue dall'altro per il carattere con cui inizia il testo. Se all'interno dell'ambiente occorre scrivere il carattere che distingue quell'ambiente da un altro allora si dovrà proteggere questo carattere con il backslashes \, ad esempio (vedi anche #Il ruolo di backslashes):
== Scrivere il simbolo \= in un titolo == + scrivere il simbolo \+ in una lista + numerata
| Carattere di escape | Carattere stampato | Ambiente di riferimento |
|---|---|---|
| \+ | + | lista semplice o numerata |
| \- | - | lista semplice o numerata |
| \; | ; | lista di definizioni |
| \: | : | lista di definizioni |
| \= | = | titolo di livello 1-5 |
| \> | > | citazione |
| \^ | ^ | sequenza escape |
| \| | | | In una tabella |
| \{ | { | In una tabella |
| \@ | @ | codice |
| \\\ | \ | ovunque nel documento |
La backslashes è un questo carattere \ ed è un simbolo fondamentale in aWiki e quindi anche il più problematico. Backslash ha tre ruoli:
Le azioni avvengono esattamente in quest'ordine di priorità, quindi in caso di ambiguità la questa priorità avrà prevalenza sull'effetto desiderato. Ricordiamo che per stampare a video il carattere \ è necessario digitare tre volte lo stesso \\\.
<nowiki></nowiki> è un ambiente speciale. In qualsiasi parte del documento è possibile inserire del testo tra i due tag <nowiki></nowiki> per evitare che aWiki vi applichi le sue regole. E' possibile farlo all'interno di qualsiasi ambiente. Ad esempio: [[link non parsato]].
Altre aree speciali sono <code></code> e <pre></pre> (assunti come sinonimi) che consentono di inserire codice HTML senza che questo venga parsato dal browser.
Tutte le aree speciali possono esendersi su più linee anche non consecutive.
Le prime righe sono riservate alle instastazioni, troverete quindi un incipit composto in questo modo:
Queste righe vanno personalizzate, ad esempio scrivendo il vostro nome vicino ad |
Gli headers contengono due parametri opzionali: |
Produrrà questo output:
<title>aWiki Syntax Help</title> <meta name="author" content="Andrea Ganduglia Mario Rossi"/> <meta name="copyright" content="(c)2005 Andrea Ganduglia"/> <meta name="date" content="2005-07-25 15:51:30"/> <meta name="description" content="Questa pagina descrive la sintassi di aWiki"/> <meta nema="keywords" content="php, apache, mysql, linux, lamp, vim, editing, wiki, free software"/> ...
Un terzo parametro opzionale è |
In ogni altra parte del documento una riga che inizia con carattere |
+ Una lista che continua
+ su righe differenti
Esistono solo 5 tag di formattazione del testo: grassetto, corsivo, sottolineato, typing e over. Questi possono essere inseriti in qualunque parte del testo (headers esclusi). Ecco la sintassi:
| Sintassi | !Output |
|---|---|
| **grassetto** | grassetto |
| //corsivo// | corsivo |
| __sottolineato__ | sottolineato |
| ||typing|| | typing |
| $$vecchia informazione$$ |
Esiste inoltre la possibilità di evidenziare un singolo paragrafo, basta iniziare il paragrafo con il simbolo !, es:
!Sono un paragrafo evidenziato con del **testo in grassetto** e in //corsivo//
Sono un paragrafo evidenziato con del testo in grassetto e in corsivo
All'interno di un paragrafo o di un altro elemento, è assolutamente possibile andare a capo nel punto desiderato; per farlo è necessario indicare questo punto con uno speciale carattere, una doppia backslashes \\. Esempio:
Esempio 1 Questo paragrafo anche se scritto su più righe sarà sempre visualizzato come fosse su una sola
**Esempio 2** Mentre in quest'altro posso decidere di andare a capo qui\\ e poi di nuovo qui\\ e scrivere ancora
Esempio 2 Mentre in quest'altro posso
decidere di andare a capo qui
e poi di nuovo qui
e scrivere ancora
Per andare a caso in modo sicuro è sufficiente lasciare uno spazio dopo la doppia backslashes, soprattutto nel caso il carattere seguente sia un carattere speciale. Vedi anche #Il ruolo di backslashes. Ecco un paio di esempi:
Ora vado a capo\\-ma inserirsco un carattere speciale
Ora vado a capo\-ma inserirsco un carattere speciale
Ora vado a capo\\ -in modo sicuro
Ora vado a capo
-in modo sicuro
I titoli servono a suddividere l'articolo in sezioni e sotto sezioni. Esistono 5 classi di titoli, dal più grande al più piccolo di cui è opportuno utilizzare soprattutto dalla 2 alla 4. L'ambiente titolo è definito a partire dal caratte =, il numero di = prima e dopo il testo indica la classe.
= Titolo 1: riservato al titolo dell'articolo = == Titolo 2 == === Titolo 3 === ==== Titolo 4 ==== ===== Titolo 5 =====
L'indice dei contenuti (TOC) è generato a partire dai titoli presenti nel documento. Il TOC può essere inserito in qualsiasi parte del testo con la sintassi
__TOC__
utilizzandolo come un normale ambiente. Solitamente è meglio usarlo negli articoli medi e lunghi, preceduto da un breve paragrafo introduttivo come abstratc. Questo indice viene stampato, vedi anche #Indice dinamico.
Sono un paragrafo introduttivo... __TOC__ == titolo di secondo livello == paragrafo paragrafo === titolo di terzo livello ===
In alto a destra è sempre presente un piccolo riquadro che dice "Mostra indice", cliccando sopra di esso si apre un indice completo di tutti i titoli che serve per navigare l'articolo. Contrariamente al primo #Indice dei contenuti questo non viene stampato, ma è incluso in ogni pagina automaticamente. Assieme alla voce mostra indice si trova la voce "Top" che permette di risalire alla testa della pagina e "Edit" che consente di editare la pagina.
Sono tre i tipi di lista che possono essere utilizzati: semplice, numerata, definizioni. Ogni lista è un ambiente, i vari elementi possono essere scritti tutti su una riga o su righe differenti, basta che siano preceduti dal carattere di inizio ambiente.
- sono una lista semplice - i miei elementi non sono numerati - e questa riga ne contiene - due differenti
+ primo elemento + secondo **elemento** + terzo elemento + altro elemento?
Le liste miste o indentate permettono di utilizzare le liste semplici e numerate su livelli differenti. Per stabilire il livello di indentazione è sufficiente ripetere il carattere di inizio ambiente. Non ci sono limiti al livello di indentazione.
+ Primo livello numerato -- Secondo livello non numerato -- Secondo livello non numerato +++ Terzo livello numerato +++ Terzo livello numerato -- Di nuovo secondo livello --- Terzo livello non numerato ---- Quarto livello +++++ Quinto livello +++++ Quinto livello + Torno al primo livello
Nel testo è possibile inserire una o più note a pié di pagina[2]. La sintassi per le note è la seguente:
{footnote Testo della nota con notazione lunga}
{fn Testo della nota con notazione abbreviata}
{FN Testo della nota con notazione abbreviata maiuscola}
Le tre sintassi possono essere usate indiffentemente.
aWiki supporta un semplice tipo di tabelle, dove ogni riga ha lo stesso numero di colonne. E' possibile stabilire una riga di intestazione della tabella ed una utilizzata come titolo della tabella. Ogni cella è separata dalle altre da una barra verticale (|). Ogni cella può essere allineata a sinistra (default) se le prime lettere sono SX, a destra se sono DX, al centro se sono XX. All'interno delle celle è possibile inserire qualsiasi tipo di #formattazione, tranne il tipo typing che dovrà essere espresso con il corrispettivo html <tt>typing</tt> e qualsiasi tipo di #link.
{||Titolo della tabella
{|!Colonna1|Colonna2|Colonna3
{| Dato colonna 1 | Dato colonna 2 | Dato colonna3
{|SX A sinistra |DX A destra |XX Al centro
| Colonna1 | Colonna2 | Colonna3 |
|---|---|---|
| Dato colonna 1 | Dato colonna 2 | Dato colonna3 |
| A sinistra | A destra | Al centro |
aWiki è fornito di una serie di sintassi avanzate che possono essere utilizzate all'interno dei documenti. Sono trattate qui in modo sintetico. Sono tutti ambienti, da trattare come tali.
| Meta carattere | Esempio | Descrizione |
|---|---|---|
| ~ | ~~~ | Linea orizzontale |
| > | >testo testo | Citazione |
| @ | @testo testo | Codice (usare #<code>) |
| ^ | ^codice html | Escape, non viene parsato (usare #<nowiki>) |
[[link]]
Il cuore di aWiki sono i link ad altri documenti. Con questo strumento è possibile unire due diversi articoli o iniziare un nuovo documento. Fare un link è davvero semplice, basta contornare le parole desiderate con doppie parentesi quadre [[parole]], questa sinstassi genererà un link che permetterà al sistema di cercare un documento che abbia come titolo le parole incluse tra le parentesi.
L'unico modo di imparare ad usare correttamente i link è provare, tenendo conto di ciò che è stato detto nella #Introduzione e nel paragrafo #Lezione di stile.
I link sono soggetti a qualche limitazione, ad esempio è bene evitare di linkare parole che contengano accentate, o caratteri strani, come virgolette, simboli, etc. In generale è opportuno scegliere le parole più significative e nel numero minore possibile.
La struttura completa di un link è:
[[namespace:link#anchor|label]]
[[awiki:install|istruzioni per l'installazione]]
Risultato: istruzioni per l'installazione
[[awiki:install]]
Risultato: install
[[mainpage|Vai alla home page]]
Risultato: Vai alla home page
[[#Link ad altri documenti]]
Risultato: #Link ad altri documenti
[[#Link ad altri documenti|Leggi la sezione dedicata ai link]]
Risultato: #Leggi la sezione dedicata ai link
[[mainpage#Sezione]]
Risultato: mainpage
[[awiki:help#Link ad altri documenti]]
Risultato: help
[[awiki:help#Link ad altri documenti|Vai alla sezione]]
Risultato: Vai alla sezione
Per linkare un sito esterno all'interno di un articolo occorre utilizzare questa sintassi:
{{http://www.indirizzo.ext|descrizione del sito}} oppure {{http://www.indirizzo.ext}}
descrizione del sito oppure http://www.indirizzo.ext
E' possibile utilizzare questa sintassi per i protocolli http, ftp, https, file. Inoltre è possibile utilizzare la medesima sintassi per gli indirizzi mail
{{some@mail.ext|Scrivi a Giovanni}} oppure {{some@mail.ext}}
Scrivi a Giovanni oppure some@mail.ext
Il namespace è una caratteristica importante, soprattutto quando si trattano molti argomenti sullo stesso aWiki perché permette - in breve - di avere lo stesso nome di file per due argomenti differenti. Ad esempio se parlate di musica e di Linux è possibile che vogliate usare in entrambi la pagina Samba, ecco allora che usando il namespace musica e linux sarà possibile riferirsi ad uno o all'altro come:
[[musica:samba|danza popolare]] [[linux:samba|documentazione tecnica]]
Attraverso #pagina speciale #All Pages si potranno cercare tutte le pagine samba o tutte le pagine che appartengono ad uno specifico namespace.
Gli articoli di aWiki possono contenere degli allegati (immagini o documenti). Questi allegati possono essere gestiti attraverso la pagina di #upload.
Per visualizzare una immagine all'interno di un documento occorre utilizzare questa sintassi:
{img nomeimmagine.ext WIDTH HEIGHT dx|sx|xx|none DESCRIPTION}
Le immagini posso essere posizionate all'interno di qualsiasi ambiente. I valori WIDTH ed HEIGHT fanno rispettivamente sostituiti con altezza e larghezza dell'immagine. I valori sx|dx|xx|none indicato rispettivamente se l'immagine deve essere posizionata a sinistra, a destra, in centro o se non si hanno preferenze. La descrizione dell'immagine (DESCRIPTION) viene utilizzata in sostituzione dell'attributo alt. Questi sono tutti esempi validi sul come inserire una immagine:
{img nomeimmagine.ext}
{img nomeimmagine.ext dx}
{img nomeimmagine.ext Descrizione dell'immagine}
{img nomeimmagine.ext sx Descrizione dell'immagine}
{img nomeimmagine.ext 300 150 sx}
L'unico parametro richiesto è il nome dell'immagine. Se si indicano le dimensioni è necessario indicarle entrambe, in caso vi sia un solo valore numerico questo viene assunto come larghezza. I valori possono essere espressi in "px" o
Per linkare un documento all'interno di un articolo occorre utilizzare questa sintassi:
((nomedeldocumento.ext|descrizione del documento)) oppure ((nomedeldocumento.ext))
descrizione del documento oppure nomedeldocumento.ext
aWiki tiene le versioni dei documenti se questi differiscono del 1
Nella pagina Edit, accando al tasto Salva e allo spazio per inserire la pwd c'è un checkbox il cui label è Force history. Questo checkbox se selezionato forza il sistema a salvare l'ultima versione del documento che state modificando nella history, indipendentemente dalla quantità delle modifiche.
Attenzione! La history è manutenuta in automatico sulla quantità non sulla qualità del testo. Per modifiche importanti, anche se minime, usate l'opzione Force history.
Le pagine speciali sono pagine che permettono particolari operazioni. Alcune delle caratteristiche qui elencate possono essere disabilitate a seconda dell'installazione e delle configurazioni fatte dall'amministratore.
All Pages permette di listare tutti gli articoli, le immagini e i documenti facendo ricerche sul nome del file. Sempre da questa pagina è possibile ottenere informazioni su ogni singolo file (dimensione, data, etc.) ed accedere alla pagina speciale Manage attraverso cui rinominare o cancellare un file.
Dalla pagina di Upload è possibile caricare sul sistema immagini, documenti e articoli (come testo). E' anche possibile rinominare il file contestualmente al caricamento, utile se ad es. avete un'immagine che si chiama 0000021.jpg e volete chiamarla foto_di_gruppo.jpg, l'estensione è mutuata dal file originario.
La pagina Search permette ricerche fulltext su tutta la base dati. Da questa pagina è possibile accedere alla pagina speciale BuildIndex per la ricostruzione dell'indice. E' necessario MySQL per questo modulo.
Dalla pagina History è possibile listare tutte le modifiche effettuate al file. Attualmente non esiste un modo per amministrare questi file, inoltre ha history è soggetta a #qualche limitazione.
E' possibile in ogni pagina visualizzare il debug della sintassi. Per farlo e' sufficiente aggiungere alla stringa ./?qq=pagename &debug=html. E' ovviamente possibile costruire un link che contenga il debug, vi veda: mostra debug per questa pagina [3].
Il debug stampa a video il codice html prodotto dal parser.
Lo stile è importante.
E' necessario che le pagine siano il più possibile omogenee e ben strutturate. Fate attenzione al fatto che aWiki non è un database, ma un ipertesto basato sulle parole. Le parole scelte per i link sono essenziali, perché devono essere poche (possibilmente una o due) e devono identificare in modo univoco una risorsa. Non c'è niente di più importante che scrivere un buon link.
Un altra cosa importante è non essere sciatti. Non scrivete un articolo a metà, non serve a nessuno. Il miglior modo per scrivere un articolo è scriverlo in locale, dentro un normale editor di testi (blocco note, gVim, etc.) e solo una volta finito copiarlo e incollarlo al posto giusto.
Non c'è bisogno di creare sempre nuovi articoli. Quando incontrate una risorsa che dice "La documentazione per questo argomento non e' ancora disponibile." e siete in grado di scrivere su quell'argomento FATELO! Una documentazione limitata, ma completa è meglio che una mappa vuota.
Se dovete iniziare un nuovo articolo, trovatene un altro che abbia le parole giuste per creare un link e iniziate di là: mettere tutto in homepage è inutile e fuorviante.
Non usate gli indici e il paragrafo evidenziato solo perché "è bello". Fatelo se ne avete realmente bisogno, regola che dovrebbe valere per tutto il resto.
Il miglior modo per imparare le regole di aWiki è copiare quello che fanno bene gli altri.
Note al documento
I due punti sono consentiti solo come separatore di #namespace, ma non alle estremità del link
Questa è una nota a pié di pagina di esempio. Le note possono contenere link ad altri documenti, testo formattato, link esterni ed altro.
Notare che si è utilizzato un link esterno a causa dei limiti sui caratteri introdotti con la versione 0.9.2 vedi change logs.