From BlenderWiki

Jump to: navigation, search

By zachować logiczną zgodność całej Dokumentacji Blendera, przyszli autorzy proszeni są o zastosowanie się do poniższego przewodnika Stylu (Style Guide).

Ludzie kompletnie nie znający składni MediaWiki mogą skierować się do oficjalnych MediaWiki Docs

Główne Wytyczne

Dokumentacja Blendera powinna być pisana w prostym, zwięzłym i poprawnym Angielskim(jeśli chcesz tłumaczyć na polski powinieneś także się zapoznać z tym dokumentem). Powinna być odpowiednio podzielona na rozdziały, sekcje i podsekscje.

Logiczny podział Głównej dokumentacji jest dyktowany przez system dokumentacji. Nowe strony nie mogą być dodawane bez wcześniejszego zatwierdzenia.

Logiczny podział dodawanych Tutoriali jest zostawiony ich autorom.

Tutoriale powinny zawierać streszczenie (do około 300 słów) wstępnie opisujące temat, zamierzenia oraz spis treści do łatwego przeglądania.

Każda strona powinna mieć odpowiedni tamplate w pierwszej linijce pomagający w nawigacji i zawierający wersje Blendera której dotyczy. Na polskiej wersji robi się to przez wstawienie:

 {{Page/Header|2.32|Meta:PL/Guides|Następna strona|39}}

gdzie:

2.32 - jest oczywiście numerem wersji której dotyczy.

Meta:PL/Guides|Następna strona - to linki do poprzedniej i następnej strony rozdzielone znakiem "|".

39 - liczba z zakresu 0 - 100, określająca procent ukończenia tłumaczenia

Wynikiem powyższego będzie to:

Jeśli poprzednia lub następna strona nie istnieje wtedy strzałka będzie czerwona i nie będzie dało się jej kliknąć.

Można pominąć dodatkowe parametry, pozostawiając część pustą.

 {{Page/Header|2.32|||39}}

Ponadto, dla długich stron pokazujących wiele funkcji, z których niektóre dotyczą innych wersji Blendera, dostepny jest inny template.

 {{version|2.32}}

Powinien być umieszczony zaraz pod tytułem sekcji/podsekcji, aby był wyświetlony zaraz pod nazwą sekcji.

Na dole każdej strony powininna być pomagająca w nawigacji stopka

 {{Page/Footer|Poprzednia strona|Następna strona}}

wyglądająca tak:




poprzednia i nastepna strona powinny mieć prawidłowe linki do odpowiednich stron!

Template'y

Blender 2.32+

Jest już zrobiony zbiór template'ów dla systemu dokumentacji. Uprasza się o stosowanie ich i tylko ich.

Lista Template'ów znajduje się w Templates

Wytyczne Obrazków

Używanie obrazków w dokumentacji jest niezbędne. Preferowane formaty to PNG i JPG. Odradzamy używania GIF'ów i innych formatów non-free. Nieskompresowane formaty jak TGA też są niepożądane.

Obrazki są wgrywane do wiki przy użyciu tego http://mediawiki.blender.org/index.php/Special:Upload linku.

Pływające Obrazki

Pływające obrazki powinnym mieć nagłówek i odniesienie w tekście. Prosze nie używać nazw typu "nastepny obrazek" lub "kolejna ilustracja". Używaj odnośników (cross references). Odnośniki te są opisane w Sekcji 7.

Odradza się używania obrazków bez odnośników. Jeśli masz obrazek do którego nie wiesz jak się odnieść to znaczy, że jest on niepotrzebny lub, że twój tekst jest zagmatfany.

Dokumentacja, zarówno Główna, jak i Tutoriale, muszą zachowywać zgodność. Rozmiary obrazków powinny być maksymalnie 800x600. Używanie obrazków szerszych niż 800 pikseli jest bardzo niepożądane ponieważ są za szerokie by wygodnie je oglądać w przeglądarce.

Najbardziej znaczącą cechą interfejsu Blendera jest to, że jest on w pełni renderowany w OpenGL'u i skalowalny. To jest świetne ale ma smutne rezultaty jakimi jest duża niejednorodność, gdy użytkownicy robią zrzuty ekranów by pokazać różne opcje takie jak, indywidualne ustawienia materiałów czy tekstur.

By zapewnić zarówno przejrzystość jak i jednorodność powinieneś ustawić rozmiar interfejsu tak aby suwak czerwieni miał 18 pikseli wysokości. To jest wtedy gdy używasz rozdzielczości 1024x768 z domyślnymi ustawieniami Blendera i naciśniesz klawisz 'home' (gdy jesteś w oknie przycisków) by ustawić domyślny rozmiar przycisków.

Jeśli używasz wyższej rozdzielczości, przejdź do 1024x768 by robić zrzuty. Mam nadzieję, że nikt już nie używa mniejszych ekranów! Jedynym sposobem aby zrobić zrzuty 1024, jeśli używasz wyższych rodzielczości jest użycie trybu otwarcia w oknie z linii poleceń nastepujacą komendą:

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

To otworzy Blendera w oknie z obszarem działania dokładnie 1024x768 pikseli. Rozmiar aplikacji bedzie większy z powodu wstawek pulpitu. By pobrać cześć z blendera możesz użyć Gimp'a z poprawnie zaznaczonym regionem (1024x768) i on automatycznie pobierze cześć okna z blenderem, bez upiekszeń tworzonych przez pulpit.

Zrzuty ekranu muszą być wformacie bezstratnym, użyj więc PNG.

Jeśli potrzebujesz zaznaczyć daną część obrazu (przycisk, wartość, lub grupę przycisków/wartości) użyj żółtej (R=255,G=255,B=0) ramki grubości 2 pikseli na całej długości .

Używaj domyślnego stylu interfejsu użytkownika z Blendera.

Obrazki w tekście

Obrazki w tekście pokazujące ikony blendera są mile widziane i czynią opisy bardziej przejrzystymi. Dopóki są to STANDARDOWE obrazki, prosze nie rób własnych, używaj dostarczonych przez system Dokumentacji.

Emotki w tekście etc

W Oficjalnej Dokumentacji nie ma miejsca dla emotek. (humor jest inna sprawą, oczywiście możesz być zabawny!)

Tabele

Tabele są odpowiedną metodą do wyświetlania wielu danych w czysty, poukładany sposób. Mogą być dobrą alternatywą dla zrzutów ekranów pokazująych różne ustawienia.

Tabelki, podobnie jak pływające obrazki, muszą mieć nagłówek i muszą mieć odnośniki w tekście.

Kod

Wiki jest niezłym środowiskiem dla wycinków kodu Pythona/C/innychjęzyków.

Wycinki kodu, tak jak pływające obrazki, muszą mieć nagłówek i muszą mieć odnośniki w tekście.

Styl dokumentacji w praktyce

Ten rozdział pokaże przykłady tego, czego oczekujemy od twoich stron.

Przykłady Obrazków

Tutaj pokazano jak wstawić obrazki do twojej strony, gdy są już wgrane na serwer:

Normalne Obrazki

To jest najprostsza metoda by umieścić obrazki w tekście, i tym samym najbezpieczniejsze dopóki nie musisz się martwić o oblewanie.

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

Wstawia obraz od nowej linii, z całym tekstem usuniętym z niej:

Obrazek Demo numer 1

Pływające obrazki

Manekin obrazka
To jest troche bardziej skomplikowane, bo musisz uwzględnić jak to może wyglądać w innych rozdzielczościach/rozmiarach okien/rozmiarach fontów niż twoje. By sprawić aby obrazek pływał po prawej stronie tekstu. Użyj tej składni:

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

Wstaw ten kod na początku pierwszej linii przy której obrazek ma się pojawić!
By zakończyć tekst przed końcem obrazka, użyj następującej składni:

{{clr}}

Obrazki w tekście

Obrazki w tekście takie jak DemoImage2.png są nawet łatwiejsze do wstawienia:

[[Image:DemoImage2.png]]

Obrazki w Tabelkach

kiedy masz zestaw małych obrazków które mają ze sobą coś wspólnego, możesz wstawić je do tabelki:

{|
 |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.

Więcej o obrazkach

Zajrzyj na tę strone by dowiedzieć się wiecej o używaniu obrazków: Images and other uploaded files

Tabelki

Tabelki mogą być pisane w HTML albo przy użyciu znacznie prostszej składni Wiki:

 {| 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
 |}
 

tworzy

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

By ułatwić formatowanie stosuje się pre-definiowany template 'UM/prettytable' więc taki kod

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

pokaże nam to

1 2 3
4 5 6


Więcej o składni tabelek

Zajrzyj na tę strone by dowiedzieć się wiecej o używaniu tabelek: Tables

Kod

Wszystkie powyższe przykłady kodu są wytwarzane przez umieszczenie ich w parze takich <nowiki></nowiki> tagów.

Przy umieszczniu jednej lub więcej spacji na początku linii ukaże nam się:

 takie coś

Innym sposobem by to zrobić (np dla dużych porcji kodu), jest włożenie go w tą <pre></pre> pare tagów.

Jako alternatywe, jeśli nie potrzebujesz lub nie chcesz dużej ramki z kodem możesz użyć <code></code> które da :

To jest przykład

Odsyłacze

Odsyłacze są zrobione w stylu wiki, podczas gdy w poprzednich doc'ach używaliśmy etykiet by odwołać się do obiektu, Wiki używa obiektu name; więc to co potrzebujemy to używać *nie powtarzających się* nazw ilustracji.

Webography

Tu są strony Wiki

Nazwy plików

Nazwy plików są delikatną sprawą ponieważ muszą być one niepowtarzalne dla całego Projektu Dokumentacji Blendera i samowyjaśniające by umożliwić poruszanie się między rozdziałami etc.

Jest bardzo wskazane by trzymać się poniższego standardu:

Dla głównej dokumentacji

 Manual/Part##/self-explanatory-name

Part## jest Częscią ##, w której ## jest numeracją rzymską części do której obiekt przynależy. Nazwy stron są dobrymi przykładami takiego nazewnictwa.

Dla obrazków w Głównej dokumentacji system nazw jest podobny. Ale niestety '/' nie jest akceptowane przez system. Więc raczej używaj '-' zamiast '/'. Na przykład:

 Manual-PartXX-self-explanatory-name

Nazwa taka zależy od autora, który jest odpowiedzialny za to by była ona niepowtarzalna.