home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 545a.lha / PowerVisor_v1.0 / ReadThisFirst.pp / ReadThisFirst
Encoding:
Text File  |  1991-09-07  |  18.6 KB  |  442 lines
  1. ****************
  2. * Introduction * Sun Sep  1 15:43:22 1991
  3. ****************
  4.  
  5.  
  6. PowerVisor V1.0
  7. ---------------
  8.  
  9.    PowerVisor is a powerful debugger designed to do almost everything
  10.    you can think of. Even if you can't think of it it will probably still be
  11.    possible :-)
  12.  
  13.    What I meant to say with the above is that PowerVisor is
  14.    rather complex to use. I recommend that you read the tutorial sections
  15.    even if you think you can cope. Once you have mastered the program
  16.    you will probably be able to debug your programs in a very short
  17.    time.
  18.  
  19.    Read the tutor files and execute each command as mentioned
  20.    there. All lines you have to type are preceded by a '<'. Some special
  21.    keys are notated as <key>. <enter> is used for the return key.
  22.    All output from PowerVisor is preceded by a '>'.
  23.    If you must press two keys together there is a '+' between them:
  24.    <alt>+<enter>.
  25.  
  26.    All input and output in this tutorial is for the AmigaDOS 2.0
  27.    version. In most cases this does not matter. If there are
  28.    differences between the two versions it is mentioned in the tutorial
  29.    in the following form: (1.3 : .......)
  30.  
  31.  
  32. Shareware
  33. ---------
  34.  
  35.    PowerVisor is shareware. This means that you can copy it and give
  36.    to everybody. If you like the program and/or use it, I'd appreciate
  37.    it if you send me a contribution. If you send $25 US or more
  38.    you automatically get the next major release when one is available.
  39.    PLEASE send money by international money order, EuroCheck (in Belgian
  40.    Francs (BF) !) or cash, because it's very difficult for me to cash
  41.    in other checks !
  42.    If you want an update please state your current version.
  43.  
  44.    Note that PowerVisor may only be redestributed with ALL FILES
  45.    PRESENT (especially this file). Below follows a list of all files
  46.    in the PowerVisor distribution.
  47.  
  48.    NOTHING in the PowerVisor distribution may be redistributed seperatelly
  49.    or used in any commercial product without prior permission from
  50.    the author.
  51.  
  52.    Note that the quickhelp utilities ('MakeHelp', 'ArcFiles', 'Help',
  53.    'MakeHelp13', 'ArcFiles13' and 'Help13') are considered seperate
  54.    from PowerVisor. You may redistribute the quickhelp utilities
  55.    without the rest of PowerVisor if you really want to (read the
  56.    'Help.doc' and 'Help13.doc' files for possible restrictions).
  57.  
  58.    This is in fact a BETA VERSION. This means that there are still
  59.    some bugs to be solved. If you use this program you are
  60.    betatesting PowerVisor. Don't worry too much about this. I think
  61.    PowerVisor is rather stable. I use it a lot and I have not
  62.    yet crashed with the current version.
  63.  
  64.    I (THE AUTHOR) TAKE NO RESPONSIBILITY FOR DAMAGES INFLICTED BY
  65.    POWERVISOR AND THE OTHER PROGRAMS IN THIS DISTRIBUTION. YOU ARE
  66.    COMPLETELY RESPONSIBLE FOR ALL EFFECTS OF USING POWERVISOR
  67.    AND ANY OF THE OTHER PROGRAMS.
  68.  
  69.  
  70. I'm sorry
  71. ---------
  72.  
  73.    I'm sorry for the bad English. I speak Dutch and English is
  74.    only my second language. The tutorial files as they are in
  75.    the current distribution are NOT corrected at all. I didn't
  76.    even reread everything. I'd very much appreciate corrections of the
  77.    online help and the tutorial files.
  78.  
  79.  
  80. Bugs
  81. ----
  82.  
  83.    PowerVisor was programmed on an Amiga 3000 with AmigaDOS 2.0.
  84.    I have tested the program on AmigaDOS 1.3 and everything seemed
  85.    to work. I have not been able to test PowerVisor on any other
  86.    Amiga configuration.
  87.  
  88.    PowerVisor is a big program. This means that bugs are unavoidable.
  89.    If you find some bugs, or have some suggestions please write.
  90.    I'd like PowerVisor to be as bug free as possible.
  91.    In this distribution there is a file 'pv.bugs' describing all bugs
  92.    in the current version. Consult this file if you discover some
  93.    weird behaviour.
  94.  
  95.    Give the following information when you report a bug :
  96.  
  97.       - Hardware configurations you have used (if a bug occurs
  98.         on one hardware configuration but not on another one, please
  99.         give both hardware configurations)
  100.         Hardware configurations includes :
  101.                Processor (68000, 68010, 68020, 68030, 68040, ...)
  102.                Coprocessor (68881, 68882, ...)
  103.                MMU (68851, ...)
  104.                Amiga model (500, 1000, 2000, 2500/20, 2500/30, 3000/16,
  105.                   3000/25, 3000UX, 3000T, CDTV, ...)
  106.                Available memory (chip ram, fast ram, other, ...)
  107.                Harddisk information
  108.                Other hardware expansions (graphics card, sound card, ...)
  109.       - Software configuration you used
  110.         Software configuration includes :
  111.                Operating system (AmigaDOS 1.2, 1.3, 2.0)
  112.                   If you can run more than one operating system on
  113.                   your Amiga, test the bug in the different versions
  114.                Version of KickStart and WorkBench (in Workbench
  115.                   about menu or with 'version' cli command)
  116.                Other programs running while the bug occurs (screen
  117.                   blankers, popup programs, ...)
  118.       - Describe the bug and the sequence of commands needed to
  119.         get the bug
  120.  
  121.  
  122. All files
  123. ---------
  124.  
  125.      MakeIndex (dir)          This subdirectory contains files needed
  126.                               to update the index file for the tutorial
  127.                               files. You only need any of these files
  128.                               if you want to add or remove some items
  129.                               from the index
  130.  
  131.        CancelDouble           This program cancels all double lines in
  132.                               a file. This program is used by
  133.                               'MakeGlobalIndex'
  134.        CancelDouble.c         The source for 'CancelDouble'. You should
  135.                               be able to compile this program on any
  136.                               C-compiler
  137.        ExtractIndex.rexx      This rexx script is used by 'MakeIndex' to
  138.                               construct the index file for one individual
  139.                               tutor file
  140.        HowToMakeAnIndex       A tutor file explaining how to make an index
  141.        MakeGlobalIndex        This script file combines all index files
  142.                               made by 'MakeIndex' to make the global index
  143.        MakeIndex              Make the index and contents file for one
  144.                               tutorial file
  145.  
  146.      PowerVisorLib (dir)      This subdirectory contains files needed
  147.                               to use to powervisor.library in your programs
  148.  
  149.        pv_lib.fd              fd-file containing function definitions for
  150.                               the powervisor.library functions
  151.        pv_lib.h               C header file containing pragmas for the
  152.                               powervisor.library functions. This file
  153.                               is written for Lattice C 5.0. If you use
  154.                               another compiler (like Aztec) you may
  155.                               need to rewrite this file. If you use a
  156.                               C compiler with no support for pragmas you
  157.                               must make stubs to call the library functions
  158.        pv_lib.i               Machinelanguage header file.
  159.  
  160.      c (dir)                  This subdirectory contains all executable
  161.                               files. All files ending with '13' are for
  162.                               AmigaDOS 1.3.
  163.  
  164.        ArcFiles               The QuickHelp utilities for AmigaDOS 2.0
  165.        Help                   Read docs/help.doc for more info
  166.        MakeHelp
  167.  
  168.        ArcFiles13             The QuickHelp utilities for AmigaDOS 1.3
  169.        Help13                 Read docs/help13.doc for more info
  170.        MakeHelp13
  171.  
  172.        MStruct                AmigaDOS 2.0 only program to convert
  173.                               pseudo include files to pvsd files.
  174.                               This program will be enhanced in future
  175.                               to support full include files.
  176.                               I apologize for the fact that this
  177.                               program is AmigaDOS 2.0 only. I have
  178.                               had no time to convert it to AmigaDOS 1.3.
  179.                               Maybe for the next release.
  180.        pv                     AmigaDOS 2.0 version of PowerVisor
  181.        pv13                   AmigaDOS 1.3 version of PowerVisor
  182.  
  183.      libs (dir)               All libraries needed by PowerVisor
  184.  
  185.        arp.library            arp.library is only needed if you use
  186.                               AmigaDOS 1.3
  187.        powervisor.library     This library is needed by PowerVisor
  188.  
  189.      docs (dir)               All documents for PowerVisor
  190.  
  191.        GettingStarted         Read this file if you are a first-time user
  192.        Expressions            All about expression evaluation in PowerVisor
  193.        Screen                 Everything about screens and windows
  194.        InstallingPowerVisor   How to install PowerVisor
  195.        Scripts                Everything about scripts (ARexx, ...)
  196.        LookingAtThings        How to look at memory, disassemble, ...
  197.        Debug                  How to debug programs
  198.  
  199.        CommandReference       All PowerVisor commands explained
  200.        Functions              All PowerVisor functions explained
  201.        Lists                  All lists
  202.  
  203.        TechnicalInfo          Some technical information
  204.        TheWizardCorner        Only for VERY experienced users
  205.  
  206.        Global.index           The index for all above files
  207.  
  208.        GettingStarted.idx     The individual index files for all tutor
  209.        Expressions.idx        and reference files
  210.        Screen.idx
  211.        InstallingPowerVisor.idx
  212.        Scripts.idx
  213.        LookingAtThings.idx
  214.        Debug.idx
  215.        CommandReference.idx
  216.        Functions.idx
  217.        Lists.idx
  218.        TechnicalInfo.idx
  219.        TheWizardCorner.idx
  220.  
  221.        Screen.contents        The contents files for all tutor files
  222.        GettingStarted.contents
  223.        Expressions.contents
  224.        InstallingPowerVisor.contents
  225.        Scripts.contents
  226.        LookingAtThings.contents
  227.        Debug.contents
  228.        CommandReference.contents
  229.        Functions.contents
  230.        Lists.contents
  231.        TechnicalInfo.contents
  232.        TheWizardCorner.contents
  233.  
  234.        Help.doc               Manual for QuickHelp
  235.        Help13.doc             Manual for QuickHelp 1.3
  236.  
  237.      Source (dir)             This subdirectory contains sources for
  238.                               various scripts and example programs
  239.                               included with PowerVisor
  240.  
  241.        FreeError.asm          These two programs crash your Amiga,
  242.        stackovf.asm           except when PowerVisor is running (I hope)
  243.                               Executables for these files are in the
  244.                               'Examples' subdirectory
  245.  
  246.        BuggyProgram.asm       Example programs used in the 'debug' tutorial
  247.        BuggyProgram2.asm      file. Executables for these files are in the
  248.                               'Examples' subdirectory
  249.  
  250.        CheckBrackets.c        Program to check brackets. Executable file
  251.                               is in 's/pv'. Source is for Lattice C 5.0
  252.                               only
  253.        GetCode.c              Program to compute the keycode for a named
  254.                               key. Executable file is in 's/pv'. Source is
  255.                               for Lattice C 5.0 only
  256.        GetQual.c              Program to compute the keyqualifier for a
  257.                               named qualifier. Executable file is in 's/pv'.
  258.                               Source is for Lattice C 5.0 only
  259.  
  260.        Exec.struct            PowerVisor source for 'Exec' structure
  261.                               definitions.
  262.                               pvsd file is in 's/pv'
  263.        intuition.struct       PowerVisor source for 'Intuition' window
  264.                               structure definition.
  265.                               pvsd file is in 's/pv'
  266.  
  267.        mkeys.explained        Same script file as 's/pv/mkeys' but with
  268.                               a lot of comments
  269.  
  270.        pptest.asm             Program to test the powervisor.library.
  271.                               Use as an example. Executable file is in
  272.                               the 'Examples' subdirectory
  273.        takeme.asm             Program to test 'debug t'
  274.                               Executable file is in the 'Examples'
  275.                               subdirectory
  276.        SearchHist.asm         Source for history search program. Executable
  277.                               file is in 's/pv'
  278.  
  279.      s (dir)                  Online help and scripts
  280.  
  281.        PowerVisor-help        Online help file. This file contains all
  282.                               online help and the templates. You can't
  283.                               use 'help' and 'why' when this file is
  284.                               not present. Note that the online help
  285.                               file is not the good place to start learning
  286.                               PowerVisor. Use the tutorial files in the
  287.                               'docs' subdirectory for that purpose.
  288.        PowerVisor-ctrl        Online help control file. Use the QuickHelp
  289.                               utilities to update this file when you
  290.                               have changed something in the PowerVisor-help
  291.                               file. You need this file if you want
  292.                               online help
  293.        PowerVisor-errors      All error messages for PowerVisor. You need
  294.                               this file if you want to make errors :-)
  295.                               No, you need this file if you want to see
  296.                               a sensible error message.
  297.                               Each line in this file must be 70 bytes
  298.        PowerVisor-startup     The startup script for PowerVisor. This
  299.                               script installs various new commands and
  300.                               keys
  301.  
  302.           pv (dir)            This subdirectory contains all scripts you
  303.                               can use
  304.  
  305.             db                PowerVisor script to install the fullscreen
  306.                               debugger. This script also assigns some
  307.                               keys to useful debugging commands
  308.             ExampleSetting    PowerVisor script to show an other window
  309.                               configuration posibility. Use as an example
  310.                               for more useful settings
  311.             fact              PowerVisor script to install a new command
  312.                               to compute the facultaty. Use as an
  313.                               example for recursive aliases
  314.             CheckBrackets     ML script to check for brackets in the
  315.                               commandline. Source is in the 'Source'
  316.                               subdirectory. See the 's/Powervisor-startup'
  317.                               file for an example of how to install this
  318.                               feature
  319.             GetCode           ML script to compute the code of a named
  320.                               key. Source is in the 'Source' subdirectory.
  321.                               Note that if you have AmigaDOS 1.3 you can
  322.                               only use this script to compute the code
  323.                               of special keys (like 'enter' and 'esc')
  324.                               and not of normal keys (like 'a', '3', ...).
  325.                               This script is installed as a function in the
  326.                               's/PowerVisor-startup' file
  327.             GetQual           ML script to compute the qualifier of a named
  328.                               qualifier. Source is in the 'Source'
  329.                               subdirectory. This script is installed as a
  330.                               function in the 's/PowerVisor-startup' file
  331.             SearchHist        ML script to search in the history buffer.
  332.                               Source is in the 'Source' subdirectory. This
  333.                               script is installed on a key in the
  334.                               's/PowerVisor-startup' file
  335.             ikey              This PowerVisor script installs various
  336.                               special features
  337.             mkeys             PowerVisor script for a memory display
  338.                               utility
  339.             PrintHist.pv      ARexx script to print the contents of the
  340.                               current history buffer
  341.             PrintMode.pv      ARexx script to print the current mode
  342.                               setting in a readable format
  343.             ShowAscii.pv      ARexx script to show all ascii chars on the
  344.                               PowerVisor window
  345.             intuition.pvsd    pvsd file for the Window structure.
  346.                               Source is in the 'Source' subdirectory
  347.             Exec.pvsd         pvsd file for all Exec structures
  348.                               Source is in the 'Source' subdirectory
  349.  
  350.      Examples (dir)           This subdirectory contains some example
  351.                               programs. Sources for most of these programs
  352.                               can be found in the 'Source' subdirectory
  353.  
  354.        BuggyProgram           Programs used in the 'Debug' tutor file
  355.        BuggyProgram2
  356.  
  357.        crash3                 Some crash programs
  358.        crash4
  359.        crash5
  360.        crash8
  361.        crasha
  362.        freeerror
  363.        stackovf
  364.  
  365.        pptest                 powervisor.library test program
  366.        takeme                 'debug t' test program
  367.  
  368.   ReadThisFirst               This file
  369.   pv.bugs                     All bugs in the current version of Powervisor
  370.  
  371.  
  372. Tutor files
  373. -----------
  374.  
  375. Here are all the files in the prefered order to read them
  376.  
  377. tutor files :
  378.  
  379.    GettingStarted
  380.    Expressions
  381.    Screen
  382.    InstallingPowerVisor
  383.    LookingAtThings
  384.    Debug
  385.    Scripts
  386.  
  387. reference files :
  388.  
  389.    Lists
  390.    CommandReference
  391.    Functions
  392.    TechnicalInfo
  393.  
  394. for very experienced users :
  395.  
  396.    TheWizardCorner (only read if you are a PowerVisor wizard !!!!!)
  397.  
  398.  
  399.  
  400. Authors
  401. -------
  402.  
  403.    André Pelckmans for the disassembler
  404.    Jorrit Tyberghein for the rest
  405.  
  406.  
  407. Address
  408. -------
  409.  
  410.    Jorrit Tyberghein
  411.    Hepmansbossen 31
  412.    2450 Meerhout BELGIUM
  413.  
  414.  
  415. Thanks to
  416. ---------
  417.  
  418.    André Pelckmans for his disassembler and for giving me all the
  419.    the programming help I need.
  420.    Without him I wouldn't have a computer in the first place (I think).
  421.  
  422.    Nico François for his debugging, his numerous remarks and
  423.    suggestions.
  424.    Without him PowerVisor would have looked COMPLETELY different :-)
  425.    (and without him I would have to use two disks to backup the source
  426.    of PowerVisor)
  427.  
  428.    Ives Aerts for his useful suggestions and criticism.
  429.  
  430.    Adam Hill, Christian Weber, Steven Reiz and Dominic Giampaolo
  431.    for there bug reports and suggestions.
  432.  
  433.    Some extra thanks to Adam Hill for his efforts to arouse
  434.    interrest in PowerVisor (in BIX for example).
  435.  
  436.    The software people at Commodore for their VERY USEFUL debugging
  437.    tools (like 'Enforcer', 'MungWall', ...).
  438.    And also for their presence on usenet.
  439.  
  440.    Also thanks to the Amiga computer for being an Amiga.
  441.  
  442.