Formatowanie tekstu artykułu

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 i standardy formatowania; zawiera także wskazówki dla użytkowników.

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.2 Spisy treści
          1.2.7 Listy
          1.2.8 Linia pozioma
          1.2.9 Wstawianie obrazków i załączników
          1.2.10 Kolorowanie składni
          1.2.11 Indeksy górne i dolne
          1.2.12 Kod wyprowadzany z klawiatury
     1.3 Formatowanie HTML
          1.3.13 Definicje, wskazówki
     1.4 Formatrowanie TeX
2 Podsumowanie

Metody formatowania

Mechanizm Coyote udostępnia w zasadzie dwa sposoby formatowania: (1) przy pomocy kodu XHTML oraz (2) przy pomocy unikalnej specyficznej składni Coyote, 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: tam również – w większości wypadków – możemy używać składni Coyote.

Dozwolone znaczniki XHTML

Dozwolone są następujące znaczniki: <a> (z atrybutem href), <b>, <i>, <u>, <del>, <kbd>, <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 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 innej strony internetowej (znajdującej się na innym serwerze), wpisujemy po prostu adres tej strony w tekście – np. Forum dyskusyjne. Adres automatycznie zostanie przekształcony na odnośnik.

Możemy także skorzystać ze znacznika <a>, dzięki któremu możemy ustawić etykietę odnośnika. Przykład: <a href="http://4programmers.net/Forum">Kliknij, aby wejść na forum</a>; rezultat: Kliknij, aby wejść na forum

Pogrubienie

Niezależnie od tego, że znacznik <b> jest dostępny w systemie, pogrubienie tekstu można także osiągnąć stosując podwójny znak gwiazdki (*). Przykładowo **lorem ipsum** spowoduje wyświetlenie tekstu w ten sposób: lorem ipsum.

Kursywa

Pochylenie tekstu łatwo osiągnąć otaczając go pojedynczym znakiem *. Przykładowo *lorem ipsum* da: lorem ipsum.

Podkreślenie

Podkreślenie tekstu (underline) realizuje taki kod: <u>foo</u>; rezultat: 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>; rezultat: foo.

Rozdziały

W przypadku większych tekstów bardzo zalecane jest używanie znaczników <h1>, <h2> itd. w celu tworzenia rozdziałów i podrozdziałów. Równie dobrze można do tego celu wykorzystać składnię 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} } (bez spacji). Da to efekt podobny do poniższego:

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.2 Spisy treści
          1.2.7 Listy
          1.2.8 Linia pozioma
          1.2.9 Wstawianie obrazków i załączników
          1.2.10 Kolorowanie składni
          1.2.11 Indeksy górne i dolne
          1.2.12 Kod wyprowadzany z klawiatury
     1.3 Formatowanie HTML
          1.3.13 Definicje, wskazówki
     1.4 Formatrowanie TeX
2 Podsumowanie

Listy

W wielu przypadkach przydatna jest możliwość tworzenia list: wypunktowanej oraz numerowanej. Oczywiście możemy skorzystać ze znaczników Ol, Ul i Li. Łatwiej jednak będzie skorzystać ze składni Coyote. Tworzenie listy numerowanej odbywa się w poprzez poprzedzenie następujących po sobie linii znakiem - lub *. Przykład:

- pozycja
- druga pozycja
 - wcięcie
   - wcięcie 
 - kolejna pozycja
- koniec

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

Identycznie wygląda tworzenie list wypunktowanych. W takim wypadku zamiast wyżej wymienionych znaków należy użyć cyfr. Rezultat:

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

Linia pozioma

Linię poziomą można stosować, jeżeli chcemy przedzielić tekst. Oczywiście można skorzystać ze znacznika Hr jak i wstawić w tekst frazę: ---. Przykład:


Proszę pamiętać jednak, że taka fraza musi znaleźć się w nowej linii i musi być oddzielona pustą linią od poprzedzającego i kolejnego paragrafu.

Wstawianie obrazków i załączników

Przypuśćmy, że chcemy wstawić do tekstu obrazek (który wcześniej wysłaliśmy na serwer). Można to zrobić korzystając ze znacznika Img; jednak dużo prościej będzie skorzystanie ze składni Markdown. Przykład: ![coyote.jpg](//static.4programmers.net/uploads/attachment/4ccd36d6997cb.jpg); rezultat:

coyote.jpg

Idea załączania innych plików do tekstu jest bardzo podobna. Przykład: [Word.zip](//4programmers.net/Download/1558/53); rezultat: word.zip

Kolorowanie składni

W tekstach o charakterze programistycznym często umieszcza się fragmenty kodu. Taki fragment należy umieścić pomiędzy znacznikami ```. Przykład:

  /*
   * Funkcja get_time: podaje czas co do milisekundy
   */
  function get_time()
  {
      $mtime = split(' ', microtime());

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

Zalecane jest, by, jeśli to możliwe, podawać nazwę języka, jakim dany kod jest napisany; należy to robić tak: ```php. Dostępne jest 36 modułów kolorowania składni różnych języków. ```php da rezultat:

  /*
   * 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.

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 użyć tzw. backticka (czyli odwróconego apostrofu: `). 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 HTML, który jest dozwolony w "normalnych" warunkach. Przykład:

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

Rezultat: **lorem ipsum** http://adam.boduch.net <b>foo</b>; w "normalnych" warunkach będzie to 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. Po pierwsze – położenie tekstu. W tym celu możemy korzystać ze znacznika <div> lub <span>. Przykłady:

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.

Formatrowanie TeX

Zarówno w artykułach, jak i na forum dostępny jest znacznik %%%%, który umożliwia formatowanie składni TeX-a. Przykład:</p> <p>%%<tex>arcctg(x) = argtan(\frac{1}{x}) = arcsin(\frac{1}{\sqrt{1+x^2}})%%

Rezultat:

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

17 komentarzy

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

Dalej <url> zostaje?

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

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

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

czyżbym widział skrypt GeSHi ;)

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

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

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

Da się jakoś utworzyć link do zakładki przy pomocy ?

Proponuje dodanie szablonu "Ciekawostka"

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

I link do zakładki dodać - bo dalej nie wiem, czy da się za pomocą ;)

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ć?

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

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

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

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.

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