From BlenderWiki

Jump to: navigation, search

On eenheid te behouden in de gehele Blender documentatie, wordt van potentiële schrijvers vriendelijk gevraagd zich te houden aan de huidige Stijl Gids.

Mensen die geen kennis hebben van de MediaWiki syntax kunnen ook de officiële MediaWiki Documentatie raadplegen

Algemene Richtlijnen

De Blender documentatie moet geschreven zijn en helder, samenhangend, idiomatisch en correct Engels. Ze moet doelmatig worden onderverdeeld in hoofdstukken, afdelingen en onder-afdelingen.

De logische onderverdeling van de Kern documentatie wordt gedicteerd door de Documentatie Raad. Nieuwe pagina's kunnen slechts na toestemming worden toegevoegd.

De logische onderverdeling voor aangedragen Tutorial(s) wordt overgelaten aan elke auteur.

Tutorials behoren een samenvatting van maximaal 300 woorden te bevatting waarin kort wordt beschreven wat het onderwerp, het doel en de inhoud is om snel bladeren mogelijk te maken.

Elke pagina dient een toepasselijke template als de Eerste'regel te hebben om navigatie hulpmiddelen te tonen en de versie van Blender waarop de pagina van toepassing is. Dit wordt gedaan middels:

 {{Page/Header|2.32}}

waarin 2.32 uiteraard het toepasselijke versienummer is.

Dit toont:


Verder is het zo dat voor lange pagina's met meerdere afdelingen -waarvan sommige over verschillende versies van Blender gaan- een andere template beschikbaar is:

 {{version|2.32}}

Deze dient direct na de titel van de betreffende afdeling/onder-afdeling te worden geplaatst, zoals hier onder is getoond.

Blender 2.32+

Onderaan elke pagina dient de navigatie-voettekst te worden geplaatst:

 {{Page/Footer|vorigepagina|volgendepagina}}

Die verschijnt als:




vorigepagina en volgendepagina dienen uiteraard geldige links zijn naar de correcte pagina's.

Templates

Er is een beperkt aantal templates door het docboard gedefiniëerd, waaronder notitie-blokken, Toetsen templates, en meer. Gebruik deze a.u.b. en alleen deze.

De lijst met templates kan gevonden worden op Templates

Referentie Materiaal

Als je referentie materiaal scrhijft, zoals de gebruikershandleiding, gebruik dan aub de Template:RefBox template en bijbehorende sub-titel structuur. Dit helpt om de handleiding consistent te houden, met algemene informatie in een goed-georganiseerde en makkelijk toegankelijke plek, zodat mensen snel kunnen bladeren en de informatie vinden die ze nodig hebben. Zie ook de Reference Box Guidelines voor meer informatie over het gebruik van deze structuren.

Een voorbeeld van het referentie-blok:

Mode: Edit Mode (Mesh)

Hotkey: CtrlR

Menu: Mesh → Edges → Loop Subdivide...

Het bespaart jou en de lezers tijd als je deze templates waar mogelijk gebruikt. Je hoeft niet meer uitleg te geven als: "Om deze tool te gebruiken moet je de X-toets op het toetesenbord te gebruiken," als er een mooi plaatje bovenin staat met een sneltoets. Doordat deze op een consequente plek staat vinden lezers het sneller. De handleiding is geen roman, dus schrijf compact en doelgericht!

Richtlijnen voor afbeeldingen

Het gebruik van afbeeldingen in de documentatie is essentiëel. De formate PNG en JPG hebben absoluut de voorkeur. Gebruik van GIF en andere niet-vrije formaten wordt sterk afgeraden. Niet gecomprimeerde formaten als TGA worden ook afgeraden.

Afbeeldingen dienen te worden ge-upload naar de wiki met behulp van de

http://mediawiki.blender.org/index.php/Special:Upload

link.

Uitgelijnde afbeeldingen

Uitgelijnde afbeeldingen dienen een kopje te hebben en een referentie vanuit de tekst. Vermijdt termen als "de volgende afbeelding" en "het volgende figuur". Gebruik Verwijzingen. Verwijzingen worden beschreven in Sectie 7.

Het gebruik van afbeeldingen zonder referentie wordt ontmoedigd. Als je niet weet hoe je naar een afbeelding moet verwijzen dan is deze ofwel overbodig, of de tekst is onduidelijk.

De documentatie, zowel Kern als Tutorials, moeten consistent blijven. Daarom moeten de afmetingen maximaal 800x600 zijn. Het gebruik van afbeeldinge groter dan 800 pixels wordt sterk afgeraden omdat deze te breed zijn om te lezen in een internet browser.

het meest prominente aan Blenders interface is dat hij volledig in OpenGL wordt gerenderd en schaalbaar is. Dit is erg mooi maar leidt helaas tot veel inconsequenties als gebruikers schermafbeeldingen maken om diverse instellingen te laten zien zoals afwijkende materiaal instellingen, etc...

Om zowel helderheid als uniformiteit te garanderen moeten de afmetingen van de interface zo worden ingesteld dat de RODE schuif in het meteriaal venster 18 pixels hoog is. Dit is wat Blender laat zien als je bij een 1024x768 beeldschermresolutie in de default schermindeling en op de 'home' knop drukt --in het knoppen menu-- om de standaard knop-grootte in te stellen.

Als je in een hogere resolutie werkt, stel deze dan a.u.b. in op 1024x786 als je scherm afbeeldingen gaat maken. Het is te hopen dat niemand lagere schermresoluties hanteerd! Eén manier om schermafbeeldingen te maken in 1024 resolutie terwijl je op een hogere resolutie werkt is om gebruik te maken van de oprachtprompt windowed' als je Blender opstart:

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


Hierdoor zal Blender in een venster starten met een desktop-afmeting van precies 1024x768 pixels. Het programmavenster zal iets groter zijn vanwege de omkadering. Om het Blender-deel van het scherm af te beelden zou je Gimp kunnen gebruiken met een 'vaste' selectie-venster (van 1024x786) waarmee dat programma automatisch dat deel van het scherm kopieert waar Blender wordt afgebeeld, zonder alle vensterranden.

Schermafbeeldingen moeten worden genomen in een LOSSLESS (niet gecomprimeerd) formaat, gebruik dus PNG.

Als je een bepaald deel van een afbeelding moet benadrukken (een knop, een waarde of een groep knoppen/waardes) gebruik dan een geel (R=255, G=255, B=0) kader dat 2 pixels dik is.

Gebruik de default interface stijl van Blender.

Afbeeldingen in de tekst

Afbeeldingen van Blender iconen in de tekst zijn welkom en maken de beschrijvingen veel helderder. Omdat dit STANDAARD afbeeeldingen zijn, gebruik a.u.b. de door het DocBoard ter beschikking gestelde afbeeldingen en maak ze niet zelf.

Emoticons in de tekst

De officiële documentatie is geen plek voor emoticons (humor is iets anders, natuurlijk mag je grappig zijn!)

Tabellen

Tabellen vormen een toepasselijke manier om veel gegevens op een heldere, gestructureerde wijze weer te geven. Ze kunnen een geldig alternatief voor schermafbeeldingen vormen als het gaat om het tonen van verschillende instellingen.

Tabellen moeten, net als losse afbeeldingen, worden voorzien van een titel en er dient naar te worden verwezen in de tekst.

Code

De Wiki heeft een prettige omgeving voor stukjes Python/C/watvoortaaldanook code.

Stukken code, net als losse afbeeldingen, moeten over een titel beschikken en er moet vanuit de tekst naar worden verwezen.

Documentatie stijl in de praktijk

In dit hoofdstuk worden enkele gedetailleerde voorbeelden getoond van hoe een Wiki pagina er verwacht wordt uit te zien.

Voorbeelden Afbeeldingen

Zo voeg je plaatjes toe aan je pagina's, nadat deze zijn ge-upload naar de server:

Normale Afbeeldingen

Dit is de makkelijkste manier om afbeeldingen in je tekst te plaatsen, en tegelijkertijd de veiligste, omdat je niet over tekstuitlijning hoeft na te denken.

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

Dit zorgt dat het plaatje op een nieuwe regel begint met alle tekst rondom verwijderd:

Demo Plaatje nummer 1

Uitgelijnde afbeeldingen

Dummy plaatje
Deze vorm komt ietwat nauwer, aangezien je er rekening mee moet houden dat het er op andere resoluties/venstergroottes/lettergroottes anders uit kan zien dan bij jou.

Om een plaatjs rechts naast de tekst uit te lijnen, gebruik je de volgende syntax:

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

Zet deze code voor de eerste regel waarnaast je de afbeeldinge wil laten verschijnen!
Om de pagina tot aan de onderzijde van het plaatje vrij te laten, gebruik je:

{{clr}}

Afbeeldingen in de tekst

Afbeeldingen in de tekst, zoals DemoImage2.png zijn nog makkelijk in te voegen:

[[Image:DemoImage2.png]]

Afbeeldingen in tabellen

Als je een serie kleine afbeeldingen hebt die met elkaar te maken hebben, kun je ze in een simpele tabel plaatsen:

{|
 |valign=top|[[Image:Manual-Part-III-materialRampsExample04.png|thumb|200px|none|Geen 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|Zowel Color als Specular Ramp.]]
|}
Geen Ramp Shader.
Color Ramp.
Zowel Color als Specular Ramp.

Meer hulp voor afbeeldingen

Voor uitgebreide informatie over het gebruik van afbeeldingen, zie: Images and other uploaded files

Tabellen

abellen kunnen ofwel in HTML, ofwel in de veel nettere Wiki syntax worden geschreven:

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

wordt

Tafel van vermenigvuldiging
× 1 2 3
1 1 2 3
2 2 4 6
3 3 6 9
4 4 8 12
5 5 10 15

Om verdere opmaak mogelijk te maken is er een kant-en-klare 'UM/prettytable' template

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

Leidt tot:

1 2 3
4 5 6


Meer over de syntax voor tabellen

Kijk op deze pagina voor uitgebreidere informatie over tabellen: Tables

Code

Alle bovenstaande voorbeelden van Wiki code werden afgebeeld door ze af te bakenen met een <nowiki></nowiki> combinatie.

Door een of meerdere spaties aan het begin van een regel te zetten ziet hij er zo uit:

 zo dus

Een andere manier om dit voor elkaar te krijgen (voor langere stukken code bijvoorbeeld), is ze af te bakenen met een <pre></pre> combinatie.

Als je tenslotte geen groot kader rond je code nodig hebt of wil kun je ook: <code></code> gebruiken hetgeen leidt tot:

This is an example

Verwijzingen

Verwijzingen worden op zijn wiki's gedaan, waarbij in de vorige documentatie labels werden gebruikt om een object te identificeren. Wiki gebruikt een object name; dus wat we nodig hebben is een *uniek* naamschema voor figuren

Webografie

Wiki sites here

Bestandsnamen

Bestandsnamen zijn een gevoelige taak in zoverre dat ze uniek moeten zijn door heel het Blender Documentatie Project en zelf-uitleggend moeten zijn om verwijzingen van het ene, naar het andere hoofdstuk mogelijk te maken.

Het is daarom erg aan te raden om vast te houden aan de gegeven standaard:

Voor de Kern documentatie

 Manual.nl/zelf-uitleggende-naam

Voor afbeeldingen in de Kern documentatie bestaat een soortgelijke naamgeving. Maar helaas wordt '/' niet geaccpeteerd door het systeem. Dus wordt '-' in plaats van '/' gebruikt. Bijvoorbeeld:

 Manual-zelf-uitleggende-naam.ext

De gebruiker die wordt gedefinieerd is geheel aan de auteur die verantwoordelijk is voor het uniek houden van het label.

Woordenlijst

Een lijst met termen die we wel een termen die we niet vertalen kun je vinden op de De Woordenlijst