ascend/trunk/README-windows.txt

README for Windows Users
========================

The following contains some specific comments for people who have
installed ASCEND on Windows using the binary 'setup' installer. If you have
built you own copy of ASCEND from the source code, comments here may not 
apply to you.

For more information about and support for ASCEND, consult our home page:
http://ascend.cheme.cmu.edu/

ASCEND documentation (such as it is) is available at the above link, or
if you selected to install the Documentation, you should have a link
called "User's Manual" in your Start Menu under ASCEND. At present the
documentation is available only as a PDF file.


Running ASCEND
--------------

There are two different GUIs for ASCEND. Depending on the software that was
available on your machine at the time when you installed ASCEND, you may
have either the Tcl/Tk GUI and the PyGTK GUI, or both of these, or neither.

The newer GUI is the PyGTK GUI. It looks nice and is under active development.
An alternative GUI is the Tcl/Tk GUI which is older but still somewhat more
stable and complete than the new GUI. It is not really under active development
any more, however. You can choose for yourself.

If you've had any problem with getting either of the two GUIs up and running
it may be worth reviewing the prerequisites list on our Wiki at

http://ascendwiki.cheme.cmu.edu/Prerequisites_for_Windows

In some cases, download/install of components may have failed during
installation. One know case where this occurs is for people who are using
their computer from behind an HTTP proxy. Our current installer is not
set up for that use-case, and you should manually install all prerequisites
before attempting to install ASCEND.


Running the PyGTK GUI
---------------------

ASCEND can be launched from the Start menu. If you didn't choose to install
the Start menu shortcuts, you can run ASCEND using

c:\Python25\pythonw.exe c:\Program Files\ASCEND\ascend

The location of 'pythonw.exe' and 'ascend' may be different depending on 
where you installed Python and where you installed ASCEND.

You can also launch the PyGTK GUI for ASCEND by double-clicking on files
with the .a4c or .a4l extension. The installer will associate ASCEND with
those file extensions.

There is not yet a manual for the PyGTK GUI. The 'Help' menu also provides
access to the online manual.


Running the Tcl/Tk GUI
----------------------

The Tcl/Tk GUI can be run from the Start menu.

If you didn't select to install start menu shortcuts, you can launch it
via

c:\Program Files\ASCEND\ascend4.exe

The file location will depend on the folder where you chose to install ASCEND.

There is no file association for .a4c and .a4l files with the Tcl/Tk GUI.

Note that .a4s files are 'scripts' for the Tcl/Tk GUI.

A PDF-file manual has been written for the Tcl/Tk GUI and may be downloaded 
from the ASCEND wiki.


If ASCEND Stops Working
-----------------------

An easy way to break ASCEND is to remove some of the software it depends
on in order to work. This includes uninstalling Python, GTK+, Tcl/Tk,
PyCairo, PyGObject, PyGTK, IPython, Numpy, Matplotlib and possibly others.

The best thing to do in this case is to uninstall ASCEND using the
Add/Remove Programs control panel, then attempting to re-install it. At this
point, the installer should tell you what components you are missing.


Configuration Settings
----------------------

There are configuration settings in the Windows Registry that the ASCEND 
PyGTK GUI uses to determine where its files have been installed.

There are also per-user settings installed in

c:\Documents and Settings\yourusername\Application Data\.ascend.ini

This last file can be edited if you want to add new folders to your
ASCENDLIBRARY path, for example if you are building up a collection of your
own ASCEND models in a directory of their own.

For example:

[Directories]
librarypath = C:\Program Files\ASCEND\models;C:\Program Files\freesteam\ascend

Other settings are also stored in this file. You can delete this file if you
to revert to the default settings that ASCEND used when you first installed
it.

Neither .ascend.ini file nor the Windows Registry are used by the Tcl/Tk
version of ASCEND. Instead, a number of files are stored in the 'ascdata'
folder within  your My Documents folder.


Removing ASCEND from your System
--------------------------------

The uninstaller for ASCEND can be found in the Start menu and also in the
Add/Remove Programs list. In any case, the uninstaller will remove all 
ASCEND components from your system.

NOTE however that when the uninstaller runs, it does NOT remove the
dependencies such as Python, PyGTK, GTK+ etc that may have been downloaded
and installed by the ASCEND installer when you first installed ASCEND.
These additional components will need to be removed by you manually. The
reason that they are not automatically removed is that it is not
possible to determine whether or not you have other programs installed
that also depend on them.

Syntax Highlighting for TextPad
-------------------------------

If you would like to be able to edit ASCEND files using a text edit that 
provides syntax highlighting support, you can use the editor 'TextPad'
available from http://www.textpad.com. If you use TextPad, you can use
the syntax file 'ascend.syn' that is installed in c:\Program Files\ASCEND
by first copying it to your c:\Program Files\TextPad 5\system folder, 
and then creating a new 'Document Class' for .a4c and .a4l files, and
selecting the 'ascend.syn' syntax file.

-- 
John Pye
4 Aug 2007.
1	jpye	1471	README for Windows Users
2			========================
3
4			The following contains some specific comments for people who have
5			installed ASCEND on Windows using the binary 'setup' installer. If you have
6			built you own copy of ASCEND from the source code, comments here may not
7			apply to you.
8
9			For more information about and support for ASCEND, consult our home page:
10			http://ascend.cheme.cmu.edu/
11
12	jpye	1573	ASCEND documentation (such as it is) is available at the above link, or
13			if you selected to install the Documentation, you should have a link
14			called "User's Manual" in your Start Menu under ASCEND. At present the
15			documentation is available only as a PDF file.
16	jpye	1471
17
18			Running ASCEND
19			--------------
20
21			There are two different GUIs for ASCEND. Depending on the software that was
22			available on your machine at the time when you installed ASCEND, you may
23			have either the Tcl/Tk GUI and the PyGTK GUI, or both of these, or neither.
24
25			The newer GUI is the PyGTK GUI. It looks nice and is under active development.
26			An alternative GUI is the Tcl/Tk GUI which is older but still somewhat more
27			stable and complete than the new GUI. It is not really under active development
28			any more, however. You can choose for yourself.
29
30	jpye	2151	If you've had any problem with getting either of the two GUIs up and running
31			it may be worth reviewing the prerequisites list on our Wiki at
32	jpye	1471
33	jpye	2151	http://ascendwiki.cheme.cmu.edu/Prerequisites_for_Windows
34
35			In some cases, download/install of components may have failed during
36			installation. One know case where this occurs is for people who are using
37			their computer from behind an HTTP proxy. Our current installer is not
38			set up for that use-case, and you should manually install all prerequisites
39			before attempting to install ASCEND.
40
41
42	jpye	1471	Running the PyGTK GUI
43			---------------------
44
45			ASCEND can be launched from the Start menu. If you didn't choose to install
46			the Start menu shortcuts, you can run ASCEND using
47
48			c:\Python25\pythonw.exe c:\Program Files\ASCEND\ascend
49
50			The location of 'pythonw.exe' and 'ascend' may be different depending on
51			where you installed Python and where you installed ASCEND.
52
53			You can also launch the PyGTK GUI for ASCEND by double-clicking on files
54			with the .a4c or .a4l extension. The installer will associate ASCEND with
55			those file extensions.
56
57			There is not yet a manual for the PyGTK GUI. The 'Help' menu also provides
58			access to the online manual.
59
60
61			Running the Tcl/Tk GUI
62			----------------------
63
64			The Tcl/Tk GUI can be run from the Start menu.
65
66			If you didn't select to install start menu shortcuts, you can launch it
67			via
68
69			c:\Program Files\ASCEND\ascend4.exe
70
71			The file location will depend on the folder where you chose to install ASCEND.
72
73			There is no file association for .a4c and .a4l files with the Tcl/Tk GUI.
74
75			Note that .a4s files are 'scripts' for the Tcl/Tk GUI.
76
77			A PDF-file manual has been written for the Tcl/Tk GUI and may be downloaded
78			from the ASCEND wiki.
79
80
81			If ASCEND Stops Working
82			-----------------------
83
84			An easy way to break ASCEND is to remove some of the software it depends
85			on in order to work. This includes uninstalling Python, GTK+, Tcl/Tk,
86			PyCairo, PyGObject, PyGTK, IPython, Numpy, Matplotlib and possibly others.
87
88			The best thing to do in this case is to uninstall ASCEND using the
89			Add/Remove Programs control panel, then attempting to re-install it. At this
90			point, the installer should tell you what components you are missing.
91
92
93	jpye	1573	Configuration Settings
94	jpye	1471	----------------------
95
96			There are configuration settings in the Windows Registry that the ASCEND
97			PyGTK GUI uses to determine where its files have been installed.
98
99			There are also per-user settings installed in
100
101			c:\Documents and Settings\yourusername\Application Data\.ascend.ini
102
103			This last file can be edited if you want to add new folders to your
104			ASCENDLIBRARY path, for example if you are building up a collection of your
105			own ASCEND models in a directory of their own.
106
107			For example:
108
109			[Directories]
110			librarypath = C:\Program Files\ASCEND\models;C:\Program Files\freesteam\ascend
111
112			Other settings are also stored in this file. You can delete this file if you
113			to revert to the default settings that ASCEND used when you first installed
114			it.
115
116			Neither .ascend.ini file nor the Windows Registry are used by the Tcl/Tk
117			version of ASCEND. Instead, a number of files are stored in the 'ascdata'
118			folder within your My Documents folder.
119
120
121	jpye	1573	Removing ASCEND from your System
122			--------------------------------
123
124			The uninstaller for ASCEND can be found in the Start menu and also in the
125			Add/Remove Programs list. In any case, the uninstaller will remove all
126			ASCEND components from your system.
127
128			NOTE however that when the uninstaller runs, it does NOT remove the
129			dependencies such as Python, PyGTK, GTK+ etc that may have been downloaded
130			and installed by the ASCEND installer when you first installed ASCEND.
131			These additional components will need to be removed by you manually. The
132			reason that they are not automatically removed is that it is not
133			possible to determine whether or not you have other programs installed
134			that also depend on them.
135
136			Syntax Highlighting for TextPad
137			-------------------------------
138
139			If you would like to be able to edit ASCEND files using a text edit that
140			provides syntax highlighting support, you can use the editor 'TextPad'
141			available from http://www.textpad.com. If you use TextPad, you can use
142			the syntax file 'ascend.syn' that is installed in c:\Program Files\ASCEND
143			by first copying it to your c:\Program Files\TextPad 5\system folder,
144			and then creating a new 'Document Class' for .a4c and .a4l files, and
145			selecting the 'ascend.syn' syntax file.
146
147	jpye	1471	--
148			John Pye
149	jpye	1573	4 Aug 2007.