Formatowanie artykułów i komentarzy

Ten artykuł opisuje formatowanie artykułów i komentarzy w Kompendium.

***

System Coyote udostępnia mechanizmy, dzięki którym prostsze staje się formatowanie tekstu w tworzonych artykułach. Jeżeli planujesz modyfikację tekstów umieszczonych w serwisie 4programmers.net (dalej w skrócie: "Serwis"), proszę: przeczytaj dokładnie ten dokument! Opisuje on zasady i standardy formatowania; zawiera także wskazówki dla użytkowników.

     1 Dostępne metody formatowania
     2 Linki
          2.1 Linki wewnętrzne Serwisu
          2.2 Linki zewnętrzne
     3 Pogrubienie
     4 Kursywa
     5 Podkreślenie
     6 Przekreślenie
     7 Rozdziały
     8 Spisy treści
     9 Listy
     10 Linia pozioma
     11 Wstawianie obrazków i załączników
     12 Kolorowanie składni
     13 Indeksy górne i dolne
     14 Kod wyprowadzany z klawiatury
     15 Położenie tekstu
     16 Formatowanie TeX
     17 Dostępna składnia języka Markdown
     18 Dostępne elementy HTML

Dostępne metody formatowania

System Coyote udostępnia trzy sposoby formatowania:

przy pomocy języka XHTML,
przy pomocy języka Markdown,
przy pomocy składni własnej systemu Coyote.

Zalecane jest korzystanie z języka Markdown oraz składni systemu Coyote, 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.

Linki

Linki wewnętrzne Serwisu

Linki wewnętrzne Serwisu tworzone są przy pomocy znaków [[ oraz ]]. Przykładowo użycie formatowania

[[Delphi/Begin]]

spowoduje utworzenie linku do strony z artykułem "Begin" w kategorii "Delphi" w Kompendium:

Begin

Należy podać pełną ścieżkę, ponieważ artykuł "Begin" może istnieć zarówno w kategorii Delphi, jak i w kategorii Turbo Pascal.

Linki, 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 formularza tworzenia tej strony.

Linkom można nadawać etykiety, wpisując je jako atrybut. Przykładowo użycie formatowania

[[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 link do jakiejkolwiek strony internetowej – czy to w ramach Serwisu, czy znajdującej się na innym serwerze – wpisujemy po prostu adres tej strony w tekście. Adres automatycznie zostanie przekształcony na link. Przykład:

http://4programmers.net/Forum

Rezultat:

Forum dyskusyjne

Możemy także skorzystać ze znacznika HTML <a>; możemy dzięki niemu ustawić dodatkowo etykietę linku. 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 HTML <b> jest dostępny, pogrubienie tekstu można także osiągnąć stosując podwójny znak gwiazdki (**). Przykładowo takie formatowanie:

**lorem ipsum**

spowoduje wyświetlenie tekstu w ten sposób:

lorem ipsum

Kursywa

Kursywę, czyli pochylenie tekstu, można osiągnąć otaczając tekst pojedynczym znakiem gwiazdki (*). Przykładowo takie formatowanie:

*lorem ipsum*

da:

lorem ipsum

Podkreślenie

Podkreślenie tekstu może zostać zrealizowane za pomocą znacznika HTML <u>. Przykładowo formatowanie:

<u>foo</u>

da:

foo

Przekreślenie

W Serwisie włączony jest znacznik HTML <del>, tak więc przekreślenie można realizować w ten sposób:

<del>foo</del>

Rezultat:

~~foo~~

Rozdziały

Rozdziały można tworzyć, korzystając ze znaczników HTML <h1>, <h2>, …, <h6>. Równie dobrze można do tego celu wykorzystać język Markdown; w tym wypadku jednak nagłówek poziomu pierwszego nie jest interpretowany (trzeba zaczynać od nagłówka poziomu drugiego).

Przykłady:

## Nagłówek poziomu drugiego

Treść

<h1>Nagłówek poziom pierwszego</h1>

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}}. Da to efekt podobny do poniższego:

Listy

W wielu przypadkach przydatna jest możliwość tworzenia list: wypunktowanej oraz numerowanej. Możemy skorzystać zarówno ze znaczników `<ol>`, `<ul>` i `<li>`, jak i z języka Markdown. W języku Markdown tworzenie listy numerowanej odbywa się poprzez poprzedzenie następujących po sobie linii znakiem - lub *. Przykład:

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

Rezultat:

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

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

Linia pozioma

Linię poziomą można stosować, jeżeli chcemy przedzielić tekst. Można zarówno skorzystać ze znacznika `<hr>`, jak i wstawić w tekst frazę ---. Przykład:

---

Rezultat:

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

Wstawianie obrazków i załączników

Przypuśćmy, że chcemy wstawić do tekstu obrazek (który wcześniej został wysłany na serwer). Można to zrobić korzystając zarówno ze znacznika `<img>`, jak i ze składni Markdown. Przykład dla składni Markdown:

![coyote.jpg](//static.4programmers.net/uploads/attachment/4ccd36d6997cb.jpg)

Rezultat:

Idea załączania innych plików do tekstu jest bardzo podobna (dostępne jedynie w składni Markdown):

[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]);
  }
```

Rezultat:

  /*
   * 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. Dostępne jest 36 modułów kolorowania składni różnych języków. Przykładowo użycie

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

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

a<sub>2</sub>
b<sup>2</sup>

otrzyma się odpowiednio

a₂
b²

Kod wyprowadzany z klawiatury

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

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 byłby interpretowany, gdyby nie użyć tych znaczników). Przykład:

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

Rezultat:

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

Bez użycia tych znaczników ten sam tekst wygląda tak:

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

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 zamienia te znaczniki na odpowiedniki zgodne ze standardem XHTML.

Formatowanie TeX

Zarówno w artykułach, jak i na forum dostępny jest znacznik <tex>, który umożliwia formatowanie za pomocą składni systemu TeX. Przykład:

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

Rezultat:

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

Dostępna składnia języka Markdown

** oraz __
* oraz _
~~
##, ###, ####, ##### oraz ######
[etykieta](adres URL linku)
![etykieta](adres URL obrazka)
``
``` oraz ```nazwa_języka, a także ~~~ oraz ~~~nazwa_języka

Dostępne elementy HTML

<a> z atrybutem href
<b>
<i>
<u>
<del>
<kbd>
<dfn>
<pre>
<blockquote>
<hr>
<sub>
<sup>
<h1> z atrybutem style
<h2>
<h3>
<h4>
<h5>
<h6>
<table> z atrybutami style oraz class
<tbody>
<thead>
<tfooter>
<th> z atrybutami style i class
<tr> z atrybutami style i class
<td> z atrybutami style i class
<div> z atrybutami style i class
<span> z atrybutami style i class
<br>
<ul> z atrybutem style
<li> z atrybutem style
<ol> z atrybutem style

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 (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ą ;)

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 ? Mialoby sie tam umiesczac jakies ciekawe informacje odnosnie danego hasla, tak?