Moduł Pod::Man

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

Co to jest?

Przetwarza dane w formacie POD do formatowanego wejścia *roff.

Składnia
use Pod::Man; my $parser = Pod::Man->new (release => $VERSION, section => 8); # Czyta ze standardowego wejścia i zapisuje na standardowe wyjście. $parser->parse_file (\*STDIN); # Czyta z pliku file.pod i zapisuje w pliku file.1. $parser->parse_from_file ('file.pod', 'file.1');

Pod::Man jest to moduł do przetwarzania dokumentów w formacie POD (preferowany język dokumentacji perla) do wejścia *roff używającego zbioru makr podręcznika (man). Wynikowy kod *roff jest odpowiedni do wyświetlania na terminalu używając nroff(1), normalnie poprzez man(1), bądź też wydrukowania używając troff(1). Jest to wywoływane standardowo używając skryptu sterującego pod2man, ale może być to użyte bezpośrednio.

Aby choć trochę można było zrozumieć co to wszystko oznacza trzeba wytłumaczyć kilka pojęć. Tak więc. Man jest to narzędzie do wyświetlania stron pomocy man, stosowane w systemach Uniks i uniksopodobnych. Nazwa jest skrótem od ang. Manual - instrukcja obsługi. Aby man mógł wyświetlić potrzebną nam pomoc wcześniej musi ona sformatowana za pomocą innych narzędzi. Jednym z pierwszych takich właśnie narzędzi dostępnych w systemach uniksowych był roff(program formatujący tekst), był on również poprzednikiem następnych doskonalszych narzędzi takich jak nroff oraz troff.

Jako klasa wywodząca się z Pod::Simple, Pod::Text wspiera te same metody oraz interfejsy. Zobacz Pod::Simple aby zapoznać się z detalami.

new() przyjmuje opcje w postaci par klucz/wartość które kontrolują zachowanie parsera. Spójrz niżej aby zapoznać się z detalami.

Jeżeli żadne opcje nie są dane, Pod::Man używa nazwy pliku wejściowego z odciętym rozszerzeniem .pod, .pm, lub .pl do tytułu strony podręcznika, do sekcji 1 chyba że plik ma rozszerzenie .pm w takim przypadku domyślnie do sekcji 3, do wyśrodkowanego tytułu "User Contributed Perl Documentation", do wyśrodkowanego wyrównania wersji perla na której jest uruchomiony, oraz do lewego wyrównania daty modyfikacji wejścia (data bieżąca jeśli dane wejściowe pobierane są ze standardowego wejścia).

Pod::Man zakłada, że twój *roff ma stałą szerokość czcionki o nazwie CE. Jeśli twoje nazywają się jakoś inaczej (np.CR), użyj opcji fixed aby ją określić. To generalnie ma znaczenie tylko dla wyjścia troff do drukowania. Podobnie możesz ustawic czcionkę używającą pogrubienia, kursywy, oraz pogrubionej kursywy o stałej szerokości.

Poza zachowaniem konwencji pod, Pod::Man również dba o formatowanie func(), func(3), oraz proste referencje zmiennych jak $foo bądź @bar więc nie musiszą być zastępowne specjalnym kodem aby zostały wyświetlone; złożone wyrażenia jak $fred{'stuff'}, wciąż będą musiały być potraktowane specjalnie. Srawia że ALLCAPS są o troszkę mniejsze w troff'ie, oraz przetwarza specjalne sekwencje które *roff traktuje jako specjalne więc ty już nie musisz.

new() przyjmuje nastepujące argumenty.

Standardowo metoda parse_from_file() z modułu Pod::Simple pobiera jeden argument, plik bądź też uchwyt do pliku z którego należy czytać, oraz pisze na standardowe wyjście, chyba że zostało to zmienione za pomocą metody output_fd().

Możesz również wywołać parse_lines() aby przetwarzać tablice linii bądź parse_string_document() do przetwarzania dokumentu który znajduje się już w pamięci. Aby ustawić wyjście do napisu zamiast do uchwytu pliku wywołaj metodę output_string(). Zobacz Pod::Simple aby poznać dokładniejsze szczegóły oraz inne alternatywne interfejsy.

Diagnostyka

roff font should be 1 or 2 chars, not "%s"

Jeśli określiłeś czcionkę *roff która nie była jedno bądź dwu znakowa. Pod::Man nie obsługuje czcionek *roff dłuższych niż dwu znakowe, mimo, że niektóre rozszerzeń *roff obsługują.

Invalid quote specification "%s"

Dane parametry cudzysłowu (opcja quotes w konstruktorze) były błędne. Określenie cudzysłowu musi być długości jeden, dwa bądź czterech znaków.

Dodatkowe informacje.

Przykład użycia
use Pod::Man; my $parser = Pod::Man->new (release => $VERSION, section => 8); $parser->parse_from_file ('Pdf.pm', 'file.1');

Program ten przekształca prosty dokument pod Pdf.pm w plik który może zostać wyświetlony za pomocą polecenia man. Wynik wyświetlony jest niżej:


Przydatne linki

Dokumentacja tego modułu w cpan'ie

Kontakt i informacje o autorze opracowania

Autor modułu:

Dave Cross z pomocą Leona Brocarda.

Autor przekładu: MD

Numer GG: Słoneczko 2194164

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