Search: Please clarify documentation about case-insensitivity

[Chealer]

The section about the main search command in less 590's manpage contains:

   /pattern
          Search  forward  in  the file for the N-th line containing the pattern.  N defaults to 1.  The pattern is a regular expression, as recognized by the regular expression library supplied by your system.  The search starts at the first line displayed (but see the -a and -j options, which change this).

          Certain characters are special if entered at the beginning of the pattern; they modify the type of search rather than become part of the pattern:

          ^N or !
                 Search for lines which do NOT match the pattern.

          ^E or *
                 Search multiple files.  That is, if the search reaches the END of the current file without finding a match, the search continues in the next file in  the  command  line list.

          ^F or @
                 Begin  the  search at the first line of the FIRST file in the command line list, regardless of what is currently displayed on the screen or the settings of the -a or -j options.

          ^K     Highlight any text which matches the pattern on the current screen, but don't move to the first match (KEEP current position).

          ^R     Don't interpret regular expression metacharacters; that is, do a simple textual comparison.

          ^W     WRAP around the current file.  That is, if the search reaches the end of the current file without finding a match, the search continues from the first line of the  current file up to the line where it started.

As for help, its section on search contains:

                      SEARCHING

/pattern * Search forward for (N-th) matching line.
?pattern * Search backward for (N-th) matching line.
n * Repeat previous search (for N-th occurrence).
N * Repeat previous search in reverse direction.
ESC-n * Repeat previous search, spanning files.
ESC-N * Repeat previous search, reverse dir. & spanning files.
ESC-u Undo (toggle) search highlighting.
ESC-U Clear search highlighting.
&pattern * Display only matching lines.
---------------------------------------------------
A search pattern may begin with one or more of:
^N or ! Search for NON-matching lines.
^E or * Search multiple files (pass thru END OF FILE).
^F or @ Start search at FIRST file (for /) or last file (for ?).
^K Highlight matches, but don't move (KEEP position).
^R Don't use REGULAR EXPRESSIONS.
^W WRAP search if no match found.

Unfortunately, none of this explains:

1. that search is case-sensitive by default
2. nor how to make it case-insensitive.

#2 is only explained in the documentation of the -i option (which implies #1):

   -i or --ignore-case
          Causes searches to ignore case; that is, uppercase and lowercase are considered identical.  This option is ignored if any uppercase letters appear in the  search  pattern;  in other words, if a pattern contains uppercase letters, then that search does not ignore case.

This is particularly hard to find as this does not use the term "sensitivity" or any term matching "sensitiv*".

I recommend to mention case-sensitivity in both help and the manual's part about /.

[gwsw]

Added to man page in 5d2bd5d.
The help page is supposed to be a very brief summary (although it's already too long), so I'd rather not add more text there. If the user searches for "case" (which seems more likely than searching for "sensitivity") they will find the -i option.

[Chealer]

If a basic description of search cannot be documented in --help, I must agree that it's already way too long (--search-skip-screen for one is surely way more advanced than case-sensitivity).

Thank you very much for the change, which is already a huge improvement. However, I think suggesting (only) -i is misleading. -I should be suggested, and I would recommend not to suggest -i, in particular if --help seeks conciseness.

Although this exceeds this ticket's scope, I cannot refrain from commenting that making --ignore-case behave case-sensitively is not the least confusion-prone design choice. I understand the distinction is meant to bring convenience, but am far from convinced that convenience outweighs the confusion it brings.

Finally, while this goes beyond this ticket's scope once again, I shall note that if documentation cannot be as clear as possible about search being case-sensitive by default, then at least behavior could be improved; rather than displaying "Pattern not found" when no case-sensitive match is found, the bottom line could display something like:

Only matches with different cases found

or

No matches with specified case found; press ... for case-insensitive search"

I would be willing to bet this would suffice to prevent many person-days of lost productivity every calendar year (which visibly even affects some software professionals who have been relying on less for more than 0x10 years).

[gwsw]

Yeah, if I were to do it over again I probably wouldn't design the -i and -I options that way. But it's too late to change their behavior now. I'll think about the "Pattern not found" messaging. I wouldn't want to do both a case-sensitive and a case-insensitive match on every search just in case there's a match in the non-selected one, which could double the amount of time it takes to do a search. But maybe the messaging could be improved.

[gwsw]

After consideration, I don't think it's appropriate to complicate the "Pattern not found" message with a potentially misleading claim that the pattern might be found if you search again with different case sensitivity. I'm not aware of any other tool that does this: vi does not, vim does not, grep does not, and ack does not.

[Chealer]

Thank you @gwsw that is a valuable point.

That being said, modern viewers search case-insensitively by default. Doing such a comparison will find ancient references. vi and vim are functionally based on ex. ack is functionally based on grep, and ex and grep are based on ed, which was developed ½ a century ago in a much different context. Performance considerations haven't disappeared since then, but if we still let them dictate defaults, we should at least make that as clear as possible.

I don't think doing a case-insensitive search and a case-sensitive search would likely take twice the time as just a case-insensitive search. A case-sensitive search could just search the matches of the case-insensitive search. But multithreading allows considering both clarity and performance. Rather than displaying "Pattern not found" when no case-sensitive match is found, the bottom line could display something like:

No matches found for specified case

...until a second, case-insensitive search completes. After completion, the message can be updated to either:

Only matches with different cases found; press ... for case-insensitive search

or

No matches found

[avih]

My 2c on this bikeshed color, is that the existing -i/-I quick help at the help page are generally enough as they clearly imply what the default is, and inform how to change it. The addition at the manpage is very good as well IMHO. I don't think mentioning sensitivity at the "not found" message is a common or good solution.

So the only thing maybe missing is that at the help page, to make it more friendly, mention the default at the search section, and/or refer to -i/-I also at the search section of the help page, maybe something like "Use -i/-I to change case-sensitivity", or "Case-sensitive by default, see -i/-I".

But personally I found the -i/-I help anyway (and FWIW, I use -i by default).

[gwsw]

It occurs to me that these suggestions don't fully address the issue. Suppose a file has "abc" on line 100, "ABC" on line 200, and "abc" on line 300. If the user does a case sensitive search for "abc" while under the erroneous impression that the search was case insensitive, they will find the first and third lines, but none of the above suggestions will alert them to the fact that they missed the second one.

[Chealer]

Right, I suggested changing the message to improve the behavior by making sure the message does not mislead the user. But the user may not even read the message, in which case his assumption would remain.

Note that the message when there is no more match is simply "Pattern not found" whether the file contains a match or not. So the approach I suggested helps regardless of the number of matches in the file.