*************************************************************************** * * * * * --- KingCON 1.1 --- * * * * --- User Documentation --- * * * * --- Copyright © 1993 David Larsson --- * * * * * *************************************************************************** ========= Preface ========= The program and files in this distribution are freely distributable, but are also copyright (c) David Larsson. They may be freely distributed as long as no more than a nominal fee is charged to cover time and copying costs. No commercial usage is permitted without written permission from the author. Everything in this distribution must be kept together, in original unmodified form. The above is generally known as freeware. Please contact me if you have any comments or suggestions: E-Mail: f92dala@dd.chalmers.se Mail: David Larsson Gibraltarg. 82:150 S-412 79 GÖTEBORG Sweden ¯¯¯¯¯¯ ! KingCON needs Kickstart 2.0 or better to run. ! ========== Contents ========== 1. KingCON compared to CON 2. Installation 3. Editing 4. Filename- command- and device-completion 5. Review-buffer 6. Menus 7. Options when opening the console-window 8. To do ============================ 1. KingCON compared to CON ============================ The WB2.0 console-handler - CON: - is really good, but it lacks some very handy features that make life easier if you use it a lot. KingCON (or KCON) is a replacement that behaves EXACTLY like CON, but it also adds these important features: * Filename completion. You just type the first letters of a filename, press the TAB-key, and - voilà! - the rest of the name is filled in for you (or you will be presented a list of alternative files that you can choose from). This makes typing MUCH faster and minimizes frustrating misspellings. You can also bring up a standard filerequester and select a file that way. DOS-commands and devicenames can be completed in a similar way. Some of you might say that the Shell should provide this function instead, but since all editing is managed by the console-handler anyway, this is only natural. And as a "sideeffect", the filename- completion will be available AT ALL TIMES - not only when you are standing at the shell-prompt. * Review-buffer. A scrollbar in the right windowborder lets you browse through all text that has been output to the window at any time. (Very useful when your compiler spits out ten pages of errorlistings.) The buffer can be turned on and off, and saved to a separate file. * Intuition-menus that give you a quick access to the features mentioned above. You can control the size of the window, clear it etc. * Jump-scroll option, which increases output speed a lot. * The console window can be iconified and put on the Workbench as an AppIcon. * Asynchronous typeahead, if you want to type in the next command while watching the output from the previous one. * Workbench icondrop is supported. * You can have the current directory displayed in the windowtitle. * The mouse can be used for positioning the cursor on the input line. * The text can be any (non-proportional) font you like. Topaz 44 is a killer. * The command-history buffer eliminates identical lines, the window is positioned more intelligently etc. Please note that KingCON does NOT patch CON in any way, it is written completely from scratch. There is a way, however, to mount KingCON as 'CON:'. In this way, every program that use 'CON:' will actually be using KingCON and all the good it stands for.:-> Of course, this is optional. KRAW: is a replacement for RAW:, but the menus, filename-completion and review don't work. It has limited use, because you can't run a Shell in it. See some DOS-documentation for details about the differences between CON: and RAW:. ================= 2. Installation ================= Simply run 'Installation' by double-clicking on its icon. The install-script does the following things: * Depending on which processor you have, 'KingCON-handler' or 'KingCON-handler.020' is copied to L:. Once copied, it is always called 'KingCON-handler'. * 'KingCON-mountlist' is copied to DEVS: * 'KCON:' and 'KRAW:' are mounted. * Optionally, the necessary Mount-commands are added to s:user-startup. They are: Mount KCON: from DEVS:KingCON-mountlist Mount KRAW: from DEVS:KingCON-mountlist When KCON: is installed and mounted, you can try it (at last!) by typing the following in a shell-window: Newshell window KCON: or: Echo "Yes it is!!" >"KCON:////Is this happening?/FONT topaz.22/WAIT/CLOSE" (Make sure you get those /'s right!) Mounting KCON: as CON: ---------------------- When KingCON is installed, the DOS-devicename for it is 'KCON:' (and 'KRAW:' for the unbuffered version). If you want that all your shell-windows you open should be KCON-windows, you just change the WINDOW-ToolType of the Shell-icon to say KCON: instead of CON:. (See your Workbench-documentation.) But in this way, you will only get a KCON-window if you start a new shell by double-clicking on the Shell-icon. Furthermore, some programs have their own console-windows and won't let you change them from CON: to KCON:. (Real3D v2.0 is one example). What you need is something that makes every reference to 'CON:' actually lead to KingCON. This is done by mounting 'KCON:' as 'CON:' instead. BUT, this is normally not possible, since 'CON:' (and 'RAW:') are mounted before the startup-sequence is executed. This is the solution: * Add these lines BEFORE the Mount-commands in the user-startup: Assign CON: DISMOUNT Assign RAW: DISMOUNT * Change the Mount-commands to: Mount CON: from DEVS:KingCON-mountlist Mount RAW: from DEVS:KingCON-mountlist Now when you boot, every console-window should be a KingCON-window. There is no need to have a special KCON: or KRAW:-device. Enjoy! !! WARNING !! Before you try the above, PLEASE make sure that the normal installation was successful and that you can mount KCON: and KRAW: when rebooting. Make sure that you follow the steps carefully. If something for some reason goes wrong after the Assign-DISMOUNT-commands, you won't have any console at all. A very frustrating situation if you must start your favourite text-editor, in order to correct the mistake, from the Shell... Remember that you have the Workbench-menu "Execute command" as a final rescue! ============ 3. Editing ============ Note: Everything said here is only true for the "cooked" KCON-console. KRAW is "raw" and has no editing capabilities. Also, if you have specified the ASYNC-option, things will work a bit different from what you may be used to. See the end of this section for details. 'KCON:' is probably most often used as output for the Shell, but editing works the same if it is a program's private AREXX-console, for example. Even the filename-completion is identical. I assume some experience of the editing used in 'CON'. Most things are identical, the exceptions from this are marked with a (!). These keys are used for the line-editing: Key Effect --------------------------------------------------------------------------- Any "printable" char. Inserts the character pressed under the cursor, shifting the characters right of the cursor one step to the right. Return or Finishes the line and adds it to the history-buffer, Control-M UNLESS it is identical to the previous line. Shift-Return (!) The line is finished and added to the history-buffer, but it is not sent to the command shell. This means that it won't be executed. Control-\ Inserts an EOF-character and finishes the line. This often means that the window is closed, but it's up to the program that opened 'KCON:' to decide. Control-J Adds a linefeed. Right Arrow Moves the cursor to the right. Left Arrow Moves the cursor to the left. Up Arrow Displays the previous history-line. Down Arrow Displays the next history-line. Shift-Right Arrow or Cursor to the end of the line. Control-Z Shift-Left Arrow or Cursor to the beginning of the line. Control-A Alt-Right Arrow (!) Cursor to the beginning of the next word. Alt-Left Arrow (!) Cursor to the beginning of the previous word. Left Mousebutton (!) Moves the cursor to to the position on the input- line that you clicked on. If you click somewhere else in the window, nothing will happen. Note that the cursor is moved when the button is released and that you must not drag the mouse pointer before you release the button. You can still select text to be copied to the clipboard as usual. Backspace Deletes the character to the left of the cursor and shifts the rest of the line to the left. Delete Deletes the character under the cursor and shifts the rest of the line to the left. Shift-Backspace (!) or Deletes the line to the left of the cursor. Control-U Shift-Delete (!) or Deletes the line to the right of the cursor and Control-K puts the characters in a cut-buffer (NOT on the clipboard.) Alt-Backspace (!) or Deletes the word that the cursor is standing on Control-W to the left. Alt-Delete Deletes the word that the cursor is standing on to the right. Amiga-Delete Deletes the word that the cursor is standing on. Control-B or Deletes the whole line. Control-X Control-L (!) Deletes the whole line and clears the console. Shift-Up Arrow Finds the next history-line whose leading characters match the first characters in the line up to the cursor. Shift-Down Arrow Clears the line and puts you at the end of the history buffer. (That means that if you then press 'Up Arrow', the last line of the history will be displayed.) Alt-Up Arrow (!) Scrolls backwards one page in the review-buffer. See section 5 about the review. Alt-Down Arrow (!) Scrolls forwards one page in the review-buffer Shift-Alt-Up Arrow (!) Scrolls to the beginning of the review-buffer. Shift-Alt-Down Arrow (!) Scrolls to the end of the review-buffer. Amiga-V Inserts text from the clipboard. Control-Y Inserts the characters deleted with Control-K or Shift-Delete. Control-S Halts the output (if you are listing a directory for example). This could be done by typing any key and then type Backspace to resume output. Control-Q Resumes output again. TAB (!) Filename-completion. See section 4 for details. Shift-TAB (!) Device-completion. See section 4. Alt-TAB (!) Command-completion. See section 4. Asynchronous typeahead ---------------------- Normally, when you press a key while a program ('list' for example) is outputting text to the console, the output is halted until you have finished the your input in some way or another. However, if you specify the ASYNC-option, your keystrokes will be buffered while the output is going on and printed on the command-line when the prompt returns. If you start stepping backwards with the arrow-keys or do something else that makes it hard for you to keep track of what currently lies in the buffer or where the cursor is, the output is halted and the buffer is printed on the command line where you can continue to edit it. ============================================= 4. Filename- command- and device-completion ============================================= The idea with xx-completion (or TAB-expansion) is to make typing faster and more accurate. Once used to it, it will be a great help you don't want to live without. Filename-completion ------------------- If you want to enter a specific filename (or a complete path), you start with entering the first characters in the filename, then press TAB (or Amiga-F, see section 6). If only one file or directory relative to the current directory matches those leading characters, the rest of the name will be filled in for you. Normally you just enter the first letters of a filename and then press TAB. If many files begin with the same letters, you can also use standard AmigaDOS wildcards to filter out the file you want. For example, if you want a file that ENDS with the characters '.gif', you type '#?.gif' and press TAB. If more than one file matches the characters you typed, a window with a list of possible filenames will be opened. You pick the file you want by: * Clicking on it and then choosing 'OK' or * Double-clicking on it or * Browse through the names with TAB and Shift-TAB or Up- and Down-Arrows, then press Return. To cancel, you: * Press 'Cancel' or * Close the window or * Press ESC. If you didn't type any characters at all before you pressed TAB (or Amiga-F), an asl-requester will be opened for you, where you select your file or directory. By default, .info-files are not shown. This can be toggled by selecting the menu Complete->Show .info. See section 6. Command-completion ------------------ Command-completion works in the same way as filename-completion. The difference is that not only the current directory is searched, but also all the command-paths. Only plain executable files are considered in the search. If your system has many command-paths, this operation may take a while. Command-completion is activated by pressing Alt-TAB or Amiga-M. Device-completion ----------------- Device-completion is quite simple, and is invoked by pressing Shift-TAB or Amiga-D. All volumes (like 'Workbench:'), assigns ('L:', 'FONTS:' etc) and DOS-devices ('PAR:', 'CON:' etc) are searched for a match. A few notes on the completion-functions --------------------------------------- After having read this, two questions come to our mind (?): The first is how spaces in filenames are handled. If you have completed a filename that includes spaces, quotation-marks will be inserted automatically in the beginning and the end of the word (where necessary). Let's say that you want to enter the following path: My Directory/The Manual.doc You start by entering 'my' and then press TAB. The line will look like this: "My Directory/ Now you enter 'the' and press TAB again. The path is now complete: "My Directory/The Manual.doc" Note how one quotation-mark was inserted in front of My Directory and one after The Manual.doc. The path will now be interpreted as one word by the command shell. If you want to match on a string that contains spaces, you must put a quotation-mark in front of the first word before you press TAB: "my dir To sum up, KingCON does the following to determine which filename to complete: If the line contains and ODD number of "'s left of the the cursor, the name is taken from the last quotation-mark to the position of the cursor. Otherwise, the beginning of the word is taken from the character next to the first space, comma, or one of ' = < >. (Dot not included.) The second question (remember?) is probably: What is this talk about 'current directories' and 'command-paths'? 'KCON:' is just a DOS-device and has no 'current dir' like the Shell. Is 'KCON:' some kind of shell or what?? The answer is that KingCON keeps track of which process that opened a KCON-window. Every time you invoke filename- or command-completion, KingCON looks at which directory is the current directory for the process that opened the window. Command-paths are also found this way. If the process that opened the window dies before the window is closed (this could be the case if it is a WAIT-window. See section 7), KingCON keeps the directory that was used last time some kind of completion was activated. Command-paths are lost, though. Dropping icons on the console ----------------------------- Another quick way to insert a filename on command-line is to drag one or more icons from the Workbench over the console window and droping them there. The complete path for the icon, including quotation-marks (when necessary), will be printed. This is only possible if the window was opened on the Workbench-screen. I've said it before, but I'll do it again, for the sake of clarity: KingCON is NOT a Shell, despite of the filename-completion and some other functions. No interpretation of what you type is done. To the programs that use 'KCON:' for input and output, it behaves just like 'CON:'. ================== 5. Review-buffer ================== One of the major differences between a CON-window and a KCON-window is that the latter has a scrollgadget in the left windowborder, that lets you browse through all the text that has been output to it since it was opened. When you have done a long directory-listing and want to go back to take a look at the first files that were listed, you just grab the knob and move it up until you find the place you looked for. The arrows can be used to scroll (approx.) one row up and down. As soon as you type something on the keyboard or a program wants to output something to the window, the "review-mode" is exited and the scrollknob moves to the bottom. This means that if you try to scroll while a file is being Type'd, the text will jump up and down between the position you want to look at and the bottom of the review-buffer. Confusing, maybe, but fully normal. If you have typed a few characters on the edit-line and then begin to scroll before you press Return, the line will disappear. But as soon as you type something again, the "review-mode" is exited and the line will be visible again. Differences between buffered text and original output ----------------------------------------------------- The text shown in the review-buffer doesn't always look like the text that originally was output to the window. Control-sequences to move the cursor, delete characters etc are not interpretated, which means that some programs that do fancy things to their output won't look that fancy when you begin dragging the scrollknob. This is not a bug, just a sacrifice for speed. :-> If you specify the NOSTYLES-option, all textstyle control-sequences will be filtered. This saves some memory and perhaps speeds up output on plain 68000's. The text in the buffer will always be black and white, though. Memory-management ----------------- The memory for the buffer is allocated dynamically when something is output to the window. Normally a maximum of 64Kb can be allocated for the buffer before the first lines start disappearing. The limit can be set to another value with the MAXBUF-option. (See section 7.) Don't forget that no memory is allocated for the buffer when the console window is opened, because of its dynamic nature. The drawback with this is that you lose memory for every line you write. This can be frustrating if you are debugging a program to see if it frees all memory when it returns. ('Avail', 'Program', 'Avail', you know.) In those situations, you should disable both the history-buffer and the review-buffer. Some notes on speed (68000-owner, read this!) ---------------------------------------------- You may notice that output is slowed down a bit when the buffer is enabled, especially if you have a plain 68000-Amiga. On faster machines, it takes more time just to scroll the window than to manage the buffer, so it shouldn't be a problem there. If you DO find it too slow, there are five things you can do: * Enable the jump-scroll. This can be done with the JUMP-option or by selecting the "Console » Jump scroll"-menu. Output will be fast but maybe a bit jumpy. * Specify the NOGADS-option. You will still have a review-buffer as usual, but no scrollgadget in the right windowborder. Because the updating of the scrollgadget has much overhead, removing it in this way is probably enough to solve the speedproblem. * Select the "Review » Enabled" menu to disable the buffer temporarily. You will still be able to scroll back to text that was buffered earlier, though. * Specify the NOREVIEW-option. In this way, you won't get any review- buffer at all. * Specify the NOSTYLES-option. The buffered text will only be black and white and you can save a lot of memory this way. Speed is also affected, especially if the text that is ouput to the window has a lot of fancy colors and styles. ========== 6. Menus ========== The menubar contains the following menus and menuitems: "Console"-menu: --------------- Reset (Z) - Clears the console-window and resets all styles etc. Use this if a program leaves the window in a complete mess. Jump scroll - If checked, output speed will be increased by scrolling the window several lines at the time. By default, jump-scroll is disabled, because it isn't 100% compatible with programs that do their own jump-scrolling, like 'more'. Use the JUMP-option to have this function enabled when the window is opened. Iconify (I) - The console window is iconified and put on the Workbench as an AppIcon. If you specify the NOICON-option, the menu will read "Minimize", and the window window will just be as small as possible instead of being turned into an icon. This will also happen in some other cases when it isn't possible to iconify the window for compability reasons. Normalize (N) - Positions the window at the same place with the same size as when it was opened. Can be disabled. Maximize (A) - Makes the window as big as possible within the visible area of the screen. Can be disabled. Halt (H) - Halts output. Resume (R) - Resumes output. About... (?) - Opens a requester telling you about the current version of KingCON, the author etc. Close (Q) - The same as clicking in the window's closegadget or typing Control-\. The process that owns the window decides if it should be closed. "Complete"-menu: (See also section 4!) -------------------------------------- Filename (F) - Completes a filename or directoryname. The same as pressing TAB. Command (M) - Completes a DOS-command. Same as pressing Alt-TAB. Device (D) - Completes a devicename. Same as pressing Shift-TAB. Show .info - If checked, .info-files will be considered when KingCON is looking for matches. "Review"-menu: (See also section 5!) ------------------------------------ Enabled - If checked, all text output to the window will be saved in the review-buffer. If not, you will still be able to scroll through old text, but no new text will be added. Clear buffer - Clears the review-buffer. Save plain text as... - Lets you select a file to which the buffer will be saved as plain text. Save with styles as... - Lets you select a file to which the buffer will be saved, including control-sequences for text style and color. "History"-menu: --------------- Enabled - If checked, lines typed by you will be saved in the command-history buffer. If not, no lines are saved, but you will still be able to browse through the lines that are already in the buffer. Clear buffer - Clears the history-buffer. The menus are ghosted while the console is in RAW-mode. The NOMENUS- option opens a window without a menubar. See section 7. ============================================ 7. Options when opening the console-window ============================================ A KCON-window is opened in the same way as a CON-window. The template for the "filename" is: KCON:LeftEdge/TopEdge/Width/Height/Title/Options/... All keywords are optional. If you want the default-value, you write nothing. For example, if you want to specify a title, but no position or size, you write: (Don't forget the quotation-marks if you have spaces in the filename!) "KCON:////My Title" The meaning of the keywords are quite obvious. The default is to open a window that covers covers the whole horisontal and half the vertical visible area of the screen. The window is positioned below the menubar of the screen if possible. The default title is 'KingCON'. This differs a bit from CON, which always opens a window in the top left corner of the screen with a fixed height. I think KingCON's way of opening is better. :-) The options allow you to customize the window. First the ones that are compatible with CON: AUTO The window isn't opened until some text is output to it or a program wants to read from it. It also gets a close-gadget. You can also use the AUTOICON-option for the same purpose if you want an icon for the window. CLOSE The window is equipped with a closegadget. BACKDROP The window is opened as a backdrop behind all other windows on the screen. NOBORDER The window has no border. Very confusing. NODRAG The window has no dragbar. NOSIZE The window has no sizing-gadget or zoom-gadget. The "Shrink"- and "Expand"-menuitems are disabled. SIMPLE You can mark and copy text from the console. This is the default. SMART The opposite of SIMPLE. This is the way the console window was before v2.0 of the OS. If the window is scaled down and then resized again, you will lose the text that was printed on the revealed portions of the window. WAIT The window isn't closed until you type Control-\, select Quit or click the closegadget. SCREEN The window will be opened on a public screen with a certain name (case-sensitive!). To open on the screen "TERM", you type: .../SCREEN TERM/... or .../SCREENTERM/... WINDOW
The console is attached to an already open window with the address expressed in hexadecimal numbers. The review-buffer will be disabled for compability. INACTIVE The window isn't activated when it is opened. ALT/// When the zoom-gadget is clicked, the window will get the position and dimensions described by x,y,w & h. For example, ...ALT100/100/400/50... will make the window a thin strip in the middle of the screen when you click the zoom-gadget. These options are new for KingCON: AUTOICON This is exactly the same as the AUTO-option, except that an AppIcon is put on the Workbench as long as the window is closed. If you try a lot of PD-programs, it can be convenient to have the following line in the startup-sequence: Run Enforcer FILE CON:////Bang!/AUTOICON MINI The window is minimized the first time you hit the zoom-gadget instead of being resized to fill the whole screen. NOGADS No scrollgadget in the right windowborder is created. On slower machines this will increase the speed of the review- buffer noticeably. You can still use the keys described in section 3 to scroll through buffered text, of course. NOREVIEW The window gets no review-buffer. No scrollgadget is created and the "Review"-menu is disabled. If you just want to gain speed, first try the NOGADS-option. NOSTYLES Control-sequences that control textstyle and -color are not saved in the review-buffer. Buffered text will be plain black and white. NOFNC (Short for No FileName Completion). The TAB, Shift-TAB and ESC-keys don't activate any completion-function in order to be compatible with CON. Note that you can still use the "Completion"-menu!!! NOMENUS No menubar is created. PLAIN The same as NOREVIEW/NOFNC/NOMENUS. The window will behave exactly like a CON-window. JUMP Enables jump-scroll. You can also use the "Console » Jump scroll" menu to enable it. Note that some programs, like 'more', don't like jump-scroll. NOICON The window will just be minimized instead of iconified when you select Iconify/Minimize from the menu. ASYNC Enables asynchronous typeahead. See also end of section 3. SHOWDIR The current directory is displayed in the titlebar. MAXBUF Sets the biggest size for the review-buffer in kilobytes. The smallest possible value 4. It is not always wise to set the size to a very big value, because your system can run out of memory if you output a lot of text to the console. FONT Another font than the default-font is used. To specify a bigger topaz-font you type: .../FONT topaz.44/... or .../FONTtopaz.44/... Note that the font must be monospaced or the window will fail to open! I suggest that you use the FONT-option to change the font instead of the SETFONT-command. ========== 8. To do ========== KingCON introduces some very useful features that makes it a worthy replacement for CON. But there are still a few things I want to see in a future version: * Most certainly next version will contain some kind of preference-editor. This will let you set the default-options (so you won't have to specify CLOSE for every window you open, for example), set the size of the buffers etc. I'm also thinking of an extra option where you select which preferences you wish to use. * Configurable editing- and function-keys. * More TAB-expansion-methods, for those who like the way that many UNIX-shells work. * The review-buffer could be more intelligent and interpret cursor-moves. * A new completion-function that completes words from a textfile that you specify. All the switches for DOS-commands, for example. * A special gadget in the titlebar for iconifying the window. * Localized menus, Kickstart 3.0-specific functions, smaller, faster... If you have something else that you would like to see implemented in KingCON (or if you find one of those annoying b*gs), feel free to mail me. Who knows, maybe I do something about it! /|t last I want to say a BIG THANKYOU to everybody / |that have reported bugs and come with good ideas. / |Most new features in this version are here thanks /¯¯¯|to you (and me of course). / | ¯¯ ¯¯¯ /¯\ David Larsson /¯\ Engineering Physics /¯\_/¯¯¯¯ / \_/¯\ /¯¯¯\_/ \ Chalmers University of Technology / Sweden / \_/ \ /¯\ /¯\ /¯\_/¯\ / ¯\ / \ / \_/ \ / \ / \_/ f92dala@dd.chalmers.se \__/ \_/ \__/