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

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

[Masatake YAMATO]

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.

=== modified file 'lisp/textmodes/rst.el'
--- lisp/textmodes/rst.el	2012-06-07 09:20:41 +0000
+++ lisp/textmodes/rst.el	2012-06-13 17:16:13 +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,63 @@
     ;; output.
     ))
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Imenu support
+(defun rst-imenu-find-adornments-for-position (adornments p)
+  "Find adornments cell for position P in ADORNMENTS"
+  (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 adornment cell to imenu index"
+  (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

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

[Stefan Monnier]

> 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:

> +  ;; 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

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

[Masatake YAMATO]

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.

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

[Stefan Monnier]

> Emacs running on a terminal). In such case `which-func' helps me to
> understand the document; and `which-func' uses imenu internally.

Side comment: while which-func can use imenu, its only a fallback (one
that's used by many major modes).  See C-h f which-function.


        Stefan

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

[Stefan Merten]

[-- Attachment #1: Type: text/plain, Size: 1989 bytes --]

Hi Masatake!

Yesterday Masatake YAMATO wrote:
>>> This is not a bug report. This is a request to merge a patch
>>> to the offcial source tree.

Thanks for the patch.

>>> 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:

It is definitely interesting. So far I never used imenu but it looks
like a very useful thing.

I already integrated your patch in my development version. However,
I'll massage it a bit to fit better.

> I found I should explain more about to the maintainer.

Good idea.

> I know `rst-toc'. People who writes a document in rst format may use
> `rst-toc' instead of imenu.

I'm thinking about whether opening a second method for this type of
functionality using imenu. Indeed imenu is a mature framework and it
is useful to use this instead of homebrew stuff like `rst-toc`.

For instance I also have using the speed bar with `rst-mode`. The
imenu documentation says it supports the speed bar somehow - so this
might be a quick win :-) .

> 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.

I didn't get `which-func` to work - not even in Emacs Lisp mode. The
documentation says

  When Which Function mode is enabled, the current function name is
  continuously displayed in the mode line, in certain major modes.

Unfortunately the mode line doesn't change when I say
`which-func-mode` :-( .

[...checking...]

Ah that's probably because I

   (setq default-mode-line-format ...)

in my `.emacs`. Uuh, these stone-old customizations bite sometimes :-( .


						Grüße

						Stefan

[-- Attachment #2: Type: application/pgp-signature, Size: 307 bytes --]

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

[Stefan Merten]

[-- Attachment #1: Type: text/plain, Size: 582 bytes --]

Hi StefanMo!

4 days ago Masatake YAMATO wrote:
> +  ;;  Which func
> +  (when (and (boundp 'which-func-modes) (listp which-func-modes))
> +    (add-to-list 'which-func-modes 'rst-mode))

This form changes the customizable variable `which-func-modes'. I
thought this is not a good idea. I thought customizable variables
should be changed by users alone.

However, in this case it seems useful. Although this might override a
customization by a user who explicitly *excluded* `rst-mode' from
`which-func-modes'.

What do you think?


						Grüße

						StefanMn

[-- Attachment #2: Type: application/pgp-signature, Size: 307 bytes --]

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

[Stefan Merten]

[-- Attachment #1: Type: text/plain, Size: 391 bytes --]

Hi Masatake!

4 days ago Masatake YAMATO wrote:
> This is not a bug report. This is a request to merge a patch
> to the offcial source tree.

There seem to be some functions missing. From the byte-compiler:

  rst.el:4263:1:Warning: the following functions are not known to be defined:
      rst-imenu-find-adornment-for-position, rst-imenu-index0


						Grüße

						Stefan

[-- Attachment #2: Type: application/pgp-signature, Size: 307 bytes --]

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

[Stefan Monnier]

>> +  ;;  Which func
>> +  (when (and (boundp 'which-func-modes) (listp which-func-modes))
>> +    (add-to-list 'which-func-modes 'rst-mode))

> This form changes the customizable variable `which-func-modes'. I
> thought this is not a good idea. I thought customizable variables
> should be changed by users alone.

Indeed, better not do it.  The default in 24.2 is to allow all modes, so
this code is not used in that case anyway.

> However, in this case it seems useful.

Better let the user make the change.


        Stefan

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

[Masatake YAMATO]

> Hi Masatake!
> 
> 4 days ago Masatake YAMATO wrote:
>> This is not a bug report. This is a request to merge a patch
>> to the offcial source tree.
> 
> There seem to be some functions missing. From the byte-compiler:
> 
>   rst.el:4263:1:Warning: the following functions are not known to be defined:
>       rst-imenu-find-adornment-for-position, rst-imenu-index0

I'm very sorry. I' am ashamed.
Revised patch is here.

2012-06-16  Masatake YAMATO  <yamato <at> 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-19 02:48:16 +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-adornments-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-convert-cell 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.