Invenzzia... po polsku - Tag - typefriendly

Co nowego w Invenzzii?

Zyx — nie, 22 mar 2009 10:38:00 +0100

Witam wszystkich! W ostatnich dniach sporo się działo wokół Invenzzii oraz jej projektów. Postanowiłem w tym zbiorczym wpisie omówić krótko najważniejsze rzeczy, dostępnym również w języku angielskim. Poruszymy temat OPT 2.0, nowego TypeFriendly, nowej strony Invenzzii oraz aktywności Invenzzii w "serwisach wspomagania open-source", że tak to ładnie nazwę.

Open Power Template 2

Kilkanaście minut temu na SVN-ie znalazła się kolejna rewizja oznaczona numerem 66, efekt ostatnich czterech dni pracy. Jak na tak krótki okres, zakres wnoszonych poprawek i nowości jest zaiste imponujący.

Zdecydowałem się przepisać na nowo kod odpowiedzialny za kompilację sekcji. Poprzedni miał poważny problem z obsługą specyficznych atrybutów, którego nie dało się w takiej postaci przeskoczyć w żaden sposób. Dzięki tej akcji, poprawiłem znacznie prostotę oraz czytelność kodu, m.in. wyposażając go w phpdoc i upraszczając strukturę. Aby upewnić się, że nowy kod nie wyprodukuje nowych błędów w tym, co dotychczas działało, pojawiło się ponad 20 nowych testów sekcji sprawdzających poprawność obsługi rozmaitych warunków brzegowych oraz współpracy z innymi instrukcjami. Dlatego nowa implementacja nie powinna sprawiać większych niespodzianek, aczkolwiek błąd #51 w dalszym ciągu pozostaje nienaprawiony.
Przy okazji ostatecznie uporządkowałem projekt formatów danych, który też w końcu uzyskał formę, z której jestem zadowolony. Trzeba jeszcze napisać do tego wszystkiego kupę unit testów, ale jesteśmy już na dobrej drodze, by takie testy faktycznie powstały.
Kolejna, dość spora partia kodu PHP została wyposażona w phpdoc. Dzięki temu IDE typu NetBeans i Eclipse będą w stanie jeszcze lepiej podpowiadać semantykę i użycie poszczególnych metod. Phpdoc w kodzie źródłowym został w większości wymuszony właśnie tą potrzebą, gdyż normalna i właściwa dokumentacja pisana jest w oparciu o TypeFriendly.
Usunięte zostało kilka irytujących błędów.

Ponadto, ulepszenia pojawiły się również w podręczniku użytkownika, gdzie pojawił się zupełnie nowy rozdział nazwany "Podręcznik programisty" (ang. "Programmer's guide"). Celem jest stworzenie kompletnego przewodnika po poszczególnych możliwościach OPT, który można czytać jak książkę i który zawiera różne praktyczne wskazówki, nie zawsze dające się opisać w zwykłej dokumentacji API. W poczet nowego rozdziału został włączony stary "API Issues". Obecnie z nowego rozdziału można dowiedzieć się następujących rzeczy:

Jak przygotować OPT do pracy?
Jak pracować z widokami?
Jak pracować z systemami wyjścia?
Jak obsługiwać błędy oraz rozszerzać ich domyślną obsługę?
Jak pracować z formatami danych.
Jak tworzyć wielojęzyczne witryny.
Jak podłączyć własną funkcję do escape'owania HTML-a w danych ze skryptu i zapobiegania atakom XSS?

Lektura dostępna jest wyłącznie w języku angielskim.

TypeFriendly 0.1.1

Niecały tydzień temu został wydany TypeFriendly 0.1.1, nowa wersja systemu generowania podręczników użytkownika. Koncentruje się on przede wszystkim na poprawie znalezionych błędów. Teraz nasze wysiłki kierują się już ku wydaniu wersji 0.2 i mamy nadzieję, że ukaże się ona znacznie szybciej :).

Nowa witryna Invenzzii

W końcu jesteśmy prawie gotowi do uruchomienia nowej strony Invenzzii. Wczoraj eXtreme odpalił ją na naszym serwerze i w chwili obecnej trwają testy oraz implementacja ostatnich funkcji. Witryna posiada zupełnie nowy design, logo (można je już podziwiać na wiki), nową, czytelniejszą nawigację oraz układ treści. Mamy nadzieję, że w przeciągu kilku następnych dni uda się ją udostępnić internautom.

OPT w Ohloh.net

Ohloh.net to nowatorski katalog projektów open-source założony przez dwójkę byłych pracowników Microsoftu, który nie tylko podaje informacje, że coś istnieje, ale pozwala również na szeroko rozumianą interakcję między użytkownikami i twórcami. Kilka dni temu założyłem w nim profil projektu Open Power Template 2. W chwili obecnej monitoruje on RSS-y, pozwala śledzić bieżący dziennik prac uaktualniany przez Jabbera (jeśli jesteś ciekaw, co aktualnie, w tej konkretnej chwili grzebiemy w kodzie, zaprenumeruj go :)) oraz przejrzeć statystyki dotyczące bieżącego kodu źródłowego (niestety tylko w repozytorium "trunk", które na razie się nie rozwija z wiadomych przyczyn). Jeśli posiadasz konto na Ohloh i jesteś użytkownikiem OPT, nie zapomnij zgłosić tego oraz ocenić projektu, gdyż m.in. dzięki temu projekt ma możliwość przyciągnięcia większej ilości użytkowników, co przełoży się na jakość samego kodu i dostępnych materiałów. Planujemy wydelegować na Ohloh również system downloadu tak, aby nie obciążać tym zadaniem naszego serwera i umożliwić zainteresowanym pobieranie projektu z rozmaitych mirrorów.

PS. Przypominam prenumeratorom RSS-a, żeby przepisali się na wersję anglojęzyczną bloga, gdzie nowe wpisy pojawiają się znacznie częściej!

TypeFriendly 0.1.0 wydane

Zyx — śro, 23 lip 2008 10:29:00 +0200

W końcu zakończyliśmy tłumaczenie dokumentacji na język angielski i gotowy od kilkunastu dni kod wreszcie został wydany jako pierwsza wersja systemu generowania dokumentacji TypeFriendly. Można ją pobrać w dziale Pliki na stronie głównej. Dokumentacja dostarczana jest w wersji źródłowej i robi jednocześnie za przykład, dlatego nie obawiajcie się, że czegoś brakuje. Wszystkie informacje potrzebne do zbudowania HTML-owej wersji dokumentacji znajdują się w pliku /info/README.txt - jest to kwestia wklepania jednego polecenia z konsoli. Trwają już prace nad nową stroną Invenzzii i znajdzie się tam miejsce na dokumentację on-line.

O TypeFriendly pisałem dokładniej w poprzednim wpisie i tam znajdziecie więcej informacji. Tutaj dodam tylko, że eXtreme odwalił kawał świetnej roboty, wyczerpująco opisując po polsku całą składnię Markdown z dziesiątkami przykładów. Z pewnością opis ten przyda się wielu osobom.

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ć.