+=======================================================================================================+
  |      _____                                              ___        __    _                            |\
  |      /  _  \                                           /  /\      /  \  / \                           | |
  |     /  /\\  \  ______  _______    _____      ______   /  / /     /    \/   \    _______    _______    | |
  |    /  /_//  /\/  ___/\/  ___  \  /  _  \    /  ___/\ /  /_/_    /  /\   /\  \  /  ___  \  /  ___  \   | |
  |   /  _   __/ /  /\__\/  / //  /\/  / \  \  /  / __\//  ___  \  /  / /\_/ /  /\/  / //  /\/  /\_/  /\  | |
  |  /  /\\  \ \/  / /  /  / //  / /  / //  /\/  / /   /  /\ /  /\/  / /  \\/  / /  / //  / /  / //  / /  | |
  | /  /_//  /\/  / /   \  \_/  / /  / //  / /  /_/_  /  / //  / /  / /    /  / /\  \_/  / /  /__/  / /   | |
  | \_______/ /__/ /     \_____/ /__/ //__/ /\_____/\/__/ //__/ /__/ /    /__/ /  \_____/ /  ______/ /    | |
  |  \______\/\__\/       \____\/\__\/ \__\/  \____\/\__\/ \__\/\__\/     \__\/    \____\/  /\_____\/     | |
  |                                                                                     /__/ /            | |
  |   BranchMap v1.0 :: z80 Program Flow Mapper                                         \__\/             | |
  |   Written by Kerm Martian :: http://www.cemetech.net :: kerm@cemetech.net                             | |
  |   Released October 5, 2009                                                                            | |
  +====================.========+==================================+======================================+ |
  | Table of Contents /\________|                                  |\______________________________________\|
  +==================/ /        | 1. Introduction                  ||
   \__________|\_____\/         | 2. Using BranchMap               ||
              | |               |     2.1. Prerequisites           ||
              | |               |     2.2. Command-Line Syntax    /\|
              | |               |     2.3. Reading the Output    / /
              | |               | 3. More Information           / /
              | |               +==============================/ /
              | |                \_____________________________\/
              | |
  +====================.==================================================================================+
  | 1. Introduction   /\___________________________________________________________________________________\
  +==================/ /
   \__________|\_____\/  BranchMap v1.0 is a Python-language program that is intended to ease the complexity
              | |        of developing z80 assembly, especially for Texas Instruments graphing calculators
              | |        such as the TI-83, TI-83+, TI-83+ Silver, TI-84+, and TI-84+ Silver.  It analyzes
              | |        plain-text z80-language source code, parses and organizes the contents thereof, and
              | |        generates Postscript (.ps) or Portable Document Format (.pdf) representations of
              | |        the source.  Among the things that BranchMap can show are calls, bcalls, and jumps
              | |        between locations both in the same file and other files, trace stack depth, and
              | |        color-code program flow for easy visualization of functionality.  Details of the
              | |        various available modes are given in section 2 below.
              | |
  +=====================.==================================================================================+
  | 2. Using Branchmap /\___________________________________________________________________________________\
  +===================/ /
   \__________|\______\/  BranchMap is easy-to use within the Windows command prompt, or from any Linux
              | |         shell.  BranchMap requires at least Python 2.5 or 3.0 to be installed (both have
              | |         been tested as functional under Windows XP/Vista/7 and Ubuntu, and BranchMap should
              | |         work with either one under other variants as well).
              |_|___________________.
              | 2.1 Prerequisites  / \
              |===================+  / BranchMap requires either Windows 2000, XP, Vista, or 7, or some
              |\___________________\/  flavor of Linux.  In addition, Mac OS X should be supported, although
              | |                      I haven't gotten to test it.  Python is also required; if you don't
              | |         have Python on your system, you can get it from http://python.org. Finally, if you
              | |         wish to export .pdf instead of .ps, you need the ps2pdf program that comes with
              | |         Ghostscript.  It can be downloaded at http://www.ghostscript.com/.
              | |
              | |         Note: On Linux/Unix systems, you may need to "chmod +x branchmap.py" after
              | |         extracting the program to allow it to be executed as shown below.
              |_|_________________________.
              | 2.2. Command-Line Syntax / \
              |=========================+  / Branchmap is executed as branchmap.py under Windows, or
              |\_________________________\/  ./branchmap.py under Linux and Unix-based operating systems. You
              | |                            can view the help and usage information at any time using the -h
              | |         switch, such as branchmap.py -h or ./branchmap.py -h.  BranchMap accepts the
              | |         following arguments:
              | |
              | |          branchmap.py [-hcbpsrta] [<asmfile>]
              | |           -h:        Display this help menu
              | |           -c:        Show calls in map file
              | |           -b:        Show bcalls in map file
              | |           -p:        Use ps2pdf to convert PS to PDF
              | |           -s:        Show push/pop stack manipulation
              | |           -r:        Display breaks between routines (best-guess)
              | |           -t:        Show tabguides
              | |           -a:        Verbose output, equivalent to "-c -b -p -s -r -t"
              | |           <asmfile>: A z80 assembly-language file to parse
              | |
              | |          The minimum syntax is "branchmap.py" or "branchmap.py <asmfile>", which will output
              | |          a postscript file showing jumps, labels, and all included files.  Adding -b or -c
              | |          shows bcalls and/or calls respectively in addition to jumps.  The -s flag adds tiny
              | |          arrows indicating stack pushes and pops.  The -r switch enables horizontal lines
              | |          between BranchMap's best guess for the boundaries of individual routines. Adding -t
              | |          adds dotted tabguides to make it easier to see how far down the stack any
              | |          particular calls, bcalls, and jumps are, which especially simplifies tracing stack
              | |          manipulation errors such as too many pushes or pops.  As shown above, the -a flag
              | |          will add all of the optional output items.  The -p flag is special in that it
              | |          affects output file format rather than the contents of the output.  If -p is
              | |          specified, the .ps file that BranchMap creates will be converted into a PDF file
              | |          using Ghostscript's ps2pdf program.  The most popular, recommended format:
              | |         
              | |           branchmap.py -a -p <asmfile>
              |_|_________________________.
              | 2.3. Reading the Output  / \
              |=========================+  / BranchMap output documents always start with a page detailing
              |\_________________________\/  all the files parsed to generate the output.  BranchMap follows
              | |                            all #include'd files, and this list may be decently long
              | |         depending on the size and complexity of the program under scrutiny.
              | |         
              | |         The second page invariably lists some vital statistics about the program: how many
              | |         jumps, calls, bcalls, and more are contained within the file, and most helpfully
              | |         for the purposes of debugging, the number and details of stack manipulations that
              | |         BranchMap believes may be invalid, where a function or routine returns without
              | |         leaving the stack where it is supposed to be.  Of course, manual manipulating of 
              | |         the /sp/ register or growing/shrinking the stack inside of a loop will not be
              | |         correctly analyzed by BranchMap; nevertheless, such cases are relatively rare.
              | |         
              | |         The remainder of the file consists of a simplified, colorized, itemized view of the
              | |         source code.  Firstly, none of the "extra" (ld, in, ex, add, xor, and hundreds of
              | |         others) command will be visible.  Each line is one of the following (after the line
              | |         number, of course):
              | |         
              | |          1) A label: left-aligned, followed by a colon
              | |          2) A call, or bcall, aligned at least one tab in from the margin, as per normal
              | |             z80 source convention.  If pushes have occured before the call or bcall, it
              | |             is tabbed in one additional time for each push; pops remove tabs.  Therefore,
              | |             the calculated stack depth at any given instruction can be immediately seen
              | |             from the output of BranchMap.  Bcalls are prefixed in the far left margin
              | |             with a b, calls with a c.
              | |          3) A jump, identical in form to calls and bcalls except for the omission of a
              | |             letter in the far left margin.
              | |         
              | |         Certain other features are present in outputs.  Calls, bcalls, and jumps that are
              | |         within the same file are indicated with an upward- or downward-pointing arrow;
              | |         branches into other files are indicated with a long arrow to the right margin
              | |         annotated with the filename and line number where the indicated label resides.
              | |         If a function called, bcalled, or jumped to cannot be found in any included file,
              | |         its suffix is invariably a string of question marks: '?????'.
              | |         
              | |         Other significant features (if enabled with the -a flag or selective flags)
              | |         include small arrows showing pushes and pops as the occur within source.  BranchMap
              | |         can try to guess at the boundaries between routines or routine chunks, and place
              | |         horizontal lines at the boundaries.
              | |         
              | |         By dint of BranchMap's intended purpose to ease the visualization and debugging of
              | |         program flow, certain constructs are not handled properly, particularly the common
              | |         jump table.  This usually consists of a single label defining the start of the
              | |         table, followed by a list of "jp label" instructions.  BranchMap does not have the
              | |         ability to understand indexed jumping, and thus will ignore the second and all
              | |         subsequent jumps in the table.  A warning will be issued noting the omission.
              | |         
  +======================.=================================================================================+
  | 3. More Information /\__________________________________________________________________________________\
  +====================/ /
   \__________|\_______\/ The first stop for any help and support on BranchMap should be Cemetech,
              | |         specifically the Cemetech forums at http://www.cemetech.net/forum.  I am there
              | |         almost constantly throughout the day, and if I am not able to answer you quickly,
              | |         some of my very knowledgeable members often jump in.  Failing that, you can email
              | |         me at the address at the top of this file.
              | |         
              | |         BranchMap is (c) 2009 Kerm Martian, nee Christopher Mitchell
              | |         
              |_|============================================================================================+
              |                                                                                              |
              +==============================================================================================+
               \____________________________________________________________________________________________/