diff --git a/twander.1 b/twander.1 index e347943..eadf8b8 100644 --- a/twander.1 +++ b/twander.1 @@ -230,6 +230,11 @@ "..." to show that it is truncated. .IP \(bu 4 + +Any "filter" that is limiting which files you see. If you've toggled +the filter, you will see the word "NOT" before the filter string. + +.IP \(bu 4 The total number of files in this directory. .IP \(bu 4 @@ -461,24 +466,6 @@ mouse. .TP -.B Display Wildcard Menu (MOUSEWILD) -Alt-Control-Right-Mouse-Button - -(Note that on Windows you must press Alt -.B then -Control -.B then -the Right-Mouse-Button for this to work. Windows appears to care deeply -about keystroke order.) - -Displays a list (if any) of any previously used selection wildcards in -a pop-up menu near the mouse. Selecting one of the entries therein -pops-up a dialog that allows you to edit the wildcard before actually -doing another selection. This allows use to modify previous wildcards -for new use. - - -.TP .B Quit Program (QUITPROG) Control-q @@ -687,142 +674,6 @@ a very long directory listing which does not all fit on-screen. .TP -.B Select Using Regular-Expression \'Wildcards\' (SELWILD) -Control-\\ - -Although \fCtwander\fP provides a very rich set of keyboard and mouse -selection commands, selecting a group of files out of list -of hundreds or thousands in a large directory can be tedious. -If the files/directories you want to select have some lexical commonality -.B in their names OR details -you can have \fCtwander\fP select them for you using so-called "Regular -Expressions". The idea here is that you press SELWILD -and enter a "matching" string or regular expression, and \fCtwander\fP will -select all entries which match this criteria for you. For example, if -you just enter the text, - -.ft C \" courier -.nf - tar -.fi -.ft \" revert - -\fCtwander\fP would select every file or directory in the current display -where the string "tar" -.B appeared anywhere on the line for that file/directory. -This is very important: Wildcard matching takes place anywhere on the -visible line. So, if you have details turned on, the match can occur -anywhere on the permissions, links, group, owner, and so on. -Obviously, if you have details turned off, the match can only occur on -the name of the file or directory since that's all that is visible. - -This is a purposeful design decision because it allows you to -make selections on more than just the name. Say you enter the -following in the SELWILD dialog: - -.ft C \" courier -.nf - drwx------ -.fi -.ft \" revert - -\fCtwander\fP will select all directories with no permissions enabled for -group or world users. - - -The matching string above could also select other entries (not having -the permissions just described), if say, this string -appeared in their name ... a rather unlikely scenario, but not -impossible. If we want to get -.B real -specific about which entries we want selected, we need to -enter a "regular expression" in the SELWILD dialog. -Regular expressions are a far more powerful pattern-matching -tool than simple text strings and will allow you to do some -fairly amazing selections. For example, this regular expression -selects all entries which contain a string beginning with "Ju" -followed by any other character, a single space, and ending -in "0": - -.ft C \" courier -.nf - Ju. 0 -.fi -.ft \" revert - -So, for instance, this would select files with date details (or names, -or anything else on the line...) like "Jun 01", "Jul 03", and "Jul -09". - -No matter what you specify, a literal matching string or a -regular expression, the ".." entry of the currently viewed -directory is never selected by SELWILD. - -Notice that these regular expressions are -.B not -the same thing as the filename "globbing" wildcards commonly -used with Unix and Windows shells. If you enter constructs like -"*.txt" or "*.tar.gz", you will not get the results you expect. -In fact, these specific examples will cause \fCtwander\fP to grumble -and present a warning message. - -For an excellent tutorial on Python-compliant regular -expressions, see: - -.ft C \" courier -.nf - http://www.amk.ca/python/howto/regex/ -.fi -.ft \" revert - -By default, SELWILD will select an entry when your regular expression -matches anything on the displayed line. This allows you to make -selections based on any visible column of information. This "match -anywhere on the line" semantic is possible because SELWILD -automatically massages the regular expression you provide to make "any -match on the line" true. There may be times when you want to provide -very specific regular expression definitions which seek a match at -specific locations. In that case, you can prevent SELWILD from -fiddling with your regular expression, by beginning it with the -double-quote (") character. SELWILD understands this to mean that -your regular expression is to be treated literally without -modification. (It only throws away this leading escape character.) - -Suppose we changed our example above slightly and used this -regular expression: - -.ft C \" courier -.nf - "^drwx------ -.fi -.ft \" revert - -Now \fCtwander\fP would select -.B only -the directories without any group and world access because: - -.IP \ 10 -The leading double-quote (") forces literal interpretation of the -regular expression - i.e. It turns off "match anywhere" semantics -as just described. - -The carat (^) at the beginning of the actual regular expression -"anchors" the match to the start of the line. For a match -to be declared (and for \fCtwander\fP to select an item) the regular -expression must be satisfied at the beginning-of-line. - -.P -.IP -Because regular expressions can get complicated and tedious to type -in, any such expression you use is saved in a history available via -the Wildcard Menu (see below). - -There is also provision for pre-defining frequently used -selection wildcards in your Configuration File (see below) so -you don't have to type them in manually each time you start -the program - you can just select them from the Wildcard Menu. - -.TP .B Mouse-Based Selections The mouse can also be used to select one or more items. A @@ -1145,6 +996,240 @@ program titlebar. +.SS Wildcard Features + +Although \fCtwander\fP provides a very rich set of keyboard and mouse +selection commands, selecting a group of files out of list +of hundreds or thousands in a large directory can be tedious. +If the files/directories you want to select have some lexical commonality +.B in their names OR details +you can have \fCtwander\fP select them for you using so-called +"Regular Expressions". + +You can do this in one of two ways. A wildcard "filter" only +.B displays +files that match the specified regular expression. A wildcard "selection" +.B selects +(highlights) the matching entries from the currently displayed list. +The general idea is to use filters to limit the number of files you'll +even see in the \fCtwander\fP interface and then optionally choose +from among them with a wildcard-based selection. + +For example, suppose you initiate a wildcard-based selection (SELWILD) +with the text, \fCtar\fP. This would select every file or +directory in the current display where the string "tar" +.B appeared anywhere on the line for that file/directory. +This is very important: Wildcard matching takes place anywhere on the +visible line. So, if you have details turned on, the match can occur +anywhere on the permissions, links, group, owner, and so on. +Obviously, if you have details turned off, the match can only occur on +the name of the file or directory since that's all that is visible. + +This is a purposeful design decision because it allows you to +make selections on more than just the name. Say you enter the +following in the FILTERWILD dialog: + +.ft C \" courier +.nf + drwx------ +.fi +.ft \" revert + +\fCtwander\fP would display only the entries that are directories with +no permissions enabled for group or world users. + + +The matching string above could also filter/select other entries (not having +the permissions just described), if say, this string +appeared in their name ... a rather unlikely scenario, but not +impossible. If we want to get +.B real +specific about which entries we want selected, we need to +enter a "regular expression" in the wildcard dialog. +Regular expressions are a far more powerful pattern-matching +tool than simple text strings and will allow you to do some +fairly amazing selections. For example, this regular expression +selects all entries which contain a string beginning with "Ju" +followed by any other character, a single space, and ending +in "0": + +.ft C \" courier +.nf + Ju. 0 +.fi +.ft \" revert + +So, for instance, this would select files with date details (or names, +or anything else on the line...) like "Jun 01", "Jul 03", and "Jul +09". + +No matter what you specify, a literal matching string or a regular +expression, the ".." entry of the currently viewed directory is never +selected for wildcard processing. This is a "special" entry that is +always present regardless of filtering and never selected with +wildcard-based selections. + +Notice that these regular expressions are +.B not +the same thing as the filename "globbing" wildcards commonly +used with Unix and Windows shells. If you enter constructs like +"*.txt" or "*.tar.gz", you will not get the results you expect. +In fact, these specific examples will cause \fCtwander\fP to grumble +and present a warning message. + +For an excellent tutorial on Python-compliant regular +expressions, see: + +.ft C \" courier +.nf + http://www.amk.ca/python/howto/regex/ +.fi +.ft \" revert + +By default, these wildcarding tools will select an entry when your +regular expression matches anything on the displayed line. This +allows you to make selections based on any visible column of +information. This "match anywhere on the line" semantic is possible +because \fCtwander\fP automatically massages the regular expression you +provide to make "any match on the line" true. There may be times when +you want to provide very specific regular expression definitions which +seek a match at specific locations. In that case, you can prevent +the program from fiddling with your regular expression, by beginning it +with the double-quote (") character. \fCtwander\fP understands this to mean +that your regular expression is to be treated literally without +modification. (It only throws away this leading escape character.) + +Suppose we changed our example above slightly and used this +regular expression: + +.ft C \" courier +.nf + "^drwx------ +.fi +.ft \" revert + +Now \fCtwander\fP would select +.B only +the directories without any group and world access because: + +.IP \(bu 4 +The leading double-quote (") forces literal interpretation of the +regular expression - i.e. It turns off "match anywhere" semantics +as just described. + +.IP \(bu 4 +The carat (^) at the beginning of the actual regular expression +"anchors" the match to the start of the line. For a match +to be declared (and for \fCtwander\fP to select an item) the regular +expression must be satisfied at the beginning-of-line. + +.P +Because regular expressions can get complicated and tedious to type +in, any such expression you use is saved in a history available via +the Filter and Select Menus (see below). There is also provision +for pre-defining frequently used wildcards in your Configuration File +(see section below on \fCWILDFILTER=\fP and \fCWILDSELECT=\fP +configuration statements) so you don't have to type them in manually +each time you start the program - you can just select them from the +relevant menu. + +A few points to keep in mind when using wildcard features: + +.IP \(bu 4 + +By default, wildcard matching is case-insensitive on Win32 systems and +case-sensitive everywhere else. This is because Windows systems allow +case in filenames and attributes, but it is not significant - i.e., The +case of a filename or attribute is ignored on Windows systems. You +can control this explicitly with the \fCWILDNOCASE=\fP configuration +option. If you set \fCWILDNOCASE=False\fP, it will force all wildcard +filters and selections to be case-sensistive. Setting it to +\fCTrue\fP makes the wildcarding case-insensitive. This option is +available for both Unix and Win32 systems so you can set the behavior +you like anywhere. + +.IP \(bu 4 +If you escape a wildcard to force \fCtwander\fP to treat it exactly as +you defined it, the case-sensitivity set by default or \fCWILDNOCASE\fP +is ignored. Escaped wildcards are always treated +.B exactly +as you enter them and they are matched against the filename and/or details +exactly as they appear. + +.IP \(bu 4 +Wildcard-based filters are applied against the +.B entire contents +of the current directory to determine which files match and should be +displayed. But, wildcard-based selections are done against the +.B currently visible +files. This is important if you do a filter and then a selection +wildcard. The first will select which files to display. The second +will select which ones to highlight from the displayed list. +.P + + +.TP +.B Display Files Matching A Regular Expression (FILTERWILD) +Control-equal + +This will present you with a dialog to enter your regular expression +matching criteria described above. After you enter it, \fCtwander\fP +will only display the files that match. The filter is reset (to no +filtering) when you manually referesh the directory (\fCREFRESH\fP) or +change directories. + +.TP +.B Toggle Active Filter (TOGFILT) +Control-minus + +Pressing this once "inverts" any filter currently active. It means "show me the files +that +.B don't +match the filtering regular expression." Pressing it again returns the filter +to its normal meaning. This is handy when you want to display everything +.B except +a group of files. You first filter for the files you don't want and then +press \fCTOGFILT\fP which will display everything except these files. + +.TP +.B Select Files Matching A Regular Expression \'Wildcards\' (SELWILD) +Control-\\ + +This will present you with a dialog to enter your regular expression +matching criteria described above. After you enter it, \fCtwander\fP will +select (highlight) the files that match. + +You can also "invert" your selections by using the \fCSELINV\fP key described +previously. This is useful when you want to select everything +.B except +a group of files. Select the ones you don't want with a selection wildcard +andthen press the \fCSELINV\fP key. + +Selections remain in effect until you make another manual selection, +clear all selections, or run a command that forces a directory refresh +after it runs - i.e., Commands defined with a leading "+". + +.TP +.B Display Selection Wildcard Menu (MOUSEFILTERSEL) +Alt-Control-Middle-Mouse-Button +.TP +.B Display Selection Wildcard Menu (MOUSEWILDSEL) +Alt-Control-Right-Mouse-Button + +(Note that on Windows you must press Alt +.B then +Control +.B then +the mouse button for this to work. Windows appears to care deeply +about keystroke order.) + +These keys popup a list near the current mouse cursor of any +previously used filtering or selection wildcards respectively. +Selecting one of the entries therein pops-up a dialog that allows you +to edit the wildcard before actually doing another wildcard filter or +selection. This allows use to modify previous wildcards for new use. + + .SH MENU OPTIONS Although \fCtwander\fP is primarily keyboard-oriented, several @@ -1200,7 +1285,7 @@ all dynamic menus. It also means that no interactive dialog will "remember" your last manual entry. For example, with MAXMENU set to 0, \fCtwander\fP will not keep track of your last manual entries for the -CHANGEDIR, SELWILD, and RUNCMD dialogs. +CHANGEDIR, FILTERWILD, SELWILD, and RUNCMD dialogs. MAXMENUBUF specifies the size of the internal storage buffer for each dynamic menu regardless of how many entries are actually displayed. @@ -2176,8 +2261,8 @@ content .B and of the last manual entry in the dialogs associated with CHANGEDIR -(default: Control-x), SELWILD (default: Control-\\), and RUNCMD -(default: Control-z). +(default: Control-x), FILTERWILD (default: Control-=), SELWILD +(default: Control-\\), and RUNCMD (default: Control-z). .IP \(bu 4 Changing MAXMENU and then reloading the Configuration File only @@ -3316,7 +3401,7 @@ For example, say file "A" \fC.include\fPs file "B" and file "B" then \fC.include\fPs file "A". This wold create a neverending "circle" of included files. If \fCtwander\fP detects this, it will display an error -describing the problem. +describing the problem and skip the offending line. .SH ADVANCED WINDOWS FEATURES @@ -4334,4 +4419,4 @@ .ft \" revert .SH DOCUMENT REVISION INFORMATION -$Id: twander.1,v 1.116 2005/02/02 22:38:54 tundra Exp $ \ No newline at end of file +$Id: twander.1,v 1.117 2005/02/03 11:17:14 tundra Exp $ \ No newline at end of file