Documentation for Most V1.45 Date: 20 April 1993 Author: Uwe Röhm Most is a 2.0 only textviewer which I wrote with full workbench support in mind. First at all an overview of interesting features: - unlimited number of windows - each text has its own process - search function - highly configurable - clipboard support - "click-and-load" function for includes - font sensitive GUI - PubScreen, CustomScreen or Workbench - AppWindow, AppIcon - ARexx Port - localization with locale.library - AmigaGuide support - XPK support - pipe support - as mentioned, kickstart 2.0 is requiered Most V1.45 *********** Copyright ********** Most 1.45 is published under the concept of GiftWare! So if you find Most a useful tool (and of course use it) please make me a present of any kind - and make me *very* happy. Beside this I keep my Copyright: Copyright (C) 1992/1993 by Uwe Röhm You *must* get my aggreement if you wish to publish Most in a commercial product. Especially it is not allowed to use Most for military purposes of any kind which includes using Most in companies which plan or only support military products. You are allowed to include Most in PD packages which cost less than $10.- ! But I ask you to keep the archive together. You have to include the documentation with each version. Thank you! Background *********** There are some goals I try to achieve with Most: - full workbench support - easy to use with mouse *and* keyboard - flexibility - memory friendly :-) So Most uses a window for *each* text - there is no possibility to use it like Commodore's More in a shell. Of course you can choose another screen to open on or even an own CustomScreen. How much windows are opened by Most and where they are is absolut without interest and only limited by the amount of free (chip-) memory! As each text is displayed in his own window there is also its own process behind. Cause of the windows are absolut independent of each other. Especially you can send ARexx commands to different windows simultaneous and you are free to open new Most windows even if previously opened windows are "busy" - there is Most's main process which handles all texts and some global ARexx commands (see ARexx Port). To be memory friendly and to display very huge texts even on a 500KB system Most does buffering. Small texts, which fit completly into the buffer, are read only once and closed than so that you can e.g. edit and save it again. But if the text is larger than the configurated buffer length (yes, of course you can change the buffer size, but read on :-) ) Most will do some sort of "paging". So memory usage will be limited by the buffer size you specified (little memory -> small buffer). On the other hand this slowes scrolling and searching down!!! Sorry for this, but if you have enough memory just increase to buffer size to - let's say - 2 MB. Don't be afraid. Of course Most only uses the amount of memory it needs if a text is smaller than the buffer ;-) There is one exception of the paging method: `XPK' packed files. In the current version Most does *no paging* to `XPK' files but reads the complete file into memory (see XPK support). Perhaps this will change in future, perhaps it will stay... Oh, I nearly forgot that Most can diplay all `ANSI' sequences. Without this it wouldn't be a real textviewer. As I don't want to do old work again and again I decided to use the console.device. This enables you to mark lines and copy them with `Amiga C' into the clipboard! I regret that there are also some problems: - You can only mark text inside the visible text portion. - Scrolling is quiet annoying on an Amiga without 680x0 (x > 1). - Don't load binary files. I warned you!!! Configuration ************** Most does the following configuration steps on startup: 1. internal defaults 2. Environments `Most/Most' and `Most/FileReq' (When used from shell local environments will be read first!) 3. Shell-start: parse command line WB-start : parse ToolTypes And now, ladys and gentlemen, here are the options to be used in 2.) and 3.): FILES ====== Usage A list of filenames to be displayed (only on shell command line!). You can use any AmigaDOS wildcards. PUBSCREEN ========== Usage Name of PubScreen where Most will open its windows on. PORTNAME ========= Usage Custom name of global ARexx Port of Most. Overrides the default name. Default MOSTPORT STARTUP ======== Usage Name of an ARexx script which will be executed every time Most opens a window. (see ARexx Port). WINDOWX ======== Shortcut WX Usage X-coordinate of The main window WINDOWY ======== Shortcut WY Usage Y-coordinate of The main window. -1 for centered windows WINDOWW ======== Shortcut WW Usage width of windows Default 600 WINDOWH ======== Shortcut WH Usage height of windows Default 400 SCREENMODE =========== Shortcut SM Usage A valid screenmode Most will use to open its on screen with (which will be a PubScreen named `Most'). You can get a list of the avaible screenmodes of your system if you start `Prefs/ScreenMode.' *Attention!* The names of the screenmodes are different for most versions of the monitor files. Remember that you must specify a valid name, which means, that you must spell it exactly as in the monitor files. If in doubt start `Prefs/ScreenMode' and read the listview. Example SCREENMODE "Pal:HighRes" FONT ===== Usage name of a font to be used. The name must include the `.font' postfix. Don't forget it! And be careful with proportional fonts. Example FONT "helvetica.font" FONTHEIGHT =========== Usage Tells Most which font height it should use. Works only together with the FONT option. If not specified Most uses the system default font's height. APPICON ======== Usage A switch, which lets Most use an AppIcon on workbench. If you start Most with the APPICON option and without further file names, Most will only put its AppIcon onto workbench and stay in background. (see The AppIcon) ICONX ====== Usage X-coordinate of Most's APPICON on workbench ICONY ====== Usage Y-coordinate of Most's APPICON on workbench BUFLEN ======= Usage Very interesting option to justify Most's buffer size. In general: On small systems use small values, on larger systems try higher buffer sizes. BUFLEN defaults to 50 KB (which is quiet small :-) ). Texts smaller than the buffer size will be read complete into memory and use only the necessary amount of memory. Default 50 000 Bytes PIPELEN ======== Usage Most can also read out of a pipe. Normally it would allocate a buffer of BUFLEN/10 Bytes for reading. With this option you can justify the buffer length for pipes by hand. Example PIPELEN 8192 QUOTES ======= Usage You can specify a sequence of quote characters. These characters will be used for the "click-and-load" option: If you doubleclick on a word which stands *between* a quote character Most will try to load a text named like this word. This is very useful for programmers as you can view include files very easy! Default "'<>(){}[] DIRS ===== Usage Specify one or more directories Most will search through if you use the "click-and-load" function (see QUOTES). All directories must be seperated by `|'. Example DIRS "Include:|TexInputs:|LC:Include/" ENDS ===== Usage Postfixes to be appended on include files with the "click-and-load" function in the given order (see DIRS, see QUOTES). Example ENDS ".c.h.tex" Keyboard commands ****************** In the current version Most supports all (and more!) keyboard shortcuts well known from More. Future versions will allow custom keyboard commands... Scrolling ========== one line forwards `CURSOR DOWN' `NUMERICPAD 2' `RETURN' `ENTER' one line backwards `CURSOR UP' `NUMERICPAD 8' `DELETE' one page forwards `SHIFT CURSOR DOWN' `SPACE' `PAGE DOWN' one page backwards `SHIFT CURSOR UP' `BACKSPACE' `PAGE UP' `b' Jump to beginning of text `HOME' `<' Jump to end of text `END' `>' oen column to the right `CURSOR RIGHT' `NUMERICPAD 6' one column to the left `CURSOR LEFT' `NUMERICPAD 4' 8 columns to the right `SHIFT CURSOR RIGHT' 8 columns to the left `SHIFT CURSOR LEFT' Searching ========== search actual searchstring again `n' ignore upper/lower case `.' searching with distinction of upper/lower case `/' Open the search requester `f' `s' Open file ========== Load new text with `l' (a filerequester shows up). Info requester =============== Beside the usual Copyright you find here some information about the current text: Its filename, the filelength, the number of lines and the visual number of lines, and also the name of the `XPK' packer (or just "---" if the file isn't packed). At last there's a message indicating that the current text has been read completly into memory or -- if not -- the length of the used read buffer. The Info requester can be opened with `h'. Help ===== If you press `HELP', the AmigaGuide will be started with the documentation of Most. Of course this requires the AmigaGuide be installed correctly. If Most can't open the amigaguide.library it will open the Info requester. AmigaGuide searches its documents in the current directory and also in the paths listed in the environment variable AMIGAGUIDE/PATH. Edit file ========== If you press `e', the current text will be loaded into an editor. The editor will be started in the background. The namen of the editors must be configurated in the environment variable EDITOR. Quit file ========== Close the text window with `ESCAPE', `CTRL-C' or `q'. Menus ****** There are the following menus available: Project ======== `New...' Opens a new window and brings up a filerequester where you can choose a text file to be displayed in the new window. If you cancel the filerequester the window will be closed. The position and dimensions of the filerequester can be stored in Settings. `Open...' Asks you for a new file to be loaded into the current window. `Edit...' Starts the editor with the current text via RUN. The name of the editor can be configurated in ENV:Editor (see Edit). `Info...' Pops up the Info requester where you find some useful information to the current text like name, length, line count, visible lines, `XPK' packername and a short comment if the text has been loaded completely into memory or if it uses an buffer. `Quit' Quits the current window (and if it was the last one Most at all) Move ===== Move through the current text as the menus describe. With the menu "Jump to line..." you can specify a certain line number in a requester where you will jump to. Menu Search ============ `searching...' The search requester will be opened with its stringgadget activated. If the search requester is open this menu is disabled. `forwards/backwards' Search string forwards/backwards (only with open search requester) Extras ======= `Refresh page' Reset console and redraw page `Execute ARexx Macro...' Asks for an ARexx Macro to be executed (see ARexx Port). Settings ========= `save' `global Prefs' Save actual settings in two environments in ENV: and ENVARC:. A subdirectory `Most' will be created automatically. All known options from workbench or shell start are saved and also the dimensions and position and the pattern string of the file requester. `local Prefs' Does the same as above, but uses local shell variables. This only works if you started Most from a Shell! The main window **************** Title In the title the filename and on the right hand side the current column and line numbers are displayed. Format: / Gadgets Beside the system gadgets there are three further ones which control text scrolling: You can use the scroller continously by click-and-draging or for scrolling one page forwards/backwards if you click under/above the knob. The knob's position represents the current text position, its height the relation between the visible and the total text length. Use the arrows to scroll one line in the correspondending direction. Mouse "Click-And-Load" function. If you doubleclick into the window Most will look at this position to find a word which is limited by one of the configurated quote characters (see QUOTES). This word (can include spaces!!) will be treated as a filename for which Most searches first in the current directory and than in each further configurated (see DIRS) directory. Most will also try the plain filename and than (if not found) append each prefix given with the ENDS option. The first found file will be displayed in a new window. If no name matches, the screen will flash (DisplayBeep). Example: Doubleclick on ``#include '' between ``<'' and ``>''. the file `Include:Exec/Exec.h' will be loaded, if you specifed ``DIRS Include:'' on startup. Clipboard You can easy mark any text in the visible text by click-and-dragging (drag without releasing the mouse button). Copy the marked block with `Amiga-C' into the clipboard. The current version doesn't support paste from the clipboard. AppWindow Take any "real" icon (no AppIcon) on workbench and drop it in Most's window. It will be loaded into the current window. If you drop more than one icons Most will open further windows. The search requester ********************* Here you can enter a search string and also manipulate the three search option. Therefor you can use the mouse and/or the keyboard shortcuts indicated by the underlined characters. Additionaly you have the same functionality as in the main window! So no annoying re-activation of The main window. - All menus are avaible as in the text window. Only the Menu Search will be disabled and instead "search forwards" and "search backwards" are unghosted. - Beside the mentioned Requester shortcuts you can use *all* normal Keyboard commands like scrolling with the cursor keys!!! (Be sure the string gadget isn't activated) The AppIcon ************ The AppIcon has two functions `Doubleclick' A filerequester will come up where you can choose a file to be loaded and displayed. If you select "Cancel" Most will show a security requester where you can quit Most. `Icons' Drag-and-drop one or more icons on the AppIcon and they will be loaded. Comments: Most uses his own program icon as its APPICON. Perhaps I will support custom icons in the future but not yet ;-) The coordinates of the AppIcon can be saved in the menu Settings. Use the options ICONX and ICONY for exact placement of the AppIcon. XPK support ************ Main goal of Most's `XPK' support is to hide any consequences of packed data from the user. This means, that any packed file (with `XPK') will automatically be unpacked from Most if the `XPK' packages is correct installed. The only hint you get is in the information requester, where the line "XPK-packer:" will show you the used packer (usually you see "---" there). There is only one thing special with `XPK' packed data: The file will be loaded completely into memory and no buffering will be done! If Most finds an encrypted files (with `XPK' of course), it opens a password requester and prompts you for the password. Be careful, because this is your only chance! If you give the wrong answer, you will see the encrypted file and have to reload it. On the other hand if you don't have `XPK' you can use Most without any difference. The xpkmaster.library is not required by Most to run at all. Of course in this case `XPK' packed data will not be unpacked :-) Pipe support ************* As a special feature Most 1.42 supports pipes. This means, that you can type something like "type foo | Most" at your (W)Shell prompt and Most will show the output of the first type command in its window! As I said this feature is brand new. So I regret that I couldn't test it for all possibilities. Please report me any failure. There are two small problems: 1. `XPK' doesn't work with pipes. 2. Second there is the problem with pipes that you cannot know how much data therein will be... So one effect is, that you cannot scroll back to the start of an file if you scrolled over the bounds of a buffer and the other one is that the size of the buffer will be (maximum BUFLEN / 10) every time (you can set the pipe's buffer size with the PIPELEN option). If the pipe's data fits completly into the buffer you have no restrictions for scrolling. But if the data is to large - Sorry. ARexx Port *********** Beside the global ARexx port MOSTPORT (or the name you gave it with the option PORTNAME on startup) of Most's main process each text window has his own private ARexx port. To select a window first send the command GetFileList to the global port. You will receive a list of the avaible windows and its portnames. All following ARexx commands can be send to a private window port, but Most's main port does only understand the first 6 commands GetFileList, GetScreenName, Quit, OpenNew, Set and Request. In RC Most will return an errorcode of * 0 for no errors * 5 if it couln'd open a new text with Open or OpenNew * 10 if the parameters for a command were wrong * 20 for an unknown ARexx command All other commands will return an errorcode of 20 if send to MOSTPORT. Sorry, but the ARexx port isn't complete today. But I'm working on it :-) The following ARexx commands are supported: GetFileList ============ Template GetFileList Result In RESULT you get a list of all available text windows and their port names. RESULT looks like this: { }^+ Example GetFileList RESULT: "Most.dok MOST.0 Most.doc MOST.1" GetScreenName ============== Template GetScreenName Result RESULT contains screen name. Usage Get the name of the screen, where the current window is on. Example GetScreenName RESULT - "Workbench" Quit ===== Template Quit Usage Quits Most and closes *all* windows. The AppIcon of Most will be deleted -- if there is one at all. Example Quit Request ======== Template Request TITLE/K/A TEXT/K/A GADGETS/K/A Resultat RESULT contains number of selected gadget: 0 the most right gadget (should be "Cancel") 1 bis n-1 the other gadgets from left to right Usage A simple method of asking the user silly questions via requester. Title and text are simple strings. With GADGETS you specify the texts of the gadgets (and how much gadgets there are), seperated with '|'. Example Request TITLE "Test" TEXT "All OK?" GADGETS "YES|No" RESULT - 1 if YES has been selected, else 0 Set ==== Template Set CASE/S WORD/S BACK/S Usage Set some internal parameters like CASE ignore upper/lower case on/off WORD search only for whole words on/off BACK search backwards on/off All parameters will be set if specified, and disabled otherwise. Example Set CASE ON Enables casesensitiv searching, but disables the other two options. OpenNew ======== Template OpenNew FILE/K Usage Load a new text in a new window. The filename is optional. If you don't specify a name a filerequester opens. You don't need to select a current window before. This command doesn't return until the new window is closed again! Example OpenNew FILE Most.dok Open ===== Template Open FILE/K Usage Load a new text in the current window. The filename is optional. If you don't specify a name a filerequester opens. This command doesn't return until the window is closed again! Example Open FILE Most.dok Close ====== Template Close Usage Closes the current window. ToFront ======== Template ToFront Usage Makes the current visible: It will be made the frontmost window and the screen it's on will be activated and go to front. GetWindowDims ============== Template GetWindowDims Result In RESULT stands ` ' Usage Get the position and dimensions of the current window in RESULT Example GetWindowDims RESULT - "40 40 600 180" Edit ===== Template Edit Usage Edit the current text (runs editor). Info ===== Template Info Usage Opens the Info requester to the current window. FirstPage ========== Template FirstPage Usage Show the first page of the current text. LastPage ========= Template LastPage Usage Show the last page of the current text. NextPage ========= Template NextPage Usage Show the next page of the current text. PrevPage ========= Template PrevPage Usage Show the previous page of the current text. NextLine ========= Template NextLine Usage Scroll up one line. PrevLine ========= Template PrevLine Usage Scroll down one line. NextColumn =========== Template NextColumn Usage Scroll left one column. PrevColumn =========== Template PrevColumn Usage Scroll right one column. NextTab ======== Template NextTab Usage Scroll left 8 columns. PrevTab ======== Template PrevTab Usage Scroll right 8 columns. Goto ===== Template Goto LINE/K/N/A COLUMN/K/N Usage Jump to the specified line. Optional you can specify a new first column. Example Goto LINE 142 Search ======= Template Search TEXT/K Usage Without argument: The search requester opens or if allready open the current string will be search again. With searchstring: Search for the given string. Example Search TEXT foobar Known bugs *********** - Several control sequences for cursor movements trash the display. Ideas - Bug reports ******************** As mentioned before Most isn't complete today. There are some points I will improve in the future. I also have Commodore's Style Guide in mind and will follow its rules the next release better. I'm absolut interested in any kind of responds - ideas, enhancements requests, criticism or bug reports. Call me, write me, mail me. I will hear you! My address: Uwe Roehm Woerthstr. 18 8390 Passau Germany EMail: bugs@roemer.adsp.sub.org Fido: 2:246/200.5 Current version **************** You can download the current version of Most from `ftp.uni-passau.de' (132.231.1.10) in the directory `pub/amiga/local/UweR'. You will also find other interesting software in `pub/amiga/local'... Greetings ********** I want to thank my beta testers Karl, obviously never sleeping David, Uli, Holger, Stefan and Stefan ;-) A special thanks to Urban for his sugesstions and `XPK'. And a great thank you to everyone who wrote me bug reports or suggestions, especially Tron!!! Index ****** XPK XPK support AINSI Sequences Background AmigaGuide Help AppIcon The AppIcon AppWindow The main window ARexx ARexx Port ARexx Port ARexx Port Author Ideas - Bug reports Background Background Bugs Known bugs Clipboard The main window Commandline Configuration Configuration Configuration Copyright Copyright Criticism Ideas - Bug reports Current version Current version Default values Configuration Edit Edit file encrypted files XPK support Environments Configuration Extras Extras Gadgets The main window Giftware Copyright Greetings Greetings Help Help Ideas Ideas - Bug reports Includefiles The main window Info requester Info requester Keyboard commands Keyboard commands Macros Extras Memory managment Background Menu Search Menu Search Menus Menus Mouse The main window Move Move packed files XPK support Paging Background Parameter Configuration Pipe support Pipe support Processes Background Project Project Refreshing Extras Scripts ARexx Port Search The search requester search requester The search requester Searching Searching Settings Settings Shell start Configuration Startup Configuration Suggestions Ideas - Bug reports Text managment Background Text marking The main window Thanks Greetings Title The main window ToolTypes Configuration Variables Configuration Window The main window Workbench start Configuration