From BlenderWiki

Jump to: navigation, search

Säilyttääkseen samankaltaisuuden Blender -dokumentaation joka puolella, kirjoittajia pyydetään kohteliaasti noudattamaan nykyisen tyylioppaan ohjeita.

Ihmiset, jotka eivät tunne MediaWiki -syntaksia, voivat myös käyttää virallista dokumentaatiota: MediaWiki Docs

Yleisiä ohjeita

Blender dokumentaatio tulisi kirjoittaa selvällä, tiiviillä, yksiselitteisellä ja oikealla suomenkielellä. Se tulisi jakaa kohtuullisesti kappaleisiin, osioihin ja aliosioihin.

Dokumentaatiolautakunta määrittelee Ydindokumentaation loogisen jaottelun. Uusia sivuja ei oleteta lisättävän paitsi hyväksynnän jälkeen.

Lahjoitettujen tutoriaalien looginen jaottelu on jätetty tekijän vastuulle.

Tutoriaalien tulisi sisältää maksimissaan n. 300 sanan lyhyt kuvaus aiheesta, tavoitteista ja sisällöstä, jotta nopea selailu on mahdollista.

Joka sivulla tulisi olla sopiva pohja, kuten sivun ensimmäinen rivi, joka näyttää navigaatiotyökalut ja sen mille Blender versiolle sivu on päivitetty. Tämä tehdään

 {{Page/Header|2.32|prevpage|nextpage}}

käskyllä, missä 2.32 on tietenkin versionumero.

Se näkyy sivulla:


Lisäksi sivuille, jotka käsittävät useita osuuksia --joista osa liittyy eri Blender versioon-- ,on olemassa erilainen pohja

 {{version|2.32}}

Tämä tulisi sijoittaa heti osion/aliosion jälkeen, kuten välittömästi alapuolella olevassa osuudessa näkyy.

Joka sivun lopussa tulisi olla navigaatioapupalkki

 {{Page/Footer|edellinen sivu|seuraava sivu}}

Se näkyy sivulla:




edellisen ja seuraavan sivun tulisi tietenkin olla linkkejä sopiville sivuille!

Pohjat

Blender 2.32+

Docboardilla (suom.?) on olemassa rajoitettu määrä pohjia. Sinua pyydetään kohteliaasti käyttämään vain ja ainoastaan niitä.

Pohjalistaus on Pohjat-sivulla.

Kuva -ohje

Kuvien käyttäminen dokumentaatiossa on olennaista. PNG ja JPG formaatit ovat suuresti suositeltuja. GIF:n ja muiden ei-vapaiden formaattien käyttöä ei todellakaan suositella. Myös pakkaamattomien formaattien, kuten TGA:n, käyttö on epäsuositeltavaa.

Kuvat ladataan wikiin käyttäen sopivaa http://mediawiki.blender.org/index.php/Special:Upload

-linkkiä.

Kelluvat kuvat

Kelluvilla kuvilla tulisi olla teksti ja niihin tulisi viitata tekstissä. Pyri olemaan käyttämättä sanailua kuten "seuraava kuva" tai "seuraava kaavio". Käytä ristiviittauksia. Ristiviittaukset kuvataan osiossa 7.

Viittaamattomien kuvien käyttöä ei kannusteta. Jos sinulla on kuva etkä tiedä kuinka viitata siihen, silloin kuva on turha tai tekstisi epäselvä.

Dokumentaation, sekä ydin että tutoriaalien, tulee säilyttää samankaltaisuus. Mittojen tulee, maksimissaan, olla 800x600. Kuvien, jotka ovat laajempia kuin 800 pikselia, käyttöä ei kannusteta, koska ne ovat liian leveitä, jotta ne voitaisiin lukea miellyttäväsi web -selaimella.

Huomattavin Blenderin käyttöliittymän ominaisuus on se, että se renderoidaan täysin OpenGL:n avulla ja se on skaalautuva. Tämä on mahtavaa mutta valitettavasti siitä seuraa monia epäsamankaltaisuuksia, jos monet käyttäjät käyttävät kuvakaappauksia näyttääkseen miltä eri tyyppiset asetukset, kuten materiaalit, tekstuurit yms. näyttävät.

Selkeyden ja yhtenäisyyden vuoksi sinun tulisi suhteuttaa käyttöliittymä siten, että materiaali-ikkunan PUNAINEN liukuohjain on 18 pikselin korkuinen. Mikäli käytät Blenderiä 1024x768 -tilassa, default näyttöasetuksella ja painat 'home' näppäintä, kun olet nappulaikkunassa, asettaaksesi perus nappulankoon päälle, Blenderin pitäisi tuottaa tämä kyseinen edellämainittu tulos.

Jos käytät suurempaa tarkkuutta, pudota se 1024x768 tarkkuuteen tehdäksesi kuvakaappauksia. Toivon ettei kenelläkään ole pienempää kuvaruutua! Eräs tapa tehdä kuvakaappauksia 1024 tarkkuudella, kun näyttösi on säädetty korkeammalle tarkkuudelle, on käyttää ikkunoitua moodia, joka aktivoidaan seuraavilla komentoriviparametreilla:

  ./blender -w -p 0 0 1024 768. 

Tämä käynnistää Blenderin ikkunassa piirtäen sen tarkalleen 1024x768 pikselin kokoon. Sovelluskehys tulee olemaan laajempi työpöydän liitteiden vuoksi. Kaapataksesi Blenderin osuuden näytöstä voit käyttää Gimpiä 'fixed' kokoa valitse alue (select region) (1024x768 suuruinen) ja se kaappaa automaattisesti Blender osuuden ohjelmasta vähennettynä työpöydän tuottamat höysteet.

Kuvakaappausten tulee olla HÄVIÖTTÖMÄSSÄ formaatissa, joten käytä PNG:tä.

Jos haluat huomioida tietyn osuuden kuvasta (nappula, arvo tai nappuloiden/arvojen ryhmä), käytä keltaista (R=255,G=255,B=0) kahden pikselin paksuista reunusta joka puolella.

Käytä Blenderin default UI -tyyliä.

Sisälletyt kuvat

Sisällytetyt kuvat, joissa on Blenderin ikoneita, ovat tervetulleita ja tekevät kuvauksista selkeämpiä. Koska nämä ovat STANDARDEJA kuvia, pyri olemaan tekemättä omiasi ja käytä sen sijaan DocBoardin tarjoamia.

Sisällytetyt smileyt yms.

Virallinen dokumentaatio ei ole paikka smileyille. (huumori on eri asia, tietysti voit olla humoristinen!)

Taulukot

Taulukot on sopiva tapa näyttää paljon tietoa selkeästi rakenteisella tavalla. Ne voivat olla hyvä vaihtoehto kuvakaappauksille tietynlaisissa tapauksissa.

Taulukoilla, kuten myös kelluvilla hahmoillakin, tulee olla kuvaus ja niihin tulee viitata tekstissä.

Koodi

Wikissä on mukava ympäristö Python/C/mikätahansakieli -koodipalasille.

Koodipalasilla, kuten myös kelluvilla hahmoillakin, tulee olla kuvaus ja niihin tulee viitata tekstissä.

Dokumentointityyli käytännössä

Tämä kappale näyttää yksityiskohtaisesti esimerkin siitä, mitä oletamme Wiki -sivujesi olevan.

Kuvaesimerkit

Kuinka lisäät kuvia sivuillesi, kun olet ladannut ne palvelimelle:

Normaalit kuvat

Tämä on helpoin tapa sijoittaa kuvia tekstiisi ja samaan aikaan turvallisin, koska sinun ei tarvitse huolehtia kellumisista.

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

Tekee kuvan uudelle riville ilman tekstiä:

Demo kuva numero 1

Kelluvat kuvat

Dummy kuva
Tämä on mutkikkaampi, koska sinun pitää ottaa huomioon miltä tämä saattaa näyttää eri resoluutioilla/ikkunakoilla/fonttikoilla kuin sillä mikä sinulla on tällä hetkellä.

Saadaksesi kuvan kelluvaksi, käytä tätä syntaksia:

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

Laita tuo koodi ennen ensimmäistä riviä, jolle haluat kuvan ilmestyvän!
Pyyhkiäksesi tekstin ennen kuvan loppua, käytä seuraavaa syntaksia:

{{clr}}

Sisällytetyt kuvat

Sisälletyt kuvat, kuten DemoImage2.png ovat vielä helpompia:

[[Image:DemoImage2.png]]

Kuvat taulukoissa

Kun sinulla on kokoelma pieniä kuvia, jotka liittyvät toisiinsa, voit laittaa ne yksinkertaiseen taulukkoon:

{|
 |valign=top|[[Image:Manual-Part-III-materialRampsExample04.png|thumb|200px|none|Ei liukuvarjostinta (Ramp Shader).]]
 |valign=top|[[Image:Manual-Part-III-materialRampsExample05.png|thumb|200px|none|Väriliuku(Color Ramp).]]
 |valign=top|[[Image:Manual-Part-III-materialRampsExample06.png|thumb|200px|none|Molemmat väri- ja heijastusliuku.]]
|}
Ei liukuvarjostinta (Ramp Shader).
Väriliuku(Color Ramp).
Molemmat väri- ja heijastusliuku.

Lisää apua kuviin liittyen

Katso tätä sivua, joka sisältää kattavan tietopaketin kuvien käyttöön liittyen: Images and other uploaded files

Taulukot

Taulukoita voidaan kirjoittaa joko HTML -muotoisena tai käyttäen paljon puhtaampaa Wiki -syntaksia:

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

luo

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

Järjestämistä varten on olemassa ennaltamääritelty pohja 'UM/prettytable'

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

Tulos

1 2 3
4 5 6


Lisää taulukoiden syntaksista

Katso tätä sivua, joka sisältää kattavan tietopaketin taulukkojen käyttöön liittyen: Tables

Koodi

Kaikki yllä olleet Wiki -koodi esimerkit tulostettiin ympäröimällä ne <nowiki></nowiki> parilla.

Laittamalla yhden tai useamman välilyönnin joka rivin eteen, rivit näkyvät:

 näin

Toinen tapa tehdä tämä (esimerkiksi laajoille koodiosioille), on sisällyttää ne <pre></pre> pariin.

Vaihtoehtoisesti mikäli et tarvitse tai halua suurta koodilaatikkoa, voit käyttää <code></code> -syntaksia, mistä seuraa:

Tämä on esimerkki.

Ristiviittaukset

Ristiviittaukset tehdään wikissä "paikan päällä", missä edellisten dokumenttien otsikot tarkoittavat objektia. Wiki käyttää objektia nimi; joten tarvitsemme *ainutlaatuisen* nimeämistavan hahmoille.

Webografia

Wiki sivustoja tähän

Tiedostonimet

Tiedostonimet ovat tarkka asia, koska niiden täytyy olla ainutlaatuisia koko Blender dokumentointiprojektissa ja niiden tulee olla itsestäänselviä, jotta voidaan tehdä ristiviitteitä kappaleesta toiseen jne.

On siksi erittäin suositeltavaa seurata standardia:

Ydindokumentaatiolle

 Manual/Part##/itsestään-selvä-nimi 

(suom. huom. suomenkielisessä osuudessa Manual.fi/Part##/itsestään-selvä-nimi, missä loppuosa on sama kuin lähde-/isäntädokumentissa, josta käännetään)

Part## on Part ##, missä ## on roomalainen numero, joka kertoo mihin osaan objekti kuuluu. Sivujen nimet itsessään ovat hyvä esimerkki tästä.

Ydindokumentaation kuvien nimeämistapa on samankaltainen. Valitettavasti järjestelmä ei kuitenkaan hyväksy '/' merkki'. Joten käytä '-' -merkkiä sen sijaan. Esimerkiksi:

 Manual-PartXX-itsestään-selvä-nimi

On kirjoittajan vastuulla, että koko nimi on ainutlaatuinen.