Zadania do wykładu o dokumentacji perla

Uniwersytet Gdański - Instytut Matematyki - Zakład Informatyki - Strona domowa

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:

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 :)

Uniwersytet Gdański - Instytut Matematyki - Zakład Informatyki - Strona domowa - Perl - Zadania
[c] Piotr Arłukowicz, materiały z tej strony udostępnione są na licencji GNU.