Bug#722539: mention random headers are generated

[Russ Allbery]

jidanni at jidanni.org writes:

> Package: perl-doc
> Version: 5.18.1-3
> Severity: wishlist
> File: /usr/share/man/man1/perldoc.1.gz

>        -f perlfunc
>             The -f option followed by the name of a perl built-in
>             function will extract the documentation of
>             this function from perlfunc.

>             Example:

>                   perldoc -f sprintf

> This should mention that it makes
> 2CKH0M1AL6(1) User Contributed Perl Documentation 2CKH0M1AL6(1)
> random headers, else it looks like a bug.

> Better yet would be saying
> "Extract from PERLFUNC(1)" or something.

This is because the default formatter for perldoc is nroff and nroff with
the man macro set requires things that aren't really appropriate for
function documentation.  It has a very fixed idea about how headings and
the like should work.

Personally, as the author of many of the formatting modules involved, I've
always just aliased perldoc to perldoc -t to use the text formatter.  I
don't feel like the small amount of formatting nroff does is worth the
extra confusion around things like headers, the additional outdenting, and
the need to cobble together a fake man page under the hood.

-- 
Russ Allbery (rra at debian.org)               <http://www.eyrie.org/~eagle/>