From BlenderWiki

Jump to: navigation, search

Per mantenere consistente l'intera Documentazione di Blender, gli eventuali autori sono gentilmente invitati ad aderire alla presente Guida allo stile.

Le persone completamente ignare della sintassi di MediaWiki possono inoltre fare riferimento al Manuale di Mediawiki ufficiale.

Linee Guida Generali

La Documentazione di Blender dovrebbe essere scritta in un inglese chiaro, conciso, idiomatico e corretto. Essa dovrebbe essere suddivisa adeguatamente in capitoli, sezioni e sottosezioni.

La suddivisione logica del nucleo della Documentazione è definito dalla Commissione per la Documentazione (DocBoard). Nessuna nuova pagina viene aggiunta, se non dopo essere stata approvata.

La suddivisione logica dei contributi, quali sono i tutorial, spetta al loro autore.

I tutorial dovrebbero contenere un abstract che in un limite di massimo 300 parole descriva brevemente l'argomento, gli obiettivi ed i contenuti per una rapida consultazione.

Ogni pagina dovrebbe avere un modello(template) appropriato come Prima riga per mostrare gli aiuti per la navigazione e a quale versione di Blender è aggiornata la pagina. Ciò è fatto tramite

 {{Page/Header|2.32}}

essendo ovviamente 2.32 il numero della versione.

Ed appare così


Inoltre, per pagine lunghe che presentino svariate sezioni --alcune delle quali riferite ad una versione diversa di Blender-- esiste un modello(template) differente

 {{version|2.32}}

Che dovrebbe venire collocato immediatamente dopo il titolo di sezione/sottosezione, come mostrato nella sezione che segue.

Al fondo di ogni pagina ci dovrebbe essere un footer con gli aiuti di navigazione

 {{Page/Footer|previouspage|followingpage}}

Che appare così




previouspage e followingpage devono ovviamente essere dei link validi alle pagine appropriate!

Modelli (templates)

Blender 2.32+

Ci sono un numero limitato di modelli definiti dalla DocBoard. Siete gentilmente invitati ad usare questi e solo questi.

La lista dei template si trova qui Templates

Immagini

L'uso di immagini nella documentazione è essenziale. I formati PNG e JPG sono altamente preferibili. GIF ed altri formati non free sono decisamente scoraggiati. Formati non compressi come TGA sono altresì scoraggiati.

Le immagini vengono trasferite al wiki usando l'appropriato http://mediawiki.blender.org/index.php/Special:Upload collegamento.

Immagini Fluttuanti

Le immagini fluttuanti dovrebbero avere una didascalia ed essere citate nel testo. Per cortesia trattenetevi dall'uso di diciture quali "the next picture" o "the following figure". Usate riferimenti incrociati. I riferimenti incrociati sono descritti nella Sezione 4.4.

L'uso di immagini senza riferimenti è scoraggiato. Se avete un'immagine che non sapete come citare allora quell'immagine non è necessaria o il vostro testo non è chiaro.

La documentazione, sia il nucleo che i tutorial, ha bisogno di mantenere consistenza. Le dimensioni dovrebbero essere, al massimo, di 800x600. L'uso di immagini più larghe di 800 pixel è fortemente scoraggiato dal momento che sono troppo larghe per una consultazione agevole all'interno di un web browser.

La caratteristica più rilevante dell'interfaccia di Blender è che essa è interamente disegnata e scalabile in openGL. Questo è grandioso, ma comporta tristi risultati nelle molte disuniformità nel caso in cui molti utenti ricorrano a schermate per mostrare vari tipi di impostazioni quali materiali particolari, texture, ecc..

Per permettere tanto la chiarezza quanto l'uniformità occorre che dimensioniate l'interfaccia in modo che lo slider nella finestra dei materiali sia alto 18 pixel. Questo è ciò che produce Blender se usate una risoluzione di 1024x768 e le impostazioni di default della schermata di Blender e premendo il pulsante 'home' per impostare la dimensione di default dei pulsanti.

Se state usando una risoluzione maggiore, per cortesia abbassatela a 1024x768 quando catturate delle schermate. Mi auguro che nessuno sia in possesso di schermi più piccoli!

Le schermate salvate devono essere in un formato LOSSLESS, per cui usate PNG.

Se avete bisogno di sottolineare una data porzione di un'immagine (un pulsante, un valore, o gruppi di pulsanti/valori) usate per cortesia una cornice gialla (R=255,G=255,B=0) con contorni di 2 pixel.

Usate lo stile default dell'interfaccia di Blender.

Immagini in linea

Le immagini in linea che mostrano le icone di Blender sono benvenute e rendono le descrizioni molto chiare. Dal momento che sono immagini STANDARD, si prega di trattenersi dal farle di vostra iniziativa, usate invece quelle fornite dalla DocBoard.

Smileys in linea etc

La Documentazione Ufficiale non è un posto per degli smileys. (l'humor è un'altra questione, per cui potete essere spiritosi!)

Tabelle

Le tabelle sono un metodo approvato per mostrare una quantità di dati in maniera chiara e strutturata. Possono essere una valida alternativa alle catture dallo schermo per illustrare varie impostazioni.

Le tabelle, come le immagini fluttuanti, devono avere una didascalia e devono essere citate nel testo.

Codice

Wiki ha un suo ambiente gradevole per per pezzi di codice Python/C/qualsiasilinguaggio.

I pezzi di codice, come le immagini fluttuanti, devono avere una didascalia e devono essere citati nel testo.

Stile della Documentazione in pratica

Questo capitolo mostra nel dettaglio come ci aspettiamo che siano le vostre pagine Wiki.

Esempi di Immagini

Qui è descritto come inserire le immagini nelle vostre pagine, una volta che sono state inviate al server:

Immagini normali

Questa è la via più semplice per collocare immagini all'interno del testo, e anche la più sicura dal momento che non dovete preoccuparvi del problema di quelle fluttuanti.

[[Image:DemoImage1.png|none|frame|Demo Image number 1]]

Fa iniziare l'immagine su di una nuova linea, con tutto il testo separato da essa:

Demo Image number 1

Immagini fluttuanti

Dummy image
Questa è leggermente più complicata, dal momento che dovete considerare che potrebbe apparire in modo diverso ad altre risoluzioni/dimensioni della finestra/dimensioni dei caratteri rispetto ai vostri. Per far fluttuare un'immagine alla destra del testo usate questa sintassi:

[[Image:Dummy.jpg|right|thumb|200px|Dummy image]]

Posizionate questo codice nella prima riga che volete affiancata all'immagine.
Per ordinare il testo fino alla fine dell'immagine, usate la sintassi seguente:

{{clr}}

Immagini in linea

Le immagini in linea come DemoImage2.png sono ancora più facili da ottenere:

[[Image:DemoImage2.png]]

Immagini in tabelle

Quando avete una serie di piccole immagini in relazione tra di loro, potete inserirle in una semplice tabella:

{|
 |valign=top|[[Image:Manual-Part-III-materialRampsExample04.png|thumb|200px|none|No Ramp Shader.]]
 |valign=top|[[Image:Manual-Part-III-materialRampsExample05.png|thumb|200px|none|Color Ramp.]]
 |valign=top|[[Image:Manual-Part-III-materialRampsExample06.png|thumb|200px|none|Both Color and Specular Ramp.]]
|}
No Ramp Shader.
Color Ramp.
Both Color and Specular Ramp.

Maggiore aiuto per le Immagini

Consultate questa pagina per informazioni dettagliate sull'uso delle immagini: Images and other uploaded files

Tabelle

Le tabelle possono sia essere scritte in HTML che usando una sintassi Wiki molto più chiara:

 {| border="1" cellpadding="2"
 |+Multiplication table
 |-
 ! × !! 1 !! 2 !! 3
 |-
 ! 1
 | 1 || 2 || 3
 |-
 ! 2
 | 2 || 4 || 6
 |-
 ! 3
 | 3 || 6 || 9
 |-
 ! 4
 | 4 || 8 || 12
 |-
 ! 5
 | 5 || 10 || 15
 |}
 

dà come risultato

Multiplication table
× 1 2 3
1 1 2 3
2 2 4 6
3 3 6 9
4 4 8 12
5 5 10 15

Per facilitare la formattazione c'è un template 'UM/prettytable' predefinito

 {| {{UM/prettytable|50%}}
 |align=center | 1 
 |align=center | 2 
 |align=center | 3 
 |-
 |align=center | 4 
 |align=center | 5 
 |align=center | 6 
 |}
 

Appare

1 2 3
4 5 6


Altra sintassi di Tabelle

Leggete questa pagina per informazioni estese sull'uso delle tabelle: Tables

Codice

Tutti gli esempi precedenti di codice Wiki sono stati scritti incapsulandoli in una coppia di <nowiki></nowiki> .

Inserendo uno o più spazi all'inizio di ogni riga, le righe sono mostrate così:

 this

Un altro modo di fare questo (per un grande pezzo di codice, per esempio), è quello di incapsularlo in una coppia di <pre></pre> .

In alternativa, se non avete bisogno di una grande cornice per il codice, potete usare <code></code> che dà come risultato il seguente:

Questo è un esempio

Riferimenti incrociati

I riferimenti incrociati sono fatti alla maniera Wiki, nel caso in cui in precedenti documenti abbiamo usato etichette per indicare degli oggetti. Wiki usa l'oggetto name; per cui quello di cui abbiamo bisogno è un schema dei nomi *unico* per le immagini.

Webography

Wiki sites here

Nomi dei File

I nomi dei file sono una questione delicata perchè devono essere sia unici in tutta la Documentazione di Blender, sia autoesplicativi per permettere riferimenti incrociati da un capitolo all'altro, ecc.

Per cui è altamente consigliabile di attenersi ad un preciso standard:

Per il nucleo della documentazione:

 Manual/Part##/self-explanatory-name

Part## è Part ##, essendo ## il numero romano della parte alla quale l'oggetto appartiene

I nomi delle pagine sono un buon esempio in questo caso.

Per le immagini nel nucleo della documentazione lo schema dei nomi è simile...ma purtroppo gli '/' non sono accettati dal sistema...quindi

 Manual-PartXX-self-explanatory-name

Risolve il problema, si usa '-' al posto di '/'.

L'autore ne decide l'uso, e sta a lui mantenere l'intera etichetta unica.