Creazione di pagine wiki

From Manjaro Linux
Jump to: navigation, search

⇐ Torna alla Pagina Principale

Panoramica

Questa pagina ha l'intento di introdurre ai concetti di base per la creazione o la modifica di pagine Wiki, in particolare per la presente Wiki, cioè la parte in italiano della Wiki di Manjaro. Verranno dettate alcune piccole regole che dovrebbero consentire un'omogeneità tra le diverse pagine della Wiki, rendendola più semplice e piacevole da consultare.

Struttura di una pagina

Per un riferimento più completo si può visitare questa pagina di Wikipedia, sfortunatamente alcuni template definiti da Wikipedia non sono presenti attualmente nella Wiki di Manjaro, ma non sono tra i più comuni.

Una pagina della Wiki possiede innanzitutto un titolo che è anche contenuto nel suo indirizzo; è possibile verificarlo semplicemente guardando il titolo di questa pagina e l'indirizzo contenuto nella barra degli indirizzi del browser.

Oltre al titolo una pagina può avere diverse strutture: una comoda divisione in paragrafi, degli elenchi puntati o numerati o altro.

Sezioni e paragrafi

Le sezioni sono utili per dividere la pagina in blocchi che trattino di un sotto-argomento specifico, facilmente accessibili dalla tabella dei contenuti presente in cima alla pagina, le sezioni sono molto semplici da creare ed il loro uso è caldamente consigliato perché facilita la consultazione del contenuto.

Semplicemente inserendo il codice

== Nome Sezione di secondo livello ==
=== Nome Sezione di terzo livello ===

verrà creata una sezione, aggiunta alla tabella dei contenuti ed al titolo verrà applicato lo stile predefinito per quel livello.

I livelli possibili sono sei, anche se quelli utilizzati più di frequente sono i primi tre o quattro. Il livello del titolo è il primo (quindi con solo un '=' per lato), ma è automaticamente inserito senza intervento dell'autore; il primo livello è riservato al titolo ed è fortemente sconsigliato il suo utilizzo all'interno della pagina Wiki.

Elenchi

È possibile creare elenchi puntati tramite la sintassi

* un'argomentazione;
** un punto dell'argomentazione;
* altra argomentazione;
  • un'argomentazione;
    • un punto dell'argomentazione;
  • altra argomentazione;

Il loro utilizzo è molto utile nel caso in cui, per esempio, si debbano enunciare le caratteristiche di un software o i punti salienti di un'argomentazione.

Sono disponibili anche gli elenchi numerati, la cui sintassi è

# prima fare questo procedimento;
## di cui questo è il primo punto;
# poi fare questo procedimento;
  1. prima fare questo procedimento;
    1. di cui questo è il primo punto;
  2. poi fare questo procedimento;

Questi sono particolarmente utili all'interno di una guida per elencare i passaggi con il loro ordine di esecuzione.

Formattazione

Un altro strumento per rendere più immediata la consultazione di pagine Wiki è l'utilizzo della formattazione adeguata.

Per utilizzare gli stili corsivo, grassetto e corsivo grassetto, è sufficiente utilizzare la sintassi

''corsivo'', '''grassetto''' e '''''corsivo grassetto'''''
Nota: I trattini non sono virgolette bensì apostrofi!

In una pagina Wiki che deve contenere esempi di comandi o output da terminale, è utile poter mettere una parte di testo in font monospace (carattere a larghezza fissa), questo può essere inserito semplicemente anteponendo uno spazio ad ogni riga di testo che si vuole ottenere in quello stile. Non essendo formattata sotto nessun aspetto, la parte di testo in monospace non verrà nemmeno mandata a capo in automatico, rischiando quindi di aumentare a dismisura la larghezza della pagina web, è necessario quindi andare a capo manualmente.

Se si vuole inserire una semplice parola in carattere monospace è sufficiente inserire la parola nel template (vd più sotto il significato) {{ic|parola}}, dove ic sta per inline code cioè codice in linea.

Mandare a capo il testo

Se nel sorgente di una pagina Wiki si manda a capo il testo una sola volta, questo non andrà a capo, verrà accodato alla linea precedente alla distanza di uno spazio. Per andare a capo è necessario mandare a capo due volte nel sorgente, questo però creerà un'interlinea maggiore del normale fra le due righe, come a separare due paragrafi. Questo comportamento è abbastanza comodo, in realtà, perché spesso non c'è necessità di andare su una nuova linea e consente di mantenere automaticamente i corpi di testo più compatti separandoli solo se viene detto esplicitamente, magari per un cambio di argomento. Durante la scrittura di una pagina Wiki è consigliabile mandare a capo sempre dopo un punto, questo permette di controllare molto più rapidamente il codice, individuando le frasi per le loro parole iniziali che si ritrovano in questo modo a margine.

Nel caso in cui sia necessario andare a capo in modo normale, quindi senza interlinea, è possibile farlo, semplicemente ponendo in coda alla riga il codice

<br>

Materiale aggiuntivo

Collegamenti

Degli strumenti utilissimi per mettere in comunicazione le diverse parti della Wiki sono i collegamenti. È possibile inserire collegamenti ad altre pagine della stessa Wiki tramite la sintassi

[[Pagina Principale]]
[[Pagina Principale|Link alla pagina principale]]

Pagina Principale
Link alla pagina principale

Oppure possono essere inseriti link esterni, facendo attenzione che siano sicuri per l'utente ed attinenti all'argomento trattato, semplicemente scrivendo

[https://it.wikipedia.org/wiki/Pagina_principale]
[https://it.wikipedia.org/wiki/Pagina_principale Pagina principale di Wikipedia]

[1]
Pagina principale di Wikipedia

Immagini

Una bellissima fotografia di nasica!

Le immagini sono un potente strumento per aiutare l'utente a comprendere cosa si può trovare ad affrontare sul proprio schermo, sono quindi consigliate in ogni guida e pagina che tratti di un software dotato di interfaccia grafica. Per aggiungere un immagine la sintassi è molto semplice.

[[File:nome_immagine.estensione|thumb|right|375px|Eventuale didascalia]]

Il significato della sintassi:

  • thumb permette di aggiungere una piccola (e graziosa) cornice attorno all'immagine;
  • right, left o center impostano l'allineamento (a destra, a sinistra o centrato);
  • 375px indica la dimensione dell'immagine nella pagina.

L'allineamento a destra è comodo perché limita i problemi di allineamento del testo, ma sia con l'allineamento a destra che con quello a sinistra è possibile sistemare eventuali problemi aggiungendo

<br clear="all"/>

Questo codice resetta l'allineamento; per esempio, se un'immagine deve essere contenuta in un paragrafo, ma questo è molto breve, spesso il paragrafo successivo rischia di iniziare di fianco all'immagine del precedente, nel caso in cui molti paragrafi abbiano immagini questo causa una gran confusione. Per risolvere il problema è sufficiente aggiungere il codice indicato sopra, appena prima dell'inizio del paragrafo successivo.

Nel caso in cui un'immagine non sia già presente nella Wiki (per esempio nella corrispondente pagina inglese) sarà sufficiente salvare la pagina, dopo aver aggiunto la stringa per l'aggiunta dell'immagine con nome ed estensione appropriati, ed apparirà un link rosso al posto dell'immagine (broken link), cliccandoci sopra si aprirà una pagina che consente un caricamento semplice e veloce di un'immagine dai vostri file locali.

Attenzione: Prima di inserire un'immagine non creata personalmente ma presa da internet, controllare che sia rilasciata sotto una licenza che ne permette la diffusione, per esempio licenze Creative Commons


Template

I template sono uno strumento potentissimo, in pratica si può definire una regola all'interno della Wiki per cui tutte le volte che compare una certa stringa (un pezzo di testo) lo stile del testo viene modificato; la parte interessante è che la modifica dello stile può essere estrema e complessa, consentendo di ripetere uno stile utile, ma complicato da realizzare, semplicemente richiamando un template già confezionato. Ma chiariamo il tutto con degli esempi pratici.

Il fatto che mettendo tra un certo numero di apostrofi una parola questa appaia in grassetto od in corsivo, è dovuto ad un template predefinito di qualunque Wiki; la stessa cosa vale per tutte le caratteristiche elencate in precedenza, come gli elenchi, il testo a larghezza fissa, i link, etc. Ovviamente chiunque può creare un template poiché questo non è altro che una pagina della Wiki, solo scritta in un modo un po' speciale.

Attenzione: Non bisogna assolutamente usare i segni di uguaglianza all'interno dei template. Nel caso in cui essi compaiano apparirà un messaggio simile a quello sotto.
Attenzione:
Error: Template loop detected: Template:Error

Corpi di testo colorati

Il template personalizzato più utilizzato su questa Wiki è il corpo di testo colorato, che viene utilizzato per richiamare l'attenzione sul suo contenuto, per diverse motivazioni. I template, a corpo di testo colorato, presenti al momento in italiano sono i seguenti.

{{nota|Questa è una '''nota''' e serve a ricordare qualche punto fondamentale 
 o a segnalare un'osservazione aggiuntiva riguardo all'argomento trattato, 
 che non deve sfuggire all'utente, perché può aiutarlo nella comprensione. 
 Su di un libro sarebbe una nota a piè di pagina.}}
{{attenzione|Questo è un messaggio che deve mettere in '''allarme''' (warning) 
 l'utente, può essere utile per segnalare i motivi per cui alcuni passaggi descritti in 
 una guida sono particolarmente rischiosi, o per ribadire gli errori da non commettere
 assolutamente. In un libro sarebbe la parte sottolineata in colori sgargianti.}}
{{suggerimento|Questo è un '''suggerimento''' ed è utile per aggiungere 
 un'informazione all'argomento trattato, magari per migliorare il procedimento, 
 un consiglio per sprecare meno tempo, o per sfruttare al massimo le potenzialità 
 del software descritto. Per un libro corrisponde alla nota aggiunta a margine o 
 scritta a mano tra le righe.}}
Nota: Questa è una nota e serve a ricordare qualche punto fondamentale o a segnalare un'osservazione aggiuntiva riguardo all'argomento trattato, che non deve sfuggire all'utente, perché può aiutarlo nella comprensione. Su di un libro sarebbe una nota a piè di pagina.
Attenzione: Questo è un messaggio che deve mettere in allarme (warning) l'utente, può essere utile per segnalare i motivi per cui alcuni passaggi descritti in una guida sono particolarmente rischiosi, o per ribadire gli errori da non commettere assolutamente. In un libro sarebbe la parte sottolineata in colori sgargianti.
Suggerimento: Questo è un suggerimento ed è utile per aggiungere un'informazione all'argomento trattato, magari un consiglio per migliorare il procedimento, per sprecare meno tempo, o per sfruttare al massimo le potenzialità del software descritto. Per un libro corrisponde alla nota aggiunta a margine o scritta a mano tra le righe.

Stile di scrittura raccomandato

Nonostante ciascuno abbia un proprio stile di scrittura, e questo possa essere rispecchiato nelle pagine che vengono redatte, è meglio mantenere alcuni punti saldi nello stile con cui vengono scritti i documenti di una stessa Wiki. Questo consente una maggiore chiarezza, permette di modificare facilmente le pagine scritte da terzi, essendo sicuri che questi hanno rispettato lo stesso stile di scrittura, mantenendo il materiale contenuto nella globalità della Wiki pressoché omogeneo. In questa sezione vengono inoltre aggiunti piccoli consigli generici legati alla scrittura, che se venissero seguiti potrebbero garantire un certo livello di qualità nella documentazione.

Link alla Pagina Principale

Poiché la parte italiana della Wiki è solo un sottoinsieme della Wiki internazionale di Manjaro, il link alla pagina principale presente nella barra di sinistra riporta ad una pagina che risulta poco utile agli utenti interessati alla lettura della Wiki italiana; per questo è molto consigliato, praticamente obbligatorio, fornire un link alla pagina principale della parte italiana in cima ad ogni pagina. Per far apparire un semplice link, è sufficiente aggiungere in cima ad ogni pagina il codice

{{Ritorna}}

Si tratta di un template creato appositamente per aggiungere il link in cima alla pagina, se viene modificata la pagina del template il link verrà modificato in tutte le pagine che richiamano il template. Al momento il link ha questo aspetto: ⇐ Torna alla Pagina Principale

Struttura

  • Come già spiegato nel paragrafo riguardante la divisione in sezioni, il livello di divisione massimo consigliato all'interno di una pagina Wiki è il secondo, quindi quello indicato da una coppia '==' su entrambi i lati del titolo del paragrafo. Si possono poi utilizzare, a scendere, tutti gli altri livelli fino al sesto '======'.
  • Per garantire che la pagina possa essere trovata dall'utente all'interno della Wiki è necessario che tutte le pagine in italiano abbiano un punto di ritrovo, siano presenti in un elenco, al momento questo viene garantito dalla categoria di appartenenza, che deve quindi essere aggiunta alla fine di qualunque pagina con questa sintassi
[[Category:Italiano]]
Nota: Le categorie diverse da Italiano devono essere rimosse, perché porterebbero la pagina a comparire nell'elenco delle pagine in inglese, od in altre lingue.
  • È consigliato utilizzare sempre lo stile corsivo per indicare nomi di programmi o comandi, di modo da segnalare all'utente che si sta fornendo un'indicazione precisa.
  • Sarebbe meglio non utilizzare inutilmente gli stili (corsivo e grassetto), poiché rischiano di rendere la pagina apparentemente poco ordinata.

Lessico e sintassi

  • Nella stesura di una pagina Wiki è consigliabile mantenere una forma impersonale, questo rende la documentazione più professionale; questo aspetto può essere sottovalutato su una Wiki di piccole dimensioni, ma sperando in una sua espansione è una buona scelta rispettarlo.
  • La lingua con cui viene scritta la documentazione deve essere il più semplice, ma precisa, possibile; sono da evitare le ripetizioni, perché fanno perdere il filo del discorso, non vanno utilizzate frasi lunghe ed articolate per lo stesso motivo. Bisogna essere in grado di stringere all'essenziale, senza trascurare alcun aspetto importante.

Collegamenti esterni