Re: problems in one or more man pages you maintain

Casey West <[email protected]>:
> It was Tuesday, December 09, 2003 when [email protected] took the soap box, saying:
> : This is automatically generated email about problems in a man page for which
> : you appear to be responsible.  If you are not the right person or list, tell
> : me and I will attempt to correct my database.
> : 
> : See http://catb.org/~esr/doclifter/problems.html for details on how and
> : why these patches were generated.  Feel free to email me with any questions.
> : 
> : Problems with DynaLoader.3pm:
> : 1. There are multiple name lines.  This makes it impossible to translate
> : the page to DocBook.  It may also confuse some implementations
> : of man -k.
> [sniped bad patch]
> : Problems with Getopt::Std.3pm:
> : 1. There are multiple name lines.  This makes it impossible to translate
> : the page to DocBook.  It may also confuse some implementations
> : of man -k.
> [sniped bad patch]
> : Problems with perlce.1:
> : 1. Missing or garbled name section.  The most common form of garbling
> : is a missing - or extra -. Or your manual page may have been generated
> : by a tool that doesn't emit a NAME section as it should.  These
> : problems make it impossible to lift the page to DocBook.  They
> : can also confuse some implementations of man -k.
> [sniped bad patch]
> 
> This one was fixed in a recent version of Perl.  For the others, see
> the patch below.  They make your system happy, but I don't know if
> they're a correct implementation.

I'll mark the perlce fix pending, then.

> diff -ru perl-current-orig/ext/DynaLoader/DynaLoader_pm.PL perl-current/ext/DynaLoader/DynaLoader_pm.PL
> --- perl-current-orig/ext/DynaLoader/DynaLoader_pm.PL   Sun Nov  2 14:41:32 2003
> +++ perl-current/ext/DynaLoader/DynaLoader_pm.PL        Tue Dec  9 16:32:10 2003
> @@ -508,8 +508,7 @@
>  
>  =head1 NAME
>  
> -DynaLoader - Dynamically load C libraries into Perl code
> -
> +DynaLoader - Dynamically load C libraries into Perl code;
>  dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_unload_file(), dl_find_symbol(), dl_find_symbol_anywhere(), dl_undef_symbols(), dl_install_xsub(), dl_load_flags(), bootstrap() - routines used by DynaLoader modules
>  
>  =head1 SYNOPSIS

You sure you din't get this patch reversed?  The removed line is good
(though technically that - should be \-; doclifter can cope with -
but some man -k implementations might not).  The replacement isn't good.


> diff -ru perl-current-orig/lib/Getopt/Std.pm perl-current/lib/Getopt/Std.pm
> --- perl-current-orig/lib/Getopt/Std.pm Tue Sep 16 16:06:11 2003
> +++ perl-current/lib/Getopt/Std.pm      Tue Dec  9 16:32:52 2003
> @@ -4,9 +4,7 @@
>  
>  =head1 NAME
>  
> -getopt - Process single-character switches with switch clustering
> -
> -getopts - Process single-character switches with switch clustering
> +getopt, getopts - Process single-character switches with switch clustering
>  
>  =head1 SYNOPSIS
>  

Good, though the - ought to be \-
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>