Moduł Pod::Man

Ta strona jest kopią starej strony, którą utrzymywałem na serwerze Manta. Serwer ten już nie istnieje, strona jest bardzo stara, i możliwe, że większość odsyłaczy już nie działa.

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.

• center

Ustawia wyśrodkowany nagłówek strony zamiast "User Contributed Perl Documentation".

• date

Ustawia lewostronne wyrównanie. Domyślnie używana jest data modyfikacji pliku wejściowego, bądź też bieżąca data jeśli stat() nie może znaleźć pliku (przypadek kiedy wejście pochodzi ze standardowego wejścia), data zostanę przetworzona do formatu YYYY-MM-DD.

• fixed

Stała szerokość czcionki która ma zostać użyta w tekście i kodzie. Domyślnie CW. Niektóre systemy zamiast tego chcą CR. Ma to znaczenie tylko dla wyjścia troff.

• fixedbold

Pogrubiona wersja czcionki. Domyślnie CB. Ma znaczenie jedynie dla wyjścia troff.

• fixeditalic

Wersja z Kursywą czcionki. Domyślnie CI. Ma znaczenie jedynie dla wyjścia troff.

• fixeditalic

Wersja z pogrubieniem oraz kursywa czcionki. Domyślnie CI. Ma znaczenie jedynie dla wyjścia troff.

• name

Ustawia nazwę strony podręcznika. Bez tej opcji, nazwa podręcznika ustawiana jest na nazwę(przetworzoną na duże litery) bazową pliku przetwarzanego. Jeśli jest to ścieżka w postaci .../lib/Pod/Man.pm zostaje przetworzona na nazwę Pod::Man. Ta opcja, jeśli jest dana nadpisuje każdą automatyczne określanie nazwy.

• quotes

Ustawienie znaków cudzysłowu aby otaczały tekst C<>. Jeśli wartością jest pojedyńczy znak, jest używany zarówno jako lewy oraz prawy cudzysłów; jeśli natomiast dwa znaki, pierwszy używany jest jako lewy cudzysłów a drugi jako prawy; natomiast jeśli są to cztery znaki, dwa pierwsze używane są jako lewy cudzysłów natomiast następne dwa jako prawy.

Może również tyć ustawione jako specjalna wartość none, w takim przypadku cudzysłów nie zostanie użyty.

• release

Ustawia wyśrodkowane wyrównanie. Domyślnie jest to wersja Perla pod którą uruchomiłeś Pod::Man. Zwróć uwagę że niektóre zbiory makr zakładają, że wyśrodkowane wyrównanie będzie datą modyfikacji i będzie poprzedzone czymś w rodzaju "Last modified:".

• section

Ustawia paragraf dla makra .TH. Standardową konwencją numerowania paragrafów jest używanie jest 1 dla komend użytkownika, 2 dla wywołań systemowych, 3 dla funkcji, 4 dla urządzeń, 5 dla formatu plików, 6 dla gier, 7 dla rozmaitych informacji, 8 dla komend administratora. Jest bardzo wiele wariantów, jednakże niektóre systemy (np. solaris) używają 4 dla formatu plików, 5 dla rozmaitych informacji, oraz 7 dla urządzeń. Ciągle inne używają 1m zamiast 8, bądź też mieszankę obu. O jednych numerach paragrafu na których można polegać są 1, 2, 3.

Domyślnie paragraf 1 będzie używany dopóki skończy sie plik w .pm, w takim przypadku paragaf 3 zostanie wybrany.

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

[c] Piotr Arłukowicz, materiały z tej strony udostępnione są na licencji GNU.