TypeFriendly 0.1

Copyright © Invenzzia Group 2008-2009
Dostępne na licencji: GNU Free Documentation License 1.2
Wygenerowano: 02.05.2010

Spis treści

Spis treści
1. Przedmowa
2. Instalacja
Następny »

1. Przedmowa

TypeFriendly to program narzędziowy napisany w PHP5 przeznaczony do generowania i publikowania tekstów w formacie HTML takich, jak dokumentacje projektów, podręczniki użytkownika, artykuły czy inne dłuższe publikacje. Został napisany tak, aby być prostym w obsłudze oraz aby rezultaty można było osiągnąć już w kilka minut po rozpoczęciu pracy. TypeFriendly domyślnie zawiera wszystko, co niezbędne, do stworzenia dokumentacji, dzięki czemu nie trzeba wyważać otwartych drzwi.

Najważniejsze cechy TypeFriendly:

  1. Modularna budowa dokumentacji - dokument wynikowy generowany jest ze zwykłych plików tekstowych, a jego układ i zależności między rozdziałami automatycznie ustalane na podstawie nazw tych plików.
  2. Prosta składnia - rozdziały można pisać w niezwykle prostym i czytelnym formacie Markdown.
  3. Wsparcie dla publikacji wielojęzycznych - TypeFriendly umożliwia równoległe tworzenie publikacji w kilku językach, a także udostępnia narzędzia ułatwiające prace, takie jak porównywanie wersji językowych.
  4. Konfigurowalne formaty wyjściowe - aktualnie TypeFriendly potrafi generować dane w dwóch formatach: XHTML - wiele stron i XHTML - jedna strona.
  5. Różne dodatki przydatne przy dokumentowaniu kodu: kolorowanie składni, referencje, zależności między klasami...
  6. Łatwe tworzenie nawigacji.
  7. Pracuje pod Linuksem i Windowsem.

TypeFriendly dostępny jest na licencji GNU General Public License 3, co oznacza, że możesz go nie tylko używać za darmo, ale także modyfikować i dostosowywać do własnych celów.

Spis treści
2. Instalacja
1. Przedmowa
« Poprzedni
3. Tworzenie własnej publikacji
Następny »

2. Instalacja

TypeFriendly jest narzędziem napisanym w PHP5 obsługiwanym z wiersza poleceń systemu operacyjnego. Aby móc z niego korzystać, musisz posiadać zainstalowane PHP 5.2 z obsługą trybu wiersza poleceń (CLI).

Instalacja PHP

PHP jest popularnym skryptowym językiem programowania wykorzystywanym powszechnie do tworzenia dynamicznych stron internetowych. Jest jednak wykorzystywany również do tworzenia tradycyjnych aplikacji. W tym rozdziale krótko opiszemy, jak zainstalować PHP na własnym komputerze.

Jeśli jesteś programistą PHP, interpreter powinien już być zainstalowany na Twoim komputerze. W tym przypadku pozostaje Ci tylko sprawdzić, czy Twoja instalacja posiada obsługę interfejsu wiersza poleceń.

System Windows

Binarne wersje PHP 5.2 dla systemu Windows są dostępne do ściągnięcia w formie archiwów ZIP ze strony www.php.net. Rozpakuj ściągnięte archiwum ZIP gdzieś na dysk twardy, np. C:\php\. Właściwie to już jest wszystko, jednak póki co korzystanie z interpretera będzie dość niewygodne, gdyż będziesz musiał podawać pełną ścieżkę dostępu do pliku php.exe. Aby usunąć tę nieprzyjemność, musisz dodać C:\php do zmiennej środowiskowej PATH w Twoim systemie.

Otwórz Panel sterowania i uruchom aplet System. W zakładce Zaawansowane wybierz przycisk Zmienne środowiskowe. W nowo otwartym oknie, w sekcji Zmienne środowiskowe znajdź zmienną PATH, zaznacz ją i kliknij przycisk Edytuj, aby zmodyfikować jej wartość. Po znaku średnika ; dopisz ścieżkę do katalogu z PHP, np.

...;C:\php\

Zapisz wszystko i zamknij panel sterowania.

Systemy uniksowe

Instalacja PHP jest dużo prostsza w systemach uniksowych, ponieważ najczęściej wyposażone są one w rozmaite narzędzia do zarządzania pakietami. Przykładowo, w Debian Linux możesz zainstalować PHP z konsoli przy pomocy następujących poleceń:

apt-get install php5-common
apt-get install php5-cli

Szczegółowe polecenia do Twojej dystrybucji mogą być inne, dlatego musisz zajrzeć do jej dokumentacji po dokładne instrukcje.

Zazwyczaj pakiety PHP są odpowiednio skonfigurowane tak, żeby nie trzeba było modyfikować zmiennej środowiskowej PATH.

Testowanie instalacji

Aby przetestować swoją instalację PHP, otwórz konsolę (w Windowsie: wiersz poleceń) i wpisz:

php --version

Jeśli zobaczysz wynik podobny do poniższego, oznacza to, że wszystko zostało prawidłowo zainstalowane.

PHP 5.2.10RC2-dev (cli) (built: May 27 2009 18:48:36)
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2009 Zend Technologies

Instalacja TypeFriendly

Ściągnij najnowszą wersję TypeFriendly ze strony www.invenzzia.org i rozpakuj ją gdzieś na swoim dysku twardym. Właściwie jest to już wszystko, o ile PHP jest poprawnie zainstalowane. Uruchom wiersz poleceń i przejdź do katalogu z TypeFriendly poleceniem cd:

cd /sciezka/do/TypeFriendly

Aby przetestować instalację, spróbuj zbudować podręcznik użytkownika do samego TypeFriendly dołączony do instalacji:

php typefriendly.php build "./docs/"

Użytkownicy systemów uniksowych mogą także przetestować skróconą formę, o ile ścieżka do interpretera w ich systemie to /usr/bin/php:

./typefriendly build "./docs/"

TypeFriendly powinien teraz przebudować swój własny podręcznik, a wygenerowany wynik powinien być dostępny w katalogu ./docs/output/.

Spis treści
3. Tworzenie własnej publikacji
2. Instalacja
« Poprzedni
3.1. Struktura katalogowa
Następny »

3. Tworzenie własnej publikacji

W tym rozdziale opiszemy, jak stworzyć swoją własną publikację.

Ręczne tworzenie

W następnych rozdziałach zakładamy, że chcesz utworzyć nową publikację ręcznie. Cały proces jest dość prosty i trwa tylko kilka minut. Jeśli używasz TypeFriendly po raz pierwszy, zalecamy rozpoczęcie swej przygody właśnie od tego, aby zapoznać się z budową wersji źródłowej publikacji.

Kreator nowych publikacji

Od wersji 0.1.2 TypeFriendly udostępnia kreator nowych publikacji uruchamiany z wiersza poleceń. Kreator samodzielnie tworzy całą niezbędną strukturę katalogów w podanym folderze, używając domyślnych szablonów oraz dostarczonych przez Ciebie informacji. Aby uruchomić kreator, stwórz nowy, pusty katalog i uruchom następującą komendę:

php typefriendly.php create "/path/to/directory"

TypeFriendly zada Ci kilka pytań dotyczących nowego projektu, a następnie utworzy wszystkie wymagane pliki.

3. Tworzenie własnej publikacji
3.1. Struktura katalogowa
3. Tworzenie własnej publikacji
« Poprzedni
3.2. Plik settings.ini
Następny »

3.1. Struktura katalogowa

Publikacja TypeFriendly musi mieć odpowiednią strukturę katalogową. Utwórz gdzieś na dysku twardym nowy, pusty folder - my oznaczymy go przez /, a w nim dodaj następujące podkatalogi:

/input
    /pl
/output
/sort_hints.txt
/settings.ini

Zasady są bardzo proste: w katalogu /input znajdują się podkatalogi reprezentujące poszczególne wersje językowe, a w nich umieszczamy charakterystyczne dla każdej z nich pliki tekstowe. W /output TypeFriendly będzie zapisywać wygenerowaną wersję HTML dokumentów, dlatego upewnij się, że nadałeś mu uprawnienia do zapisu. Bezpośrednio w głównym katalogu zapisywane są pliki z ustawieniami, w których możesz wpływać na różne aspekty publikacji. Najważniejszym z nich jest settings.ini zawierający ustawienia główne. sort_hints.txt zawiera wskazówki dotyczące kolejności rozdziałów. Dokładna budowa każdego z plików wyjaśniona jest dalej.

Opcjonalnie, każdy katalog z wersją językową może zawierać dwa dodatkowe foldery: /input/JEZYK/media oraz /input/JEZYK/templates do przechowywania:

Zostaną one omówione dalej.

3. Tworzenie własnej publikacji
3.2. Plik settings.ini
3.1. Struktura katalogowa
« Poprzedni
3.3. Rozdziały
Następny »

3.2. Plik settings.ini

Jest to główny plik konfiguracyjny z listą opcji. Jak sama nazwa pliku wskazuje, jest to typowa składnia plików INI:

opcja1 = "wartosc1"
opcja2 = "wartosc2"
opcja3 = "wartosc3"
; komentarz

Znak średnika rozpoczyna komentarz, który ciągnie się aż do końca linii.

Podstawowe opcje, jakie należy ustawić, to:
title
tytuł publikacji
version
wersja publikacji
copyright
prawa autorskie do publikacji
license
licencja, na jakiej udostępniana jest publikacja
projectType
rodzaj publikacji
dostępne wartości: manual (domyślna), documentation, article, book
Dodatkowe opcje:
copyrightLink
odnośnik do strony posiadacza praw autorskich
licenseLink
odnośnik do strony z treścią licencji
Opcje techniczne związane z projektem:
outputs
lista formatów, w jakich chcesz generować dokumentację, odseparowanych przecinkami.
baseLanguage
dla każdej publikacji musi zostać wybrany podstawowy język, w którym powstaje oryginalna treść. Tutaj możesz go ustawić. Ważne, aby nazwa pokrywała się z nazwą katalogu, w którym znajduje się wersja publikacji w tym języku.
navigation

określa sposób łączenia stron w pasku nawigacyjnym "Poprzedni/Następny". Dozwolone wartości to:

tree
linki "Poprzedni" i "Następny" zawsze wskazują na sąsiada danego rozdziału. Jeżeli sąsiad nie istnieje, link nie jest wyświetlany. Jest to domyślna wartość.
book
rozdziały są tak łączone, aby klikając "Poprzedni" lub "Następny" można było przejść całą publikację (jak w książce).
showNumbers
czy włączyć numerowanie rozdziałów (wartości true lub false).
versionControlInfo
czy wyświetlać wartości tagów dotyczących systemu kontroli wersji? (domyślnie false)

Przykładowy plik konfiguracyjny, który służy do wygenerowania tego podręcznika, wygląda następująco:

; Opcje podstawowe
 
title = "TypeFriendly"
version = "0.1"
copyright = "Invenzzia Group 2008-2009"
copyrightLink = "http://www.invenzzia.org/"
license = "GNU Free Documentation License 2.1"
licenseLink = "http://www.gnu.org/licenses/fdl.html"
projectType = "manual"
 
; Ustawienia wyświetlania itd...
 
outputs = "xhtml, xhtml_single"
baseLanguage = "en"
navigation = "book"
showNumbers = true
3. Tworzenie własnej publikacji
3.3. Rozdziały
3.2. Plik settings.ini
« Poprzedni
3.4. Składnia pliku
Następny »

3.3. Rozdziały

W TypeFriendly poszczególne rozdziały dokumentacji tworzysz jako pliki tekstowe w katalogu /input/jezyk/. Każdy taki plik składa się z dwóch części:

  1. Nagłówek
  2. Treść

W nagłówku znajduje się kilka opcji, które pozwalają ustawić np. właściwy tytuł danego rozdziału lub powiązania z innymi częściami dokumentacji. Pod nagłówkiem umieszczana jest treść w formacie Markdown. Dokładny opis składni tych plików znajduje się dalej, gdyż tutaj pragniemy omówić inną rzecz związaną z rozdziałami, mianowicie ustalanie ich kolejności.

W każdej publikacji rozdziały ułożone są w pewnym, określonym porządku i mogą zawierać dodatkowe podrozdziały. Niekiedy pragniemy nadać im alfabetyczną kolejność, np. gdy podrozdziały są indeksem dostępnych funkcji. W innych przypadkach, będziemy chcieli, aby czytelnik zapoznawał się z rozdziałami w żądanym przez nas porządku, gdyż późniejsze rozdziały mogą bazować na informacjach podanych w tych początkowych. TypeFriendly pozwala osiągnąć wszystkie te efekty.

Pliki rozdziałów wykorzystują rozszerzenie *.txt, natomiast pozostała część nazwy używana jest do określenia zależności między rozdziałami. Każdy rozdział ma swój własny identyfikator zbudowany z liter, cyfr, pauz i podkreśleń. Aby zaznaczyć, że B i C są podrozdziałami A, dodajemy identyfikator rozdziału A do B i C, a obie części oddzielamy kropką. Poniżej przedstawiamy przykładową listę rozdziałów:

  1. wstep.txt
  2. instalacja.txt
  3. instalacja.prosta.txt
  4. instalacja.zlozona.txt
  5. api.txt
  6. api.klasa.txt
  7. api.klasa.funkcja1.txt
  8. api.klasa.funkcja2.txt
  9. api.interfejs.txt
  10. api.interfejs.funkcja1.txt
  11. api.interfejs.funkcja2.txt

Przyjrzyjmy się np. rozdziałowi poświęconemu instalacji. Jest stworzony plik tekstowy dla niego, w którym możemy zamieścić jakieś wprowadzenie. Jednocześnie umieszczamy w nim dwa podrozdziały: instalacja.prosta i instalacja.zlozona. TypeFriendly na podstawie nazw pliku powiąże jedno z drugim i wygeneruje odpowiednią nawigację. Opis API jest już bardziej złożony, ponieważ mamy tutaj aż trzy poziomy. Po słowie wstępu w pliku api.txt tworzymy wprowadzenie do opisu pierwszej z klas (api.klasa.txt). Klasa ma jakieś funkcje, tak więc opisujemy każdą z nich jako osobny podrozdział. Pamiętaj, że jeżeli chcesz stworzyć plik o nazwie foo.bar.joe.txt, w dokumentacji muszą również istnieć foo.txt i foo.bar.txt - inaczej TypeFriendly zwróci błąd.

Domyślnie TypeFriendly sortuje poziomy zagnieżdżeń alfabetycznie:

  1. api.txt
  2. api.interfejs.txt
  3. api.interfejs.funkcja1.txt
  4. api.interfejs.funkcja2.txt
  5. api.klasa.txt
  6. api.klasa.funkcja1.txt
  7. api.klasa.funkcja2.txt
  8. instalacja.txt
  9. instalacja.prosta.txt
  10. instalacja.zlozona.txt
  11. wstep.txt

Jest to trochę bez sensu, ponieważ o ile super, że funkcje są sortowane automatycznie, o tyle wstęp na końcu publikacji może już wzbudzić u czytelników zdumienie. Aby zmienić kolejność, musimy w głównym katalogu publikacji utworzyć plik sort_hints.txt z paroma wskazówkami:

wstep
instalacja
instalacja.prosta
instalacja.zlozona
api
api.klasa
api.interfejs

Plik zawiera listę rozdziałów w żądanym przez nas porządku. Zauważ, że nie wymieniliśmy tu wszystkich plików. Jeśli w jakimś poziomie zagnieżdżeń pasuje nam alfabetyczna kolejność, po prostu nie wymieniamy tych podrozdziałów na liście (np. nie wypisaliśmy tutaj żadnych funkcji z api.klasa i api.interfejs).

Musisz albo określić kolejność wszystkich podrozdziałów na danym poziomie, albo nie określać jej w ogóle. Jeżeli wymienisz tylko część podrozdziałów, TypeFriendly zgłosi błąd.

Wskazówki:

  1. Plik ze wskazówkami jest jeden dla wszystkich języków, dlatego bardzo ważne jest, aby w każdej wersji językowej odpowiadające sobie rozdziały miały tę samą nazwę pliku.

  2. Nazwa pliku jest też wykorzystywana do identyfikowania rozdziałów przy tworzeniu ręcznym odnośników w tekście. Dlatego wybieraj nazwy krótkie i intuicyjne, trzymając się jakichś reguł. Ułatwi to późniejsze odnalezienie się w tym wszystkim.

  3. TypeFriendly pomija pliki z innym rozszerzeniem lub kończące się np. tyldą, tak więc nie trzeba wyłączać opcji tworzenia kopii zapasowej w edytorze, aby tworzyć publikację.

Zobacz także:

3. Tworzenie własnej publikacji
3.4. Składnia pliku
3.3. Rozdziały
« Poprzedni
3.4.1. Wprowadzenie
Następny »

3.4. Składnia pliku

Przykładowy plik rozdziału wygląda następująco:

Title: Tytuł
Opcja1: Wartość
Opcja2: Wartość
ListaUstawień:
 - Wartość 1
 - Wartość 2

---

Treść rozdziału

W ustawieniach umieszczamy kolejne znaczniki w sposób pokazany powyżej. Obowiązkowy jest Title, ale jest też kilka innych. Właściwie ich lista zależy bardziej od tego, w jakim formacie wyjściowym będziemy generować dokumentację. Można bardzo łatwo opracować własny i zacząć używać tam nowe znaczniki - zostanie to omówione dalej.

Treść nagłówka od właściwej treści rozdziału rozdzielamy co najmniej trzema pauzami --- otoczonymi pojedynczymi pustymi linijkami.

Do formatowania treści rozdziału używana jest składnia "PHP Markdown Extra" z paroma rozszerzeniami i modyfikacjami. Spotkać się z nią można na wielu stronach internetowych, ponieważ parsery są publicznie dostępne, stąd istnieje szansa, że już ją znasz. Gdyby jednak nie, odwiedź stronę jednego z parserów (np. tę podaną powyżej), by dowiedzieć się więcej. W następnych rozdziałach szczegółowo została opisana składnia tego języka oraz wyszczególnione zostały drobne modyfikacje zastosowane w TypeFriendly.

Zobacz także:

3.4. Składnia pliku
3.4.1. Wprowadzenie
3.4. Składnia pliku
« Poprzedni
3.4.2. Akapity i tekst
Następny »

3.4.1. Wprowadzenie

Markdown został stworzony, by być zarówno łatwy w użyciu, jak i przyjazny w czytaniu plików źródłowych. Pliki źródłowe dokumentacji TypeFriendly mogą dzięki temu służyć za pomoc nawet bez przepuszczenia ich przez generator. Przyjęte jest założenie, że znaki formatujące powinny jak najmniej rzucać się w oczy czytelnikowi i mieć zbliżone zastosowanie do tego, jakiego już się używa np. w poczcie elektronicznej czy plikach README. Zauważyć można też podobieństwa do składni reStructuredText. Oprócz podstawowego formatowania, do użytku dopuszczony jest także HTML i modyfikacje TypeFriendly czasem z tego faktu korzystają. W kolejnych rozdziałach opisane zostały szczegółowo wszystkie elementy tego języka.

TypeFriendly korzysta z bardziej rozbudowanej składni Markdown Extra, której rozwojem zajmuje się Michel Fortin.

TypeFriendly jako podstawę swojego parsera źródeł rozdziałów korzysta z oryginalnego parsera Michela Fortina o nazwie PHP Markdown Extra. Do kolejnych wydań TypeFriendly zamieszczać będziemy najaktualniejsze jego wersje.

Dokładna specyfikacja języka Markdown jest cały czas w trakcie opracowywania i do języka mogą dojść nowe elementy i rozwiązania. Autorzy planują zachować kompatybilność wsteczną.

3.4. Składnia pliku
3.4.2. Akapity i tekst
3.4.1. Wprowadzenie
« Poprzedni
3.4.3. Wyróżnienia
Następny »

3.4.2. Akapity i tekst

Akapit to jedna - bądź więcej, następujących po sobie - linijki tekstu. Osobne akapity oddzielone są jedną, bądź więcej pustą linijka. (Pusta linijka, jak sama nazwa wskazuje, nie może zawierać nic prócz spacji lub tabulacji.) Akapity nie powinny mieć wcięć spacjami na początku.

Litwo! Ojczyzno moja! Ty jesteś jak zdrowie. Ile cię stracił. Dziś piękność twą w Litwie chodził po całym domu lasami i Rzeczpospolita! Zawżdy z jakich rąk strzelby, którą powinna młodź dla żony przy Bernardynie, bernardyn zmówił krótki pacierz wieczorny, pomału usnął ostatni w ręku trzyma obyczajem pańskim i żywot Katona.

Dalej w ulicę się dowie kto gości wysoko siadł pomiędzy nim wiedzą, lekce go kaznodzieją, że tamuje progresy, że przeszkadza kulturze, że nam się ta chwała należy chartu Sokołowi.

Pytano zdania innych. więc będzie jego bok usiadła owa piękność twą w szklankę panny Róży a potem Sędzia z tych łąk zielonych szeroko nad błękitnym Niemnem rozciągnionych.

Litwo! Ojczyzno moja! Ty jesteś jak zdrowie. Ile cię stracił. Dziś piękność twą w Litwie chodził po całym domu lasami i Rzeczpospolita! Zawżdy z jakich rąk strzelby, którą powinna młodź dla żony przy Bernardynie, bernardyn zmówił krótki pacierz wieczorny, pomału usnął ostatni w ręku trzyma obyczajem pańskim i żywot Katona.

Dalej w ulicę się dowie kto gości wysoko siadł pomiędzy nim wiedzą, lekce go kaznodzieją, że tamuje progresy, że przeszkadza kulturze, że nam się ta chwała należy chartu Sokołowi.

Pytano zdania innych. więc będzie jego bok usiadła owa piękność twą w szklankę panny Róży a potem Sędzia z tych łąk zielonych szeroko nad błękitnym Niemnem rozciągnionych. 1

Akapit może składać się z następujących po sobie linijek, które nie zostaną złamane w tekście wyjściowym przez <br />. Oznacza to, że możemy formatować tekst, tak, jak jest to robione np. w tekstowych mailach.

Litwo! Ojczyzno moja! Ty jesteś jak zdrowie. Ile cię stracił. 
Dziś piękność twą w Litwie chodził po całym domu lasami i Rzeczpospolita! 
Zawżdy z jakich rąk strzelby, którą powinna młodź dla żony przy 
Bernardynie, bernardyn zmówił krótki pacierz wieczorny, pomału usnął 
ostatni w ręku trzyma obyczajem pańskim i żywot Katona.

Mimo tego, że powyższy tekst ma 5 linijek, zostanie on zamieniony na pojedynczy akapit, bez złamań wierszy:

Litwo! Ojczyzno moja! Ty jesteś jak zdrowie. Ile cię stracił. Dziś piękność twą w Litwie chodził po całym domu lasami i Rzeczpospolita! Zawżdy z jakich rąk strzelby, którą powinna młodź dla żony przy Bernardynie, bernardyn zmówił krótki pacierz wieczorny, pomału usnął ostatni w ręku trzyma obyczajem pańskim i żywot Katona.

Aby zrobić zwykłe przełamanie linijki, należy zakończyć ją dwoma lub więcej spacjami i przejść do nowej linijki.

W poniższym przykładzie spacje na końcu linijek zastąpione zostały znakiem podkreślenia _ aby pokazać ich umiejscowienie
Litwo!__
Ojczyzno moja!__
Ty jesteś jak zdrowie.

Litwo!
Ojczyzno moja!
Ty jesteś jak zdrowie.

Znaki specjalne: >, < i &

Składnia markdown umożliwia wstawianie bezpośrednio do tekstu znaczników języka HTML, co zostało opisane w następnych rozdziałach. Wymaga więc specjalnego traktowania znaków > < & w przypadku, gdy nie używamy ich do wstawiania znaczników HTML.

W HTML-u jeśli np. chcesz napisać np o muzyce R&B musisz posłużyć się tzw. kodami ucieczki HTML, badź encjami i napisać R&amp;B. Co więcej, musisz również w podobny sposób zapisywać nawet adresy URL, w których występuje znak &!

Szukaj <a href="http://images.google.com/images?num=30&amp;q=beata+kozidrak">zdjęć</a>

Parser Markdown jest jednak na tyle inteligentny, że potrafi z kontekstu odczytać, który znak należy zamienić na encję, a który nie. Jeśli więc chcesz wstawić znak praw autorskich ©, możesz zapisać go normalną encją HTML: &copy;.

Ale jeśli zechcesz jednak pisać o tej muzyce R&B, Markdown automatycznie zamieni & na encję:

Muzyka R&B

Choć Markdown wspiera wstawianie znaczników HTML-a bezpośrednio do treści, możesz bez obaw napisać prawdę matematyczną, że:

4 < 5

A znak < zostanie zamieniony na odpowienik encji: &lt;. Podobnie ma się sytuacja z >, którego encją jest &gt;.

Poziome linie

Można wstawić poziomą linię oddzielającą (<hr />) umieszczając co najmniej trzy gwiazdki *, pauzy - lub podkreślenia _ obok siebie w linijce. Opcjonalnie możesz rozdzielić spacją te znaki.

* * *

***

*****

- - -

---------------------------------------

  1. Tekst wygenerowany przez Generator Lorem Ipsum ↩

3.4. Składnia pliku
3.4.3. Wyróżnienia
3.4.2. Akapity i tekst
« Poprzedni
3.4.4. Wstawki kodu
Następny »

3.4.3. Wyróżnienia

Markdown do pogrubiania i pochylania tekstu wykorzystuje znaki gwiazdki * oraz podkreślenia _ przed i po fragmencie, który chcemy sformatować. Fragment tekstu otoczony jednym znakiem * lub _ zostanie pochylony HTML-owym znacznikiem <em>. Podwójne użycie tych znaków wstawi znacznik <strong> i pogrubi tekst.

*pojedyncze gwiazdki*  
_pojedyncze podkreślenia_

**podwójne gwiazdki**  
__podwójne podkreślenia__

pojedyncze gwiazdki
pojedyncze podkreślenia

podwójne gwiazdki
podwójne podkreślenia

Możesz użyć którego znaku chcesz, jednym wymogiem jest użycie tego samego znaku do otworzenia i zamknięcia wyróżnienia.

Jeśli chcesz, aby fragment był i pogrubiony, i pochylony, użyj trzech znaków.

***potrójne gwiazdki***

potrójne gwiazdki

Wyróżnienia możesz użyć również wewnątrz słowa:

Litwo*Ojczyzno*Moja

LitwoOjczyznoMoja

Powyższa reguła stosuje się jedynie do gwiazdek. Znaki podkreślenia wyróżnią tekst tylko jeśli odnoszą się do całego słowa, możesz więc bez obaw pisać:

Użyj funkcji mysql_escape_string

Jeśli otoczysz _ lub * przez pojedyncze spacje, tekst nie zostanie sformatowany, a znaki potraktowane po prostu jak gwiazdki lub podkreślenia.

Gdy nie chcesz, by wstawione _ lub * przed i po fragmencie zostały potraktowane jako wyróżnienie, wystarczy poprzedzić je znakiem backslashu \:

\*ten tekst jest otoczony zwykłymi gwiazdkami\*

*ten tekst jest otoczony zwykłymi gwiazdkami*

3.4. Składnia pliku
3.4.4. Wstawki kodu
3.4.3. Wyróżnienia
« Poprzedni
3.4.5. Nagłówki
Następny »

3.4.4. Wstawki kodu

W tej dokumentacji już pewnie kilkakrotnie widziałeś tekst o stałej szerokości na żółtym tle wstawiony bezpośrednio do akapitu. Tworzy się go wykorzystując znak odwróconego apostrofu ` przed i po fragmencie, który chcemy sformatować.

Użyj funkcji `print()` by wyświetlić tekst.

Użyj funkcji print() by wyświetlić tekst.

Jeśli we wstawianym tekście także występują odwrócone apostrofy, do włączenia formatowania można użyć podwojonego odwróconego apostrofu.

``Ten tekst zawiera odwrócony apostrof (`) w środku``

Ten tekst zawiera odwrócony apostrof (`) w środku

Jeśli odwrócony apostrof znajduje się na początku lub końcu kodu, wystarczy oddzielić go spacją.

Pojedynczy odwrócony apostrof: `` ` ``

Ciąg tekstu otoczony odwróconymi apostrofami: `` `coś` ``

Pojedynczy odwrócony apostrof: `

Ciąg tekstu otoczony odwróconymi apostrofami: `coś`

Umieszczone we wstawce znaki <, > oraz & automatycznie zamieniane są na encje, a znaczniki HTML w nich nie są przetwarzane.

Wpisanie:
Nigdy nie używaj znacznika `<blink>`.
Da nam:

Nigdy nie używaj znacznika <blink>.

Zobacz także:

3.4. Składnia pliku
3.4.5. Nagłówki
3.4.4. Wstawki kodu
« Poprzedni
3.4.6. Linki
Następny »

3.4.5. Nagłówki

Markdown obsługuje dwa systemy wstawiania nagłówków: Setext oraz atx. Tak jak akapity, są one elementami blokowymi, co znaczy, że do oddzielenia od innych elementów blokowych (listy, akapity, bloki kodu) stosuje się co najmniej jedną pustą linijkę.

Notacja Setext

W notacji Setext, nagłówki zostają "optycznie" podkreślone znakami równości = (nagłówek pierwszego rzędu) lub pauz - (nagłówek drugiego rzędu).

Nagłówek 1
==========

Nagłówek 2
----------

Ilość znaków = lub - nie ma znaczenia, może służyć jedynie celom estetycznym.

Notacja atx

Druga metoda pozwala wstawić nagłówki wszystkich rzędów, przy użyciu od jednego do sześciu znaków krzyżyka (hashu) # przed treścią nagłówka.

# nagłówek 1

## nagłówek 2

##### nagłówek 5

Dopuszczalne jest też zamknięcie nagłówka tymi samymi znakami. Służy to jedynie celom estetycznym, a ilość znaków po nagłówku nie musi się zgadzać z ilością przed nagłówkiem.

# nagłówek 1 #

## nagłówek 2 ####

##### nagłówek 5 #

W stosunku do oryginalnego parsera Markdowna, w TypeFriendly poczynione zostały zmiany, które obniżają w generowanym wyjściu XHTML poziom nagłówka o jeden. Ma to związek z tym, że tytuł artykułu jest zawsze najważniejszy, i to on zyskuje znacznik <h1>. Wpisany w kod nagłówek pierwszego rzędu zostanie zamieniony na nagłowek drugiego rzędu, drugiego na trzeciego itd. Oznacza to, że choć Markdown (i HTML) udostępnia 6 poziomów nagłówków, to w TypeFriendly dostępnych jest ich 5.

Przykładowe nagłówki:

Nagłówek 1

Nagłówek 2

Nagłówek 3

Nagłówek 4
Nagłówek 5

Kotwice w nagłówkach

Nagłówki umożliwiają stworzenie kotwic, dzięki który będzie można odnieść się z innych części dokumentacji do wybranego fragmentu rozdziału.

Znacznik wygląda następująco: {#kotwica}. Umieszcza się go po tekście nagłówka w notacji setext lub na końcu linijki w notacji atx.

Nagłówek {#kotwica}
========

### Nagłówek ### {#kotwica}

##### Nagłówek {#kotwica}

Aby identyfikatory nagłówków były unikalne w obrębie dokumentacji, TypeFriendly dodaje do nich prefiks: h:id_rodziału:, dlatego odwołanie się bezpośrednio do kotwicy w linku: [odnośnik](#kotwica) nie zadziała.

3.4.6. Linki

Markdown pozwala wstawiać linki do innych stron na trzy sposoby: bezpośrednio liniowo w tekście, poprzez referencję oraz automatycznie.

Dwa pierwsze sposoby korzystają z nawiasów kwadratowych [ ] do otoczenia fragmentu tekstu, który ma stać się linkiem.

Bezpośrednio w tekście

By wstawić odnośnik bezpośrednio w tekście wystarczy wstawić zwykłe nawiasy bezpośrednio po kwadratowych. Możesz również podać opcjonalnie tytuł linku (umieszczony zostanie w atrybucie title w HTML-u wyjściowym) po spacji, otoczony cudzysłowami.

TypeFriendly zostało stworzone przez [grupę Invenzzia](http://www.invenzzia.org)

TypeFriendly zostało stworzone przez [grupę Invenzzia](http://www.invenzzia.org "Invenzzia")

TypeFriendly zostało stworzone przez grupę Invenzzia

TypeFriendly zostało stworzone przez grupę Invenzzia

Poprzez referencje

Referencja do odnośnika używa również nawiasów kwadratowych, które umieszczamy tuż po nawiasach nazwy linku. W referencji podaje się nazwę etykiety do której później można się odnieść. Można opcjonalnie oddzielić spacją referencję od nazwy linku.

To jest [przykład][id] linków z referencją.

To jest [przykład] [id] linków z referencją.

Definicja referencji wygląda następująco:

[id]: http://www.example.org/ "Opcjonalny tytuł"

Są to kolejno:

  1. Nawiasy kwadratowe, w których umieszczona jest nazwa etykiety referencji
  2. Dwukropek
  3. Co najmniej jedna spacja lub tabulacja
  4. Adres URL, do którego odnosi się referencja
  5. Opcjonalnie, po spacji, bądź w nowej linijce wcięty spacjami lub tabulacją, otoczony cudzysłowami, apostrofami lub nawiasami tytuł linku

Poniższe linijki oznaczają to samo:

[id]: http://www.example.org/ 'Opcjonalny tytuł'
[id]: http://www.example.org/ (Opcjonalny tytuł)
[id]: http://www.example.org/ 
      "Opcjonalny tytuł"

Możesz również opcjonalnie otoczyć link nawiasami kierunkowymi (< >):

[id]: <http://www.example.org/>

Definicje referencji używane są tylko przez parser Markdowna i wycinane z treści wynikowego dokumentu.

Etykiety referencji mogą się składać z liter, cyfr, spacji, znaków interpunkcyjnych, ale nazwa nie zależy od wielkości liter.

Poniższe linijki odnoszą się do tej samej referencji:

[tekst odnośnika][a]
[tekst odnośnika][A]

Można również pominąć nazwę etykiety, poprzez umieszczenie pustych nawiasów klamrowych [] - wtedy za etykietę przyjęta zostaje nazwa odnośnika.

Możesz np. napisać:

[Invenzzia][]

I utworzyć definicję:

[Invenzzia]: http://www.invenzzia.org

W podobny sposób można tworzyć referencje nawet do nazw linków składających się z kilku słów!

[Grupa Invenzzia][]

[Grupa Invenzzia]: http://www.invenzzia.org

Definicje referencji mogą być umieszczone gdziekolwiek w dokumencie, oddzielone od elementów blokowych (akapity, listy..) pustymi linijkami. Można je umieścić np. pod akapitem, w którym zostały użyte referencje, albo na końcu dokumentu.

Przykład użycia referencji:
Mamy 10 razy więcej ruchu z wyszukiwarki [Google][1] niż z [Netsprint][2] lub [Onet][3].

W rzeczywistości, [Google][1] jest najpopularniejszą wyszukiwarką.

 [1]: http://www.google.pl
 [2]: http://www.netsprint.pl
 [3]: http://szukaj.onet.pl
Z użyciem automatycznych etykiet:
Mamy 10 razy więcej ruchu z wyszukiwarki [Google][] niż z [Netsprint][] lub [Onet][].

 [google]:    http://www.google.pl
 [netsprint]: http://www.netsprint.pl
 [onet]:      http://szukaj.onet.pl

Po co używać referencji?

Tekst źródłowy staje się dzięki temu czytelniejszy. Linki umieszczone są w osobnych linijkach pod akapitami i nie mieszają się z tekstem (szczególnie te bardzo długie).

Automatycznie

Markdown umożliwia również wstawienie bezpośrednio linków do tekstu w bardzo prosty sposób, przy użyciu nawiasów kierunkowych < >, w których umieszczony zostaje link.

Zajrzyj na naszą stronę: <http://www.invenzzia.org/>

Zajrzyj na naszą stronę: http://www.invenzzia.org/

W podobny sposób można postąpić a adresami e-mail. W tym przypadku jednak parser Markdown zamieni je w wyjściowym HTML-u na "sieczkę" HTML-owych encji.

Adres kontaktowy: <kontakt@example.org>

Adres kontaktowy: kontakt@example.org

Odnośniki do pozostałych rozdziałów dokumentacji

TypeFriendly definiuje listę domyślnych referencji do wszystkich rozdziałów generowanej dokumentacji przy użyciu ich identyfikatorów. Jeżeli chcemy odnieść się do rozdziału api.klasy.jakas-klasa wystarczy napisać:

Zajrzyj do [tego rozdziału][api.klasy.jakas-klasa]

Spowoduje to automatyczne utworzenie linku do żądanego rodziału.

Od wersji 0.1.3 TypeFriendly można odnosić się do kotwic w innych rozdziałach.

Składnia jest taka sama jak normalnie do rozdziału, dodaje się tylko po identyfikatorze odnośnik kotwicy: #kotwica:

Zajrzyj do [tego fragmentu rozdziału][api.klasy.jakas-klasa#kotwica]

Aby odnieść się do kotwicy w tym samym rozdziale nadal należy stosować powyższą składnię i nie używać [odnośnik](#kotwica). Jest tak z powodu tego, że TypeFriendly do każdej kotwicy nagłówka dodaje prefiks h:id_rodziału:, tak, aby kotwice były unikalne w całej dokumentacji.

3.4. Składnia pliku
3.4.7. Grafika i obrazki
3.4.6. Linki
« Poprzedni
3.4.8. Listy porządkowe
Następny »

3.4.7. Grafika i obrazki

Wstawianie obrazków do tekstu w składni Markdown jest bardzo podobne do wstawiania linków i różni się tylko tym, że zaczyna się od znaku wykrzyknika !. Składnia wstawiania obrazków również umożliwia używanie referencji.

![Tekst alternatywny](/sciezka/do/obrazka.jpg)

![Tekst alternatywny](/sciezka/do/obrazka.jpg "Opcjonalny tytuł")

Tekst alternatywny jest tym, co znajdzie się w atrybucie alt w wyjściowym kodzie HTML.

Referencja w obrazkach wygląda analogicznie do linków:

![Tekst alternatywny][id]

gdzie "id" jest etykietą referencji. Definicja referencji jest identyczna z linkami:

[id]: /sciezka/do/obrazka.jpg  "Opcjonalny tytuł"

Więcej informacji na temat referencji znaleźć można w rozdziale o linkach.

Grafika i obrazki w TypeFriendly

Odnoszenie się do obrazków znajdujących się w internecie w przypadku dokumentacji nie ma najmniejszego sensu. Dlatego TypeFriendly umożliwia umieszczenie obrazków w folderze media/ znajdującym się w katalogu z rozdziałami dokumentacji w danym języku (/input/JĘZYK/media). Podczas procesu budowania dokumentacji, katalog ten zostanie przeniesiony do folderu output/.

![Wykres](media/graph.png)  
**Przykład wstawienia obrazka**

Wykres
Przykład wstawienia obrazka

W naszej dokumentacji powyższy plik graph.png znajduje się w katalogu /input/en/media/.

Zobacz także:

3.4. Składnia pliku
3.4.8. Listy porządkowe
3.4.7. Grafika i obrazki
« Poprzedni
3.4.9. Bloki kodu
Następny »

3.4.8. Listy porządkowe

Markdown wspiera listy wypunktowane oraz numeryczne. Listy są elementami blokowymi, należy je więc poprzedzać i kończyć co najmniej jedną pustą linijką.

Dodanie listy numerowanej jest niezwykle proste:

Tekst

1. Element 1
2. Element 2
3. Element 3

Tekst

Tekst

  1. Element 1
  2. Element 2
  3. Element 3

Tekst

Wpisane numery nie mają znaczenia - mogą być w innej kolejności, mogą się powtarzać, tworzą jedynie walor estetyczny podczas przeglądania kodu dokumentu. Poniższa lista da taki sam efekt jak podana wyżej:

3.  Element 1
3.  Element 2
68. Element 3

Do tworzenia listy wypunktowanej, linijka musi zaczynać się od znaku gwiazdki *, plusa + lub minusa (pauzy) -:

+  Element 1
+  Element 2
+  Element 3

tekst

*  Element 1
*  Element 2
*  Element 3

tekst

-  Element 1
-  Element 2
-  Element 3
  • Element 1
  • Element 2
  • Element 3

To, którego znaku użyjemy, nie ma znaczenia - może to być którykolwiek z nich.

Znaczniki list mogą być oddzielone od tekstu jedną, bądź więcej spacją lub tabulacją. Znaczniki list powinny zaczynać się na początku linijek, można jednak odsunąć je od brzegu maksymalnie trzema spacjami.

Linijki w elementach listy można przełamywać, możesz je również odsunąć dla estetyki na tą samą odległość co pierwsza linijka:

 *  Litwo! Ojczyzno moja! ty jesteś jak zdrowie.
    Ile cię trzeba cenić, ten tylko się dowie,
    Kto cię stracił. Dziś piękność twą w całej ozdobie
    Widzę i opisuję, bo tęsknię po tobie.
 *  Panno Święta, co jasnej bronisz Częstochowy
    I w Ostrej świecisz Bramie! Ty, co gród zamkowy...

Jeśli jesteś jednak leniwy, nie musisz tego robić:

 *  Litwo! Ojczyzno moja! ty jesteś jak zdrowie.
Ile cię trzeba cenić, ten tylko się dowie,
Kto cię stracił. Dziś piękność twą w całej ozdobie
Widzę i opisuję, bo tęsknię po tobie.
 *  Panno Święta, co jasnej bronisz Częstochowy
I w Ostrej świecisz Bramie! Ty, co gród zamkowy...
  • Litwo! Ojczyzno moja! ty jesteś jak zdrowie. Ile cię trzeba cenić, ten tylko się dowie, Kto cię stracił. Dziś piękność twą w całej ozdobie Widzę i opisuję, bo tęsknię po tobie.
  • Panno Święta, co jasnej bronisz Częstochowy I w Ostrej świecisz Bramie! Ty, co gród zamkowy...

Jeśli elementy listy oddzielone są jedną pustą linijką, Markdown ich treść zawrze w znacznikach akapitu <p>.

Gdy wpiszesz:

*  Element 1
*  Element 2
*  Element 3

Otrzymasz:

  • Element 1
  • Element 2
  • Element 3

Ale oddzielenie elementów pustymi linijkami:

*  Element 1

*  Element 2

*  Element 3

Da efekt w postaci:

  • Element 1

  • Element 2

  • Element 3

Możesz w elementach listy zawrzeć kolejne akapity. Muszą być one otoczone pustymi linijkami oraz zaczynać się czterema spacjami bądź tabulacją.

*   Litwo! Ojczyzno moja! ty jesteś jak zdrowie.
    Ile cię trzeba cenić, ten tylko się dowie,

    Kto cię stracił. Dziś piękność twą w całej ozdobie
    Widzę i opisuję, bo tęsknię po tobie.

*   Panno Święta, co jasnej bronisz Częstochowy
    I w Ostrej świecisz Bramie! Ty, co gród zamkowy...

  • Litwo! Ojczyzno moja! ty jesteś jak zdrowie. Ile cię trzeba cenić, ten tylko się dowie,

    Kto cię stracił. Dziś piękność twą w całej ozdobie Widzę i opisuję, bo tęsknię po tobie.

  • Panno Święta, co jasnej bronisz Częstochowy I w Ostrej świecisz Bramie! Ty, co gród zamkowy...

System wstawiania akapitów niesie ze sobą pewne konsekwencje. Niemożliwe jest umieszczenie bezpośrednio pod sobą osobnych list, gdyż zamienione zostają one w jedną:

1. Element 1
2. Element 2
3. Element 3

1. Element 1
2. Element 2
3. Element 3
  1. Element 1
  2. Element 2
  3. Element 3
  4. Element 1
  5. Element 2
  6. Element 3

Sprawa ta nadal dyskutowana jest podczas opracowywania specyfikacji języka Markdown. Jedynym zalecanym rozwiązaniem jest skorzystanie z HTML-owego komentarza <!-- # --> i wstawienie go między listami, co spowoduje ich rozdzielenie.

Zagnieżdżone listy

Kolejne poziomy zagnieżdżonych list należy poprzedzać spacjami bądź tabulacjami.

Wpisanie:
1. Element 1
   - Element 1.1
   - Element 1.2
     1. Element 1.2.1
   - Element 1.3
2. Element 2
   * Element 2.1
   * Element 2.2
3. Element 3
Da nam:
  1. Element 1
    • Element 1.1
    • Element 1.2
      1. Element 1.2.1
    • Element 1.3
  2. Element 2
    • Element 2.1
    • Element 2.2
  3. Element 3

Listy z innymi elementami składni Markdown

W listach można umieścić inne elementy składni Markdown. Tak jak akapity, muszą one być poprzedzone czterema spacjami bądź tabulacją. W przypadku bloku kodu należy pamiętać o tym, że prócz konieczności jego poprzedzenia przez cztery spację lub tabulację, trzeba jeszcze dodać wcięcie listy.

1.  Litwo! Ojczyzno moja! ty jesteś jak zdrowie.
    Ile cię trzeba cenić, ten tylko się dowie,

        przykładowy blok kodu

    Kto cię stracił. Dziś piękność twą w całej ozdobie
    Widzę i opisuję, bo tęsknię po tobie.

    *   Element 1

            przykładowy blok kodu

    *   Element 2

    Panno Święta, co jasnej bronisz Częstochowy
    I w Ostrej świecisz Bramie! Ty, co gród zamkowy...

2.  Cośtam dalej.

  1. Litwo! Ojczyzno moja! ty jesteś jak zdrowie. Ile cię trzeba cenić, ten tylko się dowie,

    przykładowy blok kodu

    Kto cię stracił. Dziś piękność twą w całej ozdobie Widzę i opisuję, bo tęsknię po tobie.

    • Element 1

      przykładowy blok kodu

    • Element 2

    Panno Święta, co jasnej bronisz Częstochowy I w Ostrej świecisz Bramie! Ty, co gród zamkowy...

  2. Cośtam dalej.

Należy uważać na ilość spacji przed każdym elementem.

Zobacz także:

3.4. Składnia pliku
3.4.9. Bloki kodu
3.4.8. Listy porządkowe
« Poprzedni
3.4.10. Tabelki
Następny »

3.4.9. Bloki kodu

Parser Markdown udostępnia dwa sposoby wstawiania dużej partii kodu. Pierwszy z nich wymaga, aby przed każdą linią kodu umieścić 4 spacje, bądź jeden znak tabulacji.

To jest jakiś paragraf.

    <?php
    $fragment = "naszego kodu źródłowego";
    if($warunek)
    {
        skryptu('który piszemy');
    }
    ?>

To jest jakiś następny paragraf.

Drugim sposobem jest wstawienie co najmniej trzech tyld ~ przed i za wstawioną partią kodu.

Ważne jest, aby ilość znaków na początku i na końcu była taka sama.

To jest jakiś paragraf.

~~~
<?php
$fragment = "naszego kodu źródłowego";
skryptu('który piszemy');
?>
~~~

To jest jakiś następny paragraf.

Ta metoda wstawiania kodu nie umożliwia jednak wstawiania nam kodu do ramek informacyjnych lub list wypunktowanych.

Kolorowanie składni

TypeFriendly dodaje nam możliwość włączenia kolorowania składni wstawionego kodu. Obsługiwane jest ono przez GeSHi. Lista obsługiwanych języków dostępna jest na stronie tego parsera.

Włączenie kolorowania składni realizowane jest poprzez wstawienie w pierwszej linijce bloku kodu znacznika: [język]. W nawiasach kwadratowych zawarta jest nazwa języka, której odpowiada plik kolorowania GeSHi znajdujący się w katalogu /vendor/geshi/geshi.

Przykładowe użycie
~~~
[php]
<?php
$fragment = "naszego kodu źródłowego";
skryptu('który piszemy');
?>
~~~
Rezultat
<?php
$fragment = "naszego kodu źródłowego";
skryptu('który piszemy');
?>

Dodatkowym dostępnym "kolorowaniem" jest console, który upodabnia ramkę z kodem do widoku z konsoli systemowej (ciemne tło, biała czcionka).

php typefriendly.php build "./docs/"

Wyłączanie kolorowania

Mogą wystąpić konflikty z pewnymi rodzajami składni, jak choćby w plikach INI. Jednak wystarczy poprzedzić znacznik backslashem \ i kod nie będzie kolorowany:

\[grupa]
klucz = "pliku ini"

Oczywiście tyczy się to tylko pierwszej linijki bloku kodu.

3.4. Składnia pliku
3.4.10. Tabelki
3.4.9. Bloki kodu
« Poprzedni
3.4.11. Listy definicji
Następny »

3.4.10. Tabelki

Możliwe jest wstawienie do kodu tabelki. Prosta tabelka wygląda w następujący sposób:

Pierwszy nagłówek | Drugi nagłówek
----------------- | -----------------
Zawartość komórki | Zawartość komórki
Zawartość komórki | Zawartość komórki
Pierwszy nagłówek Drugi nagłówek
Zawartość komórki Zawartość komórki
Zawartość komórki Zawartość komórki

Pierwsza linijka zawiera nagłówki tabelki. Druga, to linie (----) oddzielające nagłówki od kolejnych wierszy tabeli. Kolumny tabeli oddzielane są pionową kreską |.

Opcjonalnie możesz dodać pionowe kreski przed i po każdej linijce tabelki:

| Pierwszy nagłówek | Drugi nagłówek    |
| ----------------- | ----------------- |
| Zawartość komórki | Zawartość komórki |
| Zawartość komórki | Zawartość komórki |

Zawartość komórek tabeli może przyjmować jedynie elementy liniowe takie jak: wyróżnienia, linki, obrazki, wstawki kodu.

Wyrównywanie do lewej lub prawej krawędzi

W tabelkach można określić do której strony ma być wyrównany tekst w komórkach danej kolumny. Realizuje się to poprzez dodanie znaku dwukropka : po lewej, prawej bądź obu stronach linii oddzielającej nagłówek od wierszy kolumny. W poniższym przykładzie również optycznie przesunięto spacjami zawartość komórek lecz nie jest to konieczne.

| Nagłówek  | Nagłówek | Nagłówek  | Nagłówek     |
| --------- |:-------- | ---------:|:------------:|
| Domyślne  | Do lewej | Do prawej |     Oraz     |
| położenie | strony   |    strony | wycentrowane |
Nagłówek Nagłówek Nagłówek Nagłówek
Domyślne Do lewej Do prawej Oraz
położenie strony strony wycentrowane

Domyślny styl CSS wyjścia (xhtml i xhtml_single) automatycznie centruje dane wpisane do komórek.

3.4. Składnia pliku
3.4.11. Listy definicji
3.4.10. Tabelki
« Poprzedni
3.4.12. Przypisy
Następny »

3.4.11. Listy definicji

Składnia obsługuje specjalny format list, nazywany listą definicji. Składa się na nią termin i wyjaśnienia, coś podobnego do słownika.

Typowa lista definicji składa się z jednolinijkowego terminu, po którym w nowej linijce znajduje się dwukropek : oraz objaśnienie.

Jabłko
:   Owoc drzewa jabłoni, z rodziny różowatych.

Pomarańcza
:   Owoc cytrusowy, zwykle o pomarańczowej skórce i włóknistym miąższu.
Jabłko
Owoc drzewa jabłoni, z rodziny różowatych.
Pomarańcza
Owoc cytrusowy, zwykle o pomarańczowej skórce i włóknistym miąższu.

Listy definicji mogą mieć więcej wyjaśnień do jednego terminu, lub kilka terminów do jednego objaśnienia:

Jabłko
:   Owoc drzewa jabłoni, z rodziny różowatych.
:   Złocista kula z krzyżem na wierzchu, jedno z insygniów władzy królewskiej i cesarskiej.

Oranż
Pomarańczowy
:   Kolor pomiędzy żółcią i czerwienią, pochodzi od koloru owocu pomarańczy.
Jabłko
Owoc drzewa jabłoni, z rodziny różowatych.
Złocista kula z krzyżem na wierzchu, jedno z insygniów władzy królewskiej i cesarskiej.
Oranż
Pomarańczowy
Kolor pomiędzy żółcią i czerwienią, pochodzi od koloru owocu pomarańczy.

Oddzielenie definicji od terminów jedną pustą linijką zawrze je w akapity.

Jabłko

:   Owoc drzewa jabłoni, z rodziny różowatych.

Pomarańcza

:   Owoc cytrusowy, zwykle o pomarańczowej skórce i włóknistym miąższu.
Jabłko

Owoc drzewa jabłoni, z rodziny różowatych.

Pomarańcza

Owoc cytrusowy, zwykle o pomarańczowej skórce i włóknistym miąższu.

Tak jak zwykłe listy porządkowe, listy definicji również mogą zawierać inne elementy blokowe: akapity, listy porządkowe, bloki kodu. Muszą być one poprzedzone czterema spacjami bądź tabulacją.

Termin 1

:   To jest definicja z dwoma akapitami. Lorem ipsum 
    dolor sit amet, consectetuer adipiscing elit. Aliquam 
    hendrerit mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus.

:   Druga definicja dla terminu 1., również w akapicie, gdyż
    poprzedzona jest pustą linijką.

Termin 2

:   Ta definicja posiada blok kodu i listę wypunktowaną.

        jakiś kod

    1.  element pierwszy
    2.  element drugi
Termin 1

To jest definicja z dwoma akapitami. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Druga definicja dla terminu 1., również w akapicie, gdyż poprzedzona jest pustą linijką.

Termin 2

Ta definicja posiada blok kodu i listę wypunktowaną.

jakiś kod
  1. element pierwszy
  2. element drugi

Należy uważać na ilość spacji przed każdym elementem.

3.4. Składnia pliku
3.4.12. Przypisy
3.4.11. Listy definicji
« Poprzedni
3.4.13. Bloki cytatu i ramki informacyjne
Następny »

3.4.12. Przypisy

Przypisy działają w podobny sposób do referencji odnośników. Na przypis składają się dwie rzeczy: odnośnik w tekście, którzy otrzyma indeks górny oraz objaśnienie przypisu, które wyląduje na końcu dokumentu.

To jest trochę tekstu z przypisem[^1].

[^1]: I to jest przypis.

To jest trochę tekstu z przypisem1.

Objaśnienia przypisów mogą znaleźć się w dowolnym miejscu w dokumencie, ale i tak będą wyświetlone na końcu dokumentu w kolejności dodania odnośników.

Nie da się stworzyć dwóch odnośników do jednego przypisu. Jeśli to zrobisz, kolejne odnośniki nie będą po prostu zamieniane.

Każdy przypis musi mieć unikalną nazwę, którą nie musi być wcale liczba - może być to też etykieta tekstowa.

Nazwa odnośnika służy tylko do adresów i nie ma wpływu na numerację przypisów w tekście.

Nazwa odnośnika musi być prawidłową nazwą atrybutów ID w HTML-u.

TypeFriendly do nazw odnośników dodaje identyfikator rozdziału.

Przypisy również mogą zawierać elementy blokowe, co oznacza, że mogą zawierać akapity, listy, bloki kodu itd. Wystarczy poprzedzić je czterema spacjami bądź tabulacją.

To jest trochę tekstu z przypisem[^1].

[^1]: I to jest przypis.

    A to jest kolejny akapit.

Dla celów estetycznych, pierwszą linijkę przypisu można pozostawić pustą:

To jest trochę tekstu z przypisem[^1].

[^1]: 
    I to jest przypis.

    A to jest kolejny akapit.

  1. I to jest przypis. ↩

3.4. Składnia pliku
3.4.13. Bloki cytatu i ramki informacyjne
3.4.12. Przypisy
« Poprzedni
3.4.14. Wstawki HTML
Następny »

3.4.13. Bloki cytatu i ramki informacyjne

Bloki cytatu ze specyfikacji składni Markdown mają trochę inne znaczenie, od tych, które wprowadzone zostały w TypeFriendly. Przyjrzyjmy się jednak najpierw, jak one wyglądają.

Jeżeli korzystałeś trochę z tekstowych maili, musiałeś spotkać się z cytowaniem treści poprzednich maili przy użyciu nawiasu kierunkowego > przed każdą linijką. W taki sam sposób robi się do w Markdownie.

> To jest cytat z dwoma akapitami. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> 
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

To jest cytat z dwoma akapitami. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Oczywiście, nie musisz ręcznie łamać każdej linjki:

> To jest cytat z dwoma akapitami. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Ten "leniwy" sposób wstawiania cytatów uniemożliwia proste oddzielenie dwóch osobnych cytatów od siebie, gdyż niezależnie od ilości pustych linijek pomiędzy blokami, zostaną one połączone w jeden. Sprawa cały czas jest dyskutowana podczas opracowywania specyfikacji języka i - póki co - zalecanym rozwiązaniem jest skorzystanie z HTML-owego komentarza <!-- # --> pomiędzy blokami.

Bloki można zagnieżdżać w sobie, dodając kolejne nawiasy >:

> To jest pierwszy poziom cytatu.
>
> > A to zagnieżdżony cytat.
>
> I tu wracamy do pierwszego poziomu.

To jest pierwszy poziom cytatu.

A to zagnieżdżony cytat.

I tu wracamy do pierwszego poziomu.

Bloki cytatu mogą zawierać również inne elementy składni Markdown, jak nagłówki, listy, bloki kodu itd.

> ### To jest nagłówek ###
> 
> 1.  To jest pierwszy element listy.
> 2.  A to drugi element.
> 
> Przykład kodu źródłowego:
> 
>     return shell_exec("echo $input | $markdown_script");

Należy uważać na ilość spacji przed każdym elementem.

Ramki informacyjne

Ramki informacyjne już wielokrotnie spotkałeś w tej dokumentacji. (- Tak, te jasnożółte pola z ikonką po lewej stronie.) Możesz tam zawrzeć przeróżne informacje, ważne lub konieczne do przekazania dla czytelnika dokumentacji.

Ramki te korzystają ze składni bloków cytatu. Różnią się tylko tym, że w pierwszej linijce znajduje się specjalny znacznik, podobny do do tych z kolorowania składni bloków kodu: [rodzaj]. Przykładowa ramka informacyjna może wyglądać tak:

> [information]
> ### Informacja ###
> 
> To jest jakaś ważna informacja dla czytelnika dokumentacji.

Informacja

To jest jakaś ważna informacja dla czytelnika dokumentacji.

Rodzaje ramek informacyjnych

[error]

[help]

[important]

[information]

[steps]

[stop]

[warning]

Wyłączanie ramek

Jeśli z jakichś powodów potrzebujesz wstawić w pierwszej linijce tekst, który wygląda jak znacznik ramki, wystarczy poprzedzić go backslashem \.

> \[important]

Oczywiście tyczy się to tylko pierwszej linijki bloku cytatu.

3.4. Składnia pliku
3.4.14. Wstawki HTML
3.4.13. Bloki cytatu i ramki informacyjne
« Poprzedni
3.4.15. Zaawansowane użycie
Następny »

3.4.14. Wstawki HTML

Jeśli składnia Markdowna nie wystarcza do osiągnięcia zamierzonego efektu, można bez problemu korzystać ze znaczników HTML, bezpośrednio w tekście. Nie trzeba stosować żadnej specjalnej składni, przełączników - po prostu używasz znaczników.

Jedynym ograniczeniem jest to, że HTML-owe znaczniki blokowe - takie jak: <div>, <table>, <pre>, <p> itd. - muszą być oddzielone pustą linijką od pozostałego tekstu i muszą zaczynać się bezpośrednio od krawędzi - nie mogą być poprzedzone tabulacjami lub spacjami. Parser jest na tyle sprytny, że nie otoczy wtedy HTML-a znacznikami akapitu.

Jeśli np. potrzeba było wstawić bardziej rozbudowaną tabelkę można po prostu napisać:

To jest normalny akapit

<table>
    <tr>
        <td>Coś</td>
    </tr>
</table>

To jest kolejny normalny akapit.

W takim jednak przypadku, składnia Markdown nie jest w znacznikach parsowana. Trzeba więc używać np. <strong> zamiast **wyróżnienia**.

Znaczniki liniowe - jak: <span>, <del>, <sup> - mogą być użyte gdziekolwiek w akapitach, listach, nagłówkach. Ba, możesz normalnie zamienić znacznikami HTML składnię Markdown, np. jeśli wolisz używać znaczników <a> lub <img> zamiast odnośników i obrazków.

W znacznikach liniowych - w przeciwieństwie do blokowych - składnia Markdown jest parsowana.

Formatowanie Markdown w elementach blokowych

Oryginalna składnia Markdown wyklucza parsowanie składni w HTML-owych znacznikach blokowych. Została jednak rozszerzona o możliwość opcjonalnego włączenia tego parsowania poprzez dopisanie do znacznika atrybutu markdown o wartości 1, co daje markdown="1":

<div markdown="1">
To jest *prawdziwy* tekst Markdownowy.
</div>
Co wygeneruje:
<div>

<p>To jest <em>prawdziwy</em> tekst Markdownowy.</p>

</div>

Parser jest bardzo sprytny i prawidłowo zachowuje się do różnych znaczników. Jeśli np. włączysz formatowanie dla znaczników <p>, spowoduje to sformatowanie jedynie elementów liniowych, nie dopuszczając list, bloków cytatu itd.

Są jednak sytuacje, gdy jest to niejednoznaczne. Spójrzmy na przykład:

<table>
<tr>
<td markdown="1">To jest *prawdziwy* tekst Markdownowy.</td>
</tr>
</table>

Komórka tabeli może przyjmować i elementy liniowe, i elementy blokowe. W takich jak ta sytuacjach Markdown zawsze włącza parsowanie jedynie elementów liniowych. Gdy potrzebujesz włączyć składnię blokową, zmień wartość atrybutu na markdown="block".

3.4. Składnia pliku
3.4.15. Zaawansowane użycie
3.4.14. Wstawki HTML
« Poprzedni
3.5. Tagi plików
Następny »

3.4.15. Zaawansowane użycie

W Markdownie bezwzględnie należy przestrzegać ilości spacji, których używamy do formatowania rozbudowanych, zagnieżdżonych elementów blokowych, jak powyższa listy wypunktowania z blokami kodu, czy ramki.

Jeśli nadal masz problemy z prawidłowym sformatowaniem jakiegoś fragmentu tekstu, upewnij się, czy wstawiłeś odpowiednią liczbę spacji, czy dałeś przejścia do nowej linii.

Dobrą wprawką jest również kod źródłowy tej dokumentacji.

Rozdzielanie list, bloków cytatu i kodu

Może zdarzyć się sytuacja, gdy chcemy mieć np. dwie osobne listy porządkowe albo dwa przykłady kodu źródłowego bezpośrednio pod sobą. Praser Markdown połączy jednak je jednak, co wynika ze specyfikacji. Nie zostało jeszcze opracowane "ładne" rozwiązanie tego problemu i zaleca się stosowanie HTML-owego komentarza, np. w postaci <!-- # --> (taką stosujemy w naszej dokumentacji). Oczywiście może to być dowolny inny, prawidłowy komentarz.

1.  Element 1
2.  Element 2
3.  Element 3

<!-- # -->

1.  Element 1
2.  Element 2
3.  Element 3

> cytat

<!-- # -->

> cytat
  1. Element 1
  2. Element 2
  3. Element 3
  1. Element 1
  2. Element 2
  3. Element 3

cytat

cytat

Wyłączanie formatowania

Jeśli w jakiejś sytuacji nie chcemy, aby wpisane znaki zamieniane były przez parser Markdown, można je escape'ować w powszechny w językach programowania sposób, przy użyciu backslasha \. Poniżej przedstawiamy kilka przykładów:

To jest nasz paragraf \[ a w nim \]() znaczniki odnośników, które nie zostaną sparsowane.

~~~
\[sekcja]
pliku = "ini"
; również nie zostanie pokolorowana
~~~

1410\. - to rok bitwy pod Grunwaldem, a nie początek listy numerowanej.

\> również nam nie zacznie cytatu

To jest nasz paragraf [ a w nim ]() znaczniki odnośników, które nie zostaną sparsowane.

[sekcja]
pliku = "ini"
; również nie zostanie pokolorowana

1410. - to rok bitwy pod Grunwaldem, a nie początek listy numerowanej.

> również nam nie zacznie cytatu

Oczywiście, backslashe są wtedy usuwane z tekstu wyjściowego.

Lista znaków, które można escape'ować:
\   backslash
`   odwrócony apostrof
*   gwiazdka
_   podkreślenie
{}  nawiasy klamrowe
[]  nawiasy kwadratowe
()  nawiasy zwykłe
>   nawias kierunkowy w prawo
#   hash
+   plus
-   minus (pauza)
.   kropka
!   wykrzyknik
~   tylda
:   dwukropek
|   kreska
3. Tworzenie własnej publikacji
3.5. Tagi plików
3.4.15. Zaawansowane użycie
« Poprzedni
3.6. Szablony
Następny »

3.5. Tagi plików

W rozdziale tym opisane są wszystkie dostępne tagi, jakich można używać w plikach rozdziałów. Większość z nich przyjmuje wartość tekstową, lecz niektóre mogą także obsługiwać zespół wartości (tablicę), którą podajemy w następujący sposób:

NazwaTagu:
 - Wartość 1
 - Wartość 2
 - Wartość 3

Pola podstawowe

Title
pełny tytuł danego rozdziału
ShortTitle

Alternatywna wersja tytułu, wbrew nazwie wcale nie musi być krótsza. Tag ten przez TypeFriendly używany jest w następujących sytuacjach:

  • W tytule dokumentu i "okruchach chleba" (breadcrumbs),
  • W tagach: SeeAlso, Extends, Implements, ExtendedBy, ImplementedBy, Throws, MultiExtends i Arguments,
  • Jako HTML-owy atrybut "title" w odnośnikach do innych rozdziałów.

Jeżeli ShortTitle nie jest ustawiony, brana jest wartość z Title.

SeeAlso
tablica identyfikatorów rozdziałów na potrzeby rubryki "Zobacz także".
SeeAlsoExternal
jak wyżej, lecz umożliwia podanie zewnętrznych odnośników. Po spacji można wpisać tekst odnośnika
Author
autor dokumentu

Przykład:

Title: Funkcja foo()
ShortTitle: foo()
SeeAlso:
 - reference.functions.bar
 SeeAlsoExternal:
 - http://www.example.com/ Przykładowa strona

Status dokumentu

Status
wyświetla pole Status w dokumencie wynikowym wraz z towarzyszącą treścią, które można wykorzystać do różnych celów.
FeatureInformation
dokleja na początek rozdziału szablon treści. Więcej o szablonach treści możesz dowiedzieć się z tego rozdziału. Znajdziesz tam także przykład użycia tego tagu.

Opis interfejsu programistycznego

Poniższe tagi są użyteczne w tworzeniu opisów interfejsów programowania aplikacji (ang. API) zawierających klasy, funkcje, interfejsy itd.

Construct
konstrukcja programistyczna opisywana przez rozdział. Możesz wpisać tutaj zarówno swoją własną nazwę, jak i jedną z predefiniowanych przez TypeFriendly (wykaz znajduje się niżej). W tym drugim przypadku, TF automatycznie przetłumaczy ich nazwy na wybrany język dokumentacji i sprawdzi możliwość stosowania pozostałych tagów.
Użycie tego tagu nie jest obowiązkowe. Jeśli nie dodasz go do rozdziału, TypeFriendly nie będzie wykonywać żadnych dodatkowych czynności związanych z użytymi tagami.
Type
typ elementu (może być użyty w różnych celach)
Visibility
widoczność/dostęp do elementu (np. public, private)
Namespace
pozwala określić przestrzeń nazw elementu.
wymaga podania identyfikatora rozdziału opisującego podaną przestrzeń nazw.
ENamespace wymaga podania nazwy przestrzeni nazw w sytuacji, gdy nasza dokumentacja jej nie opisuje.
Extends
bazowa klasa.
tag nie może być używany jednocześnie z MultiExtends w tym samym rozdziale.
wymaga podania identyfikatora rozdziału, który opisuje klasę bazową.
EExtends wymaga podania nazwy klasy bazowej w sytuacji, gdy nasza dokumentacja jej nie opisuje.
MultiExtends
bazowe klasy dla języków wspierających wielokrotne dziedziczenie.
tag nie może być używany jednocześnie z Extends w tym samym rozdziale.
wymaga podania listy identyfikatorów rozdziałów opisujących poszczególne klasy bazowe.
EMultiExtends wymaga podania listy z nazwami klas bazowych, gdy nie obejmuje ich nasza dokumentacja.
Implements
zaimplementowane interfejsy dla języków, które obsługują tę opcję.
wymaga podania listy identyfikatorów rozdziałów opisujących poszczególne interfejsy.
EImplements wymaga podania listy z nazwami interfejsów, gdy nie obejmuje ich nasza dokumentacja.
ExtendedBy
klasy/interfejsy rozszerzające aktualną.
wymaga podania listy identyfikatorów rozdziałów opisujących poszczególne klasy.
EExtendedBy wymaga podania listy z nazwami klas, gdy nie obejmuje ich nasza dokumentacja.
ImplementedBy
klasy implementujące podany interfejs.
wymaga podania listy identyfikatorów rozdziałów opisujących poszczególne klasy.
EImplementedBy wymaga podania listy z nazwami klas, gdy nie obejmuje ich nasza dokumentacja.
Mixins
lista domieszek (ang. mixin) używanych w klasie.
wymaga podania listy identyfikatorów rozdziałów opisujących poszczególne domieszki.
EMixins wymaga podania listy z nazwami domieszek, gdy nie obejmuje ich nasza dokumentacja.
Traits
lista cech (ang. trait) używanych w klasie.
wymaga podania listy identyfikatorów rozdziałów opisujących poszczególne cechy.
ETraits wymaga podania listy z nazwami cech, gdy nie obejmuje ich nasza dokumentacja.
Throws
rzucane wyjątki.
wymaga podania listy identyfikatorów rozdziałów opisujących poszczególne klasy wyjątków.
EThrows wymaga podania listy z nazwami klas wyjątków, gdy nie obejmuje ich nasza dokumentacja.
PartOf
używany z konstrukcją internal class do określenia klasy zawierającej podaną klasę wewnętrzną.
wymaga podania identyfikatora rozdziału opisującego daną klasę.
EPartOf wymaga podania nazwy klasy, gdy nie obejmuje jej nasza dokumentacja.
Reference
prototyp funkcji, np. void foo(int a, int b [, int c])
Arguments
lista argumentów funkcji/metody
spodziewany format pojedynczego argumentu: Name: nazwa_arg | Type: rozdzial.typu.argumentu | EType: nazwa_typu_argumentu | Desc: opis
tagi Type oraz EType są opcjonalne, jeśli jednak decydujesz się na ich użycie, muszą być zastosowane we wszystkich wymienionych argumentach.
Returns
opis tego, co funkcja zwraca.
File
plik zawierający omawiany element.
Files
lista nazw plików
odmiana tagu File pozwalająca wymienić kilka plików.
Package
pakiet zawierający klasę
wymaga podania identyfikatora rozdziału opisującego dany pakiet.
EPackage wymaga podania nazwy pakietu.
TimeComplexity
pozwala podać złożoność czasową algorytmu lub funkcji.
MemoryComplexity
pozwala podać złożoność pamięciową algorytmu lub funkcji.

Przykładowe użycie:

Title: Class "foo"
Construct: class
Extends: reference.bar
Implements:
 - reference.foo-interface
 - reference.bar-interface
ExtendedBy:
 - reference.joe

Jak widać, tagi wymagają domyślnie podania identyfikatorów rozdziałów opisujących wybraną opcję. Jeśli jednak pochodzi ona z jakiejś zewnętrznej biblioteki i nie jest ujęta w naszej dokumentacji, możemy utworzyć dodatkowe tagi z nazwą poprzedzoną dużą literą E do ich wymienienia:

Title: Klasa "foo"
EExtends: PDO
Implements:
 - reference.my-interface
EImplements:
 - Countable
 - IteratorAggregate

Obie wersje tagów mogą być użyte jednocześnie w obrębie tego samego rozdziału.

Dostępne konstrukcje programistyczne rozpoznawane przez tag Construct:

Tagi opisujące zachowanie

Pozwalają na udokumentowanie spodziewanego zachowania elementu poprzez zdefiniowanie efektów ubocznych, warunków początkowych, końcowych, ograniczeń itd.

StartConditions
lista warunków początkowych opisanych słownie.
EndConditions
lista warunków końcowych opisanych słownie.
SideEffects
lista efektów ubocznych opisanych słownie.
Limitations
lista ograniczeń opisanych słownie.
DataSources
lista źródeł danych wykorzystywanych przez element.
wymagana lista identyfikatorów rozdziałów opisujących wybrane źródła danych.
EDataSources wymaga listy źródeł danych opisanych słownie w sytuacji, gdy nie opisuje ich nasza dokumentacja.

Przykładowe użycie:

Title: Pobranie listy elementów
StartConditions:
 - istnieje co najmniej jeden element
SideEffects:
 - zwiększenie ilości wyświetleń elementów o 1
EDataSources:
 - tabela "Elementy"

----

Opis...

Tagi kontroli wersji

Informacje o wersjach oraz z systemów kontroli wersji.

VCSKeywords
miejsce, gdzie system kontroli wersji może rozwijać swoje słowa kluczowe. Są one uwzględniane w dokumencie wynikowym, gdy włączymy opcję versionControlInfo w konfiguracji projektu.
VersionSince
pierwsza wersja, która zawiera opisywaną opcję.
VersionTo
ostatnia wersja, która zawiera opisywaną opcję.

Przykładowe użycie:

Title: Przykładowa strona
VCSKeywords: $Id$
VersionSince: 1.0.2
VersionTo: 1.4.6

Teraz systemy kontroli wersji takie, jak Subversion, mogą rozwijać swoje słowa kluczowe w nagłówku, a ponadto mamy możliwość ich uwzględnienia przy generowaniu dokumentów wynikowych.

Typy rozdziałów

Poniższe tagi pomagają TypeFriendly identyfikować rodzaje poszczególnych rozdziałów.

Appendix
akceptuje wartość logiczną (true, false, yes, no). Oznacza dany rozdział jako "Dodatek", co powoduje, że otrzymuje on zamiast tradycyjnej numeracji kolejną literę alfabetu zgodnie z ustawieniami kolejności TypeFriendly. Ponadto tytuł rozdziału zostaje poprzedzony słowem "Dodatek".
3. Tworzenie własnej publikacji
3.6. Szablony
3.5. Tagi plików
« Poprzedni
4. TypeFriendly
Następny »

3.6. Szablony

TypeFriendly 0.1.2 wprowadza pojęcie szablonów treści. Szablony takie są dodatkowymi plikami tekstowymi z fragmentami tekstu sformatowanego w Markdownie, które mogą zostać doklejone do dowolnego rozdziału. Mogą być stosowane do zapisania w jednym miejscu często wykorzystywanych stałych fragmentów tekstu (np. ostrzeżeń), które można później łatwo modyfikować bez konieczności poprawiania ich z osobna w każdym rozdziale.

Szablony są przechowywane w katalogu /input/JEZYK/templates/ jako zwykłe pliki tekstowe o nazwie identyfikatorSzablonu.txt. Nie zawierają żadnego nagłówka, a jedynie czysty tekst sformatowany Markdownem. Przyjrzyjmy się, jak to działa w praktyce i utwórzmy szablon experimental.txt:

> [warning]
> Ta funkcjonalność ma status eksperymentalny i szczegóły jej działania mogą w przyszłości ulec zmianie.

Następnie możemy dokleić ten szablon do dowolnego rozdziału przy pomocy tagu FeatureInformation:

Title: Przykładowy rozdział
FeatureInformation: experimental

---

Jakiś tekst

TypeFriendly wyprodukuje wtedy następujący rezultat:

Przykładowy rozdział

Ta funkcjonalność ma status eksperymentalny i szczegóły jej działania mogą w przyszłości ulec zmianie.

Jakiś tekst

Obecnie wspierana funkcjonalność

Na dzień dzisiejszy, szablony treści mogą być doklejane wyłącznie do początku rozdziału przy pomocy tagu FeatureInformation. Przekazywanie argumentów do szablonów nie jest obsługiwane.

Przyszłe rozszerzenia

W następnych wersjach implementacja szablonów treści zostanie wzbogacona o możliwość umieszczania szablonów w dowolnym miejscu rozdziału oraz przekazywania dodatkowych argumentów. Znacznie poszerzy to zakres ich stosowania. Dokładna data wprowadzenia tych planów w życie zależy od czasu potrzebnego na odpowiednią rozbudowę parsera Markdown używanego w TypeFriendly.

Zobacz także:

Spis treści
4. TypeFriendly
3.6. Szablony
« Poprzedni
4.1. Interfejs wiersza poleceń
Następny »

4. TypeFriendly

W tym rozdziale opisane zostały różne aspekty samego TypeFriendly.

4. TypeFriendly
4.1. Interfejs wiersza poleceń
4. TypeFriendly
« Poprzedni
4.2. Interfejs wyjścia
Następny »

4.1. Interfejs wiersza poleceń

TypeFriendly jest obsługiwany wyłącznie z wiersza poleceń systemu operacyjnego. Współpracuje zarówno z rozmaitymi odmianami Uniksa, jak i z systemem Windows. Wywołanie jest następujące:

# Windows oraz systemy uniksowe
php typefriendly.php

# Systemy uniksowe (od wersji TF 0.1.2)
./typefriendly

TypeFriendly 0.1.0 i 0.1.1

Niezbędnym parametrem jest zawsze ścieżka do katalogu, w którym znajduje się dokumentacja (tj. zawierającego plik settings.ini i inne), np.

php typefriendly.php "./docs/"

Dostępne są następujące opcje, które podajemy w kolejności alfabetycznej przed ścieżką:

-c JĘZYK
narzędzie dla dokumentacji wielojęzycznych. Porównuje czas modyfikacji plików źródłowych podanego języka z plikami języka bazowego. Wyświetla wszystkie pliki, które mają wersję bazową nowszą, niż tę w danym języku, a także różnice w rodzaju brakujących plików.
-l JĘZYK
generuje dokumentację w podanym języku (domyślnie wybierany jest język bazowy).
-o WYJSCIE
generuje dokumentację, korzystając jedynie z podanego wyjścia. Musi ono być zdefiniowane na liście dostępnych wyjść dokumentacji.

Przykład:

php typefriendly.php "./docs/" -l en -o xhtml

Aby wyświetlić informacje o TypeFriendly, należy wywołać skrypt bez żadnych parametrów.

TypeFriendly 0.1.2 i nowsze

W TypeFriendly 0.1.2 interfejs linii komend został ulepszony, a jego użycie zmienione. Jako pierwszy argument podajemy zawsze akcję, którą chcemy wykonać. Następnie podajemy ścieżkę do dokumentacji i na końcu ewentualne opcje.

Dostępne komendy:

  1. create - zakłada w podanym (pustym) katalogu nową dokumentację na podstawie szablonu. TypeFriendly zadaje cztery pytania, a odpowiedzi używa do wygenerowania pliku konfiguracyjnego. Użycie

    ./typefriendly create "/sciezka/do/dokumentacji"

  2. build - tworzy wynikowy dokument z plików źródłowych. Dostępne opcje to -l (język) oraz -o (system wyjścia). Użycie:

    ./typefriendly build "/sciezka/do/dokumentacji" -l pl -o xhtml

  3. compare - porównuje tłumaczenie dokumentacji z wersją oryginalną. Komenda wymaga podania opcji -l do wybrania tłumaczenia.

    ./typefriendly compare "/path/to/directory" -l en

  4. version - wyświetla wersję TypeFriendly.

    ./typefriendly version
4. TypeFriendly
4.2. Interfejs wyjścia
4.1. Interfejs wiersza poleceń
« Poprzedni
4.3. Dokumentacja wielojęzyczna
Następny »

4.2. Interfejs wyjścia

TypeFriendly pozwala łatwo tworzyć własne systemy wyjścia, które będą mogły być później użyte do generowania dokumentacji. Do ich tworzenia wymagana jest pewna znajomość języka PHP.

Zasada parsowania

TypeFriendly rozpoczyna działanie od utworzenia obiektu projektu, za pomocą którego możliwe są wszelkie manipulacje na dokumentacji. Odczytywana jest konfiguracja, a następnie wszystkie rozdziały są przetwarzane i układane w odpowiedniej kolejności. Na końcu skrypt ładuje wszystkie wyjścia, które będa wykorzystywane i nakazuje każdemu z nich przetwarzać wstępnie obrobione wyniki.

Każde wyjście zapisane jest w niezależnym pliku PHP w katalogu outputs/. Ma postać klasy o takiej samej nazwie, jak nazwa pliku (z pominięciem rozszerzenia) i musi rozszerzać klasę standardOutput definiującą trzy metody opisane niżej. Zadaniem wyjścia jest opakowanie meta-danych w kod HTML lub inny bazujący na nim format. Niestety, obecnie wykorzystywany parser Markdown nie potrafi generować kodu wynikowego w niczym innym, stąd póki co niemożliwe jest napisanie wyjścia np. do formatu LaTeX. Prace nad umożliwieniem tego zostaną podjęte w niedalekiej przyszłości.

Wyjście samo musi dbać o zapisanie wyniku do odpowiednich plików - TypeFriendly nie narzuca tu żadnych ograniczeń i jedynie przekazuje katalog, w którym wszystko ma się znaleźć. Do dyspozycji programisty jest kilka interfejsów skryptu.

API

standardOutput

Jest to klasa abstrakcyjna, którą musi rozszerzać i implementować klasa wyjścia. Zawiera metody:

Dodatkowe tagi w meta-danych rozdziału

tfTranslate

Obiekt tej klasy służy do tłumaczenia interfejsu dokumentacji na różne języki.

tfProject

Obiekt projektu.

tfFilesystem

Klasa reprezentująca system plików w obrębie podanego katalogu. Umożliwia szybką i prostą manipulację plikami oraz katalogami. W opisie przez ''system plików'' będziemy rozumieć folder, na który został ustawiony obiekt tej klasy i w obrębie którego możemy dokonywać manipulacji.

4. TypeFriendly
4.3. Dokumentacja wielojęzyczna
4.2. Interfejs wyjścia
« Poprzedni
5. Dodatki
Następny »

4.3. Dokumentacja wielojęzyczna

W tym rozdziale opiszemy wszystkie aspekty tworzenia dokumentacji wielojęzycznych.

Model wielojęzyczny TypeFriendly zakłada, że w dokumentacji wyróżnimy jeden z języków (tzw. język bazowy), w którym tworzymy oryginalną treść, z której robione są później tłumaczenia do języków pochodnych. Język bazowy wybieramy w konfiguracji projektu, ustawiając opcję baseLanguage. Każdy z języków identyfikowany jest za pomocą dwuliterowego kodu, np. en, de, pl.

Tłumaczenie rozdziałów

Aby utworzyć tłumaczenie naszej publikacji, tworzymy nowy folder wewnątrz /input dla nowego języka. Jako jego nazwę wybieramy dwuliterowy symbol języka. Następnie po prostu zapisujemy tam przetłumaczone wersje oryginalnych rozdziałów. Tłumaczenie musi posiadać identyczną strukturę, jak oryginał i nie jest dozwolone dodawanie do niego dodatkowych rozdziałów (zostaną wtedy zignorowane). Poniżej znajdziesz poprawną strukturę tłumaczenia:

/input/pl/  (główny język publikacji)
preface.txt
chapter1.txt
chapter1.subchapter1.txt
chapter1.subchapter2.txt
chapter2.txt
chapter2.subchapter1.txt
chapter2.subchapter2.txt

/input/de/  (tłumaczenie na niemiecki)
preface.txt
chapter1.txt
chapter1.subchapter1.txt
chapter1.subchapter2.txt
chapter2.txt
chapter2.subchapter1.txt
chapter2.subchapter2.txt

Identyfikatory rozdziałów we wszystkich tłumaczeniach muszą być identyczne, jak w oryginale. Nie ma możliwości ich przetłumaczenia.

Nie musisz tłumaczyć wszystkich rozdziałów naraz. Jeśli TypeFriendly zauważy, że jakiegoś pliku brakuje w tłumaczeniu, wykorzystuje w jego miejscu treść z oryginalnej wersji językowej. Poniżej możesz zobaczyć przykład takiego niedokończonego tłumaczenia na język francuski:

/input/fr/
preface.txt
chapter1.txt
chapter1.subchapter1.txt
chapter2.txt

W tym przykładzie, treść rozdziałów chapter1.subchapter2.txt, chapter2.subchapter1.txt oraz chapter2.subchapter2.txt jest zaczerpnięta z oryginalnej wersji, tj. z /input/pl/. Umożliwia to osobom odpowiedzialnym za główną wersję dodawanie nowych rozdziałów, dzięki czemu są one od razu widoczne także w innych wersjach językowych, zaś opiekunowie poszczególnych wersji mogą dodać odpowiednie tłumaczenia później.

Tłumaczenie plików graficznych

Każda wersja językowa posiada swój własny katalog /media z własnymi grafikami itd. Podobnie jak w przypadku rozdziałów, TypeFriendly uzupełnia brakujące pliki graficzne w tłumaczeniach plikami z podstawowej wersji językowej.

Tłumaczenie szablonów treści

Każda wersja językowa posiada swój własny katalog /templates z szablonami treści. Podobnie jak w przypadku rozdziałów, TypeFriendly uzupełnia brakujące szablony w tłumaczeniach plikami z podstawowej wersji językowej.

Tłumaczenie interfejsu publikacji

TypeFriendly tłumaczy również interfejs nawigacyjny samej publikacji, tj. komunikaty takie jak "Spis treści". Konkretne teksty przypisane do komunikatów zdefiniowane są w plikach w obrębie katalogu globalnego /languages. Podkatalogi reprezentują różne wersje językowe, dla których aktualnie dostępne są tłumaczenia. Każdy komunikat jest częścią jakiejś grupy i posiada swój unikalny identyfikator ułatwiający znalezienie go. Każda grupa zapisana jest w osobnym pliku o składni plików INI:

; komentarz
 
identyfikator1 = "Tekst 1"
identyfikator2 = "Tekst 2"
identyfikator3 = "Tekst 3"
; itd.

Aby przetłumaczyć interfejs publikacji, utwórz nowy folder wewnątrz /languages, wykorzystując ten sam dwuliterowy kod języka. Następnie skopiuj pliki grup z innego języka i rozpocznij podmianę tekstów. Pamiętaj - jeśli jakiś komunikat nie jest dostępny w danej wersji językowej, TypeFriendly próbuje załadować go z plików podstawowego języka publikacji. Jeśli i tam go nie ma, generowany jest wyjątek.

Na dzień dzisiejszy, TypeFriendly posiada tłumaczenia interfejsu do trzech języków:

Jeśli stworzyłeś nowe tłumaczenie, bylibyśmy bardzo wdzięczni, gdybyś opublikował je w Internecie i podesłał, aby można było włączyć je do oficjalnej dystrybucji TypeFriendly tak, aby i inni mogli z niego korzystać.

Spis treści
5. Dodatki
4.3. Dokumentacja wielojęzyczna
« Poprzedni
A. Rozwój i wsparcie
Następny »

5. Dodatki

Dodatkowe informacje dotyczące TypeFriendly.

5. Dodatki
A. Rozwój i wsparcie
5. Dodatki
« Poprzedni
B. Licencja i autorzy
Następny »

Dodatek A. Rozwój i wsparcie

Wsparcie dotyczące TypeFriendly znajdziesz na forum dyskusyjnym grupy Invenzzia zarówno w języku polskim, jak i w angielskim. Zachęcamy do nadsyłania uwag i nowych pomysłów. Jeśli znalazłeś jakiś błąd, odwiedź nasz bugtracker - pamiętaj, że błędy dodajemy wyłącznie w języku angielskim!!!

Wersje robocze są do pobrania z repozytorium Subversion. Repozytorium TypeFriendly jest publicznie dostępne do odczytu pod adresem http://svn.invenzzia.org/svn/typefriendly (jest to adres, którego należy użyć w poleceniu ''checkout''). Możesz także obejrzeć repozytorium on-line pod adresem svn.invenzzia.org.

5. Dodatki
B. Licencja i autorzy
A. Rozwój i wsparcie
« Poprzedni

Dodatek B. Licencja i autorzy

Skrypt TypeFriendly został stworzony przez grupę Invenzzia. Odpowiedzialne za niego osoby to:

W projekcie został użyty parser PHP Markdown Extra napisany przez Michela Fortina i bazujący na kodzie Johna Grubera. Dostępny jest on na zmodyfikowanej licencji BSD.

W projekcie został użyty parser GeSHi napisany przez Benny'ego Baumanna i dostępny na licencji GNU GPL.

W szablonie dokumentacji użyto ikonek zestawu Tango Icon Library, części projektu Tango Desktop Project dostępnej na licencji Creative Commons Attribution-ShareAlike 2.5.

Opis składni markdown jest adaptacją oryginalnego dokumentu Markdown Syntax page napisanego przez Daringa Fireballa oraz opisu składni PHP Markdown Extra Michela Fortina.

TypeFriendly dostępny jest na zasadach licencji GNU General Public License 3. Treść tej licencji dołączona jest do pakietu w katalogu info/COPYING, a w razie jej braku możesz zapoznać się z nią pod adresem http://www.gnu.org/licenses/gpl.html.

Niniejsza dokumentacja dostępna jest na zasadach licencji GNU Free Documentation License 1.2. Treść tej licencji dołączona jest do pakietu w katalogu info/COPYING_DOCS, a w razie jej braku możesz zapoznać się z nią pod adresem http://www.gnu.org/licenses/fdl.html.

Licencje te w żaden sposób nie stosują się do dokumentacji stworzonych przez Ciebie i przetwarzanych przez TypeFriendly tak samo, jak grafika stworzona w programie na licencji GNU GPL nie jest automatycznie obejmowana tą samą licencją.