1999-01-09 Emil Brink Doing a text search 1. INTRODUCTION This file describes how to use the Search-command built-into the internal textviewer in gentoo. The textviewer is the one you see when you use the ViewText and ViewHex commands, and also when doing command output capturing. The Search command is envoked by clicking the button labeled "Search..." found close to the bottom right corner of the textviewer window. As you click it, a dialog window appears that asks for search parameters. 2. THE SEARCH DIALOG There are three things you can change in the search parameter dialog that appears after you click "Search...". These things are: 1. Search text (RE) 2. "Ignore Case?"-flag 3. "Don't Span Newlines?"-flag These things are further explained in the following secionts: 2.1 The Search Text Of course, when doing a text search you expect to enter the text to search for. This is what you do in the entry field in the dialog. Note that you're not restricted to entering simple text, you can in fact enter a full regular expression (RE), giving you pretty much expressive power to be take advantage of. For an introduction to regular expressions as they are used in various places in gentoo, see the "docs/misc.html" file. If you're just looking for some old string, and don't bother about all these RE things, just pretend they're not there, and enter the string directly. Since any simple string is a RE that simply matches itself, this works as expected. Note that the expression you type in the field will be remembered and reappear the next time you open the dialog, for your convenience. 2.2 The "Ignore Case?" Flag If you want the search to disregard the difference between upper and lower case of characters, check this box before clicking OK. Like the search text itself, the setting of this flag will be remembered between dialog envokations. 2.3 The "Dont Span Newlines?" Flag This flag is for advanced searches only, and can typically be safely ignored (and left in its default OFF state). When active, it will disallow the regular expression matcher to match the any-character meta characters (mainly ".") against newline. This is perhaps not the most useful thing in the world to do, but it was supported by the regex routines I use, and sounds cool, so there. :^) 3. PERFORMING THE SEARCH Once you're satisfied with the settings in the dialog, click the OK button (or press RETURN) to perform the search. To abandon the search, click Cancel (or press ESCAPE). If the search is successful and something is found, gentoo will select (highlight) the matching text, and attempt to make the line(s) containing it visible. NOTE: In the current implementation, gentoo will only succeed in making the match line visible if there are NO (or very few) wrapped lines in the text viewer window. This is silly but true. If the search fails, nothing happens. In particular, there is no annoying failure-dialog or some such. The only feedback is the lack of feedback. 4. SEARCH POSITION The first time you envoke the Search command on a particular text, the search starts from the first character in the text, as you might expect. The next time you envoke it (on the same text), it will CONTINUE at the position right after the last in the matched text. This allows multiple searches for the same thing to be easily performed "back-to-back", thus covering the entire text. If you want to reset the search so that it starts over from the beginning, click the "Top" button in the text viewer command button row. This will move the viewer to the top, AND reset the search so that it again will look at the first character in the text. The "Bottom" button has the same effect, by the way. 5. MISSING FEATURES There are several things that are missing from gentoo's text search command. One thing is the ability to search backwards, something that is commonly found in functions like this. The reason why this isn't present is simple: the POSIX regex(3) functions that gentoo uses don't support it. Also, I find I almost never use it myself. :) The handling of search position/continuation is probably not very intuitive, I will look for a better way to do it. There should be some easy way of just repeating the last search, without having to see the dialog again. Keyboard... The "scroll" that attempts to put the matching line in view doesn't take wrapped lines into account, and thus misses by far if the window contains wrapped lines. This sucks, but it's still a lot better than what the GtkText widget itself would do (which is scroll (slowly!) to the matching line). Whine, nag. If you're trying to search the display given by the built-in ViewHex command, you might expect the Search command to realize that the data is in hex and adapt. It doesn't, however. I'm sure there's more...