Převod souboru POD do PDF

Čtečka, tiskový pracovní postup nebo systém správy dokumentů může vyžadovat PDF namísto zdrojového formátu POD jazyka Perl. Převod POD nejprve do HTML spolehlivěji zachová nadpisy, seznamy, příklady kódu a odkazy než zpracování zdroje jako prostého textu.

Co je formát POD

POD znamená Plain Old Documentation, odlehčený značkovací jazyk jazyka Perl určený k dokumentaci programů a modulů. Běžně se objevuje v samostatných souborech .pod a uvnitř souborů .pm nebo .pl. Direktivy jako =head1, =over, =item a =cut definují nadpisy, seznamy a hranici mezi dokumentací a kódem jazyka Perl.

Distribuce jazyka Perl, balíčky CPAN, repozitáře zdrojového kódu jazyka Perl, pracovní postupy se zdroji unixových manuálových stránek a archivy dokumentace pro vývojáře používají POD. Soubor POD obsahuje zdrojové značky, nikoli dokument určený k rozvržení stránky, takže jeho výsledný vzhled závisí na vykreslovači.

Co je formát PDF

PDF je dokumentový formát orientovaný na stránky, který dokáže v různých operačních systémech zachovat stránkování, písma, obrázky, odkazy, metadata a nastavení tisku. Hodí se k tisku, jako příloha e-mailu, pro archivní kopie, systémy správy dokumentů a zařízení bez jazyka Perl nebo vykreslovače POD.

PDF se strukturálně upravuje obtížněji než POD. Po vytvoření PDF si ponechte původní soubor .pod, .pm nebo .pl jako upravitelný zdroj.

Jak lokálně převést POD do PDF

Vygenerujte HTML pomocí pod2html

1. Nainstalujte Perl. Linux a macOS ho často obsahují; v systému Windows poskytuje Strawberry Perl Perl a standardní nástroje POD.
2. Otevřete terminál v adresáři obsahujícím zdrojový soubor a spusťte:

pod2html --outfile=manual.html manual.pod

Stejný příkaz může načíst modul nebo skript jazyka Perl obsahující POD:

pod2html --outfile=manual.html Module.pm

Vykreslí se pouze dokumentace POD; kód jazyka Perl mimo sekce POD se nespouští ani nepřevádí na formátovaný zdrojový kód.

Vytiskněte HTML jako PDF

1. Otevřete manual.html v prohlížeči Chrome, Chromium, Microsoft Edge nebo Firefox.
2. Vyberte Print, zvolte Save as PDF nebo Microsoft Print to PDF, vyberte velikost papíru a okraje a uložte výstup jako manual.pdf.
3. Grafiku na pozadí povolte pouze tehdy, když šablona stylů používá pozadí. Zkontrolujte záhlaví, zápatí, konce stránek, odkazy, odsazení kódu a konečný počet stránek.

Automatizujte výstup PDF z prohlížeče

Chrome nebo Chromium mohou vytvořit PDF bez otevření tiskového dialogu:

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

Nahraďte chromium názvem google-chrome nebo názvem spustitelného souboru nainstalovaného v systému. Použijte absolutní adresu URL file://; relativní cesty mohou v příkazech bezhlavého prohlížeče selhat.

Ovládejte rozvržení pomocí CSS

Pro nadpisy, bloky kódu a okraje stránek předejte při generování HTML šablonu stylů:

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

Tiskové CSS může definovat okraje stránek a omezit nevhodné rozdělení bloků kódu:

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

Nastavení tisku prohlížeče stále řídí velikost papíru, záhlaví, zápatí, měřítko a vykreslování pozadí. Lokální šablona stylů nebo obrázek odkazovaný relativní cestou musí zůstat dostupný při otevření HTML.

Možnosti online převodu

Přímá podpora převodu .pod do PDF je neobvyklá, protože přípona .pod může označovat nesouvisející typy souborů a mnoho konverzních služeb neobsahuje analyzátor Perl POD. U souboru, který neobsahuje důvěrné informace, vygenerujte manual.html lokálně pomocí pod2html a poté odešlete HTML do důvěryhodné služby pro převod HTML do PDF, například CloudConvert, pokud lokální převod v prohlížeči není k dispozici.

Předtím, než se na výstup spolehnete, ověřte, že služba přijímá HTML a zachovává propojené CSS, obrázky, Unicode a hypertextové odkazy. Nenahrávejte proprietární zdrojový kód ani soukromou dokumentaci, pokud podmínky poskytovatele týkající se uchovávání, přenosu a mazání dat nejsou přijatelné; po převodu nahrané soubory odstraňte, pokud to služba umožňuje.

Kontroly kvality a kompatibility

pod2html interpretuje sémantiku POD, ale přesně nereprodukuje výstup terminálu, formátování unixových manuálových stránek ani vlastní styly vykreslovačů jazyka Perl. Nepodporované formátovací direktivy mohou být ignorovány a odkazy na místní soubory, nainstalované moduly nebo vygenerované manuálové stránky nemusí v PDF fungovat.

Zkontrolujte vnořené seznamy, odsazení doslovného kódu, escapované znaky, symboly Unicode, hypertextové odkazy, tabulky, obrázky a konce stránek. Prázdné čtverečky obvykle označují chybějící znak; v prohlížeči nebo CSS použijte písmo s podporou Unicode. Velmi dlouhé bloky kódu se mohou rozdělit mezi stránky i přes break-inside: avoid, protože prohlížeče někdy nedokážou udržet příliš velký blok na jedné stránce.