Ticket #4878: new-install.diff

docs/install.txt

@@ -11 +11 @@
 
 It works with any Python version 2.3 and higher.
 
-Get Python at http://www.python.org. If you're running Linux or Mac OS X, you
-probably already have it installed.
+Python is available from http://www.python.org. If you are running Linux or
+Mac OS X, you probably already have a suitable version installed.  If you are
+running Windows, you will almost certainly need to download the latest Windows
+MSI installer package for your particular machine architecture (Intel x86,
+AMD 64 or Itanium).  Double-clicking on the MSI file will then begin the
+installation process.
 
 Install Apache and mod_python
 =============================
 
-If you just want to experiment with Django, skip ahead to the next
-section; Django includes a lightweight web server you can use for
-testing, so you won't need to set up Apache until you're ready to
-deploy Django in production.
+If you just want to experiment with Django, skip ahead to the next section;
+Django includes a lightweight web server you can use for testing, until you're
+ready to deploy Django in production.
 
-If you want to use Django on a production site, use Apache with `mod_python`_.
-mod_python is similar to mod_perl -- it embeds Python within Apache and loads
-Python code into memory when the server starts. Code stays in memory throughout
-the life of an Apache process, which leads to significant performance gains
-over other server arrangements. Make sure you have Apache installed, with the
-mod_python module activated. Django requires Apache 2.x and mod_python 3.x.
+If you want to use Django on a production site, use the Apache_ web server
+with `mod_python`_.  mod_python is similar to mod_perl -- it embeds Python
+within Apache and loads Python code into memory when the server starts. Code
+stays in memory throughout the life of an Apache process, which leads to
+significant performance gains over other server arrangements.  Django
+requires Apache 2.x and mod_python 3.x.
 
-See `How to use Django with mod_python`_ for information on how to configure
-mod_python once you have it installed.
+Apache is available as source code for all major platforms.  If you are
+running Windows, you will probably be better off `downloading it in binary
+form`_ as an MSI package.  If you require SSL support, make sure that you
+download the 'openssl' version of the installer, not the 'no_ssl' version.
+The installer will prompt you to supply basic information such as domain,
+server name, administrator email address and port number (normally 80) as part
+of the installation procedure, and you will also be able to choose whether
+to run Apache as a service.
 
+mod_python should be installed after Apache.  It, too, can be compiled from
+source or downloaded as a Windows binary installer program.  If you do
+the latter, be sure to use the version of the installer that matches the
+versions of Python and Apache running on your system.  After installing, you
+will need to edit ``httpd.conf`` and activate mod_python by adding the
+following line to the file::
+
+  LoadModule python_module modules/mod_python.so
+
+If you can then get Apache to restart successfully, you will be ready to
+configure it for use with Django -- see `How to use Django with mod_python`_
+for further details.
+
 If you can't use mod_python for some reason, fear not: Django follows the WSGI_
 spec, which allows it to run on a variety of server platforms. See the
 `server-arrangements wiki page`_ for specific installation instructions for
 each platform.
 
+.. admonition:: What about Internet Information Server?
+
+   If you are a Windows user, you may be wondering whether it is possible
+   to run Django on Microsoft's own web server, IIS.  Considerable progress
+   has been made towards this goal, `summarized on the Django wiki`_, but
+   the current procedure is not trivial, and some issues remain unresolved.
+   If you have expertise in IIS and ISAPI extensions, your assistance in
+   dealing with these issues would be much appreciated!
+
 .. _Apache: http://httpd.apache.org/
 .. _mod_python: http://www.modpython.org/
+.. _downloading it in binary form: http://www.apache.org/dyn/closer.cgi/httpd/binaries/win32/
 .. _WSGI: http://www.python.org/peps/pep-0333.html
 .. _How to use Django with mod_python: ../modpython/
 .. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
+.. _summarized on the Django wiki: http://code.djangoproject.com/wiki/DjangoOnWindowsWithIISAndSQLServer
 
 Get your database running
 =========================
 
 If you plan to use Django's database API functionality, you'll need to
-make sure a database server is running. Django works with PostgreSQL_,
-MySQL_, Oracle_ and SQLite_ (although SQLite doesn't require a separate server
-to be running).
+make sure that a database is available. Django works with the PostgreSQL_,
+MySQL_ and Oracle_ database servers and with the SQLite_ embedded database.
+The latter is a good choice if you are just experimenting with Django.
 
-Additionally, you'll need to make sure your Python database bindings are
+Additionally, you'll need to make sure that your Python database bindings are
 installed.
 
 * If you're using PostgreSQL, you'll need the psycopg_ package. Django supports
   both version 1 and 2. (When you configure Django's database layer, specify
   either ``postgresql`` [for version 1] or ``postgresql_psycopg2`` [for version 2].)
 
-  If you're on Windows, check out the unofficial `compiled Windows version`_.
+  If you're on Windows, check out the unofficial `compiled Windows versions`_
+  and choose the one that matches your versions of Python and PostgreSQL.
 
 * If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher.
   You will also want to read the database-specific notes for the `MySQL backend`_.
 
-* If you're using SQLite, you'll need pysqlite_. Use version 2.0.3 or higher.
+* If you're using SQLite with Python 2.3 or 2.4, you'll need pysqlite_, version
+  2.0.3 or higher.  Python 2.5 comes with the necessary SQLite bindings as
+  standard.  If you are running Windows, note that the binary distributions
+  of pysqlite include SQLite itself, so using one of these will save you
+  some time.
 
 * If you're using Oracle, you'll need cx_Oracle_, version 4.3.1 or higher.
 
@@ -81 +119 @@
 .. _MySQL: http://www.mysql.com/
 .. _Django's ticket system: http://code.djangoproject.com/report/1
 .. _psycopg: http://initd.org/tracker/psycopg
-.. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/
+.. _compiled Windows versions: http://stickpeople.com/projects/python/win-psycopg/
 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
 .. _SQLite: http://www.sqlite.org/
 .. _pysqlite: http://initd.org/tracker/pysqlite
@@ -131 +169 @@
 Check the `distribution specific notes`_ to see if your
 platform/distribution provides official Django packages/installers.
 Distribution-provided packages will typically allow for automatic
-installation of dependancies and easy upgrade paths.
+installation of dependencies and easy upgrade paths.
 
 Installing an official release
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -151 +189 @@
        privileges and run the command ``setup.py install``.
 
 These commands will install Django in your Python installation's
-``site-packages`` directory.
+``site-packages`` directory -- see "Where are my ``site-packages`` stored?"
+above for information on how to locate this directory.
 
 .. _distribution specific notes: ../distributions/
 .. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
@@ -163 +202 @@
 If you'd like to be able to update your Django code occasionally with the
 latest bug fixes and improvements, follow these instructions:
 
-1. Make sure that you have Subversion_ installed, and that you can run its
-   commands from a shell. (Enter ``svn help`` at a shell prompt to test
-   this.)
+1. Make sure that you have Subversion_ installed.  You can download it
+   as source and compile it yourself, or use one of the unofficial binary
+   packages.  If you are running Windows, make sure that you download
+   the binary that matches your version of Apache (2.0 or 2.2), as this
+   will allow you to then run Apache as a Subversion server if you wish.
+   If you are a Windows user, you will probably also want to install
+   TortoiseSVN_, a Subversion client implemented as a Windows shell
+   extension.
 
-2. Check out Django's main development branch (the 'trunk') like so::
+   After installing, make sure that you can run Subversion commands
+   commands from a shell.  Enter ``svn help`` at a shell prompt to test
+   this.  If you are using TortoiseSVN on Windows, make sure that the
+   *TortoiseSVN* menu is visible in the *File* menu of Windows Explorer.
 
+2. Check out Django's main development branch (the 'trunk') from a
+   a command shell like so::
+
        svn co http://code.djangoproject.com/svn/django/trunk/ django-trunk
 
+   If you are using TortoiseSVN on Windows, go to the folder within which
+   you wish to check out the trunk, right-click to bring up the context
+   menu and select *TortoiseSVN*, followed by *Checkout..*.  In the
+   resulting dialog box, enter http://code.djangoproject.com/svn/django/trunk/
+   as the URL of the repository and the name of a new or empty folder as the
+   checkout directory.
+
 3. Next, make sure that the Python interpreter can load Django's code. There
    are various ways of accomplishing this.  One of the most convenient, on
-   Linux, Mac OSX or other Unix-like systems, is to use a symbolic link::
+   Linux, Mac OS X or other Unix-like systems, is to use a symbolic link::
 
        ln -s `pwd`/django-trunk/django SITE-PACKAGES-DIR/django
 
@@ -205 +262 @@
    any directory, rather than having to qualify the command with the full path
    to the file.
 
-You *don't* have to run ``python setup.py install``, because you've already
-carried out the equivalent actions in steps 3 and 4.
+You *don't* have to run ``python setup.py install`` here, because you've
+already carried out the equivalent actions in steps 3 and 4.
 
 When you want to update your copy of the Django source code, just run the
-command ``svn update`` from within the ``django-trunk`` directory. When you do
-this, Subversion will automatically download any changes.
+command ``svn update`` from within the ``django-trunk`` directory.  Or, if
+you are using TortoiseSVN on Windows, right-click on this directory and
+choose *TortoiseSVN*, followed by *Update*, from the Windows Explorer
+context menu.  When you do this, Subversion will automatically download any
+changes.
 
 .. _`download page`: http://www.djangoproject.com/download/
 .. _Subversion: http://subversion.tigris.org/
+.. _TortoiseSVN: http://tortoisesvn.tigris.org/
 .. _from the Control Panel: http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/sysdm_advancd_environmnt_addchange_variable.mspx