USER HELP GUIDE

WISH Mini-Console 2008
by David McClamrock <mcclamrock@locl.net>

WISH Mini-Console is a simple, Tcl-based, Unix-type command-line console. It can run single-line and multiple-line Tcl/Tk commands, as well as common Unix commands (except for a few, like "su"--use a terminal emulator such as "rxvt" or "xterm" for those).

To run the program, if you don't have a menu item for it, type "wishmin &" (without the quotes) at the command line in your "old" Unix console. You can get WISH Mini-Console to run a command when it starts up, by putting the command between the "wishmin" and the "&" at the command line, like this:

wishmin rpm -ql snackAmp &

The ordinary way to run a single-line command is no surprise: type the command and press Enter. WISH Mini-Console doesn't care whether it's a Tcl command or a non-Tcl Unix command, so long as it can run on your system. If it can't run on your system, you'll get a friendly error message, like this:

[david@localhost david]% bogomips
couldn't execute "bogomips": no such file or directory

You'll note the Tcl "percent" prompt, rather than the customary Unix dollar sign, after the standard Unix [user@host directory] prefix. This means that WISH Mini-Console uses the Tcl/Tk shell (wish) to run both Tcl/Tk commands (by "eval"-ing them) and non-Tcl/Tk commands (by "eval exec"-ing them). Output from non-Tcl/Tk commands will be piped so that any available output will show up right away even if it takes a long time to put out all that becomes available. If you enter a Tcl/Tk command that is also a standard Unix command (e.g., "cd" to change directory), it will be treated as a Tcl/Tk command.

If you run a Tk command, you'll see a Tk window open up just as if you had entered "wish" in a standard Unix console. If you don't want to see the Tk window, hit F3 or click "Hide Tk Window" in the "View" menu; if you do want to see it but it isn't there, hit F4 or click "Show Tk Window" in the same menu. Don't click the "Close" button on the Tk window; if you do, you'll get an error message saying the application has been destroyed whenever you try to run any more Tk commands. (If this happens, just click "New Console" in the File menu; the new console will then let you run Tk commands.)

For multiple-line Tcl/Tk commands, WISH Mini-Console will let you do some text-editing things that the typical Unix console won't, like multiple-line cutting, deleting, and backspacing. Multiple-line expressions are auto-tabbed in accordance with standard Tcl style; paired braces, brackets, and the like can be inserted (and the cursor can be positioned between them) with a single key combination. You can display your commands with word wrap if you wish (they'll work the same as they would with no word wrap). For single-line commands, there's a command history listbox, which allows you to review and re-run commands more quickly (on average) than hitting the up arrow many times in a standard Unix console. You don't have to press Enter to run a command if you insert it from the command history listbox; otherwise, press Enter when your command is complete.

You can do some more things, too; there are mini-toolbar buttons and menu items for them. Here's what the mini-toolbar buttons are and what they do; below that you can read about the menu items are and what they do. If there's an accelerator key combination that does the same thing, I'll say so.

##### MINI-TOOLBAR #####

# New: If your WISH Mini-Console window gets filled with a lot of commands you don't need any more, and the scrollbar slider gets so tiny that you can hardly see it--or if you mistakenly clicked the Close box in a Tk window--or if the old console just stops working right for some unforeseen reason--you may want to start fresh. Just click this menu item; then you can exit the old console if you wish, and the new console you just opened will remain.

# Cut (Control+x): Cuts out the selected text and puts it on the clipboard, ready to be pasted in. Easy.

# Copy (Control+c): Copies the selected text and puts it on the clipboard, ready to be pasted in. Equally easy.

# Paste (Control+g--it was supposed to be "Control+v," but that didn't work quite right for some reason unknown to me): Pastes in text from the clipboard at the cursor location. The cursor goes to the end of the pasted-in text, and the text scrolls to the new cursor position if necessary. The letter "g" doesn't stand for "paste," but it does stand for "glue"; this may be a memory aid of some kind.

# Undo (Control+z): Undoes the last significant action performed (e.g., typing a word, deleting some text, etc.).

# Redo (Control+r): If you're inclined toward unlimited vacillation, you can redo an unlimited number of actions after undoing them; then you can undo them again, redo them again, and so on *ad infinitum*. (Ugh!)

# History (Control+Up[arrow]): This will display the command history listbox. To re-run a command, you can (1) right-click, (2) double left-click, or (3) single left-click and then click Run. (Don't be alarmed when you find that the command you just ran has vanished from its place in the listbox and re-appeared at the bottom; that's what's supposed to happen.) The past commands are saved in a file called "minpast.tcl" in the ".wishes" subdirectory of your home directory. To find a past command in the list, type all or part of the command into the "Search" box and click Search or hit Enter. All matching commands will be highlighted, and the number found will be shown; then just re-run the one you want in the usual way.

To change the number of past commands that will be saved, enter a number between 1 and 9999 in the "Show [number] commands" spinbox. To unlist one or more commands, select the command listings and click Unlist. You can only run one command at a time (as WISH Mini-Console will politely remind you if you try to run more than one at a time), but you can select any number to unlist; hold down Control and click to select individual items, or hold down Shift and click to select all items between the clicked item and the most recently selected other item. To deselect all items, click "Deselect." If you decide you don't like single-click insertion of commands any more, click "Close."

# Source (Control+F1): If you've got a file containing Tcl/Tk commands, you can "source" the file by using this menu item, holding down Control and pressing F1, or clicking the "Source" button. A box like the command history listbox will open up, showing the names of files you've sourced before. If the name of the file you want isn't there, click "Any File" to find it using a standard file dialog box. The commands in the sourced file will take effect when you open the file. You can also just use the Tcl "source" command from the command line. WISH Mini-Console will assume that the sourced file may contain Tk commands, so the Tk window will open up automatically. If you don't want it, hit F3 or click the "View--Hide Tk Window" menu item.

# Find (F2): To search for text in commands, output, or error messages, use this menu item, hit F2, or click the "Find" button. You can't automatically replace the text with other specified text (at least in this version), but you can type text to replace the found items one by one as you go along. (The found text will be selected; just start typing the replacement text and the selection containing the found text will disappear.)

# Quit: This means what it says. You won't be asked whether you want to save the console contents. If you want to save them, do it ahead of time.

##### MENU ITEMS #####

# File -- New Console: Does what the "New" button does.

# File -- Save Selection, Save All: If your commands don't work right, you can save them in a file (complete with prompts, output, error messages, and all) to show to some geek in the know who may be able to figure out what's wrong. If you write some superb multi-line Tcl/Tk code that you may want to use or display again, you can save that too. Select the code you want and use "Save Selection," or use "Save All" to do just that.

# File -- Exit: Does what the "Quit" button does.

# Edit -- Copy, Paste, Cut, Delete, Select All, Undo, Redo: All standard text-editing stuff, with accelerator keys (shown in the menu items) that can probably do the job faster than the mouse. All but Delete and Select All have their own mini-toolbar buttons, too.

# Insert -- Past Command: Does what the "History" button does.

# Insert -- Source (Tcl/Tk): Does what the "Source" button does.

# Insert -- Curly Braces, Next Braces, Leave Braces: To insert a pair of curly braces {} and put the cursor between them, use the "Curly Braces" menu item or (preferably) hold down Control and type the "{" character. (This actually means Control-Shift plus the key with the character, of course.) To insert another pair (separated from the first pair by a space) and jump the cursor to the new pair, use "Next Braces" or Shift-Home. To leave a pair of braces and revert to the next lower auto-tab level (from the one you got to by pressing Enter when the cursor was between the braces, if you did that), use "Leave Braces" or Shift-End. (The change in auto-tab levels won't work right if the cursor isn't still between the two braces, so make sure it is.)

# Insert -- Square Brackets, Angle Brackets, Parentheses, Quotes: More paired characters with the cursor between them; more easy-to-remember key combinations, Control plus whatever you would use to type the first character in the pair.

# View -- Find: Does what the "Find" button does.

# View -- Word Wrap, Character Wrap, No Wrap: Word wrap is on by default. If you don't like it, click one of the other options.

# View -- Size: If you think the WISH Mini-Console window is too big, click "Small"; if too small, click "Large."

# View -- Hide Tk Window and Show Tk Window: I already told you about these self-explanatory menu items.

# View -- Color Display: This menu item will open up a "WISH Color Picker Plus" box to let you determine what colors will appear in the program's windows. In the box, you'll see sliders to change the proportions of red, green, and blue, and a button to display the color. The sliders go from 0 (none) to 255 (maximum). There's also a listbox containing color names; you can right-click or double left-click to select a color, and then modify it with the sliders if you wish. The "PICK" button displays the selected color, with its name or hexadecimal (base 16) code in black letters if the color is light, or white ones if the color is dark. For example, if you select a color with 255 parts red, 204 parts green, and 153 parts blue, the hexadecimal code (displayed in black letters) will be "FFCC99" because "FF" in hexadecimal numeration means 255, "CC" means 204, and "99" means 153.

To the right of the color names, there's a label that says "CHOOSE COLOR TO CHANGE," followed by a bunch of things you can change the color of (e.g., window background, buttons, boxes, labels, and more). On each line here, there's a radiobutton, then the name of something to change the color of, and finally a little button displaying the current color and name or code of that thing. Click a radiobutton to select a line; then click the big "PICK" button, or a little color button on another line. The color from the button you click will be copied to the color button on the selected line. The change won't show up elsewhere until you click the "Apply Picked Colors" button below the color-name listbox.

Near the bottom left corner of the box, there's a color-scheme listbox with an entry line for adding or changing color-scheme names. Some names of sample color schemes should be in the listbox. (They come from a subdirectory of your home directory, "/home/[you]/.wishes/colorschemes"; the code for each color scheme is kept in a separate, human-readable file.) To apply a color scheme, select it and then click "Apply Color Scheme" (you can also just right-click or double-click the color name). To create a new color scheme, pick the colors for the scheme and click "Apply Picked Colors"; then put a name for the scheme on the entry line and click "Name This Color Scheme" or hit Enter. To revise an existing color scheme, change some colors and enter the scheme name on the entry line (if it isn't already there); then hit Enter or click "Yes" in the box that will ask whether to revise the color scheme. Obviously, click the color-scheme name and "Delete Color Scheme" to delete a color scheme. Finally, click "OK" to save the currently applied colors as your preferred colors, or "Close" to close the color-selection box without saving.

It's that simple--I think! If you find something that isn't as simple as I think it is, or if you find any bugs (simple or complex), please let me know by e-mail.

David McClamrock <mcclamrock@locl.net>
March 2008