Improve the docstring of case-fold-search

Improve the docstring of case-fold-search

[Bastien]

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

I suggest to complete the docstring of `case-fold-search' like the
attached patch does.

In the current docstring, the expression "ignore case" is not really
appropriate because the search will not ignore uppercase characters in
the search string.  A very short way to tell this would be "*Non-nil if
searches and matches should ignore lowercase."  But while accurate, this
is confusing IMO.  Hence the long sentence in this patch, inspired by
the "Search case" section of Emacs manual.

Should I apply it?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: buffer.c.patch --]
[-- Type: text/x-diff, Size: 571 bytes --]

--- buffer.c.~1.583.~	2009-07-17 21:12:21.000000000 +0200
+++ buffer.c	2009-07-22 03:55:26.000000000 +0200
@@ -5727,7 +5727,9 @@
 
   DEFVAR_PER_BUFFER ("case-fold-search", &current_buffer->case_fold_search,
 		     Qnil,
-		     doc: /* *Non-nil if searches and matches should ignore case.  */);
+		     doc: /* *Non-nil if searches and matches should ignore case.
+If there is an uppercase character in the search string
+then the search becomes case sensitive.  */);
 
   DEFVAR_PER_BUFFER ("fill-column", &current_buffer->fill_column,
 		     make_number (Lisp_Int),

[-- Attachment #3: Type: text/plain, Size: 14 bytes --]


-- 
 Bastien

Re: Improve the docstring of case-fold-search

[Eli Zaretskii]

> From: Bastien <bastienguerry@googlemail.com>
> Date: Wed, 22 Jul 2009 04:17:10 +0200
> 
> +If there is an uppercase character in the search string
> +then the search becomes case sensitive.  */);

Are you sure this isn't only true for interactive searches?

Re: Improve the docstring of case-fold-search

[Stefan Monnier]

> In the current docstring, the expression "ignore case" is not really
> appropriate because the search will not ignore uppercase characters in
> the search string.  A very short way to tell this would be "*Non-nil if
> searches and matches should ignore lowercase."  But while accurate, this
> is confusing IMO.  Hence the long sentence in this patch, inspired by
> the "Search case" section of Emacs manual.

> Should I apply it?

As written, the doc is wrong.  The magic "pay attention to case if
there's a capital letter" is not done "within case-fold-search" but
within isearch (and maybe a few more places) which then bind
case-fold-search to the appropriate value.
The case-fold-search variable is pretty low-level and applies to
functions like re-search-forward.  Maybe it shouldn't be customizable to
avoid such confusion.


        Stefan


> --- buffer.c.~1.583.~	2009-07-17 21:12:21.000000000 +0200
> +++ buffer.c	2009-07-22 03:55:26.000000000 +0200
> @@ -5727,7 +5727,9 @@
 
>    DEFVAR_PER_BUFFER ("case-fold-search", &current_buffer->case_fold_search,
>  		     Qnil,
> -		     doc: /* *Non-nil if searches and matches should ignore case.  */);
> +		     doc: /* *Non-nil if searches and matches should ignore case.
> +If there is an uppercase character in the search string
> +then the search becomes case sensitive.  */);
 
>    DEFVAR_PER_BUFFER ("fill-column", &current_buffer->fill_column,
>  		     make_number (Lisp_Int),



> -- 
>  Bastien

Re: Improve the docstring of case-fold-search

[Bastien]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> As written, the doc is wrong.  The magic "pay attention to case if
> there's a capital letter" is not done "within case-fold-search" but
> within isearch (and maybe a few more places) which then bind
> case-fold-search to the appropriate value.

/me trying to figure out what other places...

> The case-fold-search variable is pretty low-level and applies to
> functions like re-search-forward.  Maybe it shouldn't be customizable to
> avoid such confusion.

Yes.  And add a `case-fold-isearch' option with a docstring reflecting
the behavior described in the Search Case of the manual.  Be maybe there
are other functions than isearch that would make use of it.

-- 
 Bastien

Re: Improve the docstring of case-fold-search

[Bastien]

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

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> The case-fold-search variable is pretty low-level and applies to
> functions like re-search-forward.  Maybe it shouldn't be customizable to
> avoid such confusion.

As a first step toward this, the attached patch creates an option for
`isearch-case-fold-search'.  The possible values for this option are:

                t : isearch ignores case
              nil : isearch does not ignore case
             'yes : isearch ignores mixed case
'case-fold-search : isearch uses the local case-fold-search

Is it okay to apply this?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: isearch.el.patch --]
[-- Type: text/x-diff, Size: 1911 bytes --]

--- isearch.el.~1.345.~	2009-02-14 17:04:46.000000000 +0800
+++ isearch.el	2009-07-27 10:37:35.000000000 +0800
@@ -90,6 +90,18 @@
   :type 'integer
   :group 'isearch)
 
+(defcustom isearch-case-fold-search nil
+  "Non-nil means search should not ignore case.
+'case-fold-search means that `isearch-case-fold-search' is set to
+the local value of `case-fold-search'.  'yes is similar to non-nil 
+except that mixed case in the search string is ignored.  Nil means 
+the search will ignore case."
+  :type '(choice (const :tag "Case insensitive" t)
+		 (const :tag "Mixed case sensitive" nil)
+                 (const :tag "Case sensitive" yes)
+                 (other :tag "Value of case-fold-search" case-fold-search))
+  :group 'isearch)
+
 (defcustom search-upper-case 'not-yanks
   "If non-nil, upper case chars disable case fold searching.
 That is, upper and lower case chars must match exactly.
@@ -544,11 +556,6 @@
 (defvar isearch-just-started nil)
 (defvar isearch-start-hscroll 0)	; hscroll when starting the search.
 
-;; case-fold-search while searching.
-;;   either nil, t, or 'yes.  'yes means the same as t except that mixed
-;;   case in the search string is ignored.
-(defvar isearch-case-fold-search nil)
-
 (defvar isearch-last-case-fold-search nil)
 
 ;; Used to save default value while isearch is active
@@ -739,13 +746,16 @@
   "Start Isearch minor mode.
 It is called by the function `isearch-forward' and other related functions."
 
+  ;; Initialize isearch-case-fold-search
+  (if (eq isearch-case-fold-search 'case-fold-search)
+      (setq isearch-case-fold-search case-fold-search))
+
   ;; Initialize global vars.
   (setq isearch-forward forward
 	isearch-regexp regexp
 	isearch-word word-p
 	isearch-op-fun op-fun
 	isearch-last-case-fold-search isearch-case-fold-search
-	isearch-case-fold-search case-fold-search
 	isearch-string ""
 	isearch-message ""
 	isearch-cmds nil

[-- Attachment #3: Type: text/plain, Size: 14 bytes --]


-- 
 Bastien

Re: Improve the docstring of case-fold-search

[Stefan Monnier]

>> The case-fold-search variable is pretty low-level and applies to
>> functions like re-search-forward.  Maybe it shouldn't be customizable to
>> avoid such confusion.
> As a first step toward this,

I don't see why you'd need steps for this.

> the attached patch creates an option for
> `isearch-case-fold-search'.  The possible values for this option are:

>                 t : isearch ignores case
>               nil : isearch does not ignore case
>              'yes : isearch ignores mixed case
> 'case-fold-search : isearch uses the local case-fold-search

> Is it okay to apply this?

I don't understand what use cases we're trying to address here.


        Stefan

Re: Improve the docstring of case-fold-search

[Bastien]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> The case-fold-search variable is pretty low-level and applies to
>>> functions like re-search-forward.  Maybe it shouldn't be customizable to
>>> avoid such confusion.
>> As a first step toward this,
>
> I don't see why you'd need steps for this.

As I understand it, the goal is to turn case-fold-search into a
non-customizable variable.  To me it makes only sense if the user 
is still able to configure the way he wants the interactive search
to behave.  Hence the "step" of finding the right way to turn
`isearch-case-fold-search' into an option.

>> the attached patch creates an option for
>> `isearch-case-fold-search'.  The possible values for this option are:
>
>>                 t : isearch ignores case
>>               nil : isearch does not ignore case
>>              'yes : isearch ignores mixed case
>> 'case-fold-search : isearch uses the local case-fold-search
>
>> Is it okay to apply this?
>
> I don't understand what use cases we're trying to address here.

The case where `case-fold-search' is not configurable anymore and the 
user want to customize the default behavior of the interactive search.

Does that make more sense?

-- 
 Bastien