Initial revision

1 files changed, 131 insertions, 0 deletions

diff --git a/Mac/USING b/Mac/USING
new file mode 100644
index 0000000..3c67fb7
--- /dev/null
+++ b/Mac/USING
@@ -0,0 +1,131 @@
+PYTHON RELEASE NOTES FOR THE MACINTOSH
+
+VERSION 1.0.2
+
+For the most part, Python on the Mac works just like Python under UNIX.
+The most important differences are:
+
+- Since there is no shell environment on the Mac, the start-up file
+  has a fixed name: PythonStartup.  If a file by this name exists
+  (either in the current folder or in the system folder) it is executed
+  when an interactive interpreter is started.
+
+- The default search path for modules is different: first the current
+  directory is searched, then the subdirectories 'lib', 'lib:stdwin' and
+  'demo'.  As always, you can change this (e.g. in your PythonStartup
+  file) by assigning or appending to sys.path -- use Macintosh pathnames!
+  (The default contains no absolute paths because these are unlikely
+  to make sense on other people's hard disks.)
+
+- The user interface for typing interactive commands is different.
+  This is actually the THINK C console I/O module, which is based on
+  the Mac toolbox TextEdit.  A standard Edit menu provides Cut, Copy,
+  Paste and Clear (Undo is only there for Desk Accessories).  A minimal
+  File menu provides Quit, which immediately exits the application,
+  without the usual cleanup.  You can Copy from previous output,
+  but you can't scroll back beyond the 24x80 screen.  The TAB key
+  always brings you to the end of the current input line; indentation
+  must be entered with spaces (a single space is enough).
+  End-of-file is generated by Command-D; Command-Period interrupts.
+  There is an annoying limit in the length of an input line to a single
+  screen line (less the prompt).  Use \ to input long statements.
+  Change your program if it requires long lines typed on input.
+  Even though there is no resize box, the window can be resized by
+  dragging its bottom right corner, but the maximum size is 24x80.
+
+- Tabs in module files are interpreted as 4 (four!) spaces.  This is
+  consistent with most Mac editors that I know.  For individual files
+  you can change the tab size with a comment like
+
+	# vi:set tabsize=8:
+
+  (exactly as shown here, including the colons!).  If you are consistent
+  in always using tabs for indentation on UNIX, your files will be
+  parsed correctly on the Mac, although they may look funny if you
+  have nicely lined-up comments or tables using tabs.  Never using tabs
+  also works.  Mixing tabs and spaces to simulate 4-character indentation
+  levels is likely to fail.
+
+- You can start a script from the Finder by selecting the script and
+  the Python interpreter together and then double clicking.  If you
+  make the owner of the script PYTH (the type should always be TEXT)
+  Python will be launched if you double click it!
+  There is no way to pass command line arguments to Python scripts.
+
+- The set of built-in modules is different:
+
+  = Operating system functions for the 'os' module is provided by the
+    built-in module 'mac', not 'posix'.  This doesn't have all the
+    functions from posix, for obvious reasons (if you know the Mac
+    O/S a little bit).  The functions in os.path are provided by
+    macpath, they know about Mac pathnames etc.
+    
+  = None of the UNIX specific modules ('socket', 'pwd', 'grp' etc.)
+    exists.
+    
+  = Module 'stdwin' is always available.  It uses the Mac version of
+    STDWIN, which interfaces directly with the Mac toolbox.  The most
+    important difference is in the font names; setfont() has a second
+    argument specifying the point size and an optional third one
+    specifying the variation: a single letter character string,
+    'i' for italics, 'b' for bold.  Note that when STDWIN is waiting
+    for events, the standard File and Edit menus are inactive but
+    still visible, and (most annoyingly) the Apple menu is also inactive;
+    conversely, menus put up by STDWIN are not active when the Python is
+    reading from the keyboard.  If you open Python together with a text
+    file containing a Python script, the script will be executed and
+    a console window is only generated when the script uses standard
+    input or output.  A script that uses STDWIN exclusively for its I/O
+    will have a working Apple menu and no extraneous File/Edit menus.
+    (This is because both stdwin and stdio try to initialize the
+    windowing environment; whoever gets there first owns the Apple menu.)
+    LIMITATIONS: a few recent additions to STDWIN for X11 have not yet
+    been added to the Mac version.  There are no bitmap objects, and
+    the setwinpos() and setwinsize() methods are non--functional.
+
+- Because launching an application on the Mac is so tedious, you will
+  want to edit your program with a desk accessory editor (e.g., Sigma
+  edit) and test the changed version without leaving Python.  This is
+  possible but requires some care.  Make sure the program is a module
+  file (filename must be a Python identifier followed by '.py').  You
+  can then import it when you test it for the first time.  There are
+  now three possibilities: it contains a syntax error; it gets a runtime
+  error (unhandled exception); or it runs OK but gives wrong results.
+  (If it gives correct results, you are done testing and don't need
+  to read the rest of this paragraph. :-)  Note that the following
+  is not Mac-specific -- it's just that on UNIX it's easier to restart
+  the entire script so it's rarely useful.
+  
+  Recovery from a syntax error is easy: edit the file and import it
+  again.
+  
+  Recovery from wrong output is almost as easy: edit the file and,
+  instead of importing it, call the function reload() with the module
+  name as argument (e.g., if your module is called foo, type
+  "reload(foo)").
+  
+  Recovery from an exception is trickier.  Once the syntax is correct,
+  a 'module' entry is placed in an internal table, and following import
+  statements will not re-read the file, even if the module's initialization
+  terminated with an error (one reason why this is done is so that
+  mutually recursive modules are initialized only once).  You must
+  therefore force re-reading the module with reload(), however, if this
+  happens the first time you try to import the module, the import statement
+  itself has not completed, and your workspace does not know the module
+  name (even though the internal table of moduesl does!).  The trick is
+  to first import the module again, then reload it.  For instance,
+  "import foo; reload(foo)".  Because the module object already exists
+  internally, the import statement does not attempt to execute the
+  module again -- it just places it in your workspace.
+  
+  When you edit a module you don't have to worry about the corresponding
+  '.pyc' file (a "compiled" version of the module, which loads much faster
+  than the textual version): the interpreter notices that the '.py' file
+  has changed (because its modification time has changed) and ignores the
+  '.pyc' file.  When parsing is successful, a new '.pyc' file is written;
+  if this fails (no write permission, disk full or whatever) it is
+  silently skipped but attempted again the next time the same module
+  is loaded.  (Thus, if you plan to place a Python library on a read-only
+  disk, it is advisable to "warm the cache" by making the disk writable
+  and importing all modules once.  The standard module 'importall' helps
+  in doing this.)