Dear monks,

I'd like to profit from your experience. Here is the story:

I was tester for Alan Fry's Pod2Pdf. This module does a very good but somehow limited job. Alan developed it for Mac users because the MacPerl companion Shuck for viewing POD documentation cannot print. He produces a well formatted and printer ready PDF without using commercial tools, very handy.

On the other hand I love (hate) LaTeX. The "pod2latex" script from the standard Perl distribution is outdated and not maintainable I think. This is because it sends the POD text through Pod::Plainer and then parses itself. The handcrafted parser is a big puzzle, running without strict, ... my life would be too short to understand the code.

A dutch guy developed some nice enhancements ("pod2ltx"). He uses pod2latex code and sends the LaTeX output through "pdflatex" which generates very nice PDFs (bookmarks, hyperlinks, table of contents, index). I tried to contribute to this script but stopped for he still relies on the old parsing code and because I discovered Pod::LaTeX. Now responsibility for parsing is within that module, part of the core distribution and much more flexible.

Pod::LaTeX lacks some features though. For instance I really want to have 8 bit european characters output when the author uses his natural language. Not many authors really care to write "E<lt>", they simply use "<" in the Pod. Some important information must be extracted from .xs files.

Now it is relatively easy to develop a wrapper script which preprocesses pod files parses with Pod::LaTeX and starts the whole LaTeX engine.

Why I ask here is simply because I can imagine quite a few number of knowledgable people did something similar to create a nice PDF from POD.

What do you think?


Best regards, Axel.

Replies are listed 'Best First'.
Re: pod-latex-pdf
by Dog and Pony (Priest) on Jun 20, 2002 at 21:55 UTC
    Why I ask here is simply because I can imagine quite a few number of knowledgable people did something similar to create a nice PDF from POD.
    While I haven't actually tried these myself (yet), I found these two on CPAN for someone a while back, and seem to recall getting some positive reviews on one or the other: Pod::HtmlPsPdf and Pod::Pdf.

    Yeah, I know, i should try them to see if they are any good before recommending them, and to know which to recommend if any. :)

    You may have reasons for wanting to go via LaTeX though, which eludes me since I don't know LaTeX. Apologies if those are of no interest. :)

    You have moved into a dark place.
    It is pitch black. You are likely to be eaten by a grue.
[reply]
[reply]

      The reasoning behind using LaTeX is to have full control over the layout, fonts, etc.

      pdflatex can produce very professional output, see e.g. http://www.pragma-ade.nl for samples.

      Another important point is using POD for diffent type of documentation. I think the whole Perl Cookbook was written with enriched POD.

[reply]
        Ah, I rather thought it might be something like that, but decided to provide what I could anyways. :) And perrin provided an excellent example on how good the result good be above (I downloaded those PDF's and it was very nice IMO).

        As for using POD for documentation, I wholeheartedly agree. I am trying to write more and more stuff in POD for this reason, including company docs that can be transfered to other formats. I'm not there yet, but I am trying.

        As for books, I don't know about the Cookbook, as I don't own it, but the Camel book says it was written entirely in POD. It is mentioned in the POD chapter among other places. So it is definetely good enough. :) As the authors say themselves:

        We don't claim that pod is sufficient for writing a book, although it was sufficient for writing this one.

        Personally, I think one of the absolute best things with POD is that it is also easy to read unprocessed. There are no other formats I know about, that is as easy. Note that I said "that I know about", though. And plain text doesn't really count either, because it doesn't contain any processing instructions. :)

        You have moved into a dark place.
        It is pitch black. You are likely to be eaten by a grue.
[reply]
Re: pod-latex-pdf
by gumby (Scribe) on Jun 20, 2002 at 21:36 UTC
    For significant project work, or simply work that would benefit from nicely formatted documentation, I nearly always use Pod::LaTeX to produce PostScript/PDF files from my POD.
[reply]
[d/l]
Re: pod-latex-pdf
by stajich (Chaplain) on Jun 21, 2002 at 20:25 UTC
    You can also convert POD to Docbook SGML using Pod::DocBook tool pod2docbook and then produce lovely PDF using OpenJade. On RH Linux this is really just a few RPMs (docbook and jade RPMs) plus the CPAN install of pod2docbook. Basically 
    % pod2docbook myfile.pod > myfile.sgml

    [download]
    If you want to avoid a bunch of error messages you need to make two small edit depending on where your docbook is installed and what version you are using. I show the 1-liner to convert to 4.1 here YMMV. It is actually not necessary to do this, but you'll get a screenful. 
    % perl -e 'while(<>){unless($f++){s/Davenport/OASIS/;s/2\.4\.1/4.1/;s/
+\"\/opt.+\"//;}print}'

    [download]
    Now convert to TeX 
    % openjade -t tex -d /usr/share/sgml/docbook/dsssl-stylesheets/print/d
+ocbook.dsl mfile.sgml

% pdfjadetex myfile.tex

    [download]
    If you wanted RTF you would just replace -t tex with -t rtf. HTML also available. When you get fancy you can make up your own stylesheets so you can have a custom layout/fontsets/etc.

    Update, its easier than that... 

    % docbook2pdf myfile.sgml

    [download]

    Other Sites:

    I hope that is helpful, I'm finding myself rather fond of docbook suddenly, thought I'd share.
[reply]
[d/l]
[select]

Back to Meditations