Zasady redagowania artykułów w poszczególnych działach Kompendium

Zasady redagowania – dział Delphi

Niniejsza sekcja opisuje zasady redagowania działu Delphi. W chwili obecnej jest to dział, w którym znajduje się największa liczba materiałów. Propozycje zawarte w tej sekcji są subiektywne (proponowane przez użytkownika @Adam Boduch) i mogą być zmienione w drodze dyskusji.

Cele

Docelowo dział Delphi ma stanowić kompletne kompendium wiedzy dla programistów, opis języka, klas, modułów, komponentów oraz artykuły i FAQ związane z programowaniem w tym języku. Do dyspozycji użytkownika należy udostępnić przydatne komponenty oraz kody źródłowe programów napisanych w Delphi.

Kolejność opisywania

Prosimy w pierwszej kolejności skupić się na składni języka. Należy opisać słowa kluczowe języka, po czym skupić się na podstawowych elementach, takich jak: pętle, moduły, instrukcje warunkowe, tablice. Następnie można przejść do opisywania funkcji. Zalecane jest zajęcie się funkcjami obecnymi w module System w pierwszej kolejności (czyli np. Inc, Writeln, Abs i inne funkcje wbudowane).

Ostatnim etapem jest opisanie klas i komponentów; jednak jeszcze nie ustalono zasad, jakim powinni kierować się autorzy.

Zobacz też

• Artykuły do zrobienia

Słowa kluczowe

Następująca zasada wykształciła się na samym początku funkcjonowania tej wersji systemu Coyote, od której każdy użytkownik ma możliwość edycji artykułów. W pierwszym akapicie opisującym słowo kluczowe języka powinno znajdować się wyjaśnienie, czym właściwie jest dane słowo kluczowe. Na przykład:

or – operator języka Delphi.

czy:

unit – słowo kluczowe języka Delphi oznaczające deklarację modułu.

W kolejnym akapicie można krótko opisać, do czego służy dane słowo kluczowe, i podać krótki przykład wykorzystania. Tutaj uwaga: aktualnie tematy takie jak tablice, rekordy czy moduły opisane są w osobnych artykułach. Tak więc opisując na przykład słowo kluczowe <kgd>unit</kbd> podajemy krótką definicję oraz link do artykułu Moduły.

Opis funkcji

Funkcje i procedury w języku Delphi zawsze należą do jakiegoś modułu. Podstawowym modułem jest System, który jest zawsze dołączany do aplikacji typu Win32. Podstawowe polecenia języka, jak Inc, Writeln czy nawet Exit, należą do modułu System.

Na początku opisywania danej funkcji/procedury korzystamy z szablonu Delphi Moduły, podając mu parametry w postaci nazwy funkcji/procedury oraz modułu, do jakiego należy. Na przykład:

<div style="border: 1px solid #C0C0C0; background-color: #F8F8F8">
<div style="padding: 10px; float: left; font-weight: bold">Writeln</div>
<div style="padding: 10px; text-align: right; font-weight: bold">Moduł: <a href="/Delphi/Moduły/System">System</a></div>
</div>

Spowoduje to wstawienie na samej górze takiego szablonu:

Następnie wpisujemy nagłówek procedury/funkcji:

procedure WriteLn([ var F: Text; ] P1 [, P2, ...,Pn ] );

W następnym akapicie należy dodać krótkie zdanie, do czego służy dana funkcja, a kolejny akapit może opisywać funkcję oraz jej parametry bardziej szczegółowo. Artykuł powinien także zawierać przykłady wykorzystania danej funkcji. Zobacz przykładowe artykuły: Inc, Dec, Abs.

Prosimy o umieszczanie w artykule linków do artykułów nawiązujących do danego hasła.

Metody

(jeszcze nie ustalono)

Formatowanie kodu

(TODO) Umieszczając w tekście czy to (artykuł – TODO: ?), czy wskazówkę, czy też opis danej funkcji, często będziesz zmuszony wstawiać przykłady wykorzystania. Zalecane jest stosowanie jednolitego stylu formatowania kodu.

Opis, jak powinien być sformatowany kod w Delphi, znajdziesz w artykule Formatowanie kodu w Delphi.

Zasady redagowania – HTML

(TODO) Ta sekcja opisuje zasady tworzenia artykułów w dziale HTML. Zasady te wyklarowały się po krótkiej dyskusji i taki styl został przyjęty i zaaprobowany przez większość użytkowników.

Cele

(TODO) Dział HTML ma docelowo opisywać wszystkie znaczniki, atrybuty i zdarzenia w językach HTML oraz XHTML.

Opis znacznika

(TODO) W pierwszej kolejności prosimy o skupienie się na opisywaniu znaczników języka XHTML. Styl, jaki wyklarował się, mówi o stosowaniu w opisie znacznika następujących elementów:

1. Na początku tekstu artykułu – znacznik w nagłówku <h1>, zapisany w odpowiedniej formie (z zachowaniem odpowiedniej wielkości znaków, jeśli jest istotna).
2. Niewielki opis samego znacznika oraz jego działania.
3. Opcjonalna sekcja "Zobacz też".
4. Sekcja "Przykład użycia" z krótkim przykładem użycia znacznika.
5. Sekcja "Główne atrybuty" z opisem innych atrybutów.
6. Sekcja "Atrybuty wizualne" z opisem atrybutów odpowiadających za wygląd.
   1. (TODO) Niekiedy zamiast sekcji "Atrybuty wizualne" może pojawić się sekcja "Atrybuty niestandardowe" z łączami do atrybutów, które są wspierane tylko przez niektóre przeglądarki i nie istnieją w standardzie języka.
7. Sekcja "Dostępne zdarzenia" z listą zdarzeń języka JavaScript przypisanych do znacznika.
   1. Może pojawić się sekcja "Zdarzenia niestandardowe" z łączami do zdarzeń wspieranych przez niektóre przeglądarki.

Gdy w tekście odwołujemy się do znacznika (opisywanego bądź innego), możemy używać albo formy "Nazwaznacznika", albo <nazwaznacznika>,

Znaczniki przestarzałe możemy oznaczać stosując szablon `

(TODO) Znaczniki przestarzałe należy także (dodać do kategorii Deprecated – TODO "Dodać do kategorii"?).

Sekcja "Zobacz też"

Nagłówek tej sekcji powinien być tworzony z użyciem znacznika <h4> (a nie <b>!). Powinna ona zawierać listę nieuporządkowaną z linkami do innych, podobnych znaczników.

Sekcja może znajdować się albo pod opisem znacznika, albo na końcu tekstu artykułu.

Atrybuty

(TODO) Atrybuty (zarówno wizualne, jak i główne) powinny być wypisane za pomocą listy nieuporządkowanej, wraz z krótkim opisem oraz odwołaniem do szerszego opisu atrybutu – odpowiedniego artykułu w kategorii Atrybuty. W wypadku gdy atrybut może mieć tylko kilka wartości, w artykule o znaczniku nie należy ich wymieniać; należy je przenieść do artykułu o atrybucie.

Atrybuty, które są dostępne praktycznie dla każdego znacznika, czyli atrybuty używane głównie przez CSS (Id, Class i Style), mogą być wstawione do tekstu (do sekcji "Główne atrybuty"!) za pomocą szablonu:

* [[(X)HTML/Atrybuty/Id]] - identyfikator
* [[(X)HTML/Atrybuty/Class]] - klasa CSS
* [[(X)HTML/Atrybuty/Style]] - przypisany styl CSS

Podobnie mogą być wstawiane inne atrybuty, także dostępne praktycznie dla każdego znacznika, czyli: Lang, Dir i Title, poprzez:

* [[(X)HTML/Atrybuty/Title]] - definiuje tytuł elementu
* [[(X)HTML/Atrybuty/Lang]] - definiuje język elementu
* [[(X)HTML/Atrybuty/Dir]] - definiuje kierunek tekstu w elemencie

Uwaga: nie opisujemy ani nie wyliczamy atrybutów xml:lang oraz xmlns, gdyż są to atrybuty czysto XML-owe i dostępne dla każdego znacznika w każdym języku pochodnym XML.

Atrybuty wizualne

Przy opisie atrybutów wizualnych należy zaznaczyć, że są one przestarzałe – na przykład stosując taki szablon:

(TODO)

<b>Atrybuty te mają status [[(X)HTML/Deprecated]] w HTML 4.01, a w XHTML 1.0 Strict są zabronione!</b> W zamian należy używać styli [[CSS]].

Atrybuty niestandardowe

Wyliczając niestandardowe atrybuty znacznika, warto zastosować taki szablon:

<div style="background-color: #FFECC6; text-align: justify; padding: 5px; border: 1px solid #845900;">
<b>Uwaga!</b>
Poniższe atrybuty znacznika `<nazwa_znacznika>` nie są zawarte w standardzie języka HTML i XHTML, ale są obsługiwane przez niektóre przeglądarki internetowe - są to pozostałości po rozszerzeniach HTML różnych firm w okresie wojny przeglądarek.
Ich używanie jest jednak <b>wysoce niezalecane</b> i powoduje <b>niezgodność strony</b> z zadeklarowanym typem dokumentu. 
</div>

Zdarzenia

By wstawić listę zdarzeń do tekstu artykułu o znaczniku, można użyć szablonu:

* [[(X)HTML/Zdarzenia/onclick]]
* [[(X)HTML/Zdarzenia/ondblclick]]
* [[(X)HTML/Zdarzenia/onmousedown]]
* [[(X)HTML/Zdarzenia/onmouseup]]
* [[(X)HTML/Zdarzenia/onmouseover]]
* [[(X)HTML/Zdarzenia/onmousemove]]
* [[(X)HTML/Zdarzenia/onmouseout]]
* [[(X)HTML/Zdarzenia/onkeypress]]
* [[(X)HTML/Zdarzenia/onkeydown]]
* [[(X)HTML/Zdarzenia/onkeyup]]

Znaczniki bez zamknięcia

Znaczniki, które nie mają znacznika zamykającego w HTML-u (ale jest on wymagany w XHTML-u), powinny mieć to wyraźnie zaznaczone. Należy wtedy zastosować szablon:

<div style="background-color: #FFDFDF; border: 1px solid #6A0000; padding: 5px; text-align: justify;">
<b>Uwaga!</b>
W języku HTML 4.01 znacznik ten nie posiada znacznika zamykającego. Natomiast w XHTML-u musi on zostać poprawnie (według standardu języka XML) zakończony: 
`<nazwa_znacznika />`

Spacja przed znakiem "/" ułatwia rozpoznanie tagu przeglądarkom nie obsługującym XHTML. [[(X)HTML/XHTML|Różnice między HTML i XHTML]].
</div>

(TODO) gdzie nazwa znacznika to to, co znajduje się pomiędzy znakami < i > – na przykład hr dla znacznika Hr. Szablon ten powoduje dodanie takiego tekstu:

Przykład użycia

(TODO) Sekcja "Przykład użycia" powinna w prosty sposób demonstrować zastosowanie danego znacznika. Przy pisaniu przykładów nie trzeba kopiować całej struktury dokumentu HTML lub XHTML, wraz z tagiem Doctype, Html, Head, wystarczy sam znacznik – chyba że całe nagłówki są potrzebne (na przykład dla znaczników znajdujących się w sekcji Head dokumentu).

(TODO) Przy zapisywaniu przykładów użycia korzystamy z poprawnego języka HTML lub XHTML. Należy pamiętać o zapisaniu poprawnego Doctype, jeśli przykład wymaga podania całości dokumentu HTML lub XHTML (wraz z tagiem początkowym).

Nie wolno pisać znaczników bez zamknięcia, nawet jeśli nie jest ono wymagane w języku HTML. Nie wolno zapisywać wartości atrybutów poza znakami cudzysłowu bądź apostrofu. Znaczniki piszemy małymi literami.

Kategoryzacja

(TODO) W dziale HTML mamy stworzone już kilka kategorii, a następne będą sukcesywnie dodawane. Gdy tworzysz opis znacznika, którego kategoria już istnieje, (dodaj go do tej kategorii – TODO "Dodaj do kategorii"?).

Jeżeli nie wiesz na przykład, czy uznać znacznik za semantyczny, (nie dodawaj do żadnej kategorii – TODO "Nie dodawaj do kategorii"?); inni użytkownicy poprawią artykuł.

Opis atrybutu

(TODO) (nieustalone)

Dostępne szablony

Przy opisie atrybutów można zastosować następujące szablony:

<div style="background-color: #FFDFDF; border: 1px solid #6A0000; padding: 5px; text-align: justify;">
<b>Uwaga!</b>
W XHTML niedozwolone jest stosowanie atrybutów bez przypisanej wartości i należy użyć pełnej formy: 

`<element atrybut="atrybut">`

Podczas gdy w języku HTML można zastosować krótszą wersję:

`<element atrybut>`
[[(X)HTML/XHTML|Różnice między HTML i XHTML]].
</div>

<div style="background-color: #FFDFDF; border: 1px solid #6A0000; padding: 10px; text-align: justify;"><b>Uwaga!</b>
Atrybut ten jest oznaczony jako [[(X)HTML/Deprecated|przestarzały]] i nie jest obecny w wersji Strict językow HTML i XHTML. Nie nalezy go używać, zamiast niego powinno się stosować nowsze techniki - na przykład dla atrybutów odpowiadających za wygląd są to odpowiednie polecenia arkuszy stylów [[CSS]].
</div>

Opis zdarzenia

(TODO) (nieustalone)

Źródła, z których warto korzystać

Bardzo zalecamy korzystanie ze sprawdzonych i naprawdę dobrych źródeł informacji o znacznikach, by uniknąć sytuacji, że opisywane są atrybuty, które są wspierane tylko przez jedną przeglądarkę, czy inne elementy nieistniejące w standardzie języka HTML lub XHTML.

Godne polecenia są:

• http://www.w3.org/TR/1999/REC-html401-19991224/index/elements.html – oficjalna specyfikacja języka HTML 4.01
• http://www.htmlref.com/reference/appa/index.htm – bardzo dobra encyklopedia znaczników, opisująca także specyficzne atrybuty czy zdarzenia

Zasady redagowania CSS

(TODO) W dziale HTML trzeba było poprawiać wiele artykułów, bo nie dość szybko powstały spójne zasady ich tworzenia. Aby uniknąć takiej sytuacji, chcielibyśmy zaproponować takie zasady już na samym początku tworzenia działu CSS.

Tę sekcję można traktować jako propozycję. Jeżeli nie zgadzasz się z tymi zasadami, zaproponuj inne.

Początek opisu polecenia

Na początku tekstu artykułu opisującego polecenie należy krótko zdefiniować rolę danego polecenia.

Następnie należy dokładnie opisać funkcje tego polecenia. Jeśli ma ono kilka funkcji, każdą należy wymienić po nagłówku sformatowanym z wykorzystaniem znacznika <h3>.

Do wypisania możliwych wartości polecenia stosuj listę nieuporządkowaną.

Polecenia pokrewne

Po takim nagłówku: <h2> "Polecenia pokrewne" należy na liście nieuporządkowanej wymienić polecenia CSS, które są mu pokrewne. Np. dla Font będą to Font-size i Font-family.

Odpowiednik HTML

(TODO) Tutaj wypisuje się ewentualne tagi lub atrybuty HTML, które działają podobnie jak opisywane polecenie CSS. W razie potrzeby należy zaznaczyć, że tag czy atrybut HTML ma status Deprecated.

Wersja specyfikacji

Tu należy zaznaczyć, w jakiej wersji CSS pojawiło się dane polecenie. Lista specyfikacji znajduje się na stronie głównej działu CSS.

Wsparcie przeglądarek

Tu należy wypisać, od jakich wersji przeglądarki wspierają to polecenie. Najważniejsze, aby napisać o Chrome oraz Firefoxie. Oczywiście jeśli ktoś posiada informacje o większej ilości przeglądarek, nic nie stoi na przeszkodzie, aby je wykorzystać.

W tym miejscu należałoby też zaznaczyć ewentualne "dziwactwa", jakie serwują nam poszczególne przeglądarki (wiadomo, że nawet nowoczesne przeglądarki miejscami odbiegają od standardu obsługi CSS). Taka informacja dla uczących się języka CSS może być bardzo przydatna.

Pseudolementy i pseudoklasy

(TODO) Nie ustalono.

Stałe wartości, które przyjmują polecenia (np. None, Wartość "hidden", inline)

(TODO) Nie ustalono.

Powtarzające się teksty, szablony

Jeżeli jakieś polecenie definiuje kolor, należy wstawić przy nim szablon:

<dfn>Kolor można zadeklarować jako jedną z 16 stałych lub w formacie rgb: #xxyyzz gdzie "xx" to zapisana szesnastkowo składowa czerwona, "yy" zielona a "zz" niebieska (np. #FFFFFF dla białego), można też użyć formy skróconej #xyz. Można też użyć zapisu `rgb(<i>r</i>, <i>g</i>, <i>b</i>)`, w którym stosuje się liczby dziesiętne.

CSS3 wprowadza trzy nowe sposoby deklarowania koloru [[css/rgba|rgb z kanałem alfa]], [[css/hsl|odcień nasycenie jasność]], [[css/hsla|odcień nasycenie jasność z kanałem alfa]]</dfn>

Kolor można zadeklarować jako jedną z 16 stałych lub w formacie rgb: #xxyyzz gdzie "xx" to zapisana szesnastkowo składowa czerwona, "yy" zielona a "zz" niebieska (np. #FFFFFF dla białego), można też użyć formy skróconej #xyz. Można też użyć zapisu rgb(<i>r</i>, <i>g</i>, <i>b</i>), w którym stosuje się liczby dziesiętne.

CSS3 wprowadza trzy nowe sposoby deklarowania koloru rgb z kanałem alfa, odcień nasycenie jasność, odcień nasycenie jasność z kanałem alfa</dfn>

Zasady redagowania – C#

Sekcja opisuje zasady pisania artykułów w dziale C# i .NET. Są one skrócone do absolutnego minimum, aby ułatwić użytkownikom modyfikację artykułów; jednak z uwagi na rozmiar języka należy przestrzegać poniższych wytycznych.

Cele

Dział C# i .NET powinien zawierać jak najwięcej informacji o specyfikacji języka, mniej zaś o opisie samych klas .NET (co nie znaczy, że tych nie wolno opisywać; trudno jednoznacznie oddzielić te dwa światy).

Opis elementów języka

Ważna rzeczą jest wskazanie informacji, od jakiej wersji języka C# i .NET dany element występuje. Informacja taka jest zbędna dla wersji 1.0 oraz 1.1. Kolejne wersje (2.0, 3.0, …) powinny mieć informacje. Na przykład: jeżeli opisujemy słowa kluczowe LINQ, powinniśmy umieścić informację, że chodzi o wersję 3.0. Należy w tym celu wykorzystać gotowy szablon w ten sposób:

<span style="color:#C0C0C0">( element wprowadzony do języka C# od wersji 3.0 )</span>

( element wprowadzony do języka C# od wersji 3.0 )

Informacja o wersji zostanie automatycznie dodana (w przykładzie: wersja 3.0).

Stary i nieużywany dział "Podręcznik"

W starej wersji Serwisu został stworzony osobny dział o nazwie "Podręcznik". W obecnej formie dział ten nie występuje, a z czasem jego artykuły będą przenoszone do odpowiednich kategorii (wcześniej artykuły się dublowały). Wobec powyższego prosimy o nie dopisywanie artykułów do działu "Podręcznik"!