texinfo-show-structure and occur

texinfo-show-structure and occur

[Thien-Thi Nguyen]

In Texinfo mode, C-c C-s runs the command `texinfo-show-structure',
which uses `occur' to prepare a buffer of section headers.

Presently `occur' displays "Searched 1 buffer..." in the echo area,
where the "..." is actually 270+ bytes, largely comprising the huge
regexp required to identify the section headers.  This output is
multiline, expanding the echo area until next keypress, and irrelevant
to the user as it is an implementation detail only.  Furthermore, on
next keypress when the echo area size reverts size, the common (for
fast-moving Emacs users who are using C-c C-s to answer the question
"where am i?" (after which the the next command is `kill-buffer' or
`delete-window' (both by default with multi-keypress bindings))) use
case produces a flickering effect.

To alleviate, i tried first the following:

      (occur (concat "^\\(?:" (if nodes-too "@node\\>\\|")
                     outline-regexp "\\)"))
      (message nil)

This clears the echo area, but only after having done the deed.  The
flickering is now inherent, extending the misery to slow-moving users.
Likewise the equivalent:

      (with-temp-message ""
        (occur (concat "^\\(?:" (if nodes-too "@node\\>\\|")
                       outline-regexp "\\)")))

The more drastic approach:

      (flet ((message (&rest ignored) nil))
        (occur (concat "^\\(?:" (if nodes-too "@node\\>\\|")
                       outline-regexp "\\)")))

DTRT, but it uses `flet' which is frowned upon.  So now we start
thinking about how to alleviate more invasively (changing `occur').
Obviously `occur' is trying to be friendly, explaining its findings
to the user, and we don't want to change that facet.  Recognizing its
role as an agent for `texinfo-show-structure', perhaps we can consider
how to define "agent friendliness".

In this case, `texinfo-show-structure' constructs a long regexp to
express the idea "section headers".  Wouldn't it be nice if `occur'
could say:

  Searched 1 buffer; found NN section headers

?  That would be both informative and concise.  How about we extend
`occur' to accept a variable name (symbol) for the REGEXP argument?  In
that case, `occur' would use `symbol-value' to get the actual (string)
value.  The symbol could have property `occur-targets' (or somesuch),
to use in the "Searched" message, otherwise the variable name directly.
Some scenarios:

  (let ((interesting (CONSTRUCT-LONG-REGEXP)))
    (put 'interesting 'occur-targets "interesting items")
    (occur 'interesting))
  |= Searched 1 buffer; found NN interesting items

  (let ((cool-foo-bits (CONSTRUCT-LONG-REGEXP)))
    (occur 'cool-foo-bits))
  |= Searched 1 buffer; found NN `cool-foo-bits'

  (defvar foo-cool-bits (CONSTRUCT-LONG-REGEXP))
  (put 'foo-cool-bits 'occur-targets "`foo-cool-bits' (see foo.el)")
  (defun (...) ...
    (occur 'foo-cool-bits))
  |= Searched 1 buffer; found NN `foo-cool-bits' (see foo.el)

The last scenario is intended to show some kind of customization hint.
It could also be effected by propertizing the string, etc., presuming
the user pokes around the *Messages* buffer.

For completely embedded agent friendliness, if `occur-targets' is t,
`occur' could simply not display the message.

What do people think?

thi

Re: texinfo-show-structure and occur

[Juri Linkov]

> What do people think?

`occur' already displays this information in the first line of the output
buffer.  I think we don't need to duplicate this information in the echo area
that should be as concise as possible, like:

  Searched 1 buffer; found 573 matches

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: texinfo-show-structure and occur

[Thien-Thi Nguyen]

() Juri Linkov <juri@jurta.org>
() Sun, 14 Mar 2010 23:57:05 +0200

   > What do people think?

   `occur' already displays this information in the first line of the output
   buffer.  I think we don't need to duplicate this information in the echo
   area that should be as concise as possible, like:

     Searched 1 buffer; found 573 matches

Could someone please make this change?

thi

Re: texinfo-show-structure and occur

[Juri Linkov]

> `occur' already displays this information in the first line of the output
> buffer.  I think we don't need to duplicate this information in the echo area
> that should be as concise as possible, like:
>
>   Searched 1 buffer; found 573 matches

This patch ensures that the length of the message in the echo area
never gets more than the width of the window:

=== modified file 'lisp/replace.el'
--- lisp/replace.el	2010-01-13 08:35:10 +0000
+++ lisp/replace.el	2010-03-15 21:49:59 +0000
@@ -1162,12 +1162,13 @@ (defun occur-1 (regexp nlines bufs &opti
 		      (not (eq occur-excluded-properties t)))))
 	  (let* ((bufcount (length active-bufs))
 		 (diff (- (length bufs) bufcount)))
-	    (message "Searched %d buffer%s%s; %s match%s for `%s'"
+	    (message "Searched %d buffer%s%s; %s match%s%s"
 		     bufcount (if (= bufcount 1) "" "s")
 		     (if (zerop diff) "" (format " (%d killed)" diff))
 		     (if (zerop count) "no" (format "%d" count))
 		     (if (= count 1) "" "es")
-		     regexp))
+		     (if (> (length regexp) (- (window-width) 42))
+			 "" (format " for `%s'" regexp))))
 	  (setq occur-revert-arguments (list regexp nlines bufs))
           (if (= count 0)
               (kill-buffer occur-buf)

There is also a related problem with multi-occur.  In the output it duplicates
the regexp for every found buffer.  For instance, see how the string
`for "chapter"' is repeated:

2 matches for "chapter" in buffer: commands.texi
      6:@chapter Characters, Keys and Commands
      8:  This chapter explains the character sets used by Emacs for input
1 match for "chapter" in buffer: cmdargs.texi
     31:in batch mode.  The sections of this chapter describe the available

and there is no information about the total number of the found matches.

The following patch adds a line with total number of matches and the regexp,
and removes duplicate regexp output for multi-occur, so the above example
becomes:

3 matches for "chapter":
2 matches in buffer: commands.texi
      6:@chapter Characters, Keys and Commands
      8:  This chapter explains the character sets used by Emacs for input
1 match in buffer: cmdargs.texi
     31:in batch mode.  The sections of this chapter describe the available

=== modified file 'lisp/replace.el'
--- lisp/replace.el	2010-01-13 08:35:10 +0000
+++ lisp/replace.el	2010-03-15 21:47:14 +0000
@@ -1294,9 +1295,11 @@ (defun occur-engine (regexp buffers out-
 		(goto-char headerpt)
 		(let ((beg (point))
 		      end)
-		  (insert (format "%d match%s for \"%s\" in buffer: %s\n"
+		  (insert (format "%d match%s%s in buffer: %s\n"
 				  matches (if (= matches 1) "" "es")
-				  regexp (buffer-name buf)))
+				  (if (> (length buffers) 1)
+				      "" (format " for \"%s\"" regexp))
+				  (buffer-name buf)))
 		  (setq end (point))
 		  (add-text-properties beg end
 				       (append
@@ -1304,6 +1307,17 @@ (defun occur-engine (regexp buffers out-
 					  `(font-lock-face ,title-face))
 					`(occur-title ,buf))))
 		(goto-char (point-min)))))))
+      (when (and (not (zerop globalcount)) (> (length buffers) 1))
+	(goto-char (point-min))
+	(let ((beg (point))
+	      end)
+	  (insert (format "%d match%s for \"%s\":\n"
+			  globalcount (if (= globalcount 1) "" "es")
+			  regexp))
+	  (setq end (point))
+	  (add-text-properties beg end (when title-face
+					 `(font-lock-face ,title-face))))
+	(goto-char (point-min)))
       (if coding
 	  ;; CODING is buffer-file-coding-system of the first buffer
 	  ;; that locally binds it.  Let's use it also for the output

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: texinfo-show-structure and occur

[Juri Linkov]

>    > What do people think?
>
>    `occur' already displays this information in the first line of the output
>    buffer.  I think we don't need to duplicate this information in the echo
>    area that should be as concise as possible, like:
>
>      Searched 1 buffer; found 573 matches
>
> Could someone please make this change?

This is now fixed.  I also added `query-replace-descr' so you won't see
a flickering effect in the echo area for multiline regexps with newlines.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: texinfo-show-structure and occur

[Thien-Thi Nguyen]

() Juri Linkov <juri@jurta.org>
() Sun, 21 Mar 2010 12:55:55 +0200

   This is now fixed.  I also added `query-replace-descr' so you won't see
   a flickering effect in the echo area for multiline regexps with newlines.

Thank you.

thi