list-matching-lines is alias for occur

list-matching-lines is alias for occur

[Juri Linkov]

The feature that shows in a separate buffer all lines containing a
regexp is known under the name "occur" rather than "list-matching-lines".
The Emacs manual confirms that the primary name is `occur':

    `M-x list-matching-lines'
         Synonym for `M-x occur'.

and code defines `list-matching-lines' is an alias for `occur':

    (defalias 'list-matching-lines 'occur)

Nevertheless, user options used to customize `occur' have the prefix
"list-matching-lines".  The following patch renames their prefixes to
"occur" and creates aliases to the names with "list-matching-lines"
prefix.

Index: lisp/replace.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/replace.el,v
retrieving revision 1.230
diff -c -r1.230 replace.el
*** lisp/replace.el	9 Nov 2005 07:41:48 -0000	1.230
--- lisp/replace.el	9 Nov 2005 09:27:54 -0000
***************
*** 857,882 ****
    :group 'matching
    :version "22.1")
  
! (defcustom list-matching-lines-default-context-lines 0
!   "*Default number of context lines included around `list-matching-lines' matches.
  A negative number means to include that many lines before the match.
  A positive number means to include that many lines both before and after."
    :type 'integer
    :group 'matching)
  
  (defalias 'list-matching-lines 'occur)
  
! (defcustom list-matching-lines-face 'match
!   "*Face used by \\[list-matching-lines] to show the text that matches.
  If the value is nil, don't highlight the matching portions specially."
    :type 'face
    :group 'matching)
  
! (defcustom list-matching-lines-buffer-name-face 'underline
!   "*Face used by \\[list-matching-lines] to show the names of buffers.
  If the value is nil, don't highlight the buffer names specially."
    :type 'face
    :group 'matching)
  
  (defcustom occur-excluded-properties
    '(read-only invisible intangible field mouse-face help-echo local-map keymap
--- 857,885 ----
    :group 'matching
    :version "22.1")
  
! (defcustom occur-context-lines 0
!   "*Default number of context lines included around `occur' matches.
  A negative number means to include that many lines before the match.
  A positive number means to include that many lines both before and after."
    :type 'integer
    :group 'matching)
+ (defvaralias 'list-matching-lines-default-context-lines 'occur-context-lines)
  
  (defalias 'list-matching-lines 'occur)
  
! (defcustom occur-match-face 'match
!   "*Face used by \\[occur] to show the text that matches.
  If the value is nil, don't highlight the matching portions specially."
    :type 'face
    :group 'matching)
+ (defvaralias 'list-matching-lines-face 'occur-match-face)
  
! (defcustom occur-buffer-name-face 'underline
!   "*Face used by \\[occur] to show the names of buffers.
  If the value is nil, don't highlight the buffer names specially."
    :type 'face
    :group 'matching)
+ (defvaralias 'list-matching-lines-buffer-name-face 'occur-buffer-name-face)
  
  (defcustom occur-excluded-properties
    '(read-only invisible intangible field mouse-face help-echo local-map keymap
***************
*** 955,962 ****
  This function can not handle matches that span more than one line.
  
  Each line is displayed with NLINES lines before and after, or -NLINES
! before if NLINES is negative.
! NLINES defaults to `list-matching-lines-default-context-lines'.
  Interactively it is the prefix arg.
  
  The lines are shown in a buffer named `*Occur*'.
--- 958,964 ----
  This function can not handle matches that span more than one line.
  
  Each line is displayed with NLINES lines before and after, or -NLINES
! before if NLINES is negative.  NLINES defaults to `occur-context-lines'.
  Interactively it is the prefix arg.
  
  The lines are shown in a buffer named `*Occur*'.
***************
*** 1041,1051 ****
  	(erase-buffer)
  	(let ((count (occur-engine
  		      regexp active-bufs occur-buf
! 		      (or nlines list-matching-lines-default-context-lines)
  		      (and case-fold-search
  			   (isearch-no-upper-case-p regexp t))
! 		      list-matching-lines-buffer-name-face
! 		      nil list-matching-lines-face
  		      (not (eq occur-excluded-properties t)))))
  	  (let* ((bufcount (length active-bufs))
  		 (diff (- (length bufs) bufcount)))
--- 1043,1052 ----
  	(erase-buffer)
  	(let ((count (occur-engine
  		      regexp active-bufs occur-buf
! 		      (or nlines occur-context-lines)
  		      (and case-fold-search
  			   (isearch-no-upper-case-p regexp t))
! 		      occur-buffer-name-face nil occur-match-face
  		      (not (eq occur-excluded-properties t)))))
  	  (let* ((bufcount (length active-bufs))
  		 (diff (- (length bufs) bufcount)))

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

Re: list-matching-lines is alias for occur

[Richard M. Stallman]

The traditional name of this command was "occur".
Then around 15 years ago I thought maybe "list-matching-lines"
would be better since it actually expresses the command's meaning
and fits into a systematic series of names for those four commands.

So I started moving towards making that the primary name
and treating "occur" as an alias.  But this was never fully
carried out.

You've proposed to reverse that, and make "occur" the principal
name.

One day we should either finish this change or reverse it,
but I am not sure which, and I don't want to decide in a hurry.

Re: list-matching-lines is alias for occur

[Juri Linkov]

> You've proposed to reverse that, and make "occur" the principal
> name.

Actually, "occur" is still the principal name.  And I haven't proposed
to reverse.  My patch makes both names "list-matching-lines" to "occur"
available for customization.

> One day we should either finish this change or reverse it,
> but I am not sure which, and I don't want to decide in a hurry.

There's no hurry for the decision about the name, but the current
transitional state makes it difficult for users to customize this feature:
the command is know primarily under the name "occur", but user options
have a different prefix.  After my patch installed, users will be able to
find these options under both names.  And the decision about obsoleting
one of them could be postponed.

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

Re: list-matching-lines is alias for occur

[Richard M. Stallman]

    There's no hurry for the decision about the name, but the current
    transitional state makes it difficult for users to customize this feature:
    the command is know primarily under the name "occur", but user options
    have a different prefix.  After my patch installed, users will be able to
    find these options under both names.  And the decision about obsoleting
    one of them could be postponed.

That would be moving in the opposite direction to that which
I decided on years ago.  I don't want to do that unless
I make a decision to abandon the ultimate goal of that change.

Perhaps that would be a good idea, but I don't want to think
about it now.