[GUIDA] Sintassi di Markup
Inviato: 26/03/2007, 0:35
AVVERTENZA: Questo post verrà aggiornato regolarmente, man mano che verranno implementate nuove regole di markup e/o che avro' tempo di spiegare e documentare quelle già implementate. Tornateci spesso!
Per "sintassi di markup" si intende un sistema di TAG per marcare parti di un testo in un determinato modo: ad esempio, un titolo va marcato come tale per differenziarlo dal testo, e lo stesso vale per un sottotitolo, per una voce in grassetto/corsivo/sottolineato, etc.; il classico esempio di sintassi di markup è l'HTML, la cui sintassi però è diventata sempre piu' uno scomodo ibrido tra markup e rendering e non puo' quindi essere utilizzato. Un'altra sintassi molto diffusa, e decisamente piu' pratica, è il BBCode, utilizzato da questo forum e dai blog.
La sintassi di markup che utilizza la Cyclopedia è la cosiddetta sintassi wiki, implementata dalla maggior parte dei wiki system esistenti (tra cui Wikipedia): come avremo modo di vedere, è molto piu' potente del semplice BBCode e consente una serie di operazioni avanzate e ampiamente configurabili per le nostre esigenze.
NOTA: La sintassi di markup è valida solo all'interno dei seguenti campi:
- Descrizione (dove comunque va ridotta all'indispensabile).
- Sezioni
- Voci correlate
Non provate quindi a inserirla all'interno di altri campi (come ad esempio il NOME), in quanto non funzionerà.
--------------------------------------------------------------------------------
Stili e formattazione del testo
--------------------------------------------------------------------------------
''Cosi' si inserisce del testo in corsivo'' <- DUE SINGOLI APICI (il tasto sotto al punto interrogativo)
produrrà il seguente risultato:
Cosi' si inserisce del testo in corsivo
'''Cosi' si inserisce del testo in grassetto''' <- TRE SINGOLI APICI (il tasto sotto al punto interrogativo)
produrrà il seguente risultato:
Cosi' si inserisce del testo in grassetto
'''''Cosi' si inserisce del testo in grassetto corsivo''''' <- CINQUE SINGOLI APICI (il tasto sotto al punto interrogativo)
produrrà il seguente risultato:
Cosi' si inserisce del testo in grassetto corsivo
--------------------------------------------------------------------------------
Titoli di paragrafo
--------------------------------------------------------------------------------
==Paragrafo 1==
<testo>
==Paragrafo 2==
<testo>
==Paragrafo 3==
<testo>
===Paragrafo 3.1===
<testo>
===Paragrafo 3.2===
<testo>
====Paragrafo 3.2.1====
<testo>
====Paragrafo 3.2.2====
<testo>
==Paragrafo 4==
<testo>
etc.
NOTA: Dove/quando possibile è consigliabile limitare al minimo i sottoparagrafi per facilitare la consultazione della voce.
--------------------------------------------------------------------------------
CycloLink (link interno alla cyclopedia)
--------------------------------------------------------------------------------
descrizione della voce
esempio:
Sono un sacerdote di Dytros, il Dio della Giustizia e mi chiamo Ayron.
visualizzerà questo:
Sono un sacerdote di Dytros, il Dio della Giustizia e mi chiamo Ayron.
NOTA: questo tipo di link può portare a piu' di un risultato (nomi non univoci o corrispondenti a keywords presenti su piu' di una voce). Per linkare una voce in modo univoco occorre utilizzare la sintassi apposita (vedi sotto).
--------------------------------------------------------------------------------
CycloLink (link interno alla cyclopedia - disambiguo)
--------------------------------------------------------------------------------
descrizione della voce
esempio:
Sono un sacerdote di Dytros, il Dio della Giustizia e mi chiamo Ayron.
visualizzerà questo:
Sono un sacerdote di Dytros, il Dio della Giustizia e mi chiamo Ayron.
NOTA: L'ID univoco di ciascuna voce viene visualizzato in basso a sinistra nella scheda di visualizzazione della voce stessa. A fianco dell'ID univoco vi è anche un link che, se cliccato, consente di copiare il CycloLink univoco direttamente negli appunti risparmiandosi la fatica di doverlo fare a mano.
--------------------------------------------------------------------------------
Link a sito esterno
--------------------------------------------------------------------------------
Se non volete il testo alternativo è sufficiente inserire l'url cosi' com'e', comprensiva di prefisso HTML:
http://www.google.it/
Se invece volete il testo alternativo, questa è la sintassi da utilizzare.
[http://url descrizione del link]
esempio: [http://www.google.it/ Motore di Ricerca Google]
--------------------------------------------------------------------------------
Link al sito di Myst
--------------------------------------------------------------------------------
descrizione del link
esempio: Blog di Solice
Nella sintassi del link interno è importante omettere il riferimento al sito.
In altre parole, se volete linkare: http://www.myst.it/campagne/vintemberg/
questa è la sintassi corretta: Testo Alternativo
NOTA: è importante che per i link relativi al sito di Myst venga utilizzata questa sintassi, e non quella specifica per link esterni.
--------------------------------------------------------------------------------
Elenco puntato
--------------------------------------------------------------------------------
* elemento 1
* elemento 2
* elemento 3
+testo in continuazione dell'elemento 3
** elemento 3.1
** elemento 3.2
*** elemento 3.2.1
*** elemento 3.2.2
* elemento 4
etc.
--------------------------------------------------------------------------------
Elenco numerato
--------------------------------------------------------------------------------
# elemento 1
# elemento 2
etc.
NOTA: Stessa sintassi dell'elenco puntato con # al posto di *
--------------------------------------------------------------------------------
Immagini esterne
--------------------------------------------------------------------------------
se l'immagine ha una estensione riconoscibile (GIF,JPG,BMP,PNG) è sufficiente inserire il link:
http://www.google.it/intl/it_it/images/logo.gif
altrimenti usare la seguente sintassi.
Se volete che cliccando sull'immagine si vada da qualche parte, questa è la sintassi:
--------------------------------------------------------------------------------
Immagini interne (link univoco)
--------------------------------------------------------------------------------
Per visualizzare un'immagine associata a una voce (utile soprattutto quando le voci sono File Multimediali e nella fattispecie immagini) questa è la sintassi:
Se volete che cliccando sull'immagine interna si vada da qualche parte, questa è la sintassi:
NOTA: Se la voce a cui fate riferimento non dovesse essere di tipo File Multimediale/Immagine, verrà visualizzata l'icona (in caso di file multimediale di altro tipo) o una delle immagini associate ad essa (in caso di altri tipi di voce).
--------------------------------------------------------------------------------
Ridimensionamento immagini on-the-fly
--------------------------------------------------------------------------------
Per implementare questa funzione ci ho messo un po', quindi mi aspetto che la accogliate con grida di giubilo
e' possibile ridimensionare on-the-fly qualsiasi immagine linkata nei modi sopra indicati (esterne o interne che siano) semplicemente aggiungendo i parametri #width#height (larghezza e altezza, rispettivamente) in calce al link.
Esempi (con la sintassi di cui sopra):
E' possibile anche limitarsi ad aggiungere soltanto la larghezza, in quel caso l'altezza sarà calcolata proporzionalmente sulla base del ridimensionamento della prima.
NOTA: il ridimensionamento avviene in modo bicubico (tipo programma di grafica), quindi con qualità migliore rispetto al semplice ridimensionamento HTML che si limita a shrinkare i pixel con un effetto scadente a livello qualitativo e soprattutto pesante sia per il browser che per il sito (che invia comunque l'immagine a dimensioni naturali).
--------------------------------------------------------------------------------
Andata a capo
--------------------------------------------------------------------------------
Tutti i segni di andata a capo vengono convertiti automaticamente in interruzioni di paragrafo e/o eliminati: per forzare una linea vuota, "riempire" la linea con due o piu' spazi prima di andare a capo (cosa che va fatta comunque solo se serve davvero: per separare piu' concetti, la cosa migliore è dividerli mediante il sistema di titoli e sottotitoli).
(continua)
Per "sintassi di markup" si intende un sistema di TAG per marcare parti di un testo in un determinato modo: ad esempio, un titolo va marcato come tale per differenziarlo dal testo, e lo stesso vale per un sottotitolo, per una voce in grassetto/corsivo/sottolineato, etc.; il classico esempio di sintassi di markup è l'HTML, la cui sintassi però è diventata sempre piu' uno scomodo ibrido tra markup e rendering e non puo' quindi essere utilizzato. Un'altra sintassi molto diffusa, e decisamente piu' pratica, è il BBCode, utilizzato da questo forum e dai blog.
La sintassi di markup che utilizza la Cyclopedia è la cosiddetta sintassi wiki, implementata dalla maggior parte dei wiki system esistenti (tra cui Wikipedia): come avremo modo di vedere, è molto piu' potente del semplice BBCode e consente una serie di operazioni avanzate e ampiamente configurabili per le nostre esigenze.
NOTA: La sintassi di markup è valida solo all'interno dei seguenti campi:
- Descrizione (dove comunque va ridotta all'indispensabile).
- Sezioni
- Voci correlate
Non provate quindi a inserirla all'interno di altri campi (come ad esempio il NOME), in quanto non funzionerà.
--------------------------------------------------------------------------------
Stili e formattazione del testo
--------------------------------------------------------------------------------
''Cosi' si inserisce del testo in corsivo'' <- DUE SINGOLI APICI (il tasto sotto al punto interrogativo)
produrrà il seguente risultato:
Cosi' si inserisce del testo in corsivo
'''Cosi' si inserisce del testo in grassetto''' <- TRE SINGOLI APICI (il tasto sotto al punto interrogativo)
produrrà il seguente risultato:
Cosi' si inserisce del testo in grassetto
'''''Cosi' si inserisce del testo in grassetto corsivo''''' <- CINQUE SINGOLI APICI (il tasto sotto al punto interrogativo)
produrrà il seguente risultato:
Cosi' si inserisce del testo in grassetto corsivo
--------------------------------------------------------------------------------
Titoli di paragrafo
--------------------------------------------------------------------------------
==Paragrafo 1==
<testo>
==Paragrafo 2==
<testo>
==Paragrafo 3==
<testo>
===Paragrafo 3.1===
<testo>
===Paragrafo 3.2===
<testo>
====Paragrafo 3.2.1====
<testo>
====Paragrafo 3.2.2====
<testo>
==Paragrafo 4==
<testo>
etc.
NOTA: Dove/quando possibile è consigliabile limitare al minimo i sottoparagrafi per facilitare la consultazione della voce.
--------------------------------------------------------------------------------
CycloLink (link interno alla cyclopedia)
--------------------------------------------------------------------------------
descrizione della voce
esempio:
Sono un sacerdote di Dytros, il Dio della Giustizia e mi chiamo Ayron.
visualizzerà questo:
Sono un sacerdote di Dytros, il Dio della Giustizia e mi chiamo Ayron.
NOTA: questo tipo di link può portare a piu' di un risultato (nomi non univoci o corrispondenti a keywords presenti su piu' di una voce). Per linkare una voce in modo univoco occorre utilizzare la sintassi apposita (vedi sotto).
--------------------------------------------------------------------------------
CycloLink (link interno alla cyclopedia - disambiguo)
--------------------------------------------------------------------------------
descrizione della voce
esempio:
Sono un sacerdote di Dytros, il Dio della Giustizia e mi chiamo Ayron.
visualizzerà questo:
Sono un sacerdote di Dytros, il Dio della Giustizia e mi chiamo Ayron.
NOTA: L'ID univoco di ciascuna voce viene visualizzato in basso a sinistra nella scheda di visualizzazione della voce stessa. A fianco dell'ID univoco vi è anche un link che, se cliccato, consente di copiare il CycloLink univoco direttamente negli appunti risparmiandosi la fatica di doverlo fare a mano.
--------------------------------------------------------------------------------
Link a sito esterno
--------------------------------------------------------------------------------
Se non volete il testo alternativo è sufficiente inserire l'url cosi' com'e', comprensiva di prefisso HTML:
http://www.google.it/
Se invece volete il testo alternativo, questa è la sintassi da utilizzare.
[http://url descrizione del link]
esempio: [http://www.google.it/ Motore di Ricerca Google]
--------------------------------------------------------------------------------
Link al sito di Myst
--------------------------------------------------------------------------------
descrizione del link
esempio: Blog di Solice
Nella sintassi del link interno è importante omettere il riferimento al sito.
In altre parole, se volete linkare: http://www.myst.it/campagne/vintemberg/
questa è la sintassi corretta: Testo Alternativo
NOTA: è importante che per i link relativi al sito di Myst venga utilizzata questa sintassi, e non quella specifica per link esterni.
--------------------------------------------------------------------------------
Elenco puntato
--------------------------------------------------------------------------------
* elemento 1
* elemento 2
* elemento 3
+testo in continuazione dell'elemento 3
** elemento 3.1
** elemento 3.2
*** elemento 3.2.1
*** elemento 3.2.2
* elemento 4
etc.
--------------------------------------------------------------------------------
Elenco numerato
--------------------------------------------------------------------------------
# elemento 1
# elemento 2
etc.
NOTA: Stessa sintassi dell'elenco puntato con # al posto di *
--------------------------------------------------------------------------------
Immagini esterne
--------------------------------------------------------------------------------
se l'immagine ha una estensione riconoscibile (GIF,JPG,BMP,PNG) è sufficiente inserire il link:
http://www.google.it/intl/it_it/images/logo.gif
altrimenti usare la seguente sintassi.
Se volete che cliccando sull'immagine si vada da qualche parte, questa è la sintassi:
--------------------------------------------------------------------------------
Immagini interne (link univoco)
--------------------------------------------------------------------------------
Per visualizzare un'immagine associata a una voce (utile soprattutto quando le voci sono File Multimediali e nella fattispecie immagini) questa è la sintassi:
Se volete che cliccando sull'immagine interna si vada da qualche parte, questa è la sintassi:
NOTA: Se la voce a cui fate riferimento non dovesse essere di tipo File Multimediale/Immagine, verrà visualizzata l'icona (in caso di file multimediale di altro tipo) o una delle immagini associate ad essa (in caso di altri tipi di voce).
--------------------------------------------------------------------------------
Ridimensionamento immagini on-the-fly
--------------------------------------------------------------------------------
Per implementare questa funzione ci ho messo un po', quindi mi aspetto che la accogliate con grida di giubilo
e' possibile ridimensionare on-the-fly qualsiasi immagine linkata nei modi sopra indicati (esterne o interne che siano) semplicemente aggiungendo i parametri #width#height (larghezza e altezza, rispettivamente) in calce al link.Esempi (con la sintassi di cui sopra):
E' possibile anche limitarsi ad aggiungere soltanto la larghezza, in quel caso l'altezza sarà calcolata proporzionalmente sulla base del ridimensionamento della prima.
NOTA: il ridimensionamento avviene in modo bicubico (tipo programma di grafica), quindi con qualità migliore rispetto al semplice ridimensionamento HTML che si limita a shrinkare i pixel con un effetto scadente a livello qualitativo e soprattutto pesante sia per il browser che per il sito (che invia comunque l'immagine a dimensioni naturali).
--------------------------------------------------------------------------------
Andata a capo
--------------------------------------------------------------------------------
Tutti i segni di andata a capo vengono convertiti automaticamente in interruzioni di paragrafo e/o eliminati: per forzare una linea vuota, "riempire" la linea con due o piu' spazi prima di andare a capo (cosa che va fatta comunque solo se serve davvero: per separare piu' concetti, la cosa migliore è dividerli mediante il sistema di titoli e sottotitoli).
(continua)
