Ogólna zasada działania nie zmieni się. Na wejście podajemy zbiór plików źródłowych dokumentacji i otrzymujemy przetworzone dokumenty HTML. Jest jednak szereg zmian w stosunku do DocBooka:
- Z definicji zakładamy, że dokumentacja złożona jest z wielu plików. TypeFriendly na podstawie nazwy pliku ustala zależności między poszczególnymi rozdziałami, a tam, gdzie nie chcemy mieć alfabetycznego porządku, możemy zdefiniować własny w osobnym pliku.
- Poszczególne pliki korzystać będą z bardzo wygodnej składni Markdown, lekko rozszerzonej pod kątem tworzenia dokumentacji. Dodatkowo jeżeli podamy parserowi listę stałych, metod, funkcji itd., będzie on mógł automatycznie zamieniać występujące w tekście odwołania do nich na odnośniki do stosownych rozdziałów. Na początku każdego dokumentu możliwe będzie umieszczenie kilku informacji o pliku, np.
Title: Tytuł strony Author: Zyx Tags: dokumentacja SeeAlso: library.class-x.foo ----- Witamy w dokumentacji ===================== To jest krótka dokumentacja napisana w Markdownie.
- Trzy tryby wyświetlania: XHTML (jedna strona), XHTML (wiele stron), wersja on-line. Dwie pierwsze wersje to generatory dokumentacji do lektury w trybie offline, podobnie jak np. aktualny manual OPT. W trzeciej, TypeFriendly utworzy zbiór zserializowanych tablic z informacjami o wszystkich podstronach. Dowolny skrypt PHP może je szybko wczytać i umieścić np. w bazie danych strony WWW tak, aby umożliwić szybką budowę dokumentacji on-line, z komentarzami użytkowników, wyszukiwarką oraz innymi bajerkami. W każdym trybie będzie istnieć kolorowanie składni identyczne z tym używanym na blogu.
- Obsługa wielu języków.
Przekonwertowałem już część dokumentacji OPT na nowy format i pisze się w nim wygodnie. Kodowanie samego TypeFriendly rozpocząłem natomiast dziś rano. Istnieje już szkielet aplikacji oraz parsery niezbędnych formatów plików. Niedługo będzie można obejrzeć to publicznie. Skrypt będzie aplikacją czysto konsolową, odpalaną z linii komend. Działać ma zarówno w systemach uniksowych, jak i pod Windowsem.
O, widzę, że nie tylko ja porzucam DocBooka.
Też chciałem parser pisać, ale ostatecznie postawiłem na docutils i format reStructuredText - całkiem wygodny zestawik.
Markdown ma składnię bardzo podobną do reStructuredText, dokumentacja do ezComponents zresztą napisana jest bodaj przy jego użyciu. Sam ostatnio sporo rzeczy robiłem z Markdownem i korzysta się z niego szalenie wygodnie.
A propo dokumentacji - moglibyście poprawić nazwy funkcji/znaczników/parametrów (które wszędzie poza przykładami są zastępywane przez '???') co bardzo utrudnia czytanie (trzeba potem szukać w przykładach o której funkcji mowa, a niekiedy nie idzie...)
hash: Pytajniki są tam, gdzie nie została napisana jeszcze odpowiednia część dokumentacji. A przepisywana jest ona teraz na inny format więc to raczej w "starej" nie będzie poprawione, działać natomiast będzie w nowej.