add hg and python

1 files changed, 241 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/mac/libmacfs.tex b/sys/src/cmd/python/Doc/mac/libmacfs.tex
new file mode 100644
index 000000000..12a7cc34b
--- /dev/null
+++ b/sys/src/cmd/python/Doc/mac/libmacfs.tex
@@ -0,0 +1,241 @@
+\section{\module{macfs} ---
+         Various file system services}
+
+\declaremodule{standard}{macfs}
+  \platform{Mac}
+\modulesynopsis{Support for FSSpec, the Alias Manager,
+                \program{finder} aliases, and the Standard File package.}
+
+\deprecated{2.3}{The macfs module should be considered obsolete. For
+\class{FSSpec}, \class{FSRef} and \class{Alias} handling use the
+\module{Carbon.File} or \refmodule{Carbon.Folder} module. For file
+dialogs use the \refmodule{EasyDialogs} module.  Also, this module is
+known to not work correctly with UFS partitions.}
+
+This module provides access to Macintosh \class{FSSpec} handling, the
+Alias Manager, \program{finder} aliases and the Standard File package.
+\index{Macintosh Alias Manager}
+\index{Alias Manager, Macintosh}
+\index{Standard File}
+
+Whenever a function or method expects a \var{file} argument, this
+argument can be one of three things:\ (1) a full or partial Macintosh
+pathname, (2) an \class{FSSpec} object or (3) a 3-tuple
+\code{(\var{wdRefNum}, \var{parID}, \var{name})} as described in
+\citetitle{Inside Macintosh:\ Files}.  An \class{FSSpec} can point to
+a non-existing file, as long as the folder containing the file exists.
+Under MacPython the same is true for a pathname, but not under \UNIX-Python
+because of the way pathnames and FSRefs works.  See Apple's documentation
+for details.
+
+A description of aliases and the
+Standard File package can also be found there.
+
+\begin{funcdesc}{FSSpec}{file}
+Create an \class{FSSpec} object for the specified file.
+\end{funcdesc}
+
+\begin{funcdesc}{RawFSSpec}{data}
+Create an \class{FSSpec} object given the raw data for the \C{}
+structure for the \class{FSSpec} as a string.  This is mainly useful
+if you have obtained an \class{FSSpec} structure over a network.
+\end{funcdesc}
+
+\begin{funcdesc}{RawAlias}{data}
+Create an \class{Alias} object given the raw data for the \C{}
+structure for the alias as a string.  This is mainly useful if you
+have obtained an \class{FSSpec} structure over a network.
+\end{funcdesc}
+
+\begin{funcdesc}{FInfo}{}
+Create a zero-filled \class{FInfo} object.
+\end{funcdesc}
+
+\begin{funcdesc}{ResolveAliasFile}{file}
+Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec},
+\var{isfolder}, \var{aliased})} where \var{fsspec} is the resulting
+\class{FSSpec} object, \var{isfolder} is true if \var{fsspec} points
+to a folder and \var{aliased} is true if the file was an alias in the
+first place (otherwise the \class{FSSpec} object for the file itself
+is returned).
+\end{funcdesc}
+
+\begin{funcdesc}{StandardGetFile}{\optional{type, \moreargs}}
+Present the user with a standard ``open input file''
+dialog. Optionally, you can pass up to four 4-character file types to limit
+the files the user can choose from. The function returns an \class{FSSpec}
+object and a flag indicating that the user completed the dialog
+without cancelling.
+\end{funcdesc}
+
+\begin{funcdesc}{PromptGetFile}{prompt\optional{, type, \moreargs}}
+Similar to \function{StandardGetFile()} but allows you to specify a
+prompt which will be displayed at the top of the dialog.
+\end{funcdesc}
+
+\begin{funcdesc}{StandardPutFile}{prompt\optional{, default}}
+Present the user with a standard ``open output file''
+dialog. \var{prompt} is the prompt string, and the optional
+\var{default} argument initializes the output file name. The function
+returns an \class{FSSpec} object and a flag indicating that the user
+completed the dialog without cancelling.
+\end{funcdesc}
+
+\begin{funcdesc}{GetDirectory}{\optional{prompt}}
+Present the user with a non-standard ``select a directory'' dialog.  You
+have to first open the directory before clicking on the ``select current
+directory'' button. \var{prompt} is the prompt string which will be
+displayed at the top of the dialog. Return an \class{FSSpec} object and
+a success-indicator.
+\end{funcdesc}
+
+\begin{funcdesc}{SetFolder}{\optional{fsspec}}
+Set the folder that is initially presented to the user when one of
+the file selection dialogs is presented. \var{fsspec} should point to
+a file in the folder, not the folder itself (the file need not exist,
+though). If no argument is passed the folder will be set to the
+current directory, i.e. what \function{os.getcwd()} returns.
+
+Note that starting with System 7.5 the user can change Standard File
+behaviour with the ``general controls'' control panel, thereby making
+this call inoperative.
+\end{funcdesc}
+
+\begin{funcdesc}{FindFolder}{where, which, create}
+Locates one of the ``special'' folders that Mac OS knows about, such as
+the trash or the Preferences folder. \var{where} is the disk to
+search, \var{which} is the 4-character string specifying which folder to
+locate. Setting \var{create} causes the folder to be created if it
+does not exist. Returns a \code{(\var{vrefnum}, \var{dirid})} tuple.
+
+The constants for \var{where} and \var{which} can be obtained from the
+standard module \var{Carbon.Folders}.
+\end{funcdesc}
+
+\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
+Return a minimal \class{alias} object that points to the given file, which
+must be specified as a full pathname. This is the only way to create an
+\class{Alias} pointing to a non-existing file.
+
+\end{funcdesc}
+
+\begin{funcdesc}{FindApplication}{creator}
+Locate the application with 4-character creator code \var{creator}. The
+function returns an \class{FSSpec} object pointing to the application.
+\end{funcdesc}
+
+
+\subsection{FSSpec Objects \label{fsspec-objects}}
+
+\begin{memberdesc}[FSSpec]{data}
+The raw data from the FSSpec object, suitable for passing
+to other applications, for instance.
+\end{memberdesc}
+
+\begin{methoddesc}[FSSpec]{as_pathname}{}
+Return the full pathname of the file described by the \class{FSSpec}
+object.
+\end{methoddesc}
+
+\begin{methoddesc}[FSSpec]{as_tuple}{}
+Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of
+the file described by the \class{FSSpec} object.
+\end{methoddesc}
+
+\begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}}
+Create an Alias object pointing to the file described by this
+FSSpec. If the optional \var{file} parameter is present the alias
+will be relative to that file, otherwise it will be absolute.
+\end{methoddesc}
+
+\begin{methoddesc}[FSSpec]{NewAliasMinimal}{}
+Create a minimal alias pointing to this file.
+\end{methoddesc}
+
+\begin{methoddesc}[FSSpec]{GetCreatorType}{}
+Return the 4-character creator and type of the file.
+\end{methoddesc}
+
+\begin{methoddesc}[FSSpec]{SetCreatorType}{creator, type}
+Set the 4-character creator and type of the file.
+\end{methoddesc}
+
+\begin{methoddesc}[FSSpec]{GetFInfo}{}
+Return a \class{FInfo} object describing the finder info for the file.
+\end{methoddesc}
+
+\begin{methoddesc}[FSSpec]{SetFInfo}{finfo}
+Set the finder info for the file to the values given as \var{finfo}
+(an \class{FInfo} object).
+\end{methoddesc}
+
+\begin{methoddesc}[FSSpec]{GetDates}{}
+Return a tuple with three floating point values representing the
+creation date, modification date and backup date of the file.
+\end{methoddesc}
+
+\begin{methoddesc}[FSSpec]{SetDates}{crdate, moddate, backupdate}
+Set the creation, modification and backup date of the file. The values
+are in the standard floating point format used for times throughout
+Python.
+\end{methoddesc}
+
+
+\subsection{Alias Objects \label{alias-objects}}
+
+\begin{memberdesc}[Alias]{data}
+The raw data for the Alias record, suitable for storing in a resource
+or transmitting to other programs.
+\end{memberdesc}
+
+\begin{methoddesc}[Alias]{Resolve}{\optional{file}}
+Resolve the alias. If the alias was created as a relative alias you
+should pass the file relative to which it is. Return the FSSpec for
+the file pointed to and a flag indicating whether the \class{Alias} object
+itself was modified during the search process. If the file does
+not exist but the path leading up to it does exist a valid fsspec
+is returned.
+\end{methoddesc}
+
+\begin{methoddesc}[Alias]{GetInfo}{num}
+An interface to the \C{} routine \cfunction{GetAliasInfo()}.
+\end{methoddesc}
+
+\begin{methoddesc}[Alias]{Update}{file\optional{, file2}}
+Update the alias to point to the \var{file} given. If \var{file2} is
+present a relative alias will be created.
+\end{methoddesc}
+
+Note that it is currently not possible to directly manipulate a
+resource as an \class{Alias} object. Hence, after calling
+\method{Update()} or after \method{Resolve()} indicates that the alias
+has changed the Python program is responsible for getting the
+\member{data} value from the \class{Alias} object and modifying the
+resource.
+
+
+\subsection{FInfo Objects \label{finfo-objects}}
+
+See \citetitle{Inside Macintosh: Files} for a complete description of what
+the various fields mean.
+
+\begin{memberdesc}[FInfo]{Creator}
+The 4-character creator code of the file.
+\end{memberdesc}
+
+\begin{memberdesc}[FInfo]{Type}
+The 4-character type code of the file.
+\end{memberdesc}
+
+\begin{memberdesc}[FInfo]{Flags}
+The finder flags for the file as 16-bit integer. The bit values in
+\var{Flags} are defined in standard module \module{MACFS}.
+\end{memberdesc}
+
+\begin{memberdesc}[FInfo]{Location}
+A Point giving the position of the file's icon in its folder.
+\end{memberdesc}
+
+\begin{memberdesc}[FInfo]{Fldr}
+The folder the file is in (as an integer).
+\end{memberdesc}