home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / compress / xpk25usr.lha / Workbench / most / Most.doc < prev    next >
Text File  |  1992-11-11  |  19KB  |  534 lines
  1.  
  2.  
  3.                          Documentation for Most V1.31
  4.  
  5.  
  6.                              Date  : 11 Nov 1992
  7.                              Author: Uwe Röhm
  8.  
  9.  
  10.  
  11.    Most is a 2.0 only textviewer which I wrote with full workbench support
  12.    in mind. First at all an overview of interesting features:
  13.  
  14.        - unlimited number of windows
  15.        - each text has its own process
  16.        - search function
  17.        - highly configurable
  18.        - clipboard support
  19.        - "click-and-load" function for includes
  20.        - font sensitive GUI
  21.        - PubScreen, CustomScreen or Workbench
  22.        - AppWindow, AppIcon
  23.        - ARexx Port
  24.        - localization with locale.library
  25.        - XPK support
  26.        - pipe support
  27.        - as mentioned, kickstart 2.0 is requiered
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.                            Table of Contents
  35.                           ===================
  36.  
  37.                            1. Copyright
  38.                            2. Background
  39.                            3. Configuration
  40.                            4. Keyboard commands
  41.                            5. Menus
  42.                            6. Most's window
  43.                            7. The search requester
  44.                            8. The AppIcon
  45.                            9. XPK support
  46.                           10. pipe support
  47.                           11. ARexx Port
  48.                           12. Ideas, Bug reports
  49.                           13. current versions
  50.                           14. Thanks
  51.  
  52.  
  53.  
  54.  
  55.  
  56. 1.  Copyright
  57.    ===========
  58.  
  59. Most 1.31 is published under the concept of GiftWare! So if you
  60. find Most a useful tool (and of course use it) please make me a present
  61. of any kind - and make me VERY happy.
  62.  
  63. Beside this I keep my Copyright:  Copyright (c) 1992 by Uwe Röhm
  64.  
  65. You MUST get my aggreement if you wish to publish Most in a commercial product.
  66. Especially it is not allowed to use Most for military purposes of any kind
  67. which includes using Most in companies which plan or only support military
  68. products.
  69.  
  70. You are allowed to include Most in PD packages which cost less than $10.- !
  71. But I ask you to keep the archive together. You have to include the
  72. documentation with each version. Thank you!
  73.  
  74.  
  75.  
  76.  
  77. 2.  Background
  78.    ============
  79.  
  80. There are some goals I try to achieve with Most:
  81.   - full workbench support
  82.   - easy to use with mouse AND keyboard
  83.   - flexibility
  84.   - memory friendly :-)
  85.  
  86. So Most uses a window for EACH text - there is no possibility to use it
  87. like Commodore's More in a shell. Of course you can choose another screen
  88. to open on or even an own CustomScreen. How much windows are opened by
  89. Most and where they are is absolut without interest and only limited by
  90. the amount of free (chip-) memory!
  91.  
  92. As each text is displayed in his own window there is also its own process
  93. behind. Cause of the windows are absolut independent of each other.
  94. Especially you can send ARexx commands to different windows simultaneous
  95. and you are free to open new Most windows even if previously opened
  96. windows are "busy" - there is Most's main process which handles all
  97. texts and some global ARexx commands.
  98.  
  99. To be memory friendly and to display very huge texts even on a 500KB
  100. system Most does buffering. Small texts, which fit completly into the
  101. buffer, are read only once and closed than so that you can e.g. edit
  102. and save it again. But if the text is larger than the configurated
  103. buffer length (yes, of course you can change the buffer size, but read
  104. on :-) ) Most will do some sort of "paging". So memory usage will be
  105. limited by the buffer size you specified (little memory -> small buffer).
  106. On the other hand this slowes scrolling and searching down!!! Sorry
  107. for this, but if you have enough memory just increase to buffer size
  108. to - let's say - 2 MB. Don't be afraid. Of course Most only uses the
  109. amount of memory it needs if a text is smaller than the buffer ;-)
  110.  
  111. There is one exception of the paging method: XPK packed files. In the
  112. current version Most does NO PAGING to XPK files but reads the complete
  113. file into memory. Perhaps this will change in future, perhaps it will
  114. stay...
  115.  
  116. Oh, I nearly forgot that Most can diplay all ANSI sequences. Without this
  117. it wouldn't be a real textviewer. As I don't want to do old work again
  118. and again I decided to use the console.device. This enables you to mark
  119. lines and copy them with "Amiga C" into the clipboard! (Don't use the
  120. FASTSCROLL Option if you want mark something). I regret that there are
  121. also some problems:
  122.  - You can only mark text inside the visible text portion.
  123.  - Scrolling is quiet annoying on an "normal" Amiga without 680x0 (x > 1).
  124.  - Don't load binary files. I warned you!!!
  125.  
  126.  
  127.  
  128.  
  129. 3.  Configuration
  130.    ===============
  131.  
  132. Most does the following configuration steps on startup:
  133.  1.) internal defaults
  134.  2.) environments "Most/Most" und "Most/FileReq"
  135.      (When used from shell local environments will be read first!)
  136.  3.) Shell-start: parse command line
  137.      WB-start   : parse ToolTypes
  138.  
  139. And now, ladys and gentlemans, here are the options to be used in 2.) and 3.):
  140. FILES             list of filenames to be displayed (shell only!!!)
  141. PUBSCREEN         name of PubScreen where Most will open its windows on
  142. PORTNAME          overwites the default ARexx portname "MostPort"
  143. STARTUP           name of an ARexx Macro executed every time Most opens a window
  144. WX=WINDOWX        X-coordinate of Most's window
  145. WY=WINDOWY        Y-coordinate of Most's window. -1 for centered windows
  146. WW=WINDOWW        width of windows  (defaults to 600)
  147. WH=WINDOWH        height of...      (defaults to 400)
  148. SM=SCREENMODE     A valid screenmode Most will use to open its on screen with
  149.                   (which will be a PubScreen named 'Most').
  150.                   You can get a list of the avaible screenmodes of your system
  151.                   if you start Prefs/ScreenMode.
  152.                   ATTENTION!
  153.                   The names of the screenmodes are different for most versions
  154.                   of the monitor files. Remember that you must specify a valid
  155.                   name, which means, that you must spell it exactly as in the
  156.                   monitor files. If in doubt start Prefs/ScreenMode and read
  157.                   the listview.
  158. FONT              name of a font to be used. The name must include the '.font'
  159.                   postfix. Don't forget it! And be careful with proportional fonts.
  160. FONTHEIGHT        works only together with the FONT option (see above).
  161.                   if not specified Most uses the system default font's height.
  162. APPICON           a switch, which lets Most use an AppIcon on workbench.
  163.                   If you start Most with the APPICON option and without
  164.                   further file names, Most will only put its AppIcon onto
  165.                   workbench and stay in background. (Read on for more details)
  166. ICONX             X-coordinate of Most's AppIcons
  167. ICONY             (see ICONX)
  168. FASTSCROLL        a switch to force Most to use console without the copy
  169.                   option. This will (slightly) increase output speed...
  170. WORDWRAP          a switch to AVOID word wrap.
  171.                   ATTENTION!
  172.                   Without word wrap Most will scroll long lines quiet strange ;-)
  173. BUFLEN            very interesting option to justify Most's buffer size.
  174.                   In general: On small systems use small values, on larger
  175.                   systems try higher buffer sizes. BUFLEN defaults to 50 KB
  176.                   (which is quiet small :-) ). Texts smaller than the buffer
  177.                   size will be read complete into memory and use only the
  178.                   necessary amount of memory.
  179. QUOTES            you can specify a sequence of quote characters.
  180.                   These characters will be used for the "click-and-load"
  181.                   option: If you doubleclick on a word which stands BETWEEN a
  182.                   quote character Most will try to load a text named like this
  183.                   word. This is very useful for programmers as you can view
  184.                   include files very easy!
  185.                   Default: "'<>(){}[]
  186. DIRS              specify one or more directories Most will search in if you
  187.                   use the "click-and-load" function (see above). All directories
  188.                   must be seperated by |
  189.                   Example: DIRS "Include:|TexInputs:|LC:Include/"
  190. ENDS              Postfixes to be appended on include files with the "click-and-
  191.                   load" function (see above) in the given order!
  192.                   Example: ENDS ".c.h.tex"
  193.  
  194.  
  195.  
  196.  
  197. 4.  Keyboard commands
  198.    ===================
  199.  
  200. In the current version Most supports all (and more!) keyboard shortcuts well
  201. known from More. Future versions will allow custom keyboard commands...
  202.  
  203.  * Scrolling
  204.    CURSOR DOWN
  205.    NUMERICALPAD 2
  206.    RETURN
  207.    ENTER
  208.       one line forwards
  209.  
  210.    CURSOR UP
  211.    NUMERICPAD 8
  212.    DELETE
  213.       one line backwards
  214.  
  215.    SHIFT CURSOR DOWN
  216.    SPACE
  217.    PAGE DOWN
  218.       one page forwards
  219.  
  220.    SHIFT CURSOR UP
  221.    BACKSPACE
  222.    "b"
  223.    PAGE UP
  224.       one page backwards
  225.  
  226.    HOME
  227.    "<"
  228.       jump to beginning of text
  229.  
  230.    END
  231.    ">"
  232.       jump to end of text
  233.  
  234.  * Searching
  235.    "n"
  236.       search actual searchstring again
  237.  
  238.    "."
  239.       ignore upper/lower case
  240.  
  241.    "/"
  242.       searching with distinction of upper/lower case
  243.  
  244.    "f"
  245.    "s"
  246.       open search requester (if it es opened, search string)
  247.  
  248.  * load new text
  249.    "l"
  250.  
  251.  * information
  252.    HELP
  253.    "h"
  254.  
  255.  * start editor (as configurated in ENV:Editor)
  256.    "e"
  257.  
  258.  * close text
  259.    ESCAPE
  260.    "q"
  261.  
  262.  
  263.  
  264. 5.  Menus
  265.    ======
  266.  
  267. Project
  268.    New...
  269.       Opens a new window and brings up a filerequester where you can choose
  270.       a text file to be displayed in the new window. If you cancel the
  271.       filerequester the window will be closed.
  272.    Open...
  273.       Asks you for a new file to be loaded into the current window
  274.    Edit...
  275.       Starts the editor with the current text via RUN. The name of the editor
  276.       can be configurated in ENV:Editor
  277.    Info...
  278.       Pops up an information requester where you find some useful
  279.       information to the current text like name, length, line count,
  280.       visible lines, XPK packername and a short comment if the text
  281.       has been loaded completely into memory or if it uses an buffer.
  282.    Quit
  283.       Quits the current window (and if it was the last one Most at all)
  284.  
  285. Move
  286.    Move through current text as the menus describe.
  287.  
  288. Search
  289.    suchen...
  290.       Opens search requester (described later) and activates its string
  291.       gadget. If the search requester is open this menu is disabled.
  292.    forwards
  293.    backwards
  294.       Search string forwards/backwards (only with open search requester)
  295.  
  296. Extras
  297.    Refresh page
  298.       Reset console and redraw page
  299.    Execute ARexx Macro...
  300.       Asks for an ARexx Macro to be executed.
  301.  
  302. Settings
  303.    save
  304.       global Prefs
  305.          Save actual settings in two environments in ENV: and ENVARC:. A
  306.          subdirectory Most will be created automatically.
  307.          All known options from workbench or shell start are saved and
  308.          also the dimensions and position and the pattern string of the
  309.          file requester.
  310.  
  311.       local Prefs
  312.          Does the same as above, but uses local shell variables. This
  313.          only works if you started Most from a Shell!
  314.  
  315.  
  316.  
  317.  
  318. 6.  Most's window
  319.    ===============
  320.  
  321. * Gadgets
  322.    Beside the system gadgets there are three further ones which control
  323.    text scrolling:
  324.    You can use the scroller continously by click-and-draging or for
  325.    scrolling one page forwards/backwards if you click under/above the
  326.    knob. The knob's position represents the current text position, its
  327.    height the relation between the visible and the total text length.
  328.    Use the arrows to scroll one line in the correspondending direction.
  329. * Mouse
  330.    "Click-And-Load" function
  331.    If you doubleclick into the window Most will look at this position to
  332.    find a word which is limited by one of the configurated quote characters.
  333.    This word (can include spaces!!) will be treated as a filename for
  334.    which Most searches first in the current directory and than in each
  335.    further configurated (DIRS option) directory. Most will also try
  336.    the plain filename and than (if not found) append each prefix given
  337.    with the ENDS option. The first found file will be displayed in a
  338.    new window. If no name matches, the screen will flash (DisplayBeep).
  339.    Example: Doubleclick on " #include <exec/exec.h>" between < and >.
  340.             the file Include:Exec/Exec.h will be loaded, if you
  341.             specifed DIRS Include: on startup.
  342.  
  343.    clipboard support
  344.    If you don't use the FASTSCROLL mode you can easy mark any text in the
  345.    visible text by click-and-dragging (drag without releasing the
  346.    mouse button). Copy the marked block with "Amiga-C" into the clipboard.
  347.    The current version doesn't support paste from the clipboard.
  348. * AppWindow
  349.    Take any "real" icon (no AppIcon) on workbench and drop it in Most's
  350.    window. It will be loaded into the current window. If you drop more
  351.    than one icons Most will open further windows.
  352.  
  353.  
  354.  
  355. 7.  The search requester
  356.    ======================
  357.  
  358. Here you can enter a search string and also manipulate the three search
  359. option. Therefor you can use the mouse and/or the keyboard shortcuts
  360. indicated by the underlined characters.
  361. Additionaly you have the same functionality as in the main window! So no
  362. annoying re-activation of Most's textwindow.
  363.  - All menus are avaible as in the text window. Only the menu
  364.    "search" will be disabled and instead "search forwards" and "search
  365.    backwards" are unghosted.
  366.  - Beside the mentioned Requester shortcuts you can use ALL normal
  367.    keyboard commands like scrolling with the cursor keys!!!
  368.    (Be sure the string gadget isn't activated)
  369.  
  370.  
  371.  
  372. 8.  The AppIcon
  373.    =============
  374.  
  375. The AppIcon has two functions
  376.  - Doubleclick
  377.    A filerequester will come up where you can choose a file to be loaded
  378.    and displayed. If you select CANCEL Most will show a security requester
  379.    where you can quit Most.
  380.  - Icons
  381.    Drag-and-drop one or more icons on the AppIcon and they will be loaded.
  382.  
  383. Comments:
  384.    Most uses his own program icon as its AppIcon. Perhaps I will support
  385.    custom icons in the future but not yet ;-)
  386.    The coordinates of the AppIcon can be saved with "Save Settings".
  387.    Use the options ICONX and ICONY for exact placement of the AppIcon.
  388.  
  389.  
  390.  
  391.  
  392. 9.  XPK support
  393.    =============
  394.  
  395. Main goal of Most's XPK support is to hide any consequences of packed
  396. data from the user. This means, that any packed file (with XPK) will
  397. automatically be unpacked from Most if the XPK packages is correct
  398. installed. The only hint you get is in the information requester,
  399. where the line "XPK-packer:" will show you the used packer (usually
  400. you see "---" there). There is only one thing special with XPK packed
  401. data: The file will be loaded completely into memory and no buffering
  402. will be done!
  403.  
  404. On the other hand if you don't have XPK you can use Most without any
  405. difference. The xpkmaster.library is not required by Most to run at all.
  406. Of course in this case XPK packed data will not be unpacked :-)
  407.  
  408.  
  409.  
  410.  
  411.  
  412. 10.  pipe support
  413.     ==============
  414.  
  415. As a new feature Most 1.31 supports pipes. This means, that you can type
  416. something like "type foo | Most" at your (W)Shell prompt and Most will show
  417. the output of the first type command in its window!
  418.  
  419. As I said this feature is brand new. So I regret that I couldn't test
  420. it for all possibilities. Please report me any failure.
  421.  
  422. There are two small problems:
  423.  XPK doesn't work with pipes (or better: I don't support it ;-) ).
  424.  
  425.  Second there is the problem with pipes that you cannot know how much
  426.  data therein will be... So one effect is, that you cannot scroll back
  427.  to the start of an file if you scrolled over the bounds of a buffer and
  428.  the other one is that the size of the buffer will be maximum bufferlen
  429.  every time. If the pipe's data fits completly into the buffer you
  430.  have no restrictions for scrolling. But if the data is to large - Sorry.
  431.  
  432.  
  433.  
  434.  
  435.  
  436. 11.  ARexx Port
  437.     ============
  438.  
  439. Beside the global ARexx port "MostPort" (or the name you gave it with the
  440. option PORTNAME on startup) of Most's main process each text window has
  441. his own private ARexx port. To select a window first send the command
  442. "GetFileList" to the global port. You will receive a list of the avaible
  443. windows and its portnames.
  444. All following ARexx commands can be send to a private window port, but
  445. Most's main port does only understand the first 6 commands "GetFileList",
  446. "GetScreenName", "Quit", "OpenNew", "Set" and "Request". All other commands
  447. will return an errorcode of 20 if send to "MostPort".
  448. Sorry, but the ARexx port isn't complete today. Especially it lakes some
  449. interesting set commands. You also cannot specify a custom portname for
  450. Most's main process. But I'm working :-)
  451.  
  452.  
  453. The following ARexx commands are supported:
  454.  
  455. GetFileList     In RESULT you receive a list of avaible textwindows and their
  456.                 port names. Format:  {<windowname> <portname> }^+
  457. GetScreenName   get the name of the PubScreen of the current window
  458. Quit            Quit Most and close ALL windows. Also the AppIcon will be removed.
  459. Request         Simple possibility to open a custom requester and to call for
  460.                 a user decition. In RESULT you get the 0 for CANCEL, 1 to...
  461.                 for the left to right gadgets.
  462.                 Format:    REQUEST <Title> <Gadgets> <Text>
  463. Set             set some internal parameters like
  464.                   CASE  ignore upper/lower case ON/OFF
  465.                   WORD  search only for whole words ON/OFF
  466.                   BACK  search backwards ON/OFF
  467.                 NOT IMPLEMENTED YET!!!
  468. OpenNew         Like Open, but loads the text in its own new window.
  469. Open            Load a new text into the current window. If you don't specify
  470.                 a filename, a filerequester will appear.
  471. Close           close the current window
  472. ToFront         bring the current window (and its screen) to front
  473. GetWindowDims   get the dimentions of the current window in RESULT
  474. Edit            start ENV:Editor with the current text
  475. Info            open information requester
  476. FirstPage       show first page
  477. LastPage        show last page
  478. NextPage        show next page
  479. PrevPage        show previous page
  480. NextLine        scroll one line forwards
  481. PrevLine        scroll one line backwards
  482. GotoLine        jump to the given line (as first line of visible page)
  483. Search          Without argument: open search requester
  484.                 With searchstring: search for the given text
  485.  
  486.  
  487.  
  488.  
  489.  
  490. 12.  Ideas, Bug reports
  491.     ====================
  492.  
  493. As mentioned before Most isn't complete today. There are some points I
  494. will improve in the future. I also have Commodore's Style Guide in
  495. mind and will follow its rules the next release better.
  496.  
  497. I'm absolut interested in any kind of responds - ideas, enhancements
  498. requests, criticism or bug reports. Call me, write me, mail me. I
  499. will hear you!
  500.  
  501. My address:
  502.    Uwe Roehm
  503.    Woerthstr. 18
  504.    8390 Passau
  505.    Germany
  506.  
  507. EMail:
  508.    roehm@kirk.fmi.uni-passau.de
  509.  
  510. Fido:
  511.    2:246/200.5
  512.  
  513.  
  514.  
  515.  
  516.  
  517. 13.  current Versions
  518.     ==================
  519.  
  520. You can download the current version of Most from forwiss.uni-passau.de
  521. (132.231.1.10) in the directory  pub/amiga/local/UweR. You will also find
  522. other interesting software in pub/amiga/local....
  523.  
  524.  
  525.  
  526.  
  527.  
  528. 14.  Thanks
  529.     ========
  530.  
  531. I want to thank my beta testers
  532.   David, Uli, Karl, Holger, Stefan und Stefan ;-)
  533. A special thanks to Urban for his sugesstions and XPK.
  534.