Re: Strange perldoc perldoc

On 12-04-30 11:19 AM, Russ Allbery wrote:
> Shawn H Corey<[email protected]>  writes:
>> On 12-04-30 10:52 AM, Smylers wrote:
>
>>> It didn't used to be verbatim, when the bold formatting was originally
>>> added. That Pod got indented in this Dev release a few months ago:
>>> https://metacpan.org/diff/file/?target=BDFOY/Pod-Perldoc-3.15_10/lib/perldoc.pod&source=BDFOY/Pod-Perldoc-3.15_09/lib/perldoc.pod
>
>> Well, if they wanted it indented, they should have used
>> =over/=back. That's what it was invented for. ;)
>
> I suspect indentation wasn't the goal, but rather preserving formatting.
> There currently isn't any way in POD to preserve line breaks and allow
> inline formatting, which gets a little annoying when writing man pages.
>
> (There's an undocumented hack in pod2man that actually preserves
> formatting in this particular situation even without indentation due to an
> accidental interaction with *roff, but it's not really something to rely
> upon.)
>

With further investigation, I found that pod::perldoc is formatted for 
regular paragraphs in is SYNOPSIS. It's the pod2... that decided that 
anything under SYNOPSIS _must_ be verbatim. Since when was this decided 
and why?


$ head -32 /usr/share/perl/5.12.4/pod/perldoc.pod

=head1 NAME

perldoc - Look up Perl documentation in Pod format.

=head1 SYNOPSIS

B<perldoc> [B<-h>] [B<-D>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]
[B<-i>] [B<-V>] [B<-T>] [B<-r>]
[B<-dI<destination_file>>]
[B<-oI<formatname>>]
[B<-MI<FormatterClassName>>]
[B<-wI<formatteroption:value>>]
[B<-n>I<nroff-replacement>]
[B<-X>]
[B<-L> I<language_code>]
PageName|ModuleName|ProgramName

B<perldoc> B<-f> BuiltinFunction

B<perldoc> B<-L> it B<-f> BuiltinFunction

B<perldoc> B<-q> FAQ Keyword

B<perldoc> B<-L> fr B<-q> FAQ Keyword

B<perldoc> B<-v> PerlVariable

See below for more description of the switches.

=head1 DESCRIPTION


-- 
Just my 0.00000002 million dollars worth,
   Shawn

Programming is as much about organization and communication
as it is about coding.

[updated for today's programmers]
"Show me your code and conceal your interfaces, and I shall continue
to be mystified. Show me your interfaces, and I won't usually need
your code; it'll be obvious."
	-- Fred Brooks

Don't be clever; being great is good enough.