bug#15848: 24.3.50; cperl-mode + which-function: Improve reporting (corner case)

[Nathan Trapuzzano]

Jambunathan K <kjambunathan@gmail.com> writes:

> Your patch looks good.  Thanks.
>
> Before trying the patch, I had the "wrong" impression that headN lines
> won't be displayed in 
>
>     Perl->Tools->Imenu-POD headers menu entry.  
>
> I see that Imenu still shows the perldoc headers.
>
> So
>
>     cperl-imenu-index-pod is a variable defined in `cperl-mode.el'.
>     Its value is t
>
>     Documentation:
>     *Whether POD `=head' directives should be indexed by imenu.
>
> the first line of the docstring is misleading.

Perhaps I misunderstand, but when I have that variable set to nil, the
POD imenu entries go away, which is what the docstring says.  Indeed,
which-function-mode uses the imenu index for determining which function
point is in.  I don't know how often which-function-mode calls the
indexing function, so make sure you have the variable set before
visiting the file.  Try again and let me know.

> ----------------------------------------------------------------
>
> Btw, if you are convinced that what this patch does is "the norm" rather
> than "an exception", you may as well consider removing the variable.
>
> ----------------------------------------------------------------

I do think it's better to say that the definitions begin earlier than
what cperl currently says (though it's not a "bug").  However, I think
indexing the POD entries by default is the better way for several
reasons:

1. cperl-mode already does it that way.
2. perl-mode does it.
3. There is no "pod-mode".  For editing pod files, perl-/cperl-mode is
   the best Emacs has.  Moreover, many people _do_ write plain pod
   files, in which case the entries should get indexed.