On Nov 15, 2005, at 9:40, Gabriel Berriz wrote:
I understand this is a FAQ but I have not been able to find the
answer: is there a way to include chunks of POD within another POD,
something in the same spirit of a C #include?
We do this pretty extensively in POD book manuscripts. Particularly
for Hacks books, where each chapter is a collection of independent
sections called "hacks". During development of the book, hacks are
frequently reordered or moved to different chapters, so maintaining
monolithic chapters becomes painful quickly. Instead, we keep one
file for each chapter that has the introduction text for the whole
chapter and a list of hacks to import, then have separate files for
each hack.
The way we currently do it is quite ugly: we preprocess the chapter
files treating L<> tags as names of .pod files to import, then run
the resulting combined file through an ordinary POD processor.
On Nov 18, 2005, at 20:22, Sean M. Burke wrote:
And logically, I guess the inclusion would have to happen at parse-
time -- we couldn't very well turn "=include whatever" into a
construct that meant the same thing in the target language, given
that few target languages have such a construct anyway.
I like "=include filename". I agree paths are problematic. They'll
probably quickly find people wishing for something like a "=uselib
path" directive. Ignoring paths is probably okay, but I'd have to use
it for a while in real life situations before I got a good sense of
whether it's too limiting or just limiting enough.
Incidentally, this is tangential to, but quite distinct from the
problem of saying "and now drop in the image foo.png"... in other
formats (HTML comes to mind most), you /can't/ drop in the raw
image data, so there has to be particularly clever changes to the
pathname...
In some ways images are more of a distribution problem than a POD
problem. That is, if you're going to ship images with your module,
you need a standard place to put them in the distribution or a way to
indicate where they're located to Makefile.PL/Build.PL, and a
standard installation location for them (with the html formatted
documents, I guess).
Our book manuscripts currently use:
=begin figure Caption text for figure.
Z<cross_ref_endpoint_for_figure>
F<figs/filename.gif>
=end figure
Less ugly than the includes, but still ugly. Pod::PsuedoPod::HTML
does no path munging (the files are provided in a path relative to
the POD file), it just translates the F<> formatting code directly
into an <img src...> tag (and outputs some extra stuff for the
caption). This isn't a particularly robust solution, and I wouldn't
want to inflict it on Graham Barr and Jon Allen, who do large scale
POD crunching, but it works in the relatively controlled environment
of a publishing company.
Which brings me to my bit of philosophizing: I generally feel
Pod::Simple should be conservative, and extensions like these belong
in subclasses. But then, there are also exceptions to any rule
(features become standard in Perl 6, or so widely known and loved
that we can't live without them, etc).
Allison
