Invenzzia... po polsku - Tag - dokumentacja

Wiki.invenzzia.org

Zyx — nie, 08 lut 2009 17:10:00 +0100

Dzisiaj oficjalnie zostało uruchomione wiki Invenzzii, na wszyscy zainteresowani będą mogli publikować porady, artykuły oraz inne materiały poświęcone projektom open-source takim, jak Open Power Template czy TypeFriendly. W przeciągu ostatnich kilku dni konfigurowałem MediaWiki oraz instalowałem niezbędne dodatki, jednak wciąż jeszcze sporo pozostało do zrobienia. Jak widać, na wiki brakuje wielu stron pomocy i szablonów technicznych, jednak powinny one zostać w najbliższych dniach dodane. Zachęcam wszystkich do opisywania tam swoich rozwiązań, pomysłów oraz dodatków - wystarczy do tego jedynie konto na naszym forum i znajomość języka angielskiego, jako że wiki dostępne jest tylko w nim.

Pożegnanie z Polską

Zyx — sob, 20 wrz 2008 17:21:00 +0200

Dzisiaj kolektywnie doszliśmy do wniosku, że postawienie na polskich programistów i język polski było dużym błędem. Sprawa tłumaczeń i utrzymywania dwujęzyczności okazała się trudniejsza, a z rodzimej części, zamiast spodziewanego odezwu, słyszymy głównie krytykę, że forum jest puste, społeczność nikła i tekstów mało. Dokładniejszy przegląd sytuacji zawarłem na moim blogu i nie chcę się tu powielać, ograniczając się jedynie do skutków dla Invenzzii.

A tych będzie trochę:

Dokumentacje będą docelowo tworzone tylko w języku angielskim. Polska wersja uzależniona jest wyłącznie od naszej dobrej woli, czasu i chęci.
Artykuły będą docelowo tworzone w języku angielskim. Jak wyżej.
Polskie forum będzie zredukowane, ale nie likwidowane.
Polski blog zostaje, ale tym razem wiadomości będą pojawiać się przede wszystkim po angielsku.
Wszystkie informacje najpierw pojawią się w języku angielskim.

Jeśli ktoś nie zna angielskiego, trudno. W końcu i tak korzysta z projektów pokroju Zend Frameworka, które przecież kompletnej i dobrej polskiej dokumentacji nie mają. Przynajmniej dzięki takiemu krokowi będzie mogła reszta świata skorzystać, a ja nie będę tracił czasu na pisanie dwukrotnie tego samego. Ponadto zauważyłem, że znacznie wygodniej pisze mi się najpierw tekst po angielsku, później tłumacząc na polski, niż w drugą stronę.

OPT 2.0.0-dev7

Zyx — śro, 20 sie 2008 11:31:00 +0200

3 miesiące i 10 dni. Tyle zajęło przepisywanie dotychczasowego kodu OPT do nowej, lepszej wersji. Dziś w końcu uznałem, że dotarł on do punktu, w którym może aspirować do miana "dev7" i odpowiednia paczka znalazła się w działach "Download". Zmian jest sporo, głównie związanych z API biblioteki, którą teraz się nieco inaczej inicjuje. Poprawiłem też nieco kompilator, dodając do szablonów parę nowych możliwości oraz znacząco rozbudowałem dokumentację, która zresztą dołączona jest do wydania.

Zmiany w API

Nowe OPT zupełnie inaczej się inicjuje. Biblioteka nie jest w pełni samodzielna - aby ułatwić późniejszą integrację z innymi produktami serii OPL, powstał pakiet OPL zawierający podstawowe interfejsy oraz klasy. Wyekspediowana tam została m.in. obsługa konsoli debugowej oraz konfiguracji, ponadto dodaje on autoloader z prawdziwego zdarzenia. Kod OPL dołączony jest domyślnie do paczki z OPT, tak więc w dalszym stopniu wystarczy skrypt tylko rozpakować.

Aby nie być gołosłownym przedstawiam odrobinę kodu:

<?php
    // OPL Initialization
    require('../../lib/opl/base.php');
    Opl_Loader::setDirectory('../../lib/');
    Opl_Registry::setState('opl_debug_console', true);
    Opl_Registry::setState('opl_extended_errors', true);
    spl_autoload_register(array('Opl_Loader', 'autoload'));
    
    try
    {
    	$tpl = new Opt_Class;
    	$tpl->sourceDir = './templates/';
    	$tpl->compileDir = './templates_c/';
    	$tpl->charset = 'utf-8';
    	$tpl->compileMode = Opt_Class::CM_REBUILD;
    	$tpl->stripWhitespaces = false;
    	$tpl->setContentType(Opt_Class::HTML);
    	$tpl->setup();
    	
    	$tpl->assign('foo', 'Blok');
    	$tpl->parse('szablon.tpl');    
    }
    catch(Opt_Exception $exception)
    {
    	Opt_Error_Handler($exception);
    }
?>

Podstawowa inicjacja polega na załadowaniu głównego pliku biblioteki OPL, ustawieniu katalogu ze źródłami oraz autoloadera. Podany katalog musi zawierać zarówno foldery "opl", jak i "opt", gdyż inaczej nic się nam nie załaduje. Przy okazji możemy ustawić ogólne aspekty funkcjonowania wszystkich bibliotek OPL.

Jak widać, zmienione zostało nazewnictwo klas. Musiałem to zrobić, ponieważ taki zapis jest znacznie łatwiej parsować w autoloaderze, a przy okazji ucieszy fanów Zend Frameworka. Zmieniłem także nazwy niektórym metodom, np. powyżej widać, że httpHeaders() został przechrzczony na setContentType(). Jeśli zajrzymy do katalogu /lib/opt/, ujrzymy, że cały kompilator został zmodularyzowany, lecz i tak nie uchroniło to głównej klasy Opt_Compiler_Class przed zajmowaniem 65 KB na dysku twardym. Tego się już bardziej odchudzić po prostu nie da, ale możecie się pocieszać, że do tego pliku właściwie tylko ja muszę zaglądać i się w nim orientować :).

Tutaj mała uwaga: z OPT wyrzuciłem system cache. Doszedłem do wniosku, że zmuszanie tej biblioteki do zajmowania się jeszcze tym to lekkie przegięcie. Zamiast tego, pozostał bardzo prosty interfejs Opt_Cache_Hook_Interface, który należy sobie zaimplementować, aby podłączyć dowolny inny system cache. W ten sposób biblioteka łatwiej będzie integrować się z frameworkami, które często obsługują ten element we własnym zakresie. Gdyby ktoś jednak czegoś takiego nie miał, dotychczasowy kod niebawem będzie dostępny z powrotem... lecz jako osobna biblioteka, dla której jeszcze nie wymyśliłem nazwy.

Zmiany w szablonach

Szablony powinny działać bez większych problemów, aczkolwiek przy okazji przepisywania pchnąłem lekko do przodu prace nad instrukcjami. Pojawił się opt:tag, a opt:extend w pełni obsługuje już escape'owanie. Nie ma jeszcze opt:tree, opt:grid i opt:pagination, gdyż zmieniłem silnik sekcji i na razie zdążyłem go przetestować jedynie na opt:section. Sekcje są teraz o tyle fajne, że obsługują tzw. klasy uchwytów (hook classes), dzięki którym można nauczyć je obsługi dowolnego formatu danych, jaki nam się tylko zamarzy. W finalnym wydaniu nie będzie żadnych problemów, żeby sekcja potrafiła odczytywać dane np. bezpośrednio z obiektów PHP-Doctrine lub różnych elementów frameworków. Wszelkie sprawy związane z wybranym formatem są zupełnie niewidoczne po stronie szablonu:

<opt:section name="sekcja">
  .... {$sekcja.blok}
</opt:section>

Format natomiast wybieramy w skrypcie, np.

$tpl->assign('sekcja', $PDOStatement, 'PDO');

OPT zajmie się całą resztą, czyli dopasowaniem formatu do sekcji, korzystając z podanej klasy uchwytów. Klasy uchwytów mogą również modyfikować działanie zwyczajnych bloków, a twórcy instrukcji mogą korzystać z ich API w swoich produkcjach. W samych sekcjach pojawił się nowy atrybut: parent, który ułatwi tworzenie relacji. Przypomnę, że w dalszym ciągu sam fakt zagnieżdżenia jednej sekcji w innej tworzy między ich elementami relację przynależności, lecz jeśli domyślne zachowanie nam nie pasuje, możemy to zmienić:

<opt:section name="sekcja1">
   <opt:section name="sekcja2">
      <opt:section name="sekcja3" parent="sekcja1">
         ....
      </opt:section>
   </opt:section>
</opt:section>

Teraz elementy sekcji3 są przyłączone do sekcji1, a nie sekcji2. Ponadto, niedawno na forum Nowaker zaproponował, aby OPT zgodnie z logiką obsługiwał następujący blok sekcji: {$sekcja.blok.elementTablicy}. Wola jego stała się faktem i teraz OPT skanuje cały taki blok w poszukiwaniu nazwy dowolnej aktywnej obecnie sekcji.

Z innych nowości należy wymienić możliwość przypisania bloku do konkretnego szablonu. Dostęp jest realizowany poprzez $this.blok.

Dokumentacja

Spędziłem niedawno dużo czasu nad dokumentacją do OPT 2, a przede wszystkim nad przekonwertowaniem dotychczasowych wyczynów na TypeFriendly. Efekt jest następujący:

Na ukończeniu jest opis składni szablonów. Jedynie dwie instrukcje nie posiadają jeszcze dokumentacji i trochę funkcji.
Opisana jest większość API biblioteki.
Opisane są wszystkie aktualnie wykorzystywane i zatwierdzone dyrektywy konfiguracyjne.
Na ukończeniu są strony opisujące migrację z: PHP, OPT 1.x oraz Smarty'ego. Szczególnie w OPT 1.1.x ludzie się krzywili na ostatni z wymienionych opisów, że głupoty opisuje, zamiast konkretów. Teraz się poprawiłem i różnica jakościowo-ilościowa powinna być widoczna gołym okiem.

Dokumentacja dołączona jest do paczki, jest także możliwość przejrzenia jej on-line: on-line. Można także zapoznać się z zalążkiem angielskiej dokumentacji do OPL.

Zakończenie

Wykaz paczek można znaleźć tutaj. Na kolejną niestety znów przyjdzie trochę poczekać. W sobotę wyjeżdżam na tydzień, a zaraz później pochłonie mnie przeprowadzka do Krakowa i egzamin na uczelni, tak więc będę "wolny" dopiero za jakiś miesiąc. W tym czasie będę wrzucać jakieś mniejsze rzeczy na SVN i tam też będzie najświeższa wersja. Z drugiej strony, eXtreme już coś tam kombinuje z Open Power Classes, a konkretniej jego klasą "Opc_Paginator" do stronicowania. Myślę, że również Radzio w końcu zrobi swoje API dla Google Charts.

Na koniec należy uczciwie zaznaczyć, że OPT 2.0.0-dev7 przeszedł z LGPL 3 na zmodyfikowaną licencję BSD, co Wam ułatwi później dodawanie go do projektów komercyjnych, a wszystkim utrudni życie z przyjmowaniem zewnętrznych patchów i poprawek. Licencja LGPL była o tyle fajna, że z definicji obejmowała sobą również wszystkie poprawki i patche. Zmodyfikowana BSD tak nie robi i będę musiał odmawiać ich dodania do SVN bez podpisanego papierka ze zgodą na wydanie ich na podanej licencji, tak jak to robi Zend ze swoim Frameworkiem. Coś za coś.

TypeFriendly

Zyx — śro, 02 lip 2008 20:51:00 +0200

Z eXtremem ciężko pracujemy, by pierwsza wersja ujrzała w końcu światło dzienne i jesteśmy już bardzo blisko. W związku z tym chciałbym bliżej przedstawić ten projekt, który z pewnością powinni docenić inni programiści, autorzy rozmaitych skryptów i poszukujących sensownego narzędzia do generowania dokumentacji. Pomysł na napisanie TypeFriendly zrodził się w mojej głowie po nieudanych zmaganiach z dodaniem paru niezbędnych rzeczy do parsera XSLT dla DocBook. Widać choćby po dokumentacji PHP, co można z tym zrobić (kolorowanie składni, wiele różnych formatów, ogromna ilość pomocnych znaczników), ale nie dajmy się zwariować. To są wręcz tygodnie siedzenia, by osiągnąć podobny efekt. Pomijam już fakt, że byłby on słabo przenośny... wolałem poświęcić te tygodnie na stworzenie czegoś bardziej przydatnego.

TypeFriendly jest więc systemem generowania dokumentacji, ale innego pokroju niż np. phpDocumentor, który skanuje kod źródłowy Twojego projektu i robi opisy do wszystkich napotkanych klas i funkcji. Tutaj rozdziały piszemy sami od A do Z i sami układamy je w żądanym porządku, podobnie jak w DocBooku. Na tym podobieństwa się kończą, ponieważ TF z definicji zawiera już wszystko, co potrzeba, a został tak zaprojektowany, by dokumentację pisało się intuicyjnie.

Cechy:

W TF dokumentację tworzymy, pisząc tekst w zwykłych plikach tekstowych, korzystając ze składni Markdown. Dodatkowo, na początku umieszczamy różne dodatkowe tagi, dzięki którym możemy ustawić tytuł, informacje o wersji czy np. listę "Zobacz także".
TF automatycznie układa nasze pliki w rozdziały na podstawie ich nazwy i sortuje alfabetycznie. Jednak zawsze możemy wprowadzić własny układ - w pliku "ze wskazówkami do sortowania" definiujemy własną kolejność. To, czego tam nie zapisaliśmy, pozostanie alfabetycznie.
TF posiada wbudowaną opcję kolorowania składni kodu źródłowego.
TF samodzielnie generuje pełną nawigację pomiędzy rozdziałami, podobnie jak spis treści.
TF jest zaprojektowany do rozwijania dokumentacji w kilku językach. Posiada nie tylko możliwość przetłumaczenia tekstów interfejsu, ale także proste narzędzie do sprawdzania aktualności "pochodnych wersji językowych".
TF umożliwia wygenerowanie wyjściowej dokumentacji w formacie XHTML (w wersji z wieloma podstronami lub na jednej). Przygotowujemy też specjalny format umożliwiający szybki import dokumentacji do bazy danych i udostępnienie np. możliwości jej komentowania on-line.
TF oprawia dokumentację w bardzo ładną szatę graficzną, którą możecie podziwiać np. w dokumentacji do OPTv2 (robionej właśnie w TF).

Wprawdzie wydania żadnego jeszcze nie było, ale chętni mogą już teraz połączyć się z naszym nowym SVN-em i ściągnąć projekt stamtąd. Link do polecenia checkout jest następujący: http://svn.invenzzia.org/svn/typefriendly/trunk/ - serdecznie zachęcam już teraz do testów. W repozytorium jest plik README oraz będąca już na ukończeniu dokumentacja w języku polskim.

Żeby nie być gołosłownym, pokażę co ciekawsze opcje na przykładzie paru fragmentów. Pierwszym z nich będzie jeden z plików manuala OPTv2 (library.optnode.txt):

Title: Klasa optNode
ShortTitle: optNode
Status: abstract
Extends: library.optcodebuffer
ExtendedBy:
 - library.optscannable
 - library.optcharacterdata
 - library.optexpression

----
Abstrakcyjna klasa węzła. Zapewnia obsługę podstawowych własności, jak rodzic i typ.

Pola klasy
----------
Wszystkie pola klasy są chronione.

 Nazwa         | Typ       | Opis
---------------|-----------|---------------------------------------
 $type         | Integer   | Numeryczny identyfikator typu.
 $parent       | optNode   | Rodzic węzła.

Dostępne identyfikatory typów:

1. `OPT_CDATA_NODE` - `optCharacterData`
2. `OPT_TEXT_NODE` - `optText`
3. `OPT_EXPRESSION_NODE` - `optExpression`
4. `OPT_ELEMENT_NODE` - `optElement`
5. `OPT_ROOT_NODE` - `optRoot`

Na początku pliku znajduje się nagłówek, w którym umieszczamy tzw. tagi. Tam właśnie określany jest właściwy tytuł, a w tym wypadku również zależności między klasami. Zauważmy, że do innych klas odwołujemy się, podając identyfikatory rozdziałów, które je opisują. Oczywiście każdy z tych "obiektowych" tagów posiada także wersję, gdzie nazwy możemy wpisać bezpośrednio (np. gdybyśmy dziedziczyli po klasie wbudowanej w PHP). Dostępnych tagów jest więcej. Przykładowo, można bardzo łatwo zrobić listę "Zobacz także", która wygląda mniej więcej tak:

SeeAlso:
 - chapter.text1
 - chapter.text2
 - chapter.text3

Gdy lista tagów dobiegnie końca, przechodzimy do właściwej treści pisanej w formacie Markdown. Autor zaprojektował go bazując na formatowaniu używanym powszechnie w rozmaitych plikach tekstowych czy e-mailach (można powiedzieć, że napisał parser do składni, która sama wyewoluowała :)). Tekst źródłowy jest przez to niesamowicie czytelny i na dobrą sprawę czyta się go niewiele gorzej, niż gdyby był faktycznie sformatowany. Trochę gorzej, gdy ktoś jest przyzwyczajony już do jakiejś składni wiki, bo MD nie zawsze takowe wiki przypomina (zwróćcie uwagę chociażby na sposób wykonania tabelki). Jednak można się dość łatwo przyzwyczaić - w Markdownie klepiemy również teksty na naszą stronę i muszę powiedzieć, że jest to całkiem przyjemne narzędzie, które z pewnością ujrzycie w niejednym produkcie Invenzzii. Jedyny mankament jest taki, że oficjalny parser obsługuje tylko jeden słuszny format - XHTML. O LaTeXu czy innych na razie trzeba niestety zapomnieć, ale na to już ostrzymy sobie zęby :).

Najgorszy problem przy tworzeniu dokumentacji to nawigacja. Linki "Poprzedni/Następny/W górę" załatwia TypeFriendly, sekcję "Zobacz także" robimy za pomocą znaczników, a co z klikalnymi nazwami funkcji i klas? Myślałem nad tym i wymyśliłem rozwiązanie genialne w swej prostocie. W dodatkowym pliku tekstowym definiujemy kawałki tekstów, które mają zostać zamienione na odnośnik. Przykładowo, wpisujemy tam, że `optClass::parse()` ma, oprócz nadania mu standardowego formatowania, zostać zmienione na odnośnik do library.optclass.parse i już się niczym więcej przejmować nie musimy. Niestety, do takich przeróbek Markdowna jeszcze nie doszliśmy i pierwsza wersja tego bajeru nie będzie jeszcze zawierać. Wszystko w swoim czasie.

TypeFriendly obsługiwany jest w całości z konsoli systemu operacyjnego. Testowaliśmy go na Linuksie i Windowsie - w obu systemach działa póki co bez zarzutów. Do działania potrzebny jest wyłącznie interpreter PHP. W połączeniu z intuicyjną składnią oraz wbudowanym wsparciem dla wielojęzyczności powinno to zachęcić wielu ludzi do pomocy przy tłumaczeniach, rozwoju oryginalnej wersji, a nawet tworzeniu nowych wyjść. Przetworzenie naszych plików na XHTML to kwestia wklepania jednego polecenia:

php ./typefriendly.php -l pl -o xhtml ./sciezka/do/dokumentacji/

Porównajmy to z DocBookiem - sam format jest nieco bardziej rozwlekły, ale stosunkowo łatwy do opanowania. Do konwersji jednak potrzeba trochę więcej narzędzi - DTD, sam zestaw DocBok XSL Stylesheet i wreszcie sam parser XSLT. Jego wybór jest nie bez znaczenia, gdyż ze zwykłym, szybkim i łatwym w użyciu xsltproc nie dostaniemy np. kolorowania składni. Użytkownicy Windowsa natomiast mają kompletnie prze.... jeśli autor projektu dodatkowo zrobi na DocBooku framework do budowania dokumentacji, w którym część narzędzi napisana jest w... Bashu. Nie trzeba takich kwiatków daleko szukać - jak myślicie, co odpowiada za dokumentację PHP? :) Z chęcią bym do niej coś popisał, gdyby choć raz udało mi się uruchomić ichniejszy framework i cokolwiek przetworzyć.

OPT 2.0.0-dev6

Zyx — sob, 10 maj 2008 14:15:00 +0200

Do ściągnięcia dostępna jest wreszcie kolejna wersja rozwojowa OPT. Jej zawartość opisałem w poprzednim wpisie, dlatego tu dodam tylko, że wbrew zapowiedziom, nie ma jeszcze instrukcji opt:grid z powodów, które zaraz wyjaśnię. Ponadto nie da się jeszcze ustawiać statusu escape'owania dla pojedynczego szablonu, ale takowy z globalnej konfiguracji i ustawień wyrażenia w klamerkach już działa ładnie. Za to dodałem implementację instrukcji opt:capture i częściową opt:cycle. Polskich użytkowników z pewnością ucieszy informacja, że podczas długiego weekendu doprowadziłem do względnego porządku nasz nowy system dokumentowania TypeFriendly i OPT 2 ma już nową, ładną dokumentację :)

Dostałem niedawno parę pytań, czy można już powoli zacząć używać OPT 2 w rzeczywistych projektach. Odpowiadałem, że większość rzeczy już jest gotowa i w nich raczej zmian nie będzie, aczkolwiek nic nie gwarantuję. W kolejnym devie okaże się, że dobrze zrobiłem, nic nie gwarantując, ponieważ OPT wymaga paru drastycznych zmian.

Sekcje

Od strony szablonu wszystko zostaje po staremu, za to zmieni się trochę interfejs skryptowy. W OPT już od pewnego czasu istnieją elementy pozwalające uniezależnić szablony od interfejsów skryptu, dzięki czemu zmiany w silniku nie muszą iść w parze z przepisywaniem wszystkich szablonów, co jest bolączką innych parserów (w tym Smarty'ego, gdzie na forach widziałem już takie cudaczne konstrukcje, że aż głowa może rozboleć). Sekcje już od dawna stanowiły jedną z nich, gdyż skrywały sposób łączenia sekcji podrzędnych i nadrzędnych, a także zawierały obsługę generowania danych "w locie" oraz alternatywny format tablic. Wszystko to było jednak zakodowane na sztywno w kodzie, a dodanie doń czegoś nowego jest kłopotliwe. Przecież formaty danych mogą być jeszcze inne, stąd pomysł, by wprowadzić modularyzację samych sekcji. Instrukcja jako taka zapewnia wyłącznie szkielet podpinający wszystko, gdzie trzeba w drzewku XML. My natomiast za pomocą pluginów możemy łatwo nauczyć sekcję, żeby np. pobierała dane np. bezpośrednio z PHP-Doctrine czy też iterowała po obiekcie :). Zastosowanie:

<opt:section name="foo">
 {$foo.bar}
</opt:section>

Nie musimy się już martwić, czy element foo jest obiektem, a my odwołujemy się do pola "bar", czy też tablicą. Po stronie szablonu foo.bar oznacza blok "bar" w elemencie "foo", natomiast zadaniem skryptu jest nadanie mu jakiegoś konkretnego znaczenia (tablica, obiekt itd.). Analogicznie, nie obchodzi nas również budowa danych dla sekcji jako takiej - czy to jest sekcja dynamiczna, czy tablica w jakimś formacie, czy też obiekt... Wszystko będzie można łatwo zaprogramować.

Po stronie skryptu pojawi się metoda w stylu setSectionType służąca do określenia, jak OPT powinien przetworzyć daną sekcję:

$tpl -> setSectionType('foo', 'mojPluginObiektowy');
$tpl -> assign('foo', new obiektPoKtorymMoznaIterowac);

Gdy nie określiliśmy typu, OPT wybierze standardową postać tablicową.

Zalety:

Po stronie szablonu już nas kompletnie nic nie obchodzi. Sekcje możemy kopiować metodą Ctrl+C, a one bez zmiany jednego znaku w pełni dostosują się do sytuacji w nowym szablonie bez naszej ingerencji.
Koniec narzekań, czemu sekcje nie obsługują czegośtam, albo że format jest debilny :)
Jednolita kontrola obsługi po stronie skryptu.

Modularyzacja kompilatora

Kompilator zostanie rozbity na większą ilość mniejszych plików, gdyż jest on ładowany raz na jakiś czas i zyski ze zbicia wszystkiego w dwa mega-pliki są znikome. Wpływ na skrypty korzystające z OPT powinien być zerowy.

Zmiany w obsłudze błędów

Niebawem pojawi się Open Power Classes 1.0.0-dev1, a w planach są też inne projekty. Jeśli ma to być coś więcej, niż tylko zbiór bibliotek o podobnej nazwie, trzeba ujednolicić niektóre elementy. Oczywiście wspólną częścią jest obsługa błędów - każda z bibliotek musi więc zawierać taki sam plik z odpowiednim współdzielonym kodem, który może być używany przez wszystkie z nich jednocześnie. Jeżeli poza przechwytywaniem wyjątku optException i kierowaniem go do optErrorHandler() nie robisz z nim nic więcej, wtedy zmiana nie powinna Cię dotknąć.

Poprawa hermetyzacji klasy głównej!!

Rzecz musi zostać ujednolicona, żeby nie powstała kolejna niedorzeczność pod postacią "dlaczego jedne dane są chronione, choć potrzebuje ich kompilator, a inne nie". Jeśli odwoływałeś się wyłącznie do pól konfiguracyjnych, zmiana nie powinna Cię dotknąć.

Nowa dokumentacja

Jak pisałem, wreszcie OPT 2 posiada nową, zapowiadaną jakiś czas temu dokumentację. Za jej generowanie odpowiada napisany w PHP silnik TypeFriendly obsługujący m.in. kolorowanie składni. Zostanie on wydany na licencji GNU GPL, gdy tylko uporządkuję trochę jego kod i napiszę dokumentację pokazującą, jak z niego korzystać. Tak czy inaczej jego obecność pozwoli nawet na takie bajery, jak wersja on-line dokumentacji z komentarzami użytkowników.

Dokumentacje

Zyx — sob, 08 mar 2008 22:29:00 +0100

Jak dotąd, wszystkie dokumentacje tworzymy w pakiecie bazującym na DocBooku (dodanych kilka drobnych znaczników), z których wersja HTML-owa tworzona jest arkuszami XSLT. Istniejące systemy przetwarzania automatycznie dbają o utworzenie nawigacji między rozdziałami oraz podział tego na pojedyncze pliki, o ile wybraliśmy taki tryb. Niestety, utworzenie kompletnego frameworka dla dokumentacji jest okropnie skomplikowane, co tłumaczy fakt, dlaczego całość zapisana jest póki co w jednym wielkim pliku XML, a przykłady nie mają kolorowania składni. Do tego dochodzi problem z parserami XSLT. Choć w DocBooku piszę od dawna, postanowiłem znaleźć alternatywne rozwiązanie i rozpocząć projekt gotowego do użycia generatora dokumentacji napisanego w PHP i korzystającego z prostszej składni. eXtreme ochrzcił go mianem TypeFriendly.

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.