POD Question

nimdokk has asked for the wisdom of the Perl Monks concerning the following question:

I'm doing some documentation using POD and running into a problem with the =begin text and =end text directives. Basically, they are being ignored. I tried this with two different versions of Perl and go the same results, so I know I'm doing something wrong. Here is an example:

=being text

some stuff goes here
and more stuff on a second line
and in a few cases, a few more things on a third line

=end text
[download]

When I run pod2html against that, it disappears. However, when I use =for text, it works the way it should. But in most cases, I have several lines and =for text won't work as nicely for that (I could put a =for text on each line, but that doesn't look as nice). Many thanks.

Comment on POD Question Download Code

Replies are listed 'Best First'.
Re: POD Question by broquaint (Abbot) on Feb 19, 2003 at 17:02 UTC
Perhaps you forgot to check your code before you posted the node but `'=being' ne '=begin'` [download] HTH `_________ broquaint`	[reply] [d/l]
Re: POD Question by jasonk (Parson) on Feb 19, 2003 at 17:05 UTC
Your example says 'being' instead of 'begin', but that probably isn't your real problem. =begin lets you specify a block of data that will be passed directly to the interpreter to either display or ignore. In the case of pod2html, it only displays =begin sections that are labeled 'html' or 'pod2html', all other formats are ignored. You could always try this: `=begin html <PRE> text. text. text. </PRE> =end` [download]	[reply] [d/l]
Re: Re: POD Question by nimdokk (Vicar) on Feb 19, 2003 at 17:26 UTC
Thanks, got it working.	[reply]
Re: POD Question by jmcnamara (Monsignor) on Feb 19, 2003 at 17:13 UTC
Pod processors can decide whether they wish to support `=begin` sections or not. For example pod2text will recognise `=begin text` but pod2html won't. If you wish to generate a <pre> block with pod2html you should indent the paragraph: `The next section will appear in a <pre> block some stuff goes here and more stuff on a second line and in a few cases, a few more things on a third line` [download] -- John.	[reply] [d/l]
Re: POD Question by hardburn (Abbot) on Feb 19, 2003 at 17:05 UTC
"=begin" starts a block that is only parsed by the named POD translater (in this case, the text translater). If you said "=begin html", then only the HTML parser would pick up on the accompanying block. Having another translater not pick that section up is defined behavior. ---- Reinvent a rounder wheel. Note: All code is untested, unless otherwise stated	[reply]
Re: POD Question by hv (Prior) on Feb 19, 2003 at 17:07 UTC
`=begin text` marks stuff that should only be used by one formatter - pod2text in this case. It is quite correct for pod2html to ignore it. What were you actually trying to achieve with the `=begin text` block? Hugo	[reply] [d/l] [select]