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.
