[ Added [EMAIL PROTECTED] to the Cc: list because the
Pod/Man.pm file concerned by the patch below is in that package. ]
* A. Costa <[EMAIL PROTECTED]> [2005-04-14 13:40]:
> On Wed, 13 Apr 2005 15:33:20 +0200
> Rafael Laboissiere <[EMAIL PROTECTED]> wrote:
>
> > ...We should
> > consider the NAME section of a manpage as a kind of machine-readable
> > description. For instance, it would make no sense to have markups like
> > bold and italics in it.
> >
> > However, *(C` and *(C' represent quotes and, since quotes can be safely
> > represented in ascii with '"', the authors of the POD sections in
> > packages concerned by this bug report should make this change.
>
> Wouldn't it be simpler to change the 'Pod::Man' code to filter out (or
> safely translate) the NAME section cruft?
>
> Pros/cons:
> 1) Only one package to change versus Several packages to change.
> 2) Fixes the problem forever vs It may happen again (more
> bugs).
> 3) POD authors not involved vs POD authors must be told, and
> must learn new stuff.
Looking at the code in Pod/Man.pm, I see that there are already
provisions for doing some cleanup of the *roff output when in the NAME
section. I came out with the trivial, one-line patch attached below
which fixes the problem.
Running pod2man with the modified Pod/Man.pm yields the following difference
in the PDL::Reduce.3pm man page:
$ diff -u PDL::Reduce.3pm PDL::Reduce.3pm-new
--- PDL::Reduce.3pm 2005-04-15 11:02:54.082755056 +0200
+++ PDL::Reduce.3pm-new 2005-04-15 11:05:21.948276080 +0200
@@ -129,9 +129,9 @@
.\" ========================================================================
.\"
.IX Title "Reduce 3pm"
-.TH Reduce 3pm "2004-09-07" "perl v5.8.4" "User Contributed Perl
Documentation"+.TH PDL::Reduce 3 "2004-09-07" "perl v5.8.4" "User Contributed
Perl Documentation"
.SH "NAME"
-PDL::Reduce \-\- a \f(CW\*(C`reduce\*(C'\fR function for PDL
+PDL::Reduce \-\- a "reduce" function for PDL
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Many languages have a \f(CW\*(C`reduce\*(C'\fR function used to reduce
--
Rafael
--- Man.pm-orig 2005-04-15 10:56:29.373239792 +0200
+++ Man.pm 2005-04-15 10:55:43.045282712 +0200
@@ -1017,6 +1017,11 @@
# several places in the following regex.
my $index = '(?: \[.*\] | \{.*\} )?';
+ # If in NAME section, just return an ascii quoted string, to avoid
+ # confusing tools like whatis
+
+ return qq{"$_"} if $$self{IN_NAME};
+
# Check for things that we don't want to quote, and if we find any of
# them, return the string with just a font change and no quoting.
m{
