Moduł Pod::HTML2Pod

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

Spis treści

  1. Co to jest?
  2. Funkcje
  3. Wskazówki
  4. Dodatkowe informacje

Co to jest?

Jest to moduł perla, który zawiera narzędzia tłumaczące kod HTML w POD.

Streszczenie
# Użyj programu 'html2pod' która pochodzi z tej dystrybucji, lub: use Pod::HTML2Pod; print Pod::HTML2Pod::convert( 'file' => 'my_stuff.html', # input file 'a_href' => 1, # try converting links );

Larry Wall powiedział kiedyś (1999-08-27, na liście ludzi związanych z pod):

Napisałem ten moduł aby ludzie którzy nie są wprawieni w POD ale śpieszą sie aby udokumentować własne programy albo moduły, mogli napisać swój dokument w zwykłym HTML'u, i przetworzyć go na POD. To jest właśnie to co robi ten moduł. W szczególności ten moduł pochyla się do tyłu aby spróbować zmienić ogólnie poprawny HTML w POD - i kiedy w ma wątpliwości, zwyczajnie ignoruje rzeczy których o których nie wie, lub nie potrafi przetworzyć.

Funkcje

Ten moduł zapewnia jedną funkcję, której nie eksportuje:

Pod::HTML2Pod::convert( ..opcje.. )
Zwraca ona pojedynczą wartość skalara zawierającą przetworzony tekst POD, z pewnymi komentarzami na końcu. Funkcja ta pobiera opcje:
'file' => FILENAME
Określa, że kod HTML ma być czytany z danej nazwy pliku
'handle' => *HANDLE
Określa, że kod HTML ma być czytany z otwartego uchwytu do pliku danego poprzez np.$fh_obj, *HANDLE, Handle{IO}, itp. Jeśli to określiłeś, ale nie udało sie określić faktycznego uchwytu do pliku, rezultatem może być zagadkowy błąd.
'content' => STRING
Określa, że kod HTML jest dany jako napis.(w alternatywie daj referencje do skalara: 'content' => \$stuff)
'tree' => OBJ
Określa, że dokument HTML zawarty w danym obiekcie HTML::TreeBuilder (lub HTML::Element).
'a_name' => BOOLEAN
Określa czy chcesz spróbować przetworzyć <a name="..."> element. Domyślnie jest to wyłączone, takie elementy są ignorowane.
'a_href' => BOOLEAN
Określa czy chcesz próbować przetwarzać zawartość elementu <a href="...">. Domyślnie jest to wyłączone, takie elementy są ignorowane. Jeśli włączone, rozważ, że pokrewne URL'e nie mogą być poprawnie przetworzone do POD. Każdy pokrewny URL nie przetworzony będzie widoczny jako "skarga" w komentarzach na końcu dokumentu. Normalnie absolutne URL'e będą traktowane najlepiej jak tylko mogą. Notka: URL zaczynający się "pod:..." będzie przetworzony w odnośniki POD do czego wskazują; oznacza to, że "pod:Getopt::Std" będzie przetworzony w Getopt::Std.
'debug' => INTEGER
Ustawia Pod::HTML2Pod w trybie gadatliwym w trakcie przetwarzania tego dokumentu HTML. INTEGER może być 0 aby nie było żadnego wyjścia błędu, 1 dla umiarkowanej ilości która spowoduje wyświetlenie drzewa składni HTML na początku przetwarzania, 2 aby dodać jeszcze pośrednie drzewo POD, plus jeszcze kilka wiadomości diagnostycznych. Przyglądnie sie wyrzuconemu drzewo może być pomocne w nadawaniu sensu wiadomościom o błędzie.

Wskazówki.

  • Nie pisz niedbałego HTML'a mając nadzieje ze ten moduł zdoła go zrozumieć.
  • Nie bierz wyjścia pod2html i nie wrzucaj go tutaj, tylko dlatego że uważasz że jest to łatwy sposób aby go sprawdzić. Nauczysz sie po prostu niemiłych rzeczy o Pod::Html i to dobrze jeśli bałagan który zobaczysz pozwoli ci udoskonalić Pod::Html, ale nie jest to raczej łatwa droga.
  • Jednakże, używaj tego modułu do przetwarzania prostych dokumentów HTML w POD, rozważ jednak kilka prostych prawd:
  • POD nie potrafi obsłużyć tabel, zdjęć, map bitowych, warstw, CSS, zakorzenionych apletów Javy i innego rodzaju obiektów, CZCIONEK. Więc nie próbuj żadnej z tych rzeczy.
  • Używaj <h1> oraz <h2> jako nagłówków.

  • Jeśli chcesz mieć blok przykładowy kodu, wstaw go w <pre>.
  • Upraszczaj wszystko
  • Pamiętaj: tylko dlatego że coś wyszło z Pod::HTML2Pod nie oznacza to, że jest to szczęśliwy normalny POD. Możesz robić wiele rzeczy w HTML które wyprodukują POD to jest dziwne ale formalnie legalne.
  • Staraj się nie używać edytora WYSIWYG HTML, ponieważ często produkuje straszny kod. To samo dotyczy przycisku "zapisz jako HTML" w twoim edytorze tekstu. Możesz zawsze spróbować, ale spójrz na HTML aby ocenić straty zanim przetworzysz go na POD.
  • Zawsze patrz na POD który został wytworzony przez HTML2Pod nigdy nie dołączaj go w ciemno.
  • Rozważ rozpoczęcie od tego szablonu: <html> <head> <title>Things::Stuff </title> <!-- html2pod ignoruje wszytko poza ciałem --> </head> <body> <h1>NAME </h1> Things::Stuff -- does some things with stuff <h1>SYNOPSIS </h1> <!-- Prosty kods --> <pre> use HTML::Stuff; do some more stuff; la la la la la; oogah; </pre> <h1>DESCRIPTION </h1> This module does things with stuff. It exports these functions: <dl> <dt> <code>thingify( ... ) </code> <dd>This function takes stuff, and returns their value as things. <dt> <code>destuffulate( ... ) </code> <dd>This function returns the things, from stuff. <p>It will throw a fatal exception if applied to things. <br>So don't do that. <dt> <code>enthinction( ... ) </code> <dd>This is where I run out of ways to make up silly sentences involving "thing" and "stuff". Mostly. </dl> <h2>Caveats and WYA's </h2> Things to be wary of: <ul> <li>The things. <li>And the stuff <p>Don't forget about that stuff. Gotta keep an eye on that. </ul> <h1>BUGS </h1> Stuff is hard. <h1>SEE ALSO </h1> <a href="pod:Class::Classless">Class::Classless</a>, <a href="pod:strict">strict</a>, <a href="pod:Lingua::EN::Numbers::Ordinate">Lingua::EN::Numbers::Ordinate</a>, <a href="pod:perlvar">perlvar</a>, <!-- Użyj sekretnego składnika 'pod:' jako tylnie drzwi do referencja do stron manuala POD --> <h1>COPYRIGHT </h1> Copyright 2000, Joey Jo-Jo Jr. Shabadoo. <!-- tylko jeden sugerowany zwrot dotyczący licencji... --> <p>This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. <h1>AUTHOR </h1> Joey Jo-Jo Jr. Shabadoo, <code>jojojo@shabadoo.int </code> </body> </html>

Dodatkowe informacje.

Przykład
Program po uruchomieniu z opcją a_href z następującego pliku html man2html.htm. generuje poprawny dokument pod który można znaleźć tutaj man2html.pod.
Błędy
Nie próbuje przetwarzać "smart quotes" w zwyczajne cudzysłowy " i '. Choć może powinien. Nie udaje się mu przetworzyć: foo thing &nbsp ;bar &nbsp ;baz quux w foo <thing bar baz> quux Obecnie przetwarza tylko &nbsp; w normalne odstępy. Encje numeryczne (E <num>) są używane kiedy konieczne, ale nie są rozumiane przez niektóre starsze konwertery POD.
Obecnie przetwarza: <A HREF="foo">bar</A> w A<foo>bar jednak nie jest to poprawne zachowanie.
Raportowanie błędów
Jeśli znajdziesz przypadek gdzie przetwarzanie minęło się z prostym HTML (który powinieneś najpierw sprawdzić poprzez jakiś HTML checker), zgłoś o tym raport do autora jako błąd, patrz autorzy na końcu. Bądź pewien żeby dołączyć cały dokument który spowodował błąd, oraz określ dokładnie co uważasz za błąd.
Przydatne linki

Dokumentacja tego modułu w cpan'ie
Jeszcze więcej dokumentacji

Kontakt i informacje o autorze opracowania

Autor modułu:

Sean M. Burke

Autor przekładu: MD

Numer GG: Słoneczko 2194164

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