

        ###     ##   #     # #### ###   #     # ###   ##    ##   ###
        #  #   #  #  #     # #    #  #  #     #  #   #  #  #  #  #  #
        #   # #    # #     # #    #   # #     #  #  #     #    # #   #
        #   # #    # #     # #    #   # #     #  #  #     #    # #   #
        #   # #/###########\# #   #
        #  #  #    # #     # #    #  #  #     #  #   #    #    # #  #
        ###  /#    # #     # ###  ###   #     #  #    #   #    #\###
        #   / #    # #     # #    #  #  #     #  #     #  #    # #  #
        #  /  #    #  #   #  #    #   #  #   #   #      # #    # #\  #
        # /   #    #  # # #  #    #   #  #   #   #      # #    # # \ #
        #/    #    #  # # #  #    #   #  #   #   #      # #    # #  \#
        #      #  #   ## ##  #    #   #   # #    #  #  #   #  #  #   #
       /#       ##    #   #  #### #   #    #    ###  ##     ##   #   #\
      /                                                                \
     /                                                                  \
    /                                                                    \
   /                                                                      \
  /                                                                        \
 /                                                                          \
||
| Introduction and general information              Tue Nov  3 17:03:38 1992 |
|____________________________________________________________________________|



PowerVisor V1.42    CopyRight  Jorrit Tyberghein (Nov 92)
----------------

   PowerVisor is a powerful debugger designed to do almost everything
   you can think of. Even if you can't think of it it will probably still be
   possible :-)

   What I meant to say with the above is that PowerVisor is
   rather complex to use. I recommend that you read the tutorial sections
   even if you think you can cope. Once you have mastered the program
   you will probably be able to debug your programs in a very short
   time.

   Note that I TRY to make PowerVisor as user friendly as possible (look
   at the emphasis on the word 'try').

   Read the tutor files and execute each command as mentioned
   there. All lines you have to type are preceded by a '<'. Some special
   keys are notated as <key>. <enter> is used for the return key.
   All output from PowerVisor is preceded by a '>'.
   If you must press two keys together there is a '+' between them:
   <alt>+<enter>.

   If you have AmigaGuide or MultiView ( Commodore) it is best that you
   use this program to read the PowerVisor manual.

   All input and output in this tutorial is for the AmigaDOS 2.0
   version. In most cases this does not matter. If there are
   differences between the two versions it is mentioned in the tutorial
   in the following form: (1.3 : .......)
   PowerVisor also works fine in AmigaDOS 3.0.


Shareware and disclaimer
------------------------

   PowerVisor is shareware. This means that you can copy it and give
   to everybody. If you like the program and/or use it, I'd appreciate
   it if you send me a contribution. If you send $25 US or more
   you automatically get the next major release when one is available
   (I will also add you to the list of registered users).
   PLEASE send money by international money order, EuroCheck (in Belgian
   Francs (BEF) !) or cash, because it's very difficult for me to cash
   in other checks !
   If you want an update please state your current version.

   Note that PowerVisor may only be redestributed with ALL FILES
   PRESENT (especially this file). Below follows a list of all files
   in the PowerVisor distribution.

   NOTHING in the PowerVisor distribution may be redistributed seperately
   or used in any commercial product without prior permission from
   the author.

   Note that the quickhelp utilities ('MakeHelp', 'ArcFiles', 'Help',
   'MakeHelp13', 'ArcFiles13' and 'Help13') are considered seperate
   from PowerVisor. You may redistribute the quickhelp utilities
   without the rest of PowerVisor if you really want to (read the
   'Help.doc' file for possible restrictions).

   You can order the source of PowerVisor if you like. Simply read the
   'HowToGetTheSource' file included in this archive.

   ReqTools is CopyRight  Nico Franois.

   PowerVisor is no longer in beta stage. I don't know if PowerVisor
   already deserves this, but some people insisted that it was time
   that I removed the beta label, so I did it. The fact that PowerVisor
   is not beta does not mean that there are no bugs left :-)  But
   I think that PowerVisor is stable enough (at least the AmigaDOS 2.0
   version looks stable enough) to make it a really usable program
   (I use it :-)

   I (THE AUTHOR) TAKE NO RESPONSIBILITY FOR DAMAGES INFLICTED BY
   POWERVISOR AND THE OTHER PROGRAMS IN THIS DISTRIBUTION. YOU ARE
   COMPLETELY RESPONSIBLE FOR ALL EFFECTS OF USING POWERVISOR
   AND ANY OF THE OTHER PROGRAMS. USE AT YOUR OWN RISK !


Short feature list
------------------

   o Fullscreen debugger

   o Full symbolic debugging

   o Very powerful tracing and breakpoint commands. You can trace until
     a certain condition becomes true, or trace just before the next
     branch, or trace until a certain register changes, ... PowerVisor has
     profiler breakpoints, conditional breakpoints and a lot more

   o Primitive source level debugging (C, assembler, ...) In future
     more will be possible

   o PowerVisor is compatible with the 68000, 68020 and 68030. The 68040
     is also supported (in the disassembler for example) although some
     features don't work on that processor (like memory protection) due
     to lack of information

   o Memory protection system. With this system you can read or write
     protect ranges of memory for all or some tasks

   o PowerVisor can show the MMU registers and special 68020/30 registers

   o Primitive floating point support (display and modify registers). In
     future more will be possible (like expressions)

   o Powerful ARexx interface

   o Intuition menus and gadtools scrollbars (AmigaDOS 2.0 version only)

   o The PowerVisor screen is a public screen (only for AmigaDOS 2.0)

   o Powerful expression evaluator. Almost all C operators are supported
     and some additional operators as well

   o Online help system with AmigaGuide or MultiView (for AmigaDOS 3.0)
     or internal system

   o Very customizable: screen or window on WorkBench, fonts, colours,
     menus, multiple windows, ...
     You can add your own PowerVisor commands with aliases
     All keys can be redefined and you can add macros or commands to
     any key you want

   o You can call any library function you want from within PowerVisor.
     With this feature you can test existing library functions or you
     can test your own libraries

   o Powerful stack usage checker. With this command you can see how
     much stack a program uses

   o Resource tracker. With this command you can see how much memory
     a program allocates (and how much memory it doesn't deallocate),
     all allocated signals, all locks and open files

   o Profiler. With this system you can see which routines use much
     CPU time and are useful to optimize

   o Crash trapping

   o You can kill and freeze tasks

   o Powerful tag and structure system. With this system you can define
     structures in PowerVisor. The disassembler will recognize these
     structures if possible and it will use names for all offsets instead
     of numbers. This makes debugging a lot easier

   o PowerVisor can list almost anything: tasks, libraries, devices, ports,
     resident modules, autoconfig devices, dos devices, windows, screens,
     fonts, ...
     In addition PowerVisor can dump the internal structures of many
     operating system elements like tasks, processes, CLI structures, ...

   o You can open any Exec device from within PowerVisor and send commands
     to it. This is useful for debugging your own devices

   o You can monitor the usage of a library function. Each time the
     library function is called PowerVisor will perform some action (like
     printing a message, or storing the information from the call in a
     buffer, or simply blinking the powerled)

   o PowerVisor can list the gadgets of a window

   o PowerVisor can remove a lot of things like tasks, resident modules,
     input handlers, windows, screens, ...


I'm sorry
---------

   I'm sorry for my bad English. I speak Dutch and English is
   only my second language. The tutorial files as they are in
   the current distribution are NOT corrected at all. I didn't
   even reread everything. I'd very much appreciate corrections of the
   online help and the tutorial files.


Compatibility with PowerVisor V1.32
-----------------------------------

      - Tag files are not compatible anymore (due to a bug fix). If you
        want to convert the old pre-V1.40 tag files to the new format
        you must change the last four bytes (00000000 in the old file
        format) to FFFFFFFF (or -1)
      - 'pvcall 65' is obsolete (it is not harmful to call this
        routine, since it is replaced by an equivalent, but less
        powerful and less useful, routine)
      - Several changes everywhere (see 'TheWizCorner.guide') because
        the 'mode' command was completely rewritten
      - PowerVisor-config file has changed a little bit. It is
        still possible to use the old config file, but it is better
        that you delete this file and make a new one


Compatibility with PowerVisor V1.31
-----------------------------------

   Due to large internal changes (memory management) there have been
   some changes. Here follow all things that have changed that
   could cause compatibility problems for specialized scripts.
   If you have made specialized ARexx programs, scripts or ML-scripts
   you will probably have to change some things :

      - 'pvcall 59' is obsolete. This is because the complete
        'PVQuickBlock' system has been removed. Note that you
        can use 'pvcall 58' instead
      - mbase_GlobalAutoClear is now a 'PVMemoryBlock' instead of
        a 'PVQuickBlock'
      - mbase_PVQuickTressHold is obsolete
      - mbase_ResidentCode is now a 'PVMemoryBlock' instead of
        a 'PVQuickBlock'
      - The 'PVQuickBlocks' in the 'debug node' have also been changed
        to 'PVMemoryBlocks'
      - 'base_CliCmdLineLen' has been replaced by 'base_Detach'
      - 'PVCallStub.lib' and 'PVCallStubNB.lib' have changed
        (new PvCall functions)
      - There is an extra field in the logical window structure
      - There is an extra field in the debug structure
      - There are some extra fields in the debug structure that were
        previously used for other things


Compatibility with PowerVisor V1.10 to V1.12
----------------------------------------------

   PowerVisor was still in beta release. This means that big changes
   were unavoidable :

      - The 'ScreenBase' structure (see 'TheWizardCorner') has changed.
        You will probably have to change and recompile all scripts
        using 'ScreenBase'
      - The 'PowerVisor-config' file is not compatible


Compatibility with PowerVisor V1.00 and V1.01
-----------------------------------------------

      - 'refresh' ALWAYS expects two arguments. The second
        argument (command) is no longer optional
      - New 'pvcall 17' and other pvcall commands
      - New strong quote operator ()
      - The '#' operator is removed. Replace it with the '\' operator :
               #<var>     ---->     \(<var>,%s)
      - The 'eval' function expects a string pointer instead of a string
      - The 'libfunc' command expects a negative argument instead of
        a positive one
      - The <maximum number of functions> argument is removed from
        the 'loadfd' command
      - 'memory', 'view' and 'unasm' work differently when another
        number of bytes is used (see documentation)
      - All error numbers have changed because the obsolete error
        numbers are removed
      - The 'PVSD' fileformat ('loadtags', 'savetags') has changed.
        There is no way to convert. You need the original source
        (.struct file)
      - 'why' command is gone and is replaced with an alias in
        the standard PowerVisor-startup file
      - Many fields described in 'TheWizardCorner' have changed. Some
        pvcall functions have become obsolete and DO NOT work anymore.
        Some pvcall functions have been REPLACED with others
      - The PowerVisor expression evaluator is more strict. You MUST
        close ALL brackets (also {} brackets)
      - PowerVisor commands called from ARexx are not interruptable anymore
        with <esc>
      - Important change in the logical window system. (See the changes
        section for more details)
      - Major change in the history buffer mechanics. The history
        buffer list has changed (see 'TheWizardCorner')
      - The File format of s:PowerVisor-config has changed !
        Please delete this file first before you start the new version of
        PowerVisor !!!
      - Commandline options for PowerVisor are removed since they were
        not very useful
      - 'scan' works differently. You don't need to free the string
        allocated with 'scan'. The pointer to the input string is
        NOT returned in 'rc' but in the predefined constant 'INPUT'
      - The number of pens in the pentable has changed from 16 to 24


The development cycle
---------------------

   I started development of PowerVisor (February 1989) on an Amiga
   500 with two diskdrives and one megabyte of memory. (except for
   holidays, I only programmed in the weekends since I was at my
   university for the rest of the week)
   PowerVisor (at that time called 'PowerBase') was going to be a
   structure viewer. The 'list' and 'info' commands are in fact the
   most ancient commands in PowerVisor (except maybe the 'quit'
   command :-)
   At that time I did not think about writing a debugger. I could
   not even write one if I wanted to. After all, PowerVisor was
   only my second machinelanguage program on Amiga and I was still
   learning machinelanguage.
   (my first program in machinelanguage was a little program to
   blink the powerled, I made this program together with someone
   else :-)
   (In fact PowerVisor is also my last machinelanguage program, I
   normally program in C)

   I bought my first harddrive about five months later (30 megs).

   In September 1990 I bought my Amiga 3000/16/40! Needless to say
   this was a great development boost. I almost immediately expanded
   my Amiga to 4 megabytes of memory.

   In August 1991 I bought a second harddrive (52 megs) for my Amiga 3000.

   At this moment (Augustus 1992) the PowerVisor source is
   approximately 47000 lines long and all other ascii files
   (help files, scripts, ...) approach approximately 40000 lines.

   Conclusion : If I were to start all over again, I would not use
   machinelanguage (or perhaps only for the exception handling and
   other special code). It is too much work. At this moment I don't
   regret my choice of machinelanguage, but this is only because I
   already have programmed all support routines and making some new
   PowerVisor command or other feature is simply a matter of calling
   the right routines (more or less).


Bugs
----

   PowerVisor was programmed on an Amiga 3000 with AmigaDOS 2.0.
   I have tested the program on AmigaDOS 1.3 and everything seemed
   to work. I have tested PowerVisor on the Amiga 500 and on the
   Amiga 4000.

   I know that the MMU protection system will NOT work on a 68040.
   As long as I don't know anyone personally with such a system I can't
   solve the bugs in this area. I also don't have any documentation
   on the 68040.

   PowerVisor is a big program. This means that bugs are unavoidable.
   If you find some bugs, or have some suggestions please write.
   I'd like PowerVisor to be as bug free as possible.
   In this distribution there is a file 'pv.bugs' describing all bugs
   in the current version. Consult this file if you discover some
   weird behaviour.

   Give (at least) the following information when you report a bug :

      - Hardware configurations you have used (if a bug occurs
        on one hardware configuration but not on another one, please
        give both hardware configurations)
        Hardware configurations includes :
               Processor (68000, 68010, 68020, 68030, 68040, ...)
               Coprocessor (68881, 68882, ...)
               MMU (68851, ...)
               Amiga model (500, 500+, 600, 600HD, 1000, 1200, 1500,
                  2000, 2500/20, 2500/30, 3000/16, 3000/25, 3000UX, 3000T,
                  4000, CDTV, ...)
               Available memory (chip ram, fast ram, other, ...)
               Harddisk information (SCSI, IDE, MFM, RLL, ...)
               Other hardware expansions (graphics card, sound card, ...)
      - Software configuration you used
        Software configuration includes :
               Operating system (AmigaDOS 1.2, 1.3, 2.0, 2.1, 3.0, ...)
                  If you can run more than one operating system on
                  your Amiga, test the bug in the different versions
               Version of KickStart and WorkBench (in Workbench
                  about menu or with 'version' cli command)
               Other programs running while the bug occurs (screen
                  blankers, popup programs, ...)
      - Describe the bug and the sequence of commands needed to
        get the bug
        Describe all output (including flashing lights, strange sounds,
        noises, ...)


All files
---------

     PowerVisorLib (dir)      This subdirectory contains files needed
                              to use to powervisor.library in your programs

       pv_lib.fd              fd-file containing function definitions for
                              the powervisor.library functions
       pv_lib.h               C header file containing pragmas for the
                              powervisor.library functions. This file
                              is written for SAS C 5.0. If you use
                              another compiler (like Aztec) you may
                              need to rewrite this file. If you use a
                              C compiler with no support for pragmas you
                              must make stubs to call the library functions
       pv_lib.i               Machinelanguage header file.

     c (dir)                  This subdirectory contains all executable
                              files. All files ending with '13' are for
                              AmigaDOS 1.3.

       dc                     Utility needed by the installation script
                              to decompress the PowerVisor-help.qq file
                              to PowerVisor-help (and all other files
                              ending with '.qq')

       ArcFiles               The QuickHelp utilities for AmigaDOS 2.0
       Help                   Read docs/help.doc for more info
       MakeHelp

       ArcFiles13             The QuickHelp utilities for AmigaDOS 1.3
       Help13                 Read docs/help.doc for more info
       MakeHelp13

       MStruct                Program to convert pseudo include files to pvsd
                              files.
                              This program will be enhanced in future
                              to support full include files.
       MStruct13              AmigaDOS 1.3 version of MStruct
       pv                     AmigaDOS 2.0 version of PowerVisor
       pv13                   AmigaDOS 1.3 version of PowerVisor

     libs (dir)               All libraries needed by PowerVisor

       powervisor.library     This library is needed by PowerVisor
       reqtools.library       This library is not strictly necessary but
                              it is a very useful library anyway
                              (currently version 2.0c is included)

     libs13 (dir)

       reqtools.library       AmigaDOS 1.3 version of the reqtools.library

     docs (dir)               All documents for PowerVisor
                              Use AmigaGuide or MultiView to read these
                              documents if you have this program. However,
                              the files are quiet readable with a normal
                              text viewer and they can be converted to be
                              even more readable (see ConvertGuide2Doc).

       PowerVisor.guide       The main menu of the hypertext manual. Use
                              this file with AmigaGuide or MultiView or
                              double click on this file in the Workbench
                              to start reading the manual.

       GettingStarted.guide   Read this file if you are a first-time user
       Expressions.guide      All about expression evaluation in PowerVisor
       Screen.guide           Everything about screens and windows
       InstallingPV.guide     How to install PowerVisor
       LookingAtThings.guide  How to look at memory, disassemble, ...
       Debug.guide            How to debug programs
       Scripts.guide          Everything about scripts (ARexx, ...)

       CommandRef.guide       All PowerVisor commands explained
       Functions.guide        All PowerVisor functions explained
       Lists.guide            All lists
       Aliases.guide          This file explains everything about the
                              aliases defined in s/PowerVisor-startup
                              and s/pv/ExtraAliases

       Glossary.guide         The PowerVisor glossary, reading this file is
                              a very good way to learn all (or most)
                              PowerVisor terminology

       HowDoYou.guide         Common questions and answers
       TechnicalInfo.guide    Some technical information
       TheWizCorner.guide     Only for VERY experienced users. Using this
                              file you can customize PowerVisor to enormous
                              degrees. Look in the 'Source' directory for
                              examples using information from this file.
                              Also look at the 'PVDevelop' directory useful
                              for making your own powerful scripts (and
                              ML-scripts)

       Help.doc               Manual for QuickHelp

       SearchIt               Utility to search keyword in PowerVisor
                              hypertext manual. This utility is used by
                              the 'searchkeyword.pv' ARexx script.
                              By default this is the SAS/C version
       SearchIt.lc            The SAS/C version (slow and large) of the
                              above utility
       SearchIt.gcc           The GNU C version (fast and small, but you
                              need the ixemul.library) of the above
                              utility
       SearchIt.c             The source
       ConvertGuide2Doc       Utility to convert an AmigaGuide file (with
                              '.guide' extension) to a normal document file.
                              This utility removes all special AmigaGuide
                              commands and makes the file somewhat more
                              readable with a normal textviewer.
                              Use this utility if you don't have MultiView
                              or AmigaGuide
       ConvertGuide2Doc.c     Source of the above utility
       doc.info               Info file needed by 'InstallPV' script to
                              change the icons of the PowerVisor manual when
                              this manual is converted to normal document
                              files
       ConvertDoc.script      Script needed by the 'InstallPV' script to
                              convert an AmigaGuide document to a normal
                              document file

     Source (dir)             This subdirectory contains sources for
                              various scripts and example programs
                              included with PowerVisor

       FreeError.asm          These two programs crash your Amiga,
       stackovf.asm           except when PowerVisor is running (I hope)
                              Executables for these files are in the
                              'Examples' subdirectory

       BuggyProgram.asm       Example programs used in the 'debug' tutorial
       BuggyProgram2.asm      file. Executables for these files are in the
                              'Examples' subdirectory

       CheckBrackets.c        Program to check brackets. Executable file
                              is in 's/pv'. Source is for Lattice C 5.0
                              only
       GetCode.c              Program to compute the keycode for a named
                              key. Executable file is in 's/pv'. Source is
                              for Lattice C 5.0 only
       GetQual.c              Program to compute the keyqualifier for a
                              named qualifier. Executable file is in 's/pv'.
                              Source is for Lattice C 5.0 only

       Exec.struct            PowerVisor source for 'Exec' structure
                              definitions.
                              pvsd file is in 's/pv'
       intuition.struct       PowerVisor source for 'Intuition' window
                              structure definition.
                              pvsd file is in 's/pv'

       mkeys.explained        Same script file as 's/pv/mkeys' but with
                              a lot of comments

       pptest.asm             Program to test the powervisor.library.
                              Use as an example. Executable file is in
                              the 'Examples' subdirectory
       takeme.asm             Program to test 'debug t'
                              Executable file is in the 'Examples'
                              subdirectory
       SearchHist.asm         Source for history search program. Executable
                              file is in 's/pv'


     PVDevelop (dir)          This subdirectory contains include files and
                              libraries useful for PowerVisor Wizards. There
                              are include files for C and machinelanguage

       include (dir)          Subdirectory containing all include files
                              for PowerVisor (except for the
                              powervisor.library include files because these
                              are in another subdirectory)

          PV (dir)            The recomended place for the include files

            ARexxBase.h       The ARexx Base structures
            ARexxBase.i
            DebugBase.h       The Debug Base structures
            DebugBase.i
            EvalBase.h        The Eval Base structures
            EvalBase.i
            FileBase.h        The File Base structures
            FileBase.i
            GeneralBase.h     The General Base structures
            GeneralBase.i
            ListBase.h        The List Base structures
            ListBase.i
            MainBase.h        The Main Base structures
            MainBase.i
            MemoryBase.h      The Memory Base structures
            MemoryBase.i
            ScreenBase.h      The Screen Base structures
            ScreenBase.i
            PVCallRoutines.h  Protos for the PVCall routines
            PVCallTable.h     Table with PVCall routine numbers
            PVCallTable.i
            PVMemory.h        PowerVisor memory allocation structures
            PVMemory.i

          Lib (dir)           All the C libraries (for SAS/C) to make
                              calling PVCall functions from C easier

            PVCallStub.lib    The library for small code
            PVCallStubNB.lib  The library for large code

            Source (dir)      The source for these libraries

              README          A README explaining some things. If you
                              'execute' this file, the two libraries
                              will be build again

              PVCallStub.i    Include file needed for all functions

              makefile        makefile used by 'README'

              PVCBeep.asm     All sources for all PVCall functions
              PVCError.asm
              PVCAddAutoClear.asm
              PVCAddGlobalAutoClear.asm
              PVCAddStringToHist.asm
              PVCAdvanceHistory.asm
              PVCAllocPVBlock.asm
              PVCAppendString.asm
              PVCCallMLScript.asm
              PVCClosePVHandle.asm
              PVCCompareStrings.asm
              PVCComputeGadgetSignal.asm
              PVCConvertAlias.asm
              PVCCopyString.asm
              PVCCreateConstant.asm
              PVCCreateFunction.asm
              PVCErrorHandler.asm
              PVCEvaluate.asm
              PVCFreePVBlock.asm
              PVCGetARexxBase.asm
              PVCGetDebugBase.asm
              PVCGetEvalBase.asm
              PVCGetExecLevel.asm
              PVCGetFileBase.asm
              PVCGetGeneralBase.asm
              PVCGetHistoryLine.asm
              PVCGetListBase.asm
              PVCGetMainBase.asm
              PVCGetMemoryBase.asm
              PVCGetModeRoutines.asm
              PVCGetRexxList.asm
              PVCGetRoutines.asm
              PVCGetScreenBase.asm
              PVCGetSnapBuffer.asm
              PVCGetStringGadget.asm
              PVCGetStringGBuf.asm
              PVCGetStringInfo.asm
              PVCGetVarAddress.asm
              PVCInstallPostCmd.asm
              PVCInstallPreCmd.asm
              PVCInstallQuitCmd.asm
              PVCInstallSnapCmd.asm
              PVCLowerHistory.asm
              PVCParseString.asm
              PVCPrint.asm
              PVCPrintNum.asm
              PVCReAllocPVMemoryBlock.asm
              PVCRefreshLogWin.asm
              PVCRefreshStringG.asm
              PVCRemoveGlobalAutoClear.asm
              PVCRemVar.asm
              PVCSetCursorPos.asm
              PVCSetDebugMode.asm
              PVCSkipSpaces.asm
              PVCSnapWord.asm
              PVCDisassemble.asm
              PVCCmdDisassemble.asm
              PVCPutChar.asm
              PVCAllocMem.asm
              PVCFreeMem.asm
              PVCReAlloc.asm

     s (dir)                  Online help and scripts

       PowerVisor-menus       Only for the AmigaDOS 2.0 version. This
                              file contains the description of the menus
                              used in PowerVisor. The format is not
                              difficult. You can change this file if
                              you'd like other menus
       PowerVisor-help        Online help file. This file contains all
                              online help and the templates. You can't
                              use 'help' and 'why' when this file is
                              not present. Note that the online help
                              file is not the good place to start learning
                              PowerVisor. Use the tutorial files in the
                              'docs' subdirectory for that purpose.
       PowerVisor-ctrl        Online help control file. Use the QuickHelp
                              utilities to update this file when you
                              have changed something in the PowerVisor-help
                              file. You need this file if you want
                              online help
       PowerVisor-errors      All error messages for PowerVisor. You need
                              this file if you want to make errors :-)
                              No, you need this file if you want to see
                              a sensible error message.
                              Each line in this file must be 70 bytes
       PowerVisor-startup     The startup script for PowerVisor. This
                              script installs various new commands and
                              keys

          pv (dir)            This subdirectory contains all scripts you
                              can use

            db                PowerVisor script to install the fullscreen
                              debugger. This script also assigns some
                              keys to useful debugging commands
            ExampleSetting    PowerVisor script to show an other window
                              configuration posibility. Use as an example
                              for more useful settings
            ExtraAliases      This file contains some extra useful
                              aliases not defined in the s/PowerVisor-startup
                              file
            icopy             PowerVisor script to install a logical window
                              copy feature. Press 'Shift-PrtSc' to store
                              the active logical window in an internal
                              buffer. Press 'PrtSc' to retrieve this buffer
                              into another active logical window.
                              This script uses 'GetLogWin' and 'CopyLogWin'
            CheckBrackets     ML script to check for brackets in the
                              commandline. Source is in the 'Source'
                              subdirectory. See the 's/Powervisor-startup'
                              file for an example of how to install this
                              feature
            GetCode           ML script to compute the code of a named
                              key. Source is in the 'Source' subdirectory.
                              Note that if you have AmigaDOS 1.3 you can
                              only use this script to compute the code
                              of special keys (like 'enter' and 'esc')
                              and not of normal keys (like 'a', '3', ...).
                              This script is installed as a function in the
                              's/PowerVisor-startup' file
            CopyLogWin        ML script to copy the active logical window
                              to a buffer. This script is used by 'icopy'.
                              Source is in the 'Source' directory
            GetLogWin         ML script to copy a buffer to the active
                              logical window. This script is used by 'icopy'.
                              Source is in the 'Source' directory
            GetQual           ML script to compute the qualifier of a named
                              qualifier. Source is in the 'Source'
                              subdirectory. This script is installed as a
                              function in the 's/PowerVisor-startup' file
            SearchHist        ML script to search in the history buffer.
                              Source is in the 'Source' subdirectory. This
                              script is installed on a key in the
                              's/PowerVisor-startup' file
            ikey              This PowerVisor script installs various
                              special features
            mkeys             PowerVisor script for a memory display
                              utility
            TypeMemory        Add structure definitions (tags) for some
                              standard structures (like ExecBase and tasks)
            ProtectRCustom    Protect all read only variables in the
                              custom chips. Only use after you have
                              used the 'watch' command
            ProtectWCustom    Protect all write only variables in the
                              custom chips. Only use after you have
                              used the 'watch' command
            StopCustom        Stop the protection set up by the previous
                              scripts. Only use if you have used the
                              'watch' command
            cmd.pv            ARexx script to execute a CLI command from
                              within PowerVisor. The output from the CLI
                              command appears on the PowerVisor window.
                              Use the 'cmd' alias to start this script.
                              You can interrupt the output with <ctrl>+<c>
            cmdline.pv        ARexx script to be started from a shell (not
                              from within PowerVisor). This script emulates
                              a PowerVisor commandline on the shell
            PrintHist.pv      ARexx script to print the contents of the
                              current history buffer
            PrintMode.pv      ARexx script to print the current mode
                              setting in a readable format
            ShowAscii.pv      ARexx script to show all ascii chars on the
                              PowerVisor window
            Assem.pv          Little ARexx assembler. Use the 'asm' alias
                              defined in s:PowerVisor-startup to call this
                              script. See the script for more info about
                              the script
            DispMemList.pv    Display the free memory in a graphical way.
                              Give the start of the memory you want
                              to view as an argument to this script (after
                              'rx')
            SearchKeyWord.pv  ARexx script to seach a keyword in the
                              PowerVisor hypertext manual. Use the
                              'index' alias to start this script
            ListEnv.pv        Specialized ARexx script to get a list
                              environment where you can select a list
                              element with a cursor. Pressing enter will
                              give you information for that element.
                              This script is a good example for some
                              rather specialized ARexx <-> PowerVisor
                              constructions. This script needs the 'co'
                              and 'qu' functions defined in the standard
                              s:PowerVisor-startup file and the
                              'CopyLogWin' and 'GetLogWin' ML-scripts in
                              this subdirectory
            intuition.pvsd    pvsd file for the Window structure.
                              Source is in the 'Source' subdirectory
            Exec.pvsd         pvsd file for all Exec structures
                              Source is in the 'Source' subdirectory

     Examples (dir)           This subdirectory contains some example
                              programs. Sources for most of these programs
                              can be found in the 'Source' subdirectory

       BuggyProgram           Programs used in the 'Debug' tutor file
       BuggyProgram2

       crash3                 Some crash programs
       crash4
       crash5
       crash8
       crasha
       freeerror
       stackovf

       pptest                 powervisor.library test program
       takeme                 'debug t' test program

  ReadThisFirst               This file
  History                     Consult this file to see what's new in
                              the current version of PowerVisor
  HowToInstall                File explaining how to install PowerVisor
  HowToGetTheSource           File explaining what you have to do to get
                              the source of PowerVisor
  pv.bugs                     All known bugs in the current version of
                              Powervisor
  InstallPV                   Install script for AmigaDOS 2.0 (uses the
                              'Installer' program). Double click from
                              the Workbench to use




   WARNING! Some of these files may be compressed. Each file with
   extension '.qq' must be decompressed with the 'dc' utility (note
   that the install script does this automatically) like this (for
   example for the 'PowerVisor-help' file) (don't use wildcards) :

       dc PowerVisor-help.qq PowerVisor-help 4
       delete PowerVisor-help.qq


Environment
-----------

   PowerVisor normally does not expect special assignments or such.
   s/PowerVisor-startup however does expect 'fd' to be assigned to
   the subdirectory containing fd-files (at least exec_lib.fd,
   dos_lib.fd, graphics_lib.fd and intuition_lib.fd). If you do not
   have these fd-files (note that you can find them on the AmigaDOS
   1.3 Extras disk) you must remove four lines in s/PowerVisor-startup
   starting with '-lfd'. You will not be able to use the library
   functions defined in the fd-files if you do this (Note that
   PowerVisor makes very good use of these fd-files, so I recommend
   that you install them if you have a harddisk).

   If you want to use AmigaGuide or MultiView to read the PowerVisor
   documentation you also need to assign 'pv:' to the root of the
   PowerVisor subdirectory (so that MultiView can find the documentation
   in 'pv:docs'). The installation script automatically changes your
   startup-sequence (it will ask first!) to include this and the 'fd:'
   assign.

   s/PowerVisor-startup and all the aliases defined in this script also
   expects the following files in the s:pv directory : db, CheckBrackets,
   GetCode, GetQual, SearchHist, assem.pv, cmd.pv and searchkeyword.pv.

   You can of course adapt s:PowerVisor-startup to your own wishes.


   If you have reqtools.library (by Nico Franois) PowerVisor will use
   it for requesters.


   If you use AmigaDOS 1.2 or 1.3 I recommend that you use
   'FastFonts' (FF) by C.Heath. This program greatly speeds up the
   PowerVisor display. This is not necessary in AmigaDOS 2.0 since
   Commodore did a good optimizing job.

   If you use AmigaDOS 1.2, 1.3, 2.0 or 3.0 and you have a fast processor
   (68020 or higher) I recommend that you use 'CpuBlit' by Eddy Carroll.
   This program gives an even greater speed increase.


Installation
------------

   Look at the 'HowToInstall' file for a very detailed description of
   the installation of PowerVisor.


Tutor files
-----------

Here are all the files in the prefered order to read them.
It is best to read these files with AmigaGuide or MultiView (if you have
one of these programs).

tutor files :

   PowerVisor.guide           Main file
   GettingStarted.guide       For the first time user
   Expressions.guide          Very important to read
   Screen.guide
   InstallingPV.guide         How to install PowerVisor
   LookingAtThings.guide
   Debug.guide
   Scripts.guide

reference files :

   CommandRef.guide           Very useful file explaining all commands
   Functions.guide
   Aliases.guide
   Lists.guide
   TechnicalInfo.guide

for additional information :

   Glossary.guide
   HowDoYou.guide

for very experienced users :

   TheWizCorner.guide         Only read if you are a PowerVisor wizard !!!!!



Authors
-------

   Andr Pelckmans for the disassembler
   Adriaan vd Brand for the floating point conversion routines
   Jorrit Tyberghein for the rest


Address
-------

   Jorrit Tyberghein
   Hepmansbossen 31
   B-2450 Meerhout
   BELGIUM


E-Mail address
--------------

   (Warning! Do NOT use this address after 2 Dec 1993)

   jorrit@uz.kuleuven.ac.be


Thanks to
---------

   Andr Pelckmans for his disassembler and for giving me all
   the programming help I need.
   Without him I wouldn't have a computer in the first place (I think).
   I also got my 68030 manual from him.

   Nico Franois for his debugging, his numerous remarks and suggestions.
   Without him PowerVisor would have looked COMPLETELY different :-)
   (and without him I would have to use two disks to backup the source
   of PowerVisor)

   Nico Franois for his WONDERFUL reqtools.library. If you want to use
   well designed, flexible and powerful requesters there is no better choice

   Ives Aerts for his useful suggestions and criticism.

   Adam Hill, Christian Weber, Steven Reiz and Dominic Giampaolo
   for their bug reports and suggestions.

   Some extra thanks to Adam Hill for his efforts to arouse
   interrest in PowerVisor (in BIX for example).

   Adriaan van den Brand for his good suggestions and information.
   For the fixing of the MMU bug for an 68020 (see V1.31)
   And for the floating point routines.

   John Harper for his bug fix for address errors on the 68000.

   The software people at Commodore for their VERY USEFUL debugging
   tools (like 'Enforcer', 'MungWall', ...).
   And also for their presence on usenet.

   To my parents of course.

   Also thanks to the Amiga computer for being an Amiga.

               __
              ///
             ///
            ///
   __      ///
   \\\    ///       Amiga, the computer for the creative mind
    \\\  ///
     \\\///
      \XX/

