pod-latex-pdf

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.

Comment on pod-latex-pdf

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]
Re: Re: pod-latex-pdf by perrin (Chancellor) on Jun 20, 2002 at 22:56 UTC
You can see Pod::HtmlPsPdf in action on http://perl.apache.org/guide/ the mod_perl site. It generates this section from POD.	[reply]
Re: Re: pod-latex-pdf by axelrose (Scribe) on Jun 21, 2002 at 10:41 UTC
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]
Re(3): pod-latex-pdf by Dog and Pony (Priest) on Jun 21, 2002 at 13:57 UTC
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: Docbook SF site docbook.org I hope that is helpful, I'm finding myself rather fond of docbook suddenly, thought I'd share.	[reply] [d/l] [select]


Don't ask to ask, just ask
	PerlMonks