Zasady redagowania artykułów
Przekierowano z Zasady_pracy
Podstawą rozbudowywania zawartości serwisu, jest ustalenie zasad i reguł jakimi będziemy się kierować w trakcie pracy. Na tej stronie znajdują się wszelkie reguły i wytyczne jakimi powinni kierować się autorzy tekstów w serwisie 4programmers.net. Nie możemy pozwolić sobie na samowolkę. Wyobraź sobie, iż każdy pisze artykuły stosując swój unikaly styl, używa formatowania tekstów, jakie jemu przypadło do gustu. Aby zapewnić odpowiedni poziom merytoryczny oraz techniczny (patrz. Formatowanie tekstu), aby materiały znajdujące się w serwisie były na odpowiednio wysokim poziomie, musimy ustalić pewne reguły i zasady według których będziemy rozbudowywać jego zawartość merytoryczną.
Spis treści
1 Podstawowe reguły
1.1 Formatowanie kodu
1.1.1 Zmienne metasyntaktyczne
1.2 Język
1.2.1 Akapity
1.2.2 Podział na rozdziały
1.2.3 Styl
1.2.4 Subiektywne opinie
1.2.5 Zwroty skierowane do czytelnika
1.2.6 Brak podpisu
2 Tworzenie stron
2.1 Tworzenie nowych artykułów
2.2 Małe i wielkie znaki
2.3 Niedozwolone znaki
3 Linkowanie
4 Zobacz też
5 Kategoryzacja
6 Zasady redagowania - Delphi
6.1 Cele
6.2 Kolejność opisywania
6.3 Słowa kluczowe
6.4 Opis funkcji
6.4.1 Kategorie funkcji i procedur
6.5 Metody
6.6 Formatowanie kodu
6.7 Kategoryzowanie
7 Zasady redagowania - (X)HTML
7.1 Cele
7.2 Opis znacznika
7.2.1 Sekcja "Zobacz też"
7.2.2 Atrybuty
7.2.2.1 Atrybuty wizualne
7.2.2.2 Atrybuty niestandardowe
7.2.3 Zdarzenia
7.2.4 Znaczniki bez zamknięcia
7.2.5 Przykład użycia
7.2.6 Kategoryzacja
7.3 Opis atrybutu
7.3.1 Dostępne szablony
7.4 Opis zdarzenia
7.5 Źródła, z których warto korzystać
8 Zasady redagowania - CSS
8.1 Początek opisu polecenia
8.2 Polecenia pokrewne
8.3 Odpowiednik HTML
8.4 Wersja specyfikacji
8.5 Wsparcie przeglądarek
8.6 Pseudolementy i pseudoklasy
8.7 Stałe wartości które przyjmują polecenia (np. none, hidden, inline)
8.8 Powtarzające się teksty, szablony
9 Zasady redagowania - C sharp
9.1 Cele
9.2 Opis elementów języka
9.3 Stary i nieużywany dział Podręcznik
Użytkowniku! Zanim rozpoczniesz edycję artykułów, proszę przeczytaj dokładnie tę stronę!
To jest serwis o programowaniu więc często będziesz musiał wklejać fragmenty kodów źródłowych. Pisz czytelny kod! Stosuj wcięcia oraz styl wielbłądzi. Nikt nie chce czytać kodu zapisanego przykładowo w ten sposób:
Zastanów się czy nie lepiej prezentuje się kod zmodyfikowany i zaprezentowany poniżej?
Opisując zagadnienia związane z programowaniem, często będziesz zmuszony prezentować przykłady działania danej funkcji. Nie musisz wówczas wymyslać logicznej nazwy programu/funkcji/modułu itp. Stosuj zmienne metasyntaktyczne! Czyli np. Foo, Bar:
Unikaj stosowania potocznych pojęć, żargonu, staraj się pisać poprawną polszczyzną, nie używaj uśmieszków - to nie miejsce na to. Przykładowy opis danego kodu zapisany przez użytkownika, z którego nie należy brać przykładu:
No trzeba tego no... o macie kod i wklejcie go do pliku dpr. jak dacie do OnCreate formy też bedzie dobrze . Aha jak wkejacie do dpr-a to dodajcie do uses windows!
Poziom takiej wypowiedzi jest żenujący. Pamiętaj! Opisując daną funkcję napisz pare zdań, do czego owa funkcja służy, co może się stać w wypadku gdy podamy błędne parametry. Również publikąc kod w działe Gotowce nie wklejaj samemgo kodu! Napisz pare zdań tytułem wstępu, opisz co dany kod robi, wymagane komponenty itp (to samo tyczy się kategorii FAQ w działach serwisu). Czy poniższy cytat nie wyglądałby lepiej (i profesionalniej) aby był zapisany w innej formie? Np.
W celu zapobiegania ponownego uruchamiania naszej aplikacji, należy skorzystać z poniższego fragmentu kodu. Należy go użyć w pliku głównym - z rozszerzeniem *.dpr aczkolwiek można go także wykorzystać w zdarzeniu OnCreate formularza. Proszę pamietać, o dodaniu do listy modułów (uses), modułu Windows.
Pamiętaj! Jeżeli coś robisz, zrób to raz, a porządnie!
Tekst wygląda czytelniej jeżeli podzielony jest na akapit. Pierwsza linia akapitu nie musi posiadać wcięcia! Pamiętaj! Jeżeli zamieszczasz w serwisie dłuższy tekst, używaj znacznika {{CONTENT}} który zostanie zamieniony na spis treści. Na samym początku tekstu napisz pare zdań tytułem wstępu, np. o czym będzie traktował artykuł itp. Po pierwszym akapicie należy umieścić spis treści (czyli wspomniany znacznik {{CONTENT}}), a następnie dalsze rozwinięcie tekstu.
Aby tekst był bardziej przejrzysty, należy stosować podział na rozdziały, podrozdziały i sekcje. Możesz to uczynić zarówno przy pomocy znaczników XHTML - <h1>, <h2> itp. jak i przy pomocy specjalnej składni systemu Coyote - patrz Formatowanie tekstu.
Stosuj hierarchię sekcji. Tj. tekst dzielisz na sekcje główne, czyli <h1> w której umieszczasz podrozdziały, <h2>, <h2> itd.
Nie umieszczaj w tekście pytań retorycznych, nie umieszczaj w tekście konwencji w stylu: Jak to zrobić? czy Ale co gdy ta zmienna będzie miała wartość X?. Unikaj stosowania zwrotów w stylu, Cześć, Witam, Pozdrawiam, Co słychać? Pamiętaj - to jest artykuł nie forum, czy blog.
Bardzo ważne! Unikaj stwierdzeń typu: "Ja zrobiłem...", "Pisałem...", "Utworzylem..."; jednym słowem unikaj stosowania pierwszej osoby liczby pojedyńczej. Pamiętaj, że artykuły w naszym serwisie mogą edytować wszyscy, jeden tekst może mieć wielu autorów, do kogo wówczas odnosi się pojęcie "Ja"? Zamiast tego traktuj tekst jakby był autorstwa serwisu - całej społeczności. Możesz pisać: "Ostatnio zrobiliśmy...", "Przed chwilą pokazaliśmy....", "Utworzyliśmy....".
Nie rozkazuj czytelnikowi! Zamiast pisać: "Musisz kliknąc tutaj, a póżniej tam..." (ew. "Kliknij tutaj, a potem tam...") pisz: "Aby to zrealizować należy kliknąć tutaj, a następnie tam....".
Unikaj stosowania subiektywnych opinii. Pamiętaj, że tekst mogą edytować wszyscy, wielu ludzi może być autorem danego tekstu, kogo opinia jest wówczas prezentowana? Zamiast pisać "Według mnie lepszym rozwiązaniem...." pisz: "Być może lepszym rozwiązaniem będzie....".
Unikaj stosowania zwrotów w tylu: Witam, Pozdrawiam, Cześć, Dzień dobry. Są one dobre w prywatnej korespondencji. Są one wówczas skierowane do konkretnej osoby. W artykułach nie stosujemy tego typu zwrotów.
Nie musisz podpisywać tekstu swoim nazwiskiem. Charakter serwisu umożliwia edycję haseł przez każdego zarejestrowanego użytkownika. Mamy nadzieje, że dzięki temu artykuły i wskazówki będą posiadały lepszy poziom merytoryczny, gdyż teksty mogą być pisane lub poprawione przez wiele osób. Autorzy poszczególnych wersji są wypisani na zakładce Historii danego artykułu.
Każdy zarejestrowany użytkownik może utworzyć stronę, jednak decyzja o jej utworzeniu powinna być przemyślana. Szczególnie wybór kategorii. Zadecydowanie zabronione jest tworzenie artykułów bez kategorii, a które opisują zagadnienia danego języka - np. http://4programmers.net/MessageBox. Prawidłowy adres do takiego artykułu powinien wyglądać tak: http://4programmers.net/Delphi/MessageBox.
Zobacz: Tworzenie nowych haseł
System nie rozróżnia wielkich lub małych znaków, więc nieistotne jest jak zapisany został tytuł tekstu. Domyślnie pierwszy znak danego hasła jest przekształcany na wielki. Bardzo zalecamy pisanie artykułów małymi znakami. W przypadku haseł czysto programistycznych - np. opisu funkcji, stosujemy styl "wielbłądzi" - np. MessageBox, ShowMessage itp. Proszę pamietać o zapisie nazw klas, charakterystycznych dla Delphi - np. TForm, TMainMenu (chodzi o to, aby dwa pierwsze znaki były napisane wielkimi znakami).
Stosowanie stylu "wielbłądziego" przyjęło się w języku Delphi. W przypadku języka PHP czy C większość programistów pisze nazwy funkcji i słowa kluczowe małymi literami. My także prosimy o dostosowanie się do tej reguły.
Istnieją pewne restrykcje w nazewnictwie stron. Co prawda tytuł może zawierać znaki zapisane w kodowaniu UTF-8, lecz następujące znaki są usuwane przez oprogramowanie: ' " | ? & \\ # $ ^ =
Spacje są automatycznie zastępowane przez znaki podkreślenia (_).
Linki są bardzo ważnym elementem dodawanych stron. Odnośniki należy tworzyć w celu odwołania się do innych tekstów. Informacje odnośnie tworzenia linków znajdziesz na stronie: Formatowanie tekstu.
Jeżeli w tytule artykułu znajdują się spacje, nie trzeba w trakcie tworzenia linków używać znaku podkreślenia.
Bardzo dobrą praktyką jest umieszczanie na końcu strony odnośników do stron, które mogą być powiązane z tematyką artykułu lub zawierają więcej informacji na dany temat. Oto jak może wyglądać taka sekcja:
Zobacz też:
Wypunktowanie, tak jak w przykładzie, tworzymy przy pomocy znaku gwiazdki (*). Zobacz: Formatowanie tekstu aby dowiedzieć się więcej.
Kategorie pozwalają zorientować się w ogólnej strukturze serwisu, a także w nawigacji po stronie. Dobrze jest więc kategoryzować daną stronę w grupy tematyczne. Przykładowo, słowa kluczowe języka Delphi tworzymy w kategorii Delphi, tak więc wszystkie strony znajdują się pod adresem http://4programmers.net/Delphi/(Nazwa tekstu) - np. http://4programmers.net/Delphi/String. Artykuł String opisuje typ danych języka Delphi o nazwie String. Warto jest więc zebrać wszystkie typy języka w jedną całość i dodać do kategorii Typy danych. W takim wypadku użytkownik, który odwiedzi stronę http://4programmers.net/Delphi/Typy_danych będzie miał podane "na talerzu" wszystkie typy języka Delphi.
Więcej! Typ String należy do typów łańcuchowych, więc można dodać ten artykuł także do kategorii Łańcuchowe, której kategorią macierzystą jest Typy danych. Mamy więc tekst String który może należeć do trzech kategorii:
Delphi
?
Typy danych
?
Łańcuchowe
Jak przypisywać dany tekst do wielu kategorii? Przeczytaj artykuł: Kategoryzowanie.
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 User:Adam Boduch) i mogą być zmienione w drodze dyskusji.
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.
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 jakich 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 opisywanie klas i komponentów, lecz jeszcze nie ustalono zasad jakim powinni kierować się autorzy.
Zobacz: Artykuły do zrobienia.
Ta zasada wykształciła się na samym początku funkcjonowania nowej wersji systemu Coyote umożliwiającej edycje tekstów każdemu użytkownikowi.
W pierwszym akapicie opisującym słowo kluczowe języka, powinno znajdować się wyjaśnienie, czym właściwie jest dane słowo kluczowe - np.:
or - operator języka Delphi.
czy:
unit - słowo kluczowe języka Delphi oznaczające deklaracje 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 np. słowo kluczoweunit podajemy krótką definicję oraz link do artykułu Moduły.
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 Template:Delphi Moduły podając mu parametry w postacii nazwy funkcji/procedury oraz modułu do jakiego należy - np.:
{ {Template:Delphi Moduły|Writeln|System}}
Uwaga! Ograniczenia techniczne, pomiędzy znakami { nie ma spacji!
Spowoduje to wstawanie na samej górze takiego szablonu:
Moduł: System
Następnie wpisujemy nagłówek procedury/funkcji korzystając ze znacznika <code>:
<code=delphi:noframe>procedure WriteLn([ var F: Text; ] P1 [, P2, ...,Pn ] );</code>
Proszę pamiętać o parametrze noframe który oznacza, że nagłówek nie będzie otoczony ramką.
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. Hasło powinno także zawierać przykłady wykorzystania danej funkcji. Zobacz przykładowe strony: Inc, Dec, Abs.
Prosimy o umieszczanie w tekście linków do stron nawiązujących do danego hasła!
Jak już wiemy, procedury i funkcje należą do modułów. W dziale Delphi moduły są opisane w kategorii Moduły, tak więc ścieżki do opisu modułów wyglądają tak: Delphi/Moduły/System, Delphi/Moduły/Math. Prosimy o umieszczanie procedur i funkcji w odpowiednich kategoriach. Przykładowo: chcesz opisać procedurę Inc. Opisujesz ją w kategorii Delphi, tak, aby link do niej wyglądał następująco: http://4programmers.net/Delphi/Inc. Dodatkowo, tę stronę należy umieścić w kategorii Delphi/Moduły/System. Dzięki temu, użytkownik będzie miał łatwy dostęp do funkcji/procedur umieszczonych w danym module. Jak to zrobić? W dowolnym miejscu tekstu umieszczamy frazę:
{ {Cat:Delphi/Moduły/System}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
Spowoduje to przypisanie danego tekstu do kategorii Delphi/Moduły/System. Zalecane jest umieszczanie takiej frazy na samym końcu tekstu. W procesie wyświetlania artykułu jest ona niewidoczna dla odbiorcy.
W Delphi często wykorzystujemy funkcje WinAPI. Są one zadeklarowane w module Windows, lecz w gruncie rzeczy takie funkcje można wykorzystać w dowolnym języku programowania, który umożliwia użycie bibliotek DLL. Postanowiliśmy, aby funkcje z modułu Windows umieszczać w kategorii WinAPI. Tak więc jeżeli opisujesz funkcje MessageBox (przykładowo), prosimy, aby odnośnik do niej wskazywał na http://4programmers.net/WinAPI/MessageBox. Dodatkowo taką funkcję można umieścić dodatkowo w dziale Delphi (również w dziale C), aby dostęp do niej był łatwiejszy. Wystarczy w tekście umieścić frazy:
{ {Cat:Delphi}} {
Uwaga! Ograniczenia techniczne. Pomiędzy znakami { nie ma spacji!
(jeszcze nie ustalono)
Umieszczając w tekście, czy to artykuł, wskazówkę, czy też opis danej funkcji, często będziesz zmuszony wstawiać przykłady wykorzystania danej funkcji. Bardzo zalecane jest stosowanie jednolitego stylu formatowania kodu.
Opis, jak powinien być sformatowany kod w Delphi, znajdziesz w artykule: Formatowanie kodu w Delphi.
Jest to bardzo ważny element w procesie powstawania artykułów z kategorii Delphi. Weźmy pod uwagę funkcję Abs. Jest to funkcja modułu System, tak więc powinna znajdować się w kategorii Delphi/Moduły/System. Ale że jest to funkcja tego właśnie modułu, dostęp do niej powinien istnieć również poprzez adres http://4programmers.net/Delphi/Abs.
Jest to także funkcja matematyczna więc można umieścić ją w kategorii Funkcje matematyczne.
Dzięki takiemu działaniu, użytkownik może trafić do opisu tej funkcji z poziomu różnych kategorii. Więcej o procesie kategoryzowania, możesz dowiedzieć się z artykułu Formatowanie tekstu.
(w trakcie realizacji)
Ta sekcja opisuje zasady tworzenia artykułów w dziale (X)HTML. Zasady te wyklarowały się po krótkiej dyskusji i taki styl został przyjęty i zaaprobowany przez większość użytkowników.
Dział (X)HTML ma docelowo opisywać wszystkie znaczniki, atrybuty i zdarzenia w języku HTML (oraz XHTML).
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:
Gdy w artykule odwołujemy się do znacznika (opisywanego bądź innego), możemy używać albo formy Nazwaznacznika, albo <nazwaznacznika> (na przykład Hr albo <hr> - należy pamietać o tagu <plain> przy zapisie tego typu).
Znaczniki przestarzałe możemy oznaczać stosując szablon { {Template:Tag_deprecated}} (Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!) wstawiający taki tekst:
Znaczniki przestarzałe należy także dodać do kategorii (X)HTML/Deprecated.
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.
Uwaga! Sekcja może znajdować się pod opisem znacznika lub na samym końcu artykułu.
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 (X)HTML/Atrybuty/. W Wypadku gdy atrybut może mieć tylko kilka wartości, w artykule o znaczniku nie należy ich wymieniać, a przenieść je 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 artykułu (do sekcji "Główne atrybuty"!) za pomocą szablonu:
{ {Template:Atrybuty_dla_CSS}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
Podobnie mogą być wstawiane inne atrybuty, także dostępne praktycznie dla każdego znacznika, czyli Lang, Dir i Title, poprzez:
{ {Template:Atrybuty_podstawowe}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
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 od XML.
Przy opisie atrybutów wizualnych należy zaznaczyć, że są one przestarzałe, na przykład stosując taki szablon:
<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]].
Wyliczając niestandardowe atrybuty znacznika warto zastosować taki szablon:
{ {Template:Attr_notstandard|nazwa_znacznika}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
Uwaga!
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 wysoce niezalecane i powoduje niezgodność strony z zadeklarowanym typem dokumentu.
By wstawić listę zdarzeń do artykułu o znaczniku można użyć szablonu:
{ {Template:Zdarzenia_HTML}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
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:
{ {Template:tag_close|nazwa_znacznika}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
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:
Uwaga!
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:
Spacja przed znakiem "/" ułatwia rozpoznanie tagu przeglądarkom nie obsługującym XHTML.
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 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).
Przy zapisywaniu przykładów użycia korzystamy z poprawnego języka XHTML, należy pamiętać o zapisaniu poprawnego Doctype jeśli przykład wymaga podania całości dokumentu HTML (wraz tagiem początkowym).
Nie wolno pisać znaczników bez zamknięcia, nawet jeśli ono w HTML-u nie jest wymagane, nie wolno zapisywać wartości atrybutów poza znakami cudzysłowu bądź apostrofu. Znaczniki piszemy małymi literami.
Kod przykładu powinien być między znacznikami <code=html4strict> </code>, dzięki którym dodawane jest kolorowanie składni.
W dziale XHTML 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.
Jeżeli nie wiesz na przykład, czy uznać znacznik za semantyczny, nie dodawaj do kategorii, inni użytkownicy poprawią artykuł.
(nieustalone)
Przy opisie atrybutów można zastosować następujące szablony:
{ {Template:null_attr|atrybut}}
Uwaga!
W XHTML niedozwolone jest stosowanie atrybutów bez przypisanej wartości i należy użyć pełnej formy:
Podczas gdy w języku HTML można zastosować krótszą wersję:
{ {Template:Attr_deprecated}}
(nieustalone)
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.
Godne polecenia są:
W dziale (X)HTML trzeba było poprawiać wiele artykułów, bo nie dość szybko powstały spójne zasady ich tworzenia. Aby uniknąć takiej sytuacji, chciałbym zaproponować takie zasady juz na samym początku tworzenia działu CSS.
Tą sekcje można traktować jako propozycje, jeżeli nie zgadzasz sie z tymi zasadami, zaproponuj inne.
Na początku artykułu opisującego polecenie należy krótko zdefiniować jego rolę.
Następnie należy dokładnie opisać jego funkcje. Jeśli polecenia ma kilka funkcji, każdą należy wymienić po nagłówku <h3>.
Do wypisania możliwych wartości polecenia stosuj listę nie uporządkowaną.
Po takim nagłówku <h2> "Polecenia pokrewne" należy na liście nieuporządkowanej wymienić polecenia CSS, bardzo podobne do opisywanego. Np dla font będą to font-size, font-family itd.
Tutaj wypisuje się ewentualne tagi lub atrybuty HTML które działają podobnie jak opisywane polecenie CSS. W razie potrzeby należy zaznaczyć ze tag czy atrybut HTML ma status Deprecated.
Tu należy zaznaczyć w jakiej wersji CSS pojawiło się dane polecenie. Lista specyfikacji znajduje sie na stronie głównej działu CSS.
Tu należy wypisać od jakich wersji przeglądarki wspierają to polecenie. Najważniejsze aby napisać o MSIE, Operze i 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ło by też zaznaczyć ewentualne "dziwactwa" jakie serwują nam poszczególne przeglądarki (wiadomo ze nawet nowoczesne przeglądarki miejscami odbiegają od standardu obsługi CSS). Taka informacja dla uczących sie CSS może być bardzo przydatna.
Nie ustalono.
Nie ustalono.
Jeżeli jakieś polecenie definuje kolor, nalezy wstawić przy nim szablon:
{ {Template:css_color}}
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(r, g, b), 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
Sekcja opisuje zasady pisania artykułów w dziale C sharp. Są one skrócone do absolutnego minimum aby ułatwić użytkownikom edycję artykułów, jednak z uwagi na ogrom języka należy przestrzegać poniższych wytycznych.
Dział C sharp 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ć, z uwagi na ciężkie rozbicie tych dwóch światów).
Ważna rzeczą podczas tworzenia artykułów jest wskazanie informacji od jakiej wersji języka C sharp 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:
{ {Template:C_sharp_version|3.0}}
Uwaga! Ograniczenia techniczne, pomiędzy znakami { nie ma spacji!
Informacja o wersji zostanie automatycznie dodana (w przykładzie wersja 3.0).
W starej wersji działu został stworzony osobny dział o nazwie Podręcznik. W obecnej formie dział ten nie występuje, a z czasem 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!
Spis treści
1 Podstawowe reguły
1.1 Formatowanie kodu
1.1.1 Zmienne metasyntaktyczne
1.2 Język
1.2.1 Akapity
1.2.2 Podział na rozdziały
1.2.3 Styl
1.2.4 Subiektywne opinie
1.2.5 Zwroty skierowane do czytelnika
1.2.6 Brak podpisu
2 Tworzenie stron
2.1 Tworzenie nowych artykułów
2.2 Małe i wielkie znaki
2.3 Niedozwolone znaki
3 Linkowanie
4 Zobacz też
5 Kategoryzacja
6 Zasady redagowania - Delphi
6.1 Cele
6.2 Kolejność opisywania
6.3 Słowa kluczowe
6.4 Opis funkcji
6.4.1 Kategorie funkcji i procedur
6.5 Metody
6.6 Formatowanie kodu
6.7 Kategoryzowanie
7 Zasady redagowania - (X)HTML
7.1 Cele
7.2 Opis znacznika
7.2.1 Sekcja "Zobacz też"
7.2.2 Atrybuty
7.2.2.1 Atrybuty wizualne
7.2.2.2 Atrybuty niestandardowe
7.2.3 Zdarzenia
7.2.4 Znaczniki bez zamknięcia
7.2.5 Przykład użycia
7.2.6 Kategoryzacja
7.3 Opis atrybutu
7.3.1 Dostępne szablony
7.4 Opis zdarzenia
7.5 Źródła, z których warto korzystać
8 Zasady redagowania - CSS
8.1 Początek opisu polecenia
8.2 Polecenia pokrewne
8.3 Odpowiednik HTML
8.4 Wersja specyfikacji
8.5 Wsparcie przeglądarek
8.6 Pseudolementy i pseudoklasy
8.7 Stałe wartości które przyjmują polecenia (np. none, hidden, inline)
8.8 Powtarzające się teksty, szablony
9 Zasady redagowania - C sharp
9.1 Cele
9.2 Opis elementów języka
9.3 Stary i nieużywany dział Podręcznik
Użytkowniku! Zanim rozpoczniesz edycję artykułów, proszę przeczytaj dokładnie tę stronę!
Podstawowe reguły
- Serwis 4programmers.net jest wortalem poświęconym programowaniu, opisujemy tutaj tylko zagadnienia związane z komputerami i programowaniem.
- 4programmers.net to nie Wikipedia, nie umieszczaj linków ani stron wyjaśniających terminy takie jak Microsoft, komputer, internet. Można natomiast umieszczać linki wskazujące na hasła takie jak Języki programowania, Programowanie itp.
- Jeżeli modyfikujemy jakiś artykuł, dobrą praktyką jest dodawanie informacji o tym co zmieniliśmy. Służy do tego pole "Opis zmian" znajdujące się na stronie służącej do edycji tekstu.
- Niezalecane jest dublowanie treści znajdujących się w innym artykule, a już na pewno tworzenie dwóch tekstów o tej samej treści.
- Jeżeli opisujesz znaczenie słowa kluczowego (np. Unit) nie pisz referatu na temat modułów. Wystarczy krótka informacja do czego służy to słowo kluczwe, notka o funkcjach modułu i jego budowie. W tekście natomiast dołącz link, wraz z informacją, że więcej informacji na ten temat, można znaleźć w artykule Moduły.
- Unikaj stosowania kolorów w tekście. To, że dana strona dobrze wygląda na jednej skórce, nie oznacza, że dobrze będzie wyglądać na innych skórkach.
- Używaj mechanizmów opisanych na stronie Formatowanie tekstu.
- Umieszczaj w tekście odnośniki do innych stron. Jak? Odpowiedź znajdziesz tutaj
- Stosuj polskie znaki!
- Unikaj stosowania nadmiernej ilości kodu (X)HTML - zamiast tego, korzystaj z mechanizmów jakie oferuje nasz system (patrz. Formatowanie tekstu).
Formatowanie kodu
To jest serwis o programowaniu więc często będziesz musiał wklejać fragmenty kodów źródłowych. Pisz czytelny kod! Stosuj wcięcia oraz styl wielbłądzi. Nikt nie chce czytać kodu zapisanego przykładowo w ten sposób:
Zastanów się czy nie lepiej prezentuje się kod zmodyfikowany i zaprezentowany poniżej?
Zmienne metasyntaktyczne
Opisując zagadnienia związane z programowaniem, często będziesz zmuszony prezentować przykłady działania danej funkcji. Nie musisz wówczas wymyslać logicznej nazwy programu/funkcji/modułu itp. Stosuj zmienne metasyntaktyczne! Czyli np. Foo, Bar:
Język
Unikaj stosowania potocznych pojęć, żargonu, staraj się pisać poprawną polszczyzną, nie używaj uśmieszków - to nie miejsce na to. Przykładowy opis danego kodu zapisany przez użytkownika, z którego nie należy brać przykładu:
No trzeba tego no... o macie kod i wklejcie go do pliku dpr. jak dacie do OnCreate formy też bedzie dobrze . Aha jak wkejacie do dpr-a to dodajcie do uses windows!
Poziom takiej wypowiedzi jest żenujący. Pamiętaj! Opisując daną funkcję napisz pare zdań, do czego owa funkcja służy, co może się stać w wypadku gdy podamy błędne parametry. Również publikąc kod w działe Gotowce nie wklejaj samemgo kodu! Napisz pare zdań tytułem wstępu, opisz co dany kod robi, wymagane komponenty itp (to samo tyczy się kategorii FAQ w działach serwisu). Czy poniższy cytat nie wyglądałby lepiej (i profesionalniej) aby był zapisany w innej formie? Np.
W celu zapobiegania ponownego uruchamiania naszej aplikacji, należy skorzystać z poniższego fragmentu kodu. Należy go użyć w pliku głównym - z rozszerzeniem *.dpr aczkolwiek można go także wykorzystać w zdarzeniu OnCreate formularza. Proszę pamietać, o dodaniu do listy modułów (uses), modułu Windows.
Pamiętaj! Jeżeli coś robisz, zrób to raz, a porządnie!
Akapity
Tekst wygląda czytelniej jeżeli podzielony jest na akapit. Pierwsza linia akapitu nie musi posiadać wcięcia! Pamiętaj! Jeżeli zamieszczasz w serwisie dłuższy tekst, używaj znacznika {{CONTENT}} który zostanie zamieniony na spis treści. Na samym początku tekstu napisz pare zdań tytułem wstępu, np. o czym będzie traktował artykuł itp. Po pierwszym akapicie należy umieścić spis treści (czyli wspomniany znacznik {{CONTENT}}), a następnie dalsze rozwinięcie tekstu.
Podział na rozdziały
Aby tekst był bardziej przejrzysty, należy stosować podział na rozdziały, podrozdziały i sekcje. Możesz to uczynić zarówno przy pomocy znaczników XHTML - <h1>, <h2> itp. jak i przy pomocy specjalnej składni systemu Coyote - patrz Formatowanie tekstu.
Stosuj hierarchię sekcji. Tj. tekst dzielisz na sekcje główne, czyli <h1> w której umieszczasz podrozdziały, <h2>, <h2> itd.
Styl
Nie umieszczaj w tekście pytań retorycznych, nie umieszczaj w tekście konwencji w stylu: Jak to zrobić? czy Ale co gdy ta zmienna będzie miała wartość X?. Unikaj stosowania zwrotów w stylu, Cześć, Witam, Pozdrawiam, Co słychać? Pamiętaj - to jest artykuł nie forum, czy blog.
Bardzo ważne! Unikaj stwierdzeń typu: "Ja zrobiłem...", "Pisałem...", "Utworzylem..."; jednym słowem unikaj stosowania pierwszej osoby liczby pojedyńczej. Pamiętaj, że artykuły w naszym serwisie mogą edytować wszyscy, jeden tekst może mieć wielu autorów, do kogo wówczas odnosi się pojęcie "Ja"? Zamiast tego traktuj tekst jakby był autorstwa serwisu - całej społeczności. Możesz pisać: "Ostatnio zrobiliśmy...", "Przed chwilą pokazaliśmy....", "Utworzyliśmy....".
Nie rozkazuj czytelnikowi! Zamiast pisać: "Musisz kliknąc tutaj, a póżniej tam..." (ew. "Kliknij tutaj, a potem tam...") pisz: "Aby to zrealizować należy kliknąć tutaj, a następnie tam....".
Subiektywne opinie
Unikaj stosowania subiektywnych opinii. Pamiętaj, że tekst mogą edytować wszyscy, wielu ludzi może być autorem danego tekstu, kogo opinia jest wówczas prezentowana? Zamiast pisać "Według mnie lepszym rozwiązaniem...." pisz: "Być może lepszym rozwiązaniem będzie....".
Zwroty skierowane do czytelnika
Unikaj stosowania zwrotów w tylu: Witam, Pozdrawiam, Cześć, Dzień dobry. Są one dobre w prywatnej korespondencji. Są one wówczas skierowane do konkretnej osoby. W artykułach nie stosujemy tego typu zwrotów.
Brak podpisu
Nie musisz podpisywać tekstu swoim nazwiskiem. Charakter serwisu umożliwia edycję haseł przez każdego zarejestrowanego użytkownika. Mamy nadzieje, że dzięki temu artykuły i wskazówki będą posiadały lepszy poziom merytoryczny, gdyż teksty mogą być pisane lub poprawione przez wiele osób. Autorzy poszczególnych wersji są wypisani na zakładce Historii danego artykułu.
Tworzenie stron
Każdy zarejestrowany użytkownik może utworzyć stronę, jednak decyzja o jej utworzeniu powinna być przemyślana. Szczególnie wybór kategorii. Zadecydowanie zabronione jest tworzenie artykułów bez kategorii, a które opisują zagadnienia danego języka - np. http://4programmers.net/MessageBox. Prawidłowy adres do takiego artykułu powinien wyglądać tak: http://4programmers.net/Delphi/MessageBox.
Tworzenie nowych artykułów
Zobacz: Tworzenie nowych haseł
Małe i wielkie znaki
System nie rozróżnia wielkich lub małych znaków, więc nieistotne jest jak zapisany został tytuł tekstu. Domyślnie pierwszy znak danego hasła jest przekształcany na wielki. Bardzo zalecamy pisanie artykułów małymi znakami. W przypadku haseł czysto programistycznych - np. opisu funkcji, stosujemy styl "wielbłądzi" - np. MessageBox, ShowMessage itp. Proszę pamietać o zapisie nazw klas, charakterystycznych dla Delphi - np. TForm, TMainMenu (chodzi o to, aby dwa pierwsze znaki były napisane wielkimi znakami).
Stosowanie stylu "wielbłądziego" przyjęło się w języku Delphi. W przypadku języka PHP czy C większość programistów pisze nazwy funkcji i słowa kluczowe małymi literami. My także prosimy o dostosowanie się do tej reguły.
Niedozwolone znaki
Istnieją pewne restrykcje w nazewnictwie stron. Co prawda tytuł może zawierać znaki zapisane w kodowaniu UTF-8, lecz następujące znaki są usuwane przez oprogramowanie: ' " | ? & \\ # $ ^ =
Spacje są automatycznie zastępowane przez znaki podkreślenia (_).
Linkowanie
Linki są bardzo ważnym elementem dodawanych stron. Odnośniki należy tworzyć w celu odwołania się do innych tekstów. Informacje odnośnie tworzenia linków znajdziesz na stronie: Formatowanie tekstu.
Jeżeli w tytule artykułu znajdują się spacje, nie trzeba w trakcie tworzenia linków używać znaku podkreślenia.
Zobacz też
Bardzo dobrą praktyką jest umieszczanie na końcu strony odnośników do stron, które mogą być powiązane z tematyką artykułu lub zawierają więcej informacji na dany temat. Oto jak może wyglądać taka sekcja:
Zobacz też:
Wypunktowanie, tak jak w przykładzie, tworzymy przy pomocy znaku gwiazdki (*). Zobacz: Formatowanie tekstu aby dowiedzieć się więcej.
Kategoryzacja
Kategorie pozwalają zorientować się w ogólnej strukturze serwisu, a także w nawigacji po stronie. Dobrze jest więc kategoryzować daną stronę w grupy tematyczne. Przykładowo, słowa kluczowe języka Delphi tworzymy w kategorii Delphi, tak więc wszystkie strony znajdują się pod adresem http://4programmers.net/Delphi/(Nazwa tekstu) - np. http://4programmers.net/Delphi/String. Artykuł String opisuje typ danych języka Delphi o nazwie String. Warto jest więc zebrać wszystkie typy języka w jedną całość i dodać do kategorii Typy danych. W takim wypadku użytkownik, który odwiedzi stronę http://4programmers.net/Delphi/Typy_danych będzie miał podane "na talerzu" wszystkie typy języka Delphi.
Więcej! Typ String należy do typów łańcuchowych, więc można dodać ten artykuł także do kategorii Łańcuchowe, której kategorią macierzystą jest Typy danych. Mamy więc tekst String który może należeć do trzech kategorii:
Delphi
?
Typy danych
?
Łańcuchowe
Jak przypisywać dany tekst do wielu kategorii? Przeczytaj artykuł: Kategoryzowanie.
Zasady redagowania - 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 User: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 jakich 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 opisywanie klas i komponentów, lecz jeszcze nie ustalono zasad jakim powinni kierować się autorzy.
Zobacz: Artykuły do zrobienia.
Słowa kluczowe
Ta zasada wykształciła się na samym początku funkcjonowania nowej wersji systemu Coyote umożliwiającej edycje tekstów każdemu użytkownikowi.
W pierwszym akapicie opisującym słowo kluczowe języka, powinno znajdować się wyjaśnienie, czym właściwie jest dane słowo kluczowe - np.:
or - operator języka Delphi.
czy:
unit - słowo kluczowe języka Delphi oznaczające deklaracje 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 np. słowo kluczowe
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 Template:Delphi Moduły podając mu parametry w postacii nazwy funkcji/procedury oraz modułu do jakiego należy - np.:
{ {Template:Delphi Moduły|Writeln|System}}
Uwaga! Ograniczenia techniczne, pomiędzy znakami { nie ma spacji!
Spowoduje to wstawanie na samej górze takiego szablonu:
Writeln
Moduł: System
Następnie wpisujemy nagłówek procedury/funkcji korzystając ze znacznika <code>:
<code=delphi:noframe>procedure WriteLn([ var F: Text; ] P1 [, P2, ...,Pn ] );</code>
Proszę pamiętać o parametrze noframe który oznacza, że nagłówek nie będzie otoczony ramką.
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. Hasło powinno także zawierać przykłady wykorzystania danej funkcji. Zobacz przykładowe strony: Inc, Dec, Abs.
Prosimy o umieszczanie w tekście linków do stron nawiązujących do danego hasła!
Kategorie funkcji i procedur
Jak już wiemy, procedury i funkcje należą do modułów. W dziale Delphi moduły są opisane w kategorii Moduły, tak więc ścieżki do opisu modułów wyglądają tak: Delphi/Moduły/System, Delphi/Moduły/Math. Prosimy o umieszczanie procedur i funkcji w odpowiednich kategoriach. Przykładowo: chcesz opisać procedurę Inc. Opisujesz ją w kategorii Delphi, tak, aby link do niej wyglądał następująco: http://4programmers.net/Delphi/Inc. Dodatkowo, tę stronę należy umieścić w kategorii Delphi/Moduły/System. Dzięki temu, użytkownik będzie miał łatwy dostęp do funkcji/procedur umieszczonych w danym module. Jak to zrobić? W dowolnym miejscu tekstu umieszczamy frazę:
{ {Cat:Delphi/Moduły/System}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
Spowoduje to przypisanie danego tekstu do kategorii Delphi/Moduły/System. Zalecane jest umieszczanie takiej frazy na samym końcu tekstu. W procesie wyświetlania artykułu jest ona niewidoczna dla odbiorcy.
W Delphi często wykorzystujemy funkcje WinAPI. Są one zadeklarowane w module Windows, lecz w gruncie rzeczy takie funkcje można wykorzystać w dowolnym języku programowania, który umożliwia użycie bibliotek DLL. Postanowiliśmy, aby funkcje z modułu Windows umieszczać w kategorii WinAPI. Tak więc jeżeli opisujesz funkcje MessageBox (przykładowo), prosimy, aby odnośnik do niej wskazywał na http://4programmers.net/WinAPI/MessageBox. Dodatkowo taką funkcję można umieścić dodatkowo w dziale Delphi (również w dziale C), aby dostęp do niej był łatwiejszy. Wystarczy w tekście umieścić frazy:
{ {Cat:Delphi}} {
Uwaga! Ograniczenia techniczne. Pomiędzy znakami { nie ma spacji!
Metody
(jeszcze nie ustalono)
Formatowanie kodu
Umieszczając w tekście, czy to artykuł, wskazówkę, czy też opis danej funkcji, często będziesz zmuszony wstawiać przykłady wykorzystania danej funkcji. Bardzo zalecane jest stosowanie jednolitego stylu formatowania kodu.
Opis, jak powinien być sformatowany kod w Delphi, znajdziesz w artykule: Formatowanie kodu w Delphi.
Kategoryzowanie
Jest to bardzo ważny element w procesie powstawania artykułów z kategorii Delphi. Weźmy pod uwagę funkcję Abs. Jest to funkcja modułu System, tak więc powinna znajdować się w kategorii Delphi/Moduły/System. Ale że jest to funkcja tego właśnie modułu, dostęp do niej powinien istnieć również poprzez adres http://4programmers.net/Delphi/Abs.
Jest to także funkcja matematyczna więc można umieścić ją w kategorii Funkcje matematyczne.
Dzięki takiemu działaniu, użytkownik może trafić do opisu tej funkcji z poziomu różnych kategorii. Więcej o procesie kategoryzowania, możesz dowiedzieć się z artykułu Formatowanie tekstu.
(w trakcie realizacji)
Zasady redagowania - (X)HTML
Ta sekcja opisuje zasady tworzenia artykułów w dziale (X)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
Dział (X)HTML ma docelowo opisywać wszystkie znaczniki, atrybuty i zdarzenia w języku HTML (oraz XHTML).
Opis znacznika
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:
- Na początku artykułu - znacznik w nagłówku <h1>, zapisany w odpowiedniej formie (z zachowaniem odpowiedniej wielkości znaków, jeśli jest istotna).
- Niewielki opis samego znacznika oraz jego działania
- Ewentualna sekcja "Zobacz też"
- Sekcja "Przykład użycia" z krótkim przykładem użycia znacznika
- Sekcja "Główne atrybuty" z opisem innych atrybutów
- Sekcja "Atrybuty wizualne" z opisem atrybutów odpowiadających za wygląd
- 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
- Sekcja "Dostępne zdarzenia" z listą zdarzeń języka JavaScript przypisanych do znacznika
- Może pojawić się sekcja "Zdarzenia niestandardowe" z łączami do zdarzeń wspieranych przez niektóre przeglądarki
Gdy w artykule odwołujemy się do znacznika (opisywanego bądź innego), możemy używać albo formy Nazwaznacznika, albo <nazwaznacznika> (na przykład Hr albo <hr> - należy pamietać o tagu <plain> przy zapisie tego typu).
Znaczniki przestarzałe możemy oznaczać stosując szablon { {Template:Tag_deprecated}} (Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!) wstawiający taki tekst:
Znacznik ten ma status Deprecated w HTML 4.01/XHTML 1.0, a w wersjach Strict tych języków już nie istnieje! Nie należy więc go używać.
Znaczniki przestarzałe należy także dodać do kategorii (X)HTML/Deprecated.
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.
Uwaga! Sekcja może znajdować się pod opisem znacznika lub na samym końcu artykułu.
Atrybuty
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 (X)HTML/Atrybuty/. W Wypadku gdy atrybut może mieć tylko kilka wartości, w artykule o znaczniku nie należy ich wymieniać, a przenieść je 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 artykułu (do sekcji "Główne atrybuty"!) za pomocą szablonu:
{ {Template:Atrybuty_dla_CSS}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
Podobnie mogą być wstawiane inne atrybuty, także dostępne praktycznie dla każdego znacznika, czyli Lang, Dir i Title, poprzez:
{ {Template:Atrybuty_podstawowe}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
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 od XML.
Atrybuty wizualne
Przy opisie atrybutów wizualnych należy zaznaczyć, że są one przestarzałe, na przykład stosując taki szablon:
<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:
{ {Template:Attr_notstandard|nazwa_znacznika}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
Uwaga!
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 wysoce niezalecane i powoduje niezgodność strony z zadeklarowanym typem dokumentu.
Zdarzenia
By wstawić listę zdarzeń do artykułu o znaczniku można użyć szablonu:
{ {Template:Zdarzenia_HTML}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
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:
{ {Template:tag_close|nazwa_znacznika}}
Uwaga! Ograniczenia techniczne - pomiędzy znakami { nie ma spacji!
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:
Uwaga!
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.
Przykład użycia
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 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).
Przy zapisywaniu przykładów użycia korzystamy z poprawnego języka XHTML, należy pamiętać o zapisaniu poprawnego Doctype jeśli przykład wymaga podania całości dokumentu HTML (wraz tagiem początkowym).
Nie wolno pisać znaczników bez zamknięcia, nawet jeśli ono w HTML-u nie jest wymagane, nie wolno zapisywać wartości atrybutów poza znakami cudzysłowu bądź apostrofu. Znaczniki piszemy małymi literami.
Kod przykładu powinien być między znacznikami <code=html4strict> </code>, dzięki którym dodawane jest kolorowanie składni.
Kategoryzacja
W dziale XHTML 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.
Jeżeli nie wiesz na przykład, czy uznać znacznik za semantyczny, nie dodawaj do kategorii, inni użytkownicy poprawią artykuł.
Opis atrybutu
(nieustalone)
Dostępne szablony
Przy opisie atrybutów można zastosować następujące szablony:
{ {Template:null_attr|atrybut}}
Uwaga!
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>
{ {Template:Attr_deprecated}}
Uwaga!
Atrybut ten jest oznaczony jako 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.
Atrybut ten jest oznaczony jako 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.
Opis zdarzenia
(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.
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
W dziale (X)HTML trzeba było poprawiać wiele artykułów, bo nie dość szybko powstały spójne zasady ich tworzenia. Aby uniknąć takiej sytuacji, chciałbym zaproponować takie zasady juz na samym początku tworzenia działu CSS.
Tą sekcje można traktować jako propozycje, jeżeli nie zgadzasz sie z tymi zasadami, zaproponuj inne.
Początek opisu polecenia
Na początku artykułu opisującego polecenie należy krótko zdefiniować jego rolę.
Następnie należy dokładnie opisać jego funkcje. Jeśli polecenia ma kilka funkcji, każdą należy wymienić po nagłówku <h3>.
Do wypisania możliwych wartości polecenia stosuj listę nie uporządkowaną.
Polecenia pokrewne
Po takim nagłówku <h2> "Polecenia pokrewne" należy na liście nieuporządkowanej wymienić polecenia CSS, bardzo podobne do opisywanego. Np dla font będą to font-size, font-family itd.
Odpowiednik HTML
Tutaj wypisuje się ewentualne tagi lub atrybuty HTML które działają podobnie jak opisywane polecenie CSS. W razie potrzeby należy zaznaczyć ze 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 sie 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 MSIE, Operze i 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ło by też zaznaczyć ewentualne "dziwactwa" jakie serwują nam poszczególne przeglądarki (wiadomo ze nawet nowoczesne przeglądarki miejscami odbiegają od standardu obsługi CSS). Taka informacja dla uczących sie CSS może być bardzo przydatna.
Pseudolementy i pseudoklasy
Nie ustalono.
Stałe wartości które przyjmują polecenia (np. none, hidden, inline)
Nie ustalono.
Powtarzające się teksty, szablony
Jeżeli jakieś polecenie definuje kolor, nalezy wstawić przy nim szablon:
{ {Template:css_color}}
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(r, g, b), 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
Zasady redagowania - C sharp
Sekcja opisuje zasady pisania artykułów w dziale C sharp. Są one skrócone do absolutnego minimum aby ułatwić użytkownikom edycję artykułów, jednak z uwagi na ogrom języka należy przestrzegać poniższych wytycznych.
Cele
Dział C sharp 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ć, z uwagi na ciężkie rozbicie tych dwóch światów).
Opis elementów języka
Ważna rzeczą podczas tworzenia artykułów jest wskazanie informacji od jakiej wersji języka C sharp 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:
{ {Template:C_sharp_version|3.0}}
Uwaga! Ograniczenia techniczne, pomiędzy znakami { nie ma spacji!
Informacja o wersji zostanie automatycznie dodana (w przykładzie wersja 3.0).
Stary i nieużywany dział Podręcznik
W starej wersji działu został stworzony osobny dział o nazwie Podręcznik. W obecnej formie dział ten nie występuje, a z czasem 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!
no i "przykład uzycia" cały czas był drugą sekcją, a tu nagle powendrował na 7 miejce
http://4programmers.net/Artykuły_do_zrobienia (TeWuX)
http://4programmers.net/WinAPI/MessageBox (N00byStance)
to mnie trzęsie
ale my, nie piszący w delphi jesteśmy sobie sami winni
//ja pisałem w Delphi wieki temu.. ale szybko znalazłem coś lepszego
Przykład: http://4programmers.net/C_shar[...]strukcje_steruj%C4%85ce/return
Nie ma czegoś takiego w C/C++/C# jak Return - jest za to return.
Delphi zezwala na różną wielkość liter przez co każdy pisze jak chce - w językach pochodnych składni C [przeogromna większość] wielkość liter jest narzucona dzięki czemu kody źródłowe są klarowne bo każdy musi pisać tak samo - więc nie powinniśmy tutaj tego zmieniać!
[i tak wiem, że to zostanie odrzucone bo Delphi rlz.....]
Ogólnie art jest spox