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.

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 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>, <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'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. 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 - np.: <a href="http://4programmers.net/Forum">Kliknij, aby wejść na forum</a>.

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 pojedyńczym znakiem * - tzn. *lorem ipsum* da: lorem ipsum.

Podkreślenie

Podkreślenie tekstu (underline) realizuje taki kod: <u>foo</u>: 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} } (bez spacji) co da efekt:

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 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ć cyfr. Rezultat:

  1. pozycja
  2. druga pozycja
    1. wcięcie
    2. wcięcie
    3. 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 i musi być oddzielona od poprzedzającego i kolejnego paragrafu, pustą linią.

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 z markdown: ![coyote.jpg](//static.4programmers.net/uploads/attachment/4ccd36d6997cb.jpg).

coyote.jpg

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

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 ```. Przykład:

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

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

Oczywiście w znaczniku należy podać nazwę języka (np. ```php). Dostępne jest 36 modułów kolorowania składni różnych języków. Dla powyższego kodu będzie to:

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

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

Formatrowanie TeX

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

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

17 komentarzy

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

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

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

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.

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

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

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

Proponuje dodanie szablonu "Ciekawostka"

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

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

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

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

czyżbym widział skrypt GeSHi ;)

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

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

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

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?