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