bug#11711: 24.0.95; [PATCH] added imenu and which-func support to rst.el

[Masatake YAMATO <yamato@redhat.com>]

Thank you for reviewing.

>> This is not a bug report. This is a request to merge a patch
>> to the offcial source tree.
> 
>> 2012-06-13  Masatake YAMATO  <yamato@redhat.com>
> 
>> 	* textmodes/rst.el (rst-mode, rst-imenu-index): Added
>> 	imenu and which-func support.
> 
> I'll let the other Stefan decide what to do with it.  It looks
> pretty good for me.  Just a few nitpicks below:

I found I should explain more about to the maintainer.

I know `rst-toc'. People who writes a document in rst format may use
`rst-toc' instead of imenu. However, there is a reason I write this
patch. Sometime I read document writtn in rst file by my colleagues(on
emacs running on a terminal). In such case `which-func' helps me to
understand the document; and `which-func' uses imenu internally.

>> +  ;; Imenu
>> +  (set (make-local-variable 'imenu-create-index-function) 'rst-imenu-index)
>> +
>> +  ;;  Which func
>> +  (when (and (boundp 'which-func-modes) (listp which-func-modes))
>> +    (add-to-list 'which-func-modes 'rst-mode))
>> +
>>    ;; Font lock.
> 
> Try to punctuate your comments.
> 
>> +(defun rst-imenu-find-adornments-for-position (adornments p)
>> +  "Find adornments cell for position P in ADORNMENTS"
> 
> And do punctuate your docstring (C-u M-x checkdoc-current-buffer RET
> might help you catch such things).
> 
> 
>         Stefan

Thanks. Here is revised version.

2012-06-16  Masatake YAMATO  <yamato@redhat.com>

	* textmodes/rst.el (rst-mode): Added imenu and which-func
	supports.
	(rst-imenu-find-adornments-for-position): New function.
	(rst-imenu-convert-cell): Ditto.
	(rst-imenu-index): Ditto.

=== modified file 'lisp/textmodes/rst.el'
--- lisp/textmodes/rst.el	2012-06-07 09:20:41 +0000
+++ lisp/textmodes/rst.el	2012-06-16 22:31:55 +0000
@@ -794,6 +794,13 @@
   (set (make-local-variable 'uncomment-region-function)
        'rst-uncomment-region)
 
+  ;; Imenu.
+  (set (make-local-variable 'imenu-create-index-function) 'rst-imenu-index)
+
+  ;; Which func.
+  (when (and (boundp 'which-func-modes) (listp which-func-modes))
+    (add-to-list 'which-func-modes 'rst-mode))
+
   ;; Font lock.
   (set (make-local-variable 'font-lock-defaults)
        '(rst-font-lock-keywords
@@ -4088,6 +4095,64 @@
     ;; output.
     ))
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Imenu support
+(defun rst-imenu-find-adornments-for-position (adornments p)
+  "Find adornments cell in ADORNMENTS for position P."
+  (let ((a nil))
+    (while adornments
+      (if (and (car adornments)
+	       (eq (car (car adornments)) p))
+	  (setq a adornments
+		adornments nil)
+	(setq adornments (cdr adornments))))
+    a))
+
+(defun rst-imenu-convert-cell (elt adornments)
+  "Convert a cell ELT in a tree returned from `rst-section-tree' to imenu index.
+ADORNMENTS is used as hint information for conversion."
+  (let* ((kar (car elt))
+	 (kdr (cdr elt))
+	 (title (car kar)))
+    (if kar
+	(let* ((p (marker-position (cadr kar)))
+	       (adornments (rst-imenu-find-adornment-for-position adornments p))
+	       (a (car adornments))
+	       (adornments (cdr adornments))
+	       (title (format "%s%s%s"
+			      (make-string (1+ (nth 3 a)) (nth 1 a))
+			       title
+			       (if (eq (nth 2 a) 'simple)
+				   ""
+				 (char-to-string (nth 1 a))))))
+	  (cons title
+		(if (null kdr)
+		    p
+		  (cons
+		   ;; A bit ugly but this make which-func happy.
+		   (cons title p)
+		   (mapcar (lambda (elt0)
+			     (rst-imenu-index0 elt0 adornments))
+			   kdr)))))
+      nil)))
+
+(defun rst-imenu-index ()
+  "Create index for imenu."
+  (rst-reset-section-caches)
+  (let ((tree (rst-section-tree))
+	;; Translate line notation to point notion
+	(adornments (save-excursion
+		      (mapcar (lambda (a)
+				(cons (progn
+					(goto-char (point-min))
+					(forward-line (1- (car a)))
+					(point))
+				      (cdr a)))
+			      (rst-find-all-adornments)))))
+    (delete nil (mapcar (lambda (elt)
+				   (rst-imenu-convert-cell elt adornments))
+				 tree))))
+
 \f
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Generic text functions that are more convenient than the defaults.