Added "git" information and fixed various inaccuracies

to bring these documents up-to-date.

_AboutTheProject.txt

@@ -5,25 +5,30 @@ ABOUT THE MACTERM PROJECT
   Welcome to this source release of MacTerm for Mac OS X!
 
   Formerly known as MacTelnet (and before that, NCSA Telnet),
-  this is now primarily a Mac OS X terminal program and is not
-  really devoted to remote connections anymore.
+  this is now primarily a Mac OS X terminal program.
 
   MacTerm's goal is to be an excellent terminal emulation
   program for Mac OS X, while also being very easy to use.  It
-  streamlines terminal work on both local and remote machines,
+  streamlines terminal work on both local and remote machines
   by giving the user just the right set of powerful features, a
   smart set of preferences and convenient window management.
 
-  The project is now structured as a C/C++/Objective-C++ library
-  that is bound to Python through SWIG.  This allows Python to be
-  used for implementing core features and user extensions.
+  MacTerm's core features are implemented in Objective-C++ and
+  Python, through bindings created by SWIG.  Python can also be
+  used to create extensions (see "macterm.net" for details).
 
-  Python, Perl, shell scripts and GNU makefiles are also used for
-  various infrastructure and the documentation utilities.
+  MacTerm's development environment makes use of Python, Perl,
+  shell scripts and GNU makefiles for various infrastructure and
+  documentation utilities.  In addition, HTML help pages are
+  generated by the PyTextile tool (included) so that original
+  help content can be maintained in a highly-readable format.
+
+  After years of using Subversion, in mid-2015 MacTerm has moved
+  to "git" and the repository is currently on GitHub (see below).
 
   Useful web resources:
-    http://www.macterm.net/ [legacy: http://www.mactelnet.com/]
-    http://sourceforge.net/projects/mactelnet/
+    http://www.macterm.net/
+    https://github.com/kmgrant/macterm
     http://www.swig.org/
     http://www.doxygen.org/
 

_Building.txt

@@ -2,15 +2,25 @@
                       How to Build MacTerm             2009-09-03
 
 PREREQUISITES
-  The latest version of Mac OS X should be used to build.  On the
-  other hand, the project currently does not support Xcode 4.x so
-  an Xcode 3.x installation is preferable.  Xcode can be anywhere
-  but see "Build/GNUmakefile" for a variable that determines
-  where the build looks for development tools.
+  Build with the latest OS X and the most recent Xcode.
 
-  MacTerm expects to compile against the 10.6 SDK.  Recent Mac
-  development environments may only include the 10.7 SDK and
-  require a separate download of the 10.6 SDK.
+  Currently, MacTerm requires the 10.6 SDK, which is not included
+  with Xcode anymore.  Download the SDK separately from Apple's
+  developer site, and put the "MacOSX10.6.sdk" directory in the
+  following location (alongside other SDKs):
+      /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/
+  (Unfortunately, even minor App Store updates to Xcode will
+  obliterate manually-copied SDKs.  This process must be repeated
+  if Xcode is updated!  Keeping a side copy of the 10.6 SDK is
+  advisable.)
+
+  Work is being done to adopt more recent SDKs; the primary issue
+  is that the 10.7 SDK abandons all Carbon APIs.  Many parts of
+  MacTerm have switched to Cocoa, and MacTerm can even *call*
+  APIs from later SDKs (see "Build/Shared/Code/CocoaFuture.*").
+  Unfortunately the most important view is the terminal itself,
+  and until its many Carbon and QuickDraw dependencies can be
+  replaced there is no feasible way to upgrade the default SDK.
 
   By default MacTerm compiles in support for Growl notifications
   (http://www.growl.info/) so a default build requires the SDK
@@ -25,10 +35,10 @@ PREREQUISITES
   Python.  This is accomplished with the Simple Wrapper Interface
   Generator (SWIG), which you must download and build separately;
   look at "Build/Tools/SwigConfig.sh".  The latest version of
-  SWIG is recommended (the 2.x series was tested recently).  See
+  SWIG is recommended (the 3.x series was tested recently).  See
   "Build/Shared/CustomPaths.xcconfig" for a variable that sets
   the install path (/opt/swig-<version>/bin/swig by default).
-
+  
   Note that the build system only uses artwork from a component's
   Resources directory (such as "Build/Application/Resources").
   If you decide to modify any of the source artwork files located
@@ -51,17 +61,14 @@ UNDERSTANDING THE DIRECTORY STRUCTURE
     Build/
         Source code for all components and documentation, and the
         scripts required to build them.  The top level has Xcode
-        projects and/or build scripts for each component.  In
-        addition, files used by more than one component are in
-        Build/Shared/.
+        projects and/or build scripts for each component.  Files
+        used by more than one component are in Build/Shared/.
     Debug/
         Scripts that simplify MacTerm debugging.
 
 HOW TO BUILD
-  The MacTerm.app bundle is constructed using a makefile, since
-  it has an unusual file layout.  However, Xcode is still called
-  by the makefile to do builds and cleans; so if a build was
-  initiated from the GUI, those results will be used by "make".
+  The MacTerm.app bundle has an unusual file layout so it is
+  constructed by a makefile.
 
   There are a few ways to do builds, and they are equivalent:
   - Use "Build/Application.xcodeproj".  The "Everything" target
@@ -73,14 +80,15 @@ HOW TO BUILD
     include settings that customize the build.
 
   You can clean in the usual ways (i.e. the Clean command on the
-  "Everything" target, or "make clean").
+  "Everything" target, or "make clean").  Note also that since
+  the vast majority of files go into "Build/_Generated", it is
+  often enough to simply trash that folder.
 
-  IMPORTANT: The build system currently will only rebuild the
-  entire Python wrapper when the SWIG file "Quills.i" is changed.
-  However, that is NOT the only file that affects the wrapper: in
-  particular, if you ever change Quills*.{cp,h}, you should also
-  "touch" Quills.i so that the wrapper is rebuilt with your
-  changes.
+  IMPORTANT: The build system currently will only rebuild Python
+  wrappers when the SWIG file "Quills.i" is changed, even though
+  this is NOT the only file affecting wrappers.  In particular,
+  if you ever change Quills*.{cp,h}, you should also "touch"
+  Quills.i so that the wrapper is rebuilt with your changes.
 
 HOW TO CUSTOMIZE THE BUILD
   It is possible to tweak the makefile or environment to change

_Licenses.txt

@@ -15,7 +15,7 @@ MAIN SOURCE CODE LICENSE
   MacTerm is free software; you may distribute it or modify it
   under the terms of the GNU General Public License, either
   version 2 of the license or (at your option) a later version.
-
+  
   Note that the "source" of a component includes everything in
   its directory tree: Code, Resources, Artwork, etc. as well as
   any scripts that are required to build it.
@@ -36,7 +36,7 @@ GENERIC CODE LICENSE
   (formerly "MAAttachedWindow.m" and "MAAttachedWindow.h" but
   extensively modified) are so modified under the terms of the
   license from Matt Gemmell.
-
+  
   A copy of Matt Gemmell's license is in Licenses/.
 
                                         Kevin Grant (kmg@mac.com)

_SubmittingBugReports.txt

@@ -4,14 +4,13 @@
 REPORTING BUGS
   You are welcome to submit via E-mail to "kmg@mac.com".
 
-  Due to recent infrastructure changes at SourceForge there is
-  currently no web page for logging bug reports in a more
-  official manner.  This may change; you can access the project
-  page here:
-    http://sourceforge.net/projects/mactelnet/
+  Issues have not been formally tracked in awhile, ever since
+  SourceForge dropped its Trac support.  Since the project has
+  recently moved to GitHub, issue-tracking may resume there;
+  check "https://github.com/kmgrant/macterm/issues" periodically.
 
-  Please see http://macterm.net/bug-reporter/ for a variety of
-  advice on submitting useful bug reports.
+  Please see http://www.macterm.net/bug-reporter/ for a variety
+  of advice on submitting useful bug reports.
 
                                         Kevin Grant (kmg@mac.com)
                                         Lead Developer, MacTerm

_Testing.txt

@@ -3,25 +3,21 @@
 
 OVERVIEW
   To be perfectly honest, automated testing is a huge hole in the
-  project right now, but something I am working on, and something
-  that will become incredibly easy to do once sufficient code is
-  exposed to Python through the Quills API.
-
-  Having said that, there are some automated tests, and plenty of
-  manual ones you can run.
+  project right now.  Tests are available though (see below).
+  The Python API may make this easier in the future.
 
 COMPILED-IN UNIT TESTS
-  The source file Build/Application/Code/Initialize.cp contains a
-  preprocessor definition "RUN_MODULE_TESTS".  If set to 1, some
-  unit tests for certain modules will be compiled in and run at
-  application startup time.  A test report will be printed to
-  standard output.
+  The source in Build/Application/Code/Initialize.* contains a
+  preprocessor definition "RUN_MODULE_TESTS".  If set to 1, the
+  unit tests for certain modules will be compiled-in and run at
+  application startup time, reporting results to standard output.
+  (Run these only after changing a well-established component.)
 
 PYTHON MODULE TESTS
   Source files implemented entirely in Python, found in folders
   named "PythonCode", generally support standard Python doctests
-  completely.  But more than that, they are set up so you can
-  simply "run" a file to invoke all of its doctests.
+  completely.  If a module file has been made executable, you can
+  simply "run" the file to invoke all of its doctests.
 
   Keep in mind that if a Python module depends on Quills, it will
   also depend on compiled libraries, and therefore is easiest to
@@ -32,21 +28,18 @@ TERMINAL TESTS
   The popular testing program "vttest" is strongly recommended;
   this is easy to Google and compile yourself.  It contains many
   very useful and thorough tests of VT100/ANSI, VT100/VT52,
-  VT102, VT220, XTerm, and more.
-
-  Mac OS X comes with the "tack" program (in /usr/bin; see also
-  "man tack"), which is another source of terminal tests.
+  VT102, VT220, XTerm, and more.  Another source of tests is the
+  "tack" program.
 
-  I am developing a series of "curses"-based Python test suites
-  to do as much automated testing of the terminal emulators as
-  possible.  Currently, these are not checked into the project
-  tree.
+  It is also generally a good idea to test popular and complex
+  programs such as the mail program "alpine", text editors, and
+  games.
 
 GRAPHICAL USER INTERFACE TESTS
-  It is theoretically possible to use AppleScript to automate GUI
-  actions.  This is something I intend to try some day.  So far,
-  there is no automatic GUI testing, so I just click on things
-  myself until I cause a crash. :)
+  It is theoretically possible to use AppleScript or a modern
+  version of Xcode to automate GUI actions.  MacTerm does not use
+  these right now; I just click on things myself until I cause a
+  crash. :)
 
                                         Kevin Grant (kmg@mac.com)
                                         Lead Developer, MacTerm