Konwertuj POD na PDF

Reader, workflow drukowania lub system zarządzania dokumentami może wymagać formatu PDF zamiast formatu źródłowego POD języka Perl. Najpierw konwersja POD do HTML pozwala bardziej niezawodnie zachować nagłówki, listy, przykłady kodu i łącza niż traktowanie źródła jako zwykłego tekstu.

Czym jest format POD

POD oznacza Plain Old Documentation — lekki język znaczników języka Perl służący do dokumentowania programów i modułów. Często występuje w samodzielnych plikach .pod oraz wewnątrz plików .pm lub .pl. Dyrektywy takie jak =head1, =over, =item i =cut definiują nagłówki, listy oraz granicę między dokumentacją a kodem Perl.

Dystrybucje Perl, pakiety CPAN, repozytoria źródłowe Perl, przepływy pracy z kodem źródłowym stron podręcznika Unix oraz archiwa dokumentacji dla programistów używają POD. Plik POD zawiera znaczniki źródłowe, a nie dokument układu strony, dlatego jego ostateczny wygląd zależy od renderera.

Czym jest format PDF

PDF to zorientowany na strony format dokumentów, który może zachowywać podział na strony, czcionki, obrazy, łącza, metadane i ustawienia drukowania w różnych systemach operacyjnych. Nadaje się do drukowania, załączników wiadomości e-mail, kopii archiwalnych, systemów zarządzania dokumentami oraz urządzeń bez języka Perl lub renderera POD.

PDF jest trudniejszy do strukturalnej edycji niż POD. Po utworzeniu pliku PDF zachowaj oryginalny plik .pod, .pm lub .pl jako źródło do edycji.

Jak lokalnie przekonwertować POD do PDF

Wygeneruj HTML za pomocą pod2html

1. Zainstaluj Perl. Linux i macOS często zawierają go już w systemie; w systemie Windows Strawberry Perl udostępnia Perl oraz standardowe narzędzia POD.
2. Otwórz terminal w katalogu zawierającym plik źródłowy i uruchom:

pod2html --outfile=manual.html manual.pod

To samo polecenie może odczytać moduł lub skrypt Perl zawierający POD:

pod2html --outfile=manual.html Module.pm

Renderowana jest wyłącznie dokumentacja POD; kod Perl znajdujący się poza sekcjami POD nie jest wykonywany ani konwertowany do sformatowanego kodu źródłowego.

Wydrukuj HTML jako PDF

1. Otwórz plik manual.html w przeglądarce Chrome, Chromium, Microsoft Edge lub Firefox.
2. Wybierz opcję Print, wybierz Zapisz jako PDF lub Microsoft Print to PDF, ustaw rozmiar papieru i marginesy, a następnie zapisz wynik jako manual.pdf.
3. Włącz grafikę tła tylko wtedy, gdy arkusz stylów używa teł. Sprawdź nagłówki, stopki, podziały stron, łącza, wcięcia kodu oraz końcową liczbę stron.

Automatyzacja generowania PDF przez przeglądarkę

Chrome lub Chromium mogą utworzyć plik PDF bez otwierania okna dialogowego drukowania:

chromium --headless --disable-gpu --print-to-pdf=manual.pdf file:///absolute/path/manual.html

Zastąp chromium nazwą google-chrome lub nazwą pliku wykonywalnego zainstalowanego w systemie. Użyj bezwzględnego adresu URL file://; ścieżki względne mogą nie działać w poleceniach przeglądarki działającej w trybie headless.

Kontrolowanie układu za pomocą CSS

Aby kontrolować nagłówki, bloki kodu i marginesy stron, podaj arkusz stylów podczas generowania HTML:

pod2html --css=manual.css --title="Manual" --outfile=manual.html manual.pod

CSS drukowania może definiować marginesy stron i ograniczać niepożądane dzielenie bloków kodu:

@page { margin: 20mm; } pre { break-inside: avoid; }

Ustawienia drukowania przeglądarki nadal kontrolują rozmiar papieru, nagłówki, stopki, skalowanie i renderowanie tła. Lokalny arkusz stylów lub obraz odwołujący się do ścieżki względnej musi pozostać dostępny podczas otwierania pliku HTML.