Pomoc » Artykuły

Formatowanie tekstu

System Coyote udostępnia mechanizmy dzięki którym prostsze staje się formatowanie tekstu w tworzonych artykułach. Jeżeli planujesz edycję tekstów umieszczonych na łamach serwisu, proszę przeczytaj dokładnie ten dokument! Opisuje on zasady, standardy oraz zawiera wskazówki dla użytkowników.

Spis treści

     1 Metody formatowania
          1.1 Dozwolone znaczniki XHTML
          1.2 Formatowanie Coyote
               1.2.1 Tworzenie linków
                    1.2.1.1 Linki zewnętrzne
               1.2.2 Pogrubienie
               1.2.3 Kursywa
               1.2.4 Podkreślenie
               1.2.5 Przekreślenie
               1.2.6 Rozdziały
                    1.2.6.1 Spisy treści
               1.2.7 Przypisy
               1.2.8 Listy
               1.2.9 Linia pozioma
               1.2.10 Wstawianie obrazków i załączników
               1.2.11 Kolorowanie składni
               1.2.12 Indeksy górne i dolne
               1.2.13 Zmienne
               1.2.14 Kod wyprowadzany z klawiatury
          1.3 Formatowanie HTML
               1.3.1 Definicje, wskazówki
     2 Znacznik Plain
     3 Znacznik Nobr
     4 Szablony
          4.1 Parametry szablonów
          4.2 Formatrowanie TeX
     5 Podsumowanie


Metody formatowania


Mechanizm Coyote udostępnia w zasadzie dwa mechanizmy formatowania: przy pomocy kodu XHTML oraz za pomocą unikalnej specyficznej składni, która ma ułatwić formatowanie. Zalecane jest korzystanie z mechanizmu Coyote'a, chyba, że naprawdę niezbędne jest użycie formatowania XHTML.

Dostępne są podstawowe znaczniki XHTML wraz z paroma podstawowymi atrybutami. Zabronione jest używanie kodu JavaScript. Podobną funkcjonalność zapewnia forum dyskusyjne. Tzn., że tam również, w większości - możemy używać składni Coyote.

Dozwolone znaczniki XHTML


Dozwolone są znaczniki <a> (z atrybutem href), <b>, <i>, <u>, <del>, <tt>, <kbd>, <sam>, <var>, <dfn>, <ins>, <pre>, <blockquote>, <hr>, <sub>, <sup>,  <h1> z atrybutem style, <h2>, <h3>, <h4>, <h5>, <h6>, <table> z atrybutem style oraz class, <tbody>, <thead>, <tfooter>, <th> z atrybutem style i class, <tr> z atrybutem style i class, <td> z atrybutem style oraz class, <div> z atrybutem style i class, <span> z atrybutem style oraz class, <br>, <ul> z atrybutem style, <li> z atrybutem style, <ol> z atrybutem style

Formatowanie Coyote


System udostępnia mechanizmy, dzięki którym można tworzyć spisy treści, przypisy, wypunktowania itp. Składnia Coyote'a jest parsowana w momencie wyświetlania artykułu.

Tworzenie linków


Bardzo ważne jest tworzenie linków do artykułów w serwisie. Pozwala to użytkownikowi na łatwiejszą nawigację pomiędzy stronami. Linki tworzone są przy pomocy znaków [[ oraz ]] - np. [[Delphi/Begin]] spowoduje utworzenie odnośnika do artykułu Begin w kategorii Delphi: Begin. Bardzo ważne jest podawanie dokładnej ścieżki do tekstu. Wszystko dlatego, że artykuł Begin może istnieć zarówno w kategorii Delphi jak i Turbo Pascal.

Odnośniki, które wskazują na nieistniejącą stronę są kolorowane na pomarańczowo, natomiast, te które są prawidłowe, są zaznaczane na zielono. Kliknięcie na link prowadzący do nieistniejącej strony spowoduje przekierowanie do strony 404, gdzie znajduje się link, dzięki któremu nieistniejącą stronę można utworzyć.

Odnośnikom można nadawać etykiety, wpisując je jako atrybut odnośnika - np. [[Regulamin|Kliknij, aby przeczytać regulamin]] da następujący efekt: Kliknij, aby przeczytać regulamin.

Linki zewnętrzne


Jeżeli chcemy umieścić w tekście odnośnik do linka zewnętrznego (znajdującego się na innym serwerze), wpisujemy po prostu adres w tekście - np. http://forum.4programmers.net. Adres automatycznie zostanie przekształcony na odnośnik.

Możemy także skorzystać ze znacznika <url> dzięki któremu możemy ustawić etykietę odnośnika - np.: <url=http://forum.4programmers.net>Kliknij, aby wejść na forum</url>.

Rezultat: Kliknij, aby wejść na forum

Pogrubienie


Mimo, że znacznik <b> jest dostępny w systemie, to pogrubienie tekstu można łatwo osiągnąć stosując podwójny znak gwiazdki (*) - np. **lorem ipsum** spowoduje wyświetlenie tekstu w ten sposób: lorem ipsum.

Kursywa


Pochylenie tekstu łatwo osiągnąć otaczając go podwójnym znakiem slasha - tzn. //lorem ipsum// da: lorem ipsum.

Podkreślenie


Podkreślenie tekstu (underline) realizuje taki kod: __foo__: foo

Przekreślenie


W serwisie 4programmers.net włączony jest znacznik <del>, tak więc przekreślenie można realizować w ten sposób: <del>foo</del>: foo.

Rozdziały


W przypadku większych tekstów, bardzo zalecane jest używanie znaczników h1, h2 itp. w celu tworzenia rozdziałów i podrozdziałów. Równie dobrze, można do tego celu wykorzystać składnie Coyote:


= Rozdział główny =



treść



== Podrozdział ==



=== Sekcja ===



== Rozdział drugi ==


Taka składnia jest zamieniana odpowiednio na znaczniki: h1, h2, h3...

Spisy treści


Na podstawie nagłówków możliwe jest wygenerowanie spisu treści. Jeżeli chcemy, aby spis treści był wyświetlany na stronie musimy w treści artykułów umieścić frazę {{CONTENT}} co da efekt:

Spis treści

     1 Metody formatowania
          1.1 Dozwolone znaczniki XHTML
          1.2 Formatowanie Coyote
               1.2.1 Tworzenie linków
                    1.2.1.1 Linki zewnętrzne
               1.2.2 Pogrubienie
               1.2.3 Kursywa
               1.2.4 Podkreślenie
               1.2.5 Przekreślenie
               1.2.6 Rozdziały
                    1.2.6.1 Spisy treści
               1.2.7 Przypisy
               1.2.8 Listy
               1.2.9 Linia pozioma
               1.2.10 Wstawianie obrazków i załączników
               1.2.11 Kolorowanie składni
               1.2.12 Indeksy górne i dolne
               1.2.13 Zmienne
               1.2.14 Kod wyprowadzany z klawiatury
          1.3 Formatowanie HTML
               1.3.1 Definicje, wskazówki
     2 Znacznik Plain
     3 Znacznik Nobr
     4 Szablony
          4.1 Parametry szablonów
          4.2 Formatrowanie TeX
     5 Podsumowanie


Przypisy


Czasami przydatna jest funkcja tworzenia przypisów w tekście. Aby utworzyć przypis należy w odpowiednim miejscu umieścić frazę [#]_ co spowoduje umieszczenie odnośnika 1
W odpowiednim miejscu strony można umieścić objaśnienie przypisu:

.. [#] Objaśnienie nr 1

Efekt:

[1] Objaśnienie nr 1

Listy


W wielu przypadkach przydatna jest możliwość tworzenia list: wypunktowanej oraz numerowanej. Oczywiście w takich przypadkach możemy skorzystać ze znaczników Ol, Ul i Li. Łatwiej jednak będzie skorzystać ze składni Coyote'a. Tworzenie listy numerowanej odbywa się w następujący sposób:


# pozycja
# druga pozycja
## wcięcie
### wcięcie
## kolejna pozycja
# koniec


Identycznie wygląda tworzenie list wypunktowanych. W takim wypadku zamiast znaku # należy użyć *. Rezultat:

  1. pozycja
  2. druga pozycja
    1. wcięcie
      1. wcięcie
    2. kolejna pozycja
  3. koniec

Uwaga! Aby lista zadziałała, znak # lub * musi być pierwszym znakiem w linii.

Linia pozioma


Linię poziomą można stosować jeżeli chcemy przedzielić tekst. Oczywiście można skorzystać ze znacznika Hr jak i wstawic w tekst fraze: ____


Proszę pamiętać jednak, że taka fraza musi znaleźć się w nowej linii.

Wstawianie obrazków i załączników


Przypuśćmy, że chcemy wstawić do tekstu obrazek wcześniej wysłany na serwer. Można to zrobić korzystając ze znacznika Img, lecz dużo prościej będzie skorzystanie ze specjalnej frazy systemu wyglądającej tak: {{Image:coyote.jpg}}. Jako przykład weżmy obrazek Image:coyote.jpg. Podwójne klamry oznaczają zagnieżdżenie jakiegoś elementu w tekście. Czy jest to obrazek, plik czy szablon. Oto efekt użycia wspomnianego znacznika:



Znacznikowi można nadawać atrybuty określające atrybut alt oraz rozmiar miniatury. Przykładowo, aby nadać obrazowi tekst zastępczy (atrybut alt) należy użyć takiego kodu: {{Image:coyote.jpg|Tytuł obrazka}}. Jak widzisz, atrybuty są rozdzielane znakiem |. Pierwszy atrybut oznacza tytuł obrazka (wyświetlany w dymku po naprowadzeniu kursora). Efekt:

Tytuł obrazka

Inny atrybut, jaki możemy nadać to rozmiar miniatury. Jako przykład weźmy obrazek boduch_pies.jpg który jest dosyć spory, bo ma rozdzielczość 1250x858. Jeżeli chcemy, aby zmieścił się na ekranie, możemy określić jego rozmiar: {{Image:boduch_pies.jpg|Pies|200}}. Ostatni parametr określa szerokość dokumentu w pikselach (w tym wypadku - 200px). Rezultat:

Pies

Idea załączania innych plików do tekstu, jest bardzo podobna: {{File:Word.zip}} da efekt: Word.zip (10,73 KB)

Kolorowanie składni


W tekstach o charakterze programistycznym, często należy umieszczać fragmenty kodu. Wówczas należy umieścić ów kod pomiędzy znacznik code. Przykład:

<code=php>

/*

* Funkcja get_time: podaje czas co do milisekundy

*/

function get_time()

{

$mtime = split(' ', microtime());

return ($mtime[1] + $mtime[0]);

}

</code>

Oczywiście w znaczniku należy podać nazwę języka. Dostępne jest 36 modułów kolorowania składni różnych języków. Oto efekt powyższego kodu:

  /*
   * Funkcja get_time: podaje czas co do milisekundy
   */
  function get_time()
  {
      $mtime = split(' ', microtime());
      return ($mtime[1] + $mtime[0]);
  }


Indeksy górne i dolne


Przykład: wpisując m,,2,, i m^2^ otrzymasz: m2 i m2.

Zmienne


Bardzo zalecane jest używanie znacznika <var> celem podkreślenia, iż dana fraza to zmienna. Oczywiście zostanie ona odpowiednio przez przeglądarkę, wyróżniona. Innym powodem, dla którego warto stosować ten znacznik, to eksport do XML. Prostsze jest użycie składni Coyote - @@zmienna@@, która zamienia dany kod na następujący: @@zmienna@@.

Kod wyprowadzany z klawiatury


Kolejny styl, z jakiego powinno się korzystać. Aby zaznaczyć, że dany fragment jest poleceniem systemowym, czy jakimkolwiek innym tekstem wyprowadzanym z klawiatury, należy skorzystać ze składni: ''lorem ipsum lores'' lub `lorem ipsum lores`, które są zamieniane odpowiednio na znacznik <tt> oraz <kbd>.

Przykład: `mysql --user=root --password=root`
Rezultat: mysql --user=root --password=root

Bardzo istotne jest, iż wewnątrz tych znaczników nie jest przeprowadzane żadne formatowanie. Tak więc nie jest brany pod uwagę również kod XHTML, który jest dozwolony w "normalnych" warunkach. Tzn.:

''**lorem ipsum** http://adam.boduch.net <b>foo</b>''

da:

**lorem ipsum** http://adam.boduch.net <b>foo</b>

co w "normalnych" warunkach będzie wyglądało tak:

lorem ipsum http://adam.boduch.net foo


Formatowanie HTML


Aby "upiększyć" nasz artykuł można stosować znaczniki (X)HTML. W szczególności chciałbym zwrócić uwagę na kilka z nich. Mianowicie - położenie tekstu. W tym celu możemy korzystać ze znacznika <div> lub <span>. Przykład:

To jest tekst wyśrodkowany

To jest tekst wyrównany do prawej


Parser systemu zamienia te znaczniki na odpowiedniki zgodne ze standardem XHTML .

Definicje, wskazówki


Jeżeli umieszczamy w tekście ważne informacje, wskazówki warte do zapamiętania, prosimy o skorzystanie ze znacznika <dfn>. Przykład:

Oto jest definicja, warta do zapamiętania informacja. Prosimy - używaj znacznika Dfn.

Wskazówka: skrót klawiaturowy to Alt+D.

Znacznik Plain


Mechanizm formatowania systemu Coyote nie działa w obrębie znaczników: <code> oraz <plain> oraz w <kbd> i <tt>. Na pewno czasami będziesz chciał, aby dane frazy nie były interpretowane przez nasz system. W takim wypadku, umieść tekst pomiędzy znacznik plain.

Uwaga! W obrębie znacznika plain, kod (X)HTML nie jest przetwarzany! Również łamanie linii nie działa w sposób "normalny". Dopiero podwójny znak enter łamie linię.

Znacznik Nobr


Często, formatując kod (X)HTML używamy wcięć do tego, aby kod ów był czytelniejszy. Nasz system w trakcie procesu parsowania tekstu, zamienia znaki nowej linii na znacznik - <br />, w miejsce podwójnej spacji wstawia  . Aby wyłączyć tę opcję, należy skorzystać ze znacznika <nobr>. W jego obrębie znaki nowej linii oraz spacji są ignorowane.

Szablony


Szablony stanowią bardziej zaawansowaną funkcję systemu Coyote. Wyobraź sobie, że w wielu artykułach, w wielu miejscach musisz umieścić taką ramkę:


Strona w budowie
Ktoś właśnie pracuje nad tą stroną, prosimy o cierpliwość



Ok. Teraz wyobraź sobie, że chcesz zmienić kod tej ramki, np. zmienić kolor obramowania. Wówczas musisz edytować każdy tekst, w którym umieściłeś ów kod. Ten problem pozwolą rozwiązać szablony.

Szablony to zwykłe strony. Takie artykuły mogą być następnie włączane do innych tekstów. A robi się to przy pomocy następującej frazy:

{{Template:W budowie}}

Taki kod zostanie zastąpiony szablonem o nazwie W budowie, który znajduje się pod adresem: W budowie. W jednym tekście może znajdować się wiele takich odwołań do szablonów.

Parametry szablonów


Do szablonów można przekazywać parametry, podobnie jak do funkcji i procedur w języku programowania. Na potrzeby tego artykułu utworzyłem szablon o nazwie Testowy szablon. Zawartość tego szablonu prezentuje się następująco:



To jest testowy szablon. Parametry przekazane przez artykuł to: {{1}} i {{2}}

Zwróć uwagę na frazy {{1}} i {{2}}. Zostaną one zastąpione wartościami parametrów przekazanych szablonu. Parametry możemy przekazać w ten sposób:

{{Template:Testowy szablon|parametr nr 1|parametr nr 2}}

Rezultat:



To jest testowy szablon. Parametry przekazane przez artykuł to: parametr 1 i parametr 2

Formatrowanie TeX


Zarówno w artykułach, jak i na forum dostępny jest znacznik <tex>, który umożliwia formatowanie składni TeX-a. Na przykład:

<tex>arcctg(x) = argtan(\frac{1}{x}) = arcsin(\frac{1}{\sqrt{1+x^2}})</tex>

spowiduje wyświetlenie:

arcctg(x) = argtan(\frac{1}{x}) = arcsin(\frac{1}{\sqrt{1+x^2}})

Podsumowanie


Jak powiedzieliśmy, w artykułach możliwe jest stosowanie większości znaczników (X)HTML. Dodatkowo nasz system rozszerza tę pulę o kilka dodatkowych znaczników, które są odpowiednio interpretowane w trakcie generowania strony (i oczywiście - zamieniane na poprawny kod (X)HTML). Tabela poniżej prezentuje krótki opis każdego z nich.

ZnacznikOpis
<wiki>Umożliwia wstawienie linku do wikipedii - np. <wiki>Programowanie</wiki>
<image>Umożliwia wstawienie w danym miejscu obrazka: <image>http://4programmers.net/obrazek.jpg</image>
<email>Umożliwia wstawienie adresu e-mail, który zostanie przekształcony na klikalny adres
<url>Umożliwia wstawienie klikalnego odnośnika - np.: <url>http://4programmers.net</url>
<quote>Znacznik wykorzystywany na forum. Ustawia styl CSS prezentujący cytat (tylko na forum)
<plain>Pomiędzy tym znacznikiem system nie dokona żadnego formatowania
<nobr>Pomiędzy tym znacznikiem nie będą wstawiane znaki nowej linii

17 komentarzy

Sebo 2007-11-09 10:38

A co z tex'em do formatowania wyrażeń matematycznych??

Misiekd 2006-06-03 18:25

to ja jeszcze w sprawie aktualizacji tego arta - dajcie tu spis wszystkich znaczników bo się trzeba połowy domyślać :P. Nie musi być kilku linijkowy opis - dwa, trzy słowa o każdym wystarczą a z czasem będzie można rozszeżyć opis

Adam Boduch 2006-01-31 11:09

Tak, dokladnie. Zreszta - ten znacznik jest rzadko uzywany :/ Nawet nie jest parsowany z <font> na <span> (font jest niezgodny ze specyfikacja XHTML). Zastanawiam sie czy w ogole nie zrezygnowac z tego.

Misiekd 2006-01-30 19:51

a to ja mam takie pytanko w edycji jest piękny guziczek "Ustaw kolor textu" - czy to celowe, że zawsze koloruje text na czerwono i inny kolor trzeba ręcznie wpisywać?

brodny 2006-01-25 18:33

I link do zakładki dodać - bo dalej nie wiem, czy da się za pomocą http://4programmers.net/ ;)

Deti 2006-01-16 22:31

Dokładnie tak .. np. zamiast żaróweczki jakiś inny znaczek.. albo bez znaczka aby nie dawać kolejnej grafiki - czesto zdarza się możliwość dodania jakiejś ciekawostki, zagadnienia, zagadki .. niektórzy dają przypis, inni jakiś tekst zielony (Marooned) .. ale można dać szablon. - taki tylko pomysł wymyslony ot tak.

Adam Boduch 2006-01-16 19:54

Hmm... a wiecej informacji? To mialoby wygladac jak styl CSS znacznika <dfn> ? Mialoby sie tam umiesczac jakies ciekawe informacje odnosnie danego hasla, tak?

Deti 2006-01-16 18:53

Proponuje dodanie szablonu "Ciekawostka"

Marooned 2006-01-08 15:23

Aby parametr 'box' dla kolorowania składni działał również na IE można wykorzystać to:
http://www.doxdesk.com/software/js/minmax.html

brodny 2005-12-29 12:04

Da się jakoś utworzyć link do zakładki przy pomocy http://4programmers.net/?

Marooned 2005-12-21 14:32

Nie chwaląc się to moja sprawka [GeSHi] :>

Tego BOXa trza by jakoś przekombinować, bo póki co nie działa na IE ;)

angel2953 2005-12-20 11:40

widzę, że GeSHi działa doskonale :P:P

prgtw 2005-12-20 01:34

czyżbym widział skrypt GeSHi ;)

Adam Boduch 2005-12-19 21:32

Parametr Box tez oczywiscie jest :) Uzupelnie dokumentacje w najblizszym czasie.

Marooned 2005-12-19 20:08

yy, a kto ukradł parametr BOX dla kolorowania składni?

Adam Boduch 2005-12-21 17:15

Włączyłem magic url. Mam nadzieje ze nie bedzie mialo to zadnego zlego wplywu :) Dodalem takze opis, dot. tworzenia linkow zewnetrznych.

Ktos 2005-12-21 16:59

E, a jak jest z linkami zewnętrznymi? Bo jak dam http://4programmers.net/ to mi będzie próbowało stworzyć artykuł o takim tytule jak link.

Dalej <url> zostaje?