Title: Rozdziały
SeeAlso:
 - docs.directories

---

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

> [warning]
> 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ę.