Zadania do wykładu o dokumentacji perla

Perl: programowanie - Zadania do wykładu o dokumentacji perla

Większość odpowiedzi i podpowiedzi do zebranych poniżej zadań można znaleźć w podręczniku systemowym do perla - dostępnym po poleceniu perldoc perlpod oraz perldoc perlpodspec.

Zadania przygotowawcze:

• Sprawdź, jakie masz oprogramowanie w systemie, które przetwarza dokumenty POD. W szczególności, chodzi o programy, które skonwertują dokumenty POD do formatów HTML, TEXT, TEX (format LaTeXa).
  Wystarczy, wykorzystując dopełnianie w powłoce bash, napisać pod i wcisnąć dwa razy klawisz TAB. Zostaną pokazane wszystkie polecenia, których nazwa zaczyna się od pod, i wśród nich znaleźć można będzie programy do obsługi PODa (zobacz rys. 1):

  Rys. 1. Sposób znalezienia programów do konwersji POD na inne formaty. Nie wszystkie muszą być konwerterami, niektóre z nich mają inne zastosowania.
  
• Przejrzyj dokumentację związaną z programem podlint. Prawdopodobnie użyjesz go do sprawdzenia swojego dokumentu POD przed jego udostępnieniem.
  Dokumentacja do programu podlint wyświetlana jest przez polecenie man podlint. I jedyne, co pozostaje, to dokładnie ją przeczytać.
• Rozejrzyj się po sali i nawiąż współpracę z koleżanką/kolegą w celu późniejszej wymiany dokumentów POD i oprogramowania perlowego. Szczegóły opisane są w zadaniach poniżej.
  Ta... w zasadzie w chwili gdy piszę odpowiedź na to zadanie, nie siedzę w sali na zajęciach tylko w pokoju przy herbacie (!) zatem pozostałe warunki raczej też nie będą spełnione... Jedyna żywa osoba obok, to obok kota - żona zajęta drukowaniem materiałów na swój wykład... nie, raczej na współpracę odnośnie perla w tej chwili nie ma co liczyć... :)

Zadania do wykonania

1. Wykorzystując polecenie man lub perldoc wygeneruj listę nagłówków występujących często w dokumentacji modułów perlowych. Wykorzystaj wszystkie znane ci nazwy modułów i programów perlowych, które opisano w perldocu, na przykład perl, perlrun, perlpod, DBI, Data::Dumper, strict, i inne, które być może znasz. Zrobić to można wykonując polecenie man lub perldoc z parametrem (np. DBI), a potem przekierować wynik tego polecenia do filtra, który wytnie cały tekst, a pozostawi tylko nagłówki. Idealne zastosowanie perla, ale można użyć także polecenia grep. W przypadku gdyby osoby początkujące nie wiedziały jak to zrobić - niech szukają pomocy u osób zaawansowanych (lub raczej po ZJP) :)
   W zasadzie wystarczy dla każdego modułu, jaki chcemy sprawdzić wykonać np. poniższe proste polecenie: perldoc -m NAZWA::MODUŁU | perl -ne 'print if /^=head[12]/' ... i tyle. To, co otrzymamy będzie po prostu listą nagłówków z dokumentacji wpisanych w sekcji =head1 oraz =head2 (inne będą pomijane). Można teraz zobaczyć, jakie nagłówki pojawiają się najczęściej, i po analizie kilku modułów wywnioskować, jakie powinno się nagłówki pisać. Z obserwacji wynika że najczęściej, obligatoryjnie wręcz, pojawiają się nagłówki: NAME, SYNOPSIS, DESCRIPTION, SEE ALSO, AUTHORS, czasami ACKNOWLEDGEMENTS, FAQ, KNOWN BUGS, i jeszcze inne, chociaż już rzadziej.
2. Na podstawie wyników uzyskanych w poprzednim zadaniu, zrób listę najczęściej pojawiających się nagłówków spotykanych w dokumentacjach POD. Dzięki temu dowiesz się, jak należy pisać dokumentację i jakie są najczęściej wykorzystywane "tytuły".
   Rozwiązanie zostało przedstawione przy okazji realizacji poprzedniego zadania.
3. Zapoznaj się z działaniem programu pod2usage. Zbadaj jego opcje i zaobserwuj, jak za jego pomocą można wypisać tylko niektóre części dokumentacji dowolnego modułu perlowego.
   Polecenie to można wykorzystać z różnymi poziomami verbose, czyli "gadatliwości". Poziom 1 wypisuje tylko część SYNOPSIS, poziom 2 pozwala zobaczyć SYNOPSIS oraz wszystkie sekcje typu OPTIONS/ARGUMENTS, a poziom verbose ustawiony na 3 pokazuje cały dokument PODa.
4. Zapoznaj się z opcjami programu perldoc, szczególnie z opcją -u oraz -m (to głównie dla hardkorowców). Jest to dla Ciebie doskonałe źródło prawdziwych, działających PODów, gdyby jakiś źródłowy tekst był potrzebny. Można zobaczyć tam, jak napisane są dokumenty POD.
   PerlDoc to system dokumentacji perla. Opcja -u powoduje wypisywanie surowego kodu dokumentacji w postaci niesformatowanej (można tego użyć np. do ekstrakcji PODa z programu). Opcja -m oprócz surowej postaci dokumentacji wyświetla także perlową część kodów modułu (nie są wyświetlane fragmenty kompilowane w rozszerzeniu XS ani inne kody z języków osadzonych w perlu).
5. Napisz prosty dokument POD. Możesz umieścić w nim kilka poleceń formatujących. Nie poświęcaj temu zadaniu zbyt wiele czasu, ponieważ bardziej zaawansowanego PODa będzie trzeba stworzyć w następnym zadaniu. Następnie przekształć swój dokument na format HTML, TEXT, LaTeX i zobacz jak wyglądają dokumenty w ten sposób otrzymane. Czy LaTeX prawidłowo kompiluje dokument otrzymany z PODa? Warto także porównać dokumenty generowane za pomocą poleceń pod2* z tymi, które otrzymuje się z perldoc o opcji -oformat, na przykład -otk, -ohtml, -oLaTeX./~piotao/pod/
   Kilka wygenerowanych formatów plików na podstawie jednego dokumentu POD można znaleźć także tutaj.
6. Teraz małe wyzwanie: napisz prosty programik perla (który nie musi robić jakichś wielkich rzeczy, wystarczy coś prostego i łatwego). DOPISZ do tego programu pełną dokumentację POD. Umieść wszystkie najważniejsze nagłówki, autora, i każdą informację, jaka wyda ci się ważna. Program możesz napisać nieczytelnie (na przykład gdyby coś liczył, zadbaj o głupie nazwy zmiennych, itp.). Postaraj się stworzyć maksymalnego gniota, po to, aby zrozumienie programu dla drugiej osoby stało się niemożliwe! (Na tym polega wyzwanie między innymi). Następnie przekaż ten program drugiej osobie z pary, a w zamian weź program, który ona napisała dla Ciebie. Postarajcie się nawzajem określić, czy dokumentacja, którą napisaliście jest wystarczająca dla kogoś, kto nie uczestniczył w pisaniu programu. W tym zadaniu jest element współzawodnictwa i zabawy, zatem wykorzystajcie dobrze czas. Wskazane jest, aby osoby początkujące dobierały się w pary z osobami początkującymi, a zaawansowane - z zaawansowanymi. Najciekawsze programy i ich dokumentacje należy wysłać do prowadzącego zajęcia pocztą (niech też się pomęczy) :)
   Niestety, nikt się tego nie podjął, a szkoda. Jak widać, już nikomu nie chce się porządnie studiować :(
   20070110: update: dostałem mały programik od jednego ze studentów, w postaci jednolinijkowca, który poza dokumentacją spełniał to zadanie. Podziękowania należą się dla R.B. :)

Przykład w miarę sensownie opracowanej dokumentacji dla dowolnego programu perlowego znajdziesz pod adresem: /~piotao/pod/. Możesz wykorzystać te pliki do pracy (być może przyszłej), a na pewno wykorzystać je trzeba, oddając programy napisane w przyszłości do sprawdzenia :)