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

From: Nathan Trapuzzano <[email-masked]>
Date: Sun, 10 Nov 2013 11:48:50 -0500

Jambunathan K <[email-masked]> writes:

> perl-mode behaves differently and correctly.  

I think you've misunderstood.  cperl-mode does exactly what it's
supposed to do, which is more than what perl-mode tries to do.

> Is it possible to show the sub name when within a function and show
> the head1 or head2 string when within a perldoc string.  (I am new to
> perl so I can talk only fuzzily about the language or it's features)

It's not really feasible, though it has nothing to do with Perl per se.
Like I said before, the "function" name displayed by which-function-mode
is the function containing point or, if none, the nearest function
before point.  In cperl-mode pod =head directives count for this purpose
as "functions", and regular subroutines begin at the position following
their name.

> My gut feeling is that the way cperl mode treats POD directives also
> limits it from doing outlining.

After a brief skim of the cperl source, I had the opposite impression.

> I would really like to get outlining work when in cperl-mode.

I'll take a look at that later.  With luck, it'll be as easy as this
one.

> I think anything that doesn't show "= " would do for me.

Again, the "= " means that the "current function" (according to the
above definition) is a pod =head directive.

Try the attached patch.  Make sure you set cperl-imenu-index-pod to nil
before invoking cperl-mode.  If it does what you want, we can ask for it
to be installed.

# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: [email-masked]
# target_branch: file:///home/nathan/opt/etc/bzr-repos/emacs/trunk/
# testament_sha1: fd4a0d8284f9bbda92ca8a31dc190cfa3b8adb78
# timestamp: 2013-11-10 11:41:32 -0500
# base_revision_id: [email-masked]
# 
# Begin patch
=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog	2013-11-10 08:35:04 +0000
+++ lisp/ChangeLog	2013-11-10 16:20:47 +0000
@@ -1,3 +1,10 @@
+2013-11-10  Nathan Trapuzzano  <[email-masked]>
+
+	* progmodes/cperl-mode.el (cperl-imenu-index-pod)
+	(cperl-imenu--create-perl-index): Define and implement
+	`cperl-imenu-index-pod' to optionally disable cperl's indexing of
+	POD directives for imenu.  (Bug#15848)
+
 2013-11-10  Michael Albinus  <[email-masked]>
 
 	* net/tramp.el (tramp-methods):

=== modified file 'lisp/progmodes/cperl-mode.el'
--- lisp/progmodes/cperl-mode.el	2013-11-04 03:44:23 +0000
+++ lisp/progmodes/cperl-mode.el	2013-11-10 16:15:36 +0000
@@ -511,6 +511,13 @@
   :type 'boolean
   :group 'cperl-help-system)
 
+(defcustom cperl-imenu-index-pod t
+  "*Whether POD `=head' directives should be indexed by imenu.
+Non-nil means `which-function-mode' won't count POD directives as
+top-level definitions."
+  :type 'boolean
+  :group 'cperl-help-system)
+
 (defcustom cperl-max-help-size 66
   "*Non-nil means shrink-wrapping of info-buffer allowed up to these percents."
   :type '(choice integer (const nil))
@@ -844,7 +851,8 @@
                 interactive sweep over the buffer);
         d) Has support for imenu, including:
                 1) Separate unordered list of \"interesting places\";
-                2) Separate TOC of POD sections;
+                2) Separate TOC of POD sections by default
+                   (cf. `cperl-imenu-index-pod');
                 3) Separate list of packages;
                 4) Hierarchical view of methods in (sub)packages;
                 5) and functions (by the full name - with package);
@@ -5551,7 +5559,7 @@
 	      (push index index-alist))
 	    (if meth (push index index-meth-alist))
 	    (push index index-unsorted-alist)))
-	 ((match-beginning 16)		; POD section
+	 ((and cperl-imenu-index-pod (match-beginning 16))	; POD section
 	  (setq name (buffer-substring (match-beginning 17) (match-end 17))
 		marker (make-marker))
 	  (set-marker marker (match-beginning 17))

# Begin bundle