Update READMEs

README.md

@@ -1,10 +1,13 @@
 # 6502bench #
 
+[Features](#key-features) - [Getting Started](#getting-started) - [About the Code](#about-the-code)
+
 6502bench is a code development "workbench" for 6502, 65C02, and 65802/65816
 code.  It currently features one tool, the SourceGen disassembler.
 
 You can download the source code and build it yourself, or click the
-"Releases" tab near the top of the github page for pre-built downloads.
+["Releases" tab](https://github.com/fadden/6502bench/releases) for
+pre-built downloads.
 
 
 ## SourceGen ##
@@ -13,72 +16,88 @@ SourceGen converts machine-language programs to assembly-language source
 code.  It has most of the features you will find in other 6502 disassemblers,
 as well as many less-common ones.
 
-A demo video is available: https://youtu.be/dalISyBPQq8
+### Key Features ###
 
-#### Features ####
+- Fully interactive point-and-click GUI.  Define labels, set addresses,
+  add comments, and see the results immediately.  Add multi-line comments
+  and have them word-wrapped automatically.
+- The disassembly engine traces code execution, automatically finding all
+  instructions reachable from a given starting point. Changes to the
+  processor status flags are tracked, allowing identification of branches
+  that are always/never taken, accurate cycle count listings, and correct
+  analysis of 65816 code with variable-width registers.
+- Easy generation of assembly source code in populate formats (currently
+  cc65 and Merlin 32). Cross-assemblers can be invoked from the GUI to
+  verify correctness.
+- Symbols and constants are provided for ROM and operating system entry
+  points on several popular systems.
 
-Analysis:
-- Support for 6502 (including undocumented opcodes), 65C02, and 65816.
-- Code flow analyzer traces execution to find all reachable
-  instructions.  Hinting mechanism allows manual specification of
-  entry points.
-- Processor status flags are tracked, allowing automatic detection
-  of branch-always and branch-never, as well as register widths on
-  16-bit CPUs.  The analyzer tracks these across subroutine calls and
-  branches.  Cycle counts factor these in automatically.
-- Editable labels are generated for every branch and data target.
+A demo video is [available on YouTube](https://youtu.be/dalISyBPQq8).
+
+#### Additional Features ####
+
+Analyzer:
+- Support for 6502, 65C02, and 65816, including undocumented opcodes.
+- Hinting mechanism allows manual identification of code, data, and inline
+  data.
+- Editable labels are generated for every branch destination and data target.
 - Automatic detection and classification of ASCII strings and runs of
   identical bytes.
-- All target-platform-specific stuff is stored in plain text files
-  loaded at runtime.  This includes symbols for ROM entry points
-  and standard zero-page locations.  Additional symbols and overrides
-  can be specified at the project level.
-- Extension scripts can be used to reformat code and identify inline
-  data that follows JSR/JSL.  Code is compiled at run time and
-  executes in a sandbox.
+- Symbol files for ROM entry points, operating system constants, and other
+  platform-specific data are stored in plain text files.
+- Extension scripts can be defined that automatically reformat code and
+  identify inline data that follows a JSR/JSL.
 
-UI:
-- Fully interactive point-and-click GUI.  Add labels and multi-line
-  comments, change addresses, and see the changes immediately.
-- Instruction operand formats (hex, decimal, etc) can be set for
-  individual lines.  Symbols that don't match the operands are automatically
-  offset, allowing simple expressions like "address - 1".
-- Full-line comments are automatically word-wrapped, and can be
-  "boxed" for an authentic retro feel.
-- Data areas can be formatted as bytes, words, addresses, and more.
-  Several types of strings are recognized (null-terminated, length
-  prefixed, etc).
-- "Infinite" undo/redo of all actions.
-- Notes can be added that aren't included in generated output.  Very
-  useful for marking up a work in progress.
-- Cross-reference tables are generated for every branch and data
-  target address, as well as for external platform symbols.
-- Instruction summaries, including cpu cycles and flags modified, are
-  shown along with a description of the opcode function.
-- Display is configurable for upper/lower case, choice of pseudo-op
-  names, expression formats, and more.
+User interface:
+- "Infinite" undo/redo of all operations.
+- Cross-reference tables are generated for every branch and data target
+  address, as well as for external platform symbols.
+- Instruction operand formats (hex, decimal, binary, ASCII, symbol) can be
+  set for individual instructions. References to nearby symbols are offset,
+  allowing simple expressions like "addr + 1".
+- Data areas can be formatted in various formats, including individual
+  bytes, 16-bit and 24-bit words, addresses, or strings.
+- Multi-line comments can be "boxed" for an authentic retro feel.
+- Notes can be added that aren't included in generated output. These also
+  function as color-coded bookmarks. Very useful for marking up a work in
+  progress.
+- Instruction summaries, including CPU cycles and flags modified, are shown
+  along with a description of the opcode's function.
+- Various aspects of the code display can be reconfigured, including
+  upper/lower case, pseudo-opcode naming, and expression formats. These
+  choices are not part of the project definition, so everyone can view a
+  project according to their own personal preferences.
 
-Output:
-- Assembly source can be generated for multiple assemblers (currently
-  cc65 and Merlin 32).
-- Cross-assemblers can be launched directly from the generation GUI to
-  verify output correctness.
-- Optional automatic conversion of labels from global to local.
-- Symbols may be exported from one project and imported into another
-  to facilitate multi-binary disassembly.
+Code generation:
+- Labels can be coaxed from global to local as allowed by the assembler.
+- Symbols may be exported from one project and imported into another to
+  facilitate multi-binary disassembly.
 
-Misc:
-- Preset project attributes (CPU type, platform symbol file sets) are defined
-  for a variety of platforms.
-- Project file is stored in a text format, and only holds metadata.  None
-  of the original file is included, allowing the project file to be shared
-  without violating copyrights (note: may vary depending on local laws).
+Miscellaneous:
+- All data files are stored in text formats (primarly JSON).
+- The project file includes nothing from the data file but a CRC. This may
+  allow the project to be shared without violating copyrights (subject to
+  local laws).
 
 There are a couple of significant areas where support is currently lacking:
 - Poor support for multi-bank 65816 files (IIgs OMF, SNES).
 - No support for alternate character sets (e.g. PETSCII).
 
 
+## Getting Started ##
+
+The best way to get started is by working through the tutorial.  Launch
+SourceGen, hit F1 to open the user manual in your web browser, then scroll
+down near the bottom of the index page.  Click on "Tutorials", and follow
+the instructions.
+
+The tutorial is one of several examples included in the SourceGen
+distribution.  The other directories contain project and data files for
+completed disassembly projects alongside the original source code, allowing
+a direct comparison between how the code was written and how SourceGen can
+display it.
+
+
 ## About the Code ##
 
 All of the code is written in C# .NET, using the (free to download) Visual

SourceGen/Examples/README.md

@@ -7,22 +7,25 @@ project to the original.
  * Tutorial: a simple project, intended for use with the tutorial in
    the manual.
  * A2-lz4fh: two functions for unpacking a simplified form of LZ4 compression.
-   One is 6502, the other is 65816.
+   One is 6502, the other is 65816.  This is pretty straightforward.
    [(Full project)](https://github.com/fadden/fhpack)
  * A2-Amper-fdraw: 6502 code that provides an Applesoft BASIC interface
    to a machine-language graphics library.  The public interface of the
-   graphics library is defined in a .sym65 file.
+   graphics library is defined in a .sym65 file.  This example has multiple
+   entry points in a jump table, and requires a bit more effort.
    [(Full project)](https://github.com/fadden/fdraw)
- * A2-HP-CDA: HardPressed Classic Desk Accessory.  This is 65816 code
-   in OMF loader format, which SourceGen doesn't support, so it's a little
-   rough.
-   [(Full project)](https://fadden.com/apple2/hardpressed.html)
  * A2-Zippy: a program for controlling an Apple IIgs CPU accelerator card.
    65816 sources, with a little bit of ProDOS 8 and IIgs toolbox usage.
+   Demonstrates how extension scripts are used during analysis.
    [(Full project)](https://fadden.com/apple2/misc.html#zippy)
+ * A2-HP-CDA: HardPressed Classic Desk Accessory.  This is 65816 code
+   in OMF loader format, which SourceGen doesn't support, so it's a little
+   rough.  (This is chiefly here to answer the question, "what does it look
+   like when you disassemble OMF binaries?")
+   [(Full project)](https://fadden.com/apple2/hardpressed.html)
 
 (You may be wondering why some of the example files have filenames with
 things like "#061d60" in them.  It's a method of preserving the file type
-for Apple II files used by some utilities.  The potential advantage here
-for SourceGen is that the file type often determines the load address,
+for Apple II files used by some utilities.  The potential advantage for
+disassembly is that the file type often determines the load address,
 possibly removing some initial guesswork.)