Documentation update (mainly for README.tracd) and a few formatting fixes so that the files conform fully to reStructuredText

cboos · cboos · commit e3d71c3483f8 · 2005-05-28T07:01:35.000Z
git-svn-id: http://trac.edgewall.org/intertrac/log:/trunk@1736 af82e41b-90c4-0310-8c96-b1721e28e2e2
diff --git a/AUTHORS b/AUTHORS
@@ -1,7 +1,10 @@
-Jonas Borgstr�m <jonas@edgewall.com>
-Daniel Lundin <daniel@edgewall.com>
-Rocky Burt <rocky@carterscove.com>
-Christopher Lenz <cmlenz@gmx.de>
-Francois Harvey <fharvey@securiweb.net>
+ * Jonas Borgstr�m <jonas@edgewall.com>
+ * Daniel Lundin <daniel@edgewall.com>
+ * Rocky Burt <rocky@carterscove.com>
+ * Christopher Lenz <cmlenz@gmx.de>
+ * Francois Harvey <fharvey@securiweb.net>
+ * Mark Rowe <trac@bdash.net.nz> 
+ * Matthew Good <trac@matt-good.net>
+ * Christian Boos <cboos@wanadoo.fr>
 
 See also THANKS for people who have contributed to the project.
diff --git a/INSTALL b/INSTALL
@@ -9,22 +9,26 @@ Requirements
 ------------
 To install Trac, the following software packages must be installed:
 
-  * Python, version >= 2.1.
-      + Please keep in mind, that for RPM-based systems you will also need
-        python-devel and python-xml packages.
-  * Subversion, version >= 1.0. (>=1.0.5 recommended)
-  * Subversion Python bindings.
-  * PySQLite, version >= 0.5.
-  * Clearsilver, version >= 0.9.3
-  * A CGI-capable web server (we QA-test on Apache2 )
+ * Python, version >= 2.2.
+   + Please keep in mind, that for RPM-based systems you will also need
+   python-devel and python-xml packages.
+ * Subversion, version >= 1.0. (1.1.4 recommended)
+ * Subversion Python bindings.
+ * PySQLite, version >= 0.5 (1.1.6 recommended)
+ * Clearsilver, version >= 0.9.3 (0.9.14 recommended)
+ * A CGI-capable web server (we QA-test on Apache2)
+
+Note that trac can also use run in standalone mode (see README.tracd)
+
 
 Installing Trac
 ---------------
-    $ python ./setup.py install
+
+  $ python ./setup.py install
 
 This will byte-compile the python source code and install it in the
 site-packages directory of your python installation. The directories cgi-bin,
-templates, htdocs and wiki-default are all copied to $prefix/share/trac/ .
+templates, htdocs and wiki-default are all copied to ``$prefix/share/trac/``.
 
 The script will also install the trac-admin command-line tool, used to create
 and maintain project environments. Trac-admin is the command center of Trac.
@@ -36,15 +40,15 @@ Advanced Users
 To install Trac in a different location, and other advanced installation
 options, run:
 
-    $ python ./setup.py --help
+  $ python ./setup.py --help
 
 Installing Trac on Windows
 --------------------------
 If you downloaded the Trac installer (the .exe file), installing is simply a
 matter of running the installer. 
 
  * NOTE: The windows installer also includes the Clearsilver DLL, so you do
-         _NOT_ have to install it manually when using the installer.
+   *NOT* have to install it manually when using the installer.
 
 After running the installer, configuration and installation is the same as
 for other platforms.
@@ -58,7 +62,7 @@ log-files and attachments.
 
 A new Trac environment is created with trac-admin:
 
-    $ trac-admin /path/to/projectenv initenv
+  $ trac-admin /path/to/projectenv initenv
 
 Note: The web server user need write permission to the environment directory
 and all the files inside.
@@ -68,38 +72,40 @@ it can find the trac templates directory (the default value should be fine).
 
 Configuring Apache
 ------------------
-Copy (or symlink) "trac/cgi-bin/trac.cgi" to you web servers /cgi-bin/
-directory. You can also configure apache to use the "trac/cgi-bin/" directory
+Copy (or symlink) ``trac/cgi-bin/trac.cgi`` to you web servers ``/cgi-bin/``
+directory. You can also configure apache to use the ``trac/cgi-bin/`` directory
 directly if you like, it's a matter of taste.
 
-Finally edit the apache config and add this config snippet, with filenams
+Finally edit the apache config and add this config snippet, with filenames
 edited to match your installation:
 
-Alias /trac/ "/usr/share/trac/htdocs/" #or where you installed the trac docs
-#You have to allow people to read the files in htdocs
-<Directory "/usr/share/trac/htdocs/">
-        Options Indexes MultiViews
-        AllowOverride None
-        Order allow,deny
-        Allow from all
-</Directory>
-
-
-# Trac need to know where the database is located
-<Location "/cgi-bin/trac.cgi">
-        SetEnv TRAC_ENV "/path/to/projectenv"
-</Location>
-
-# You need this to allow users to authenticate
-# trac.htpasswd can be created with 
-# cmd 'htpasswd -c trac.htpasswd' (UNIX)
-# do 'man htpasswd' to see all the options
-<Location "/cgi-bin/trac.cgi/login">
-        AuthType Basic
-        AuthName "trac"
-        AuthUserFile /somewhere/trac.htpasswd
-        Require valid-user
-</location>
+::
+  
+  Alias /trac/ "/usr/share/trac/htdocs/" #or where you installed the trac docs
+  #You have to allow people to read the files in htdocs
+  <Directory "/usr/share/trac/htdocs/">
+          Options Indexes MultiViews
+          AllowOverride None
+          Order allow,deny
+          Allow from all
+  </Directory>
+  
+  
+  # Trac need to know where the database is located
+  <Location "/cgi-bin/trac.cgi">
+          SetEnv TRAC_ENV "/path/to/projectenv"
+  </Location>
+  
+  # You need this to allow users to authenticate
+  # trac.htpasswd can be created with 
+  # cmd 'htpasswd -c trac.htpasswd' (UNIX)
+  # do 'man htpasswd' to see all the options
+  <Location "/cgi-bin/trac.cgi/login">
+          AuthType Basic
+          AuthName "trac"
+          AuthUserFile /somewhere/trac.htpasswd
+          Require valid-user
+  </location>
 
 Note: When creating a new environment, trac-admin will print a config snippet
 customized for your project.
@@ -108,7 +114,7 @@ Using Trac
 ----------
 You should now have a working Trac installation at:
 
-http://<yourhostname>/cgi-bin/trac.cgi
+  http://<yourhostname>/cgi-bin/trac.cgi
 
 There you should be able to browse your subversion repository, create tickets,
 view the timeline etc. Keep in mind that anonymous users (not logged in) can
diff --git a/README b/README
@@ -8,8 +8,8 @@ facilities.
 
 Trac is distributed using the GNU General Public License.
 
-**For installation instructions, please see the INSTALL. **
-**If you are upgrading from a previous Trac version, please read UPGRADE. **
+ * For installation instructions, please see the INSTALL. *
+ * If you are upgrading from a previous Trac version, please read UPGRADE. *
 
 You might also want to take a look at the RELEASE and ChangeLog files for more
 information.
diff --git a/README.tracd b/README.tracd
@@ -1,35 +1,47 @@
 Trac in stand-alone mode
 ========================
-Trac 0.7 introduces among many other important features, the capability to run
-Trac as a stand-alone server (daemon), without a web server.
 
-*** NOTE:  THIS IS STILL AN EXPERIMENTAL FEATURE ***
+Trac 0.7 introduced among many other important features, the capability to run
+Trac as a stand-alone server (daemon), without a web server.
 
-As of writing, tracd is still experimental, but we encourage testing it and
-providing feedback so we can improve it. Tracd supports all features of
-the CGI version (trac.cgi), and can serve multiple projects from a single
-server instance.
+Tracd supports all features of the CGI version (trac.cgi), 
+and can serve multiple projects from a single server instance.
 
 Running tracd
 -------------
-tracd [options] <database> [database] ...
-Options:
 
-    -a --auth [project],[htdigest_file],[realm]
-    -p --port [port]\t\tPort number to use (default: 80)
-    -b --hostname [hostname]\tIP to bind to (default: '')
+  tracd [options] <database> [database] ...
+
+  Options:
+
+-a, --auth <project,htdigest_file,realm>    Per-project authentication information
+-p, --port <port>                           Port number to use (default: 80)
+-b, --hostname <hostname>                   IP to bind to (default: '')
 
 
-Example:
+Example 1: Single Project (non-authenticated)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
   $ tracd -p 9090 /var/trac/myproject
 
+Example 2: Multiple Projects (authenticated)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  $ tracd -p 9090 \
+     -a projectA,/var/trac/htdigest.ALPHA,ALPHA  \
+     -a projectB,/var/trac/htdigest.ALPHA,ALPHA  \
+     /var/trac/projectA \
+     /var/trac/projectB
+
+The file ``htdigest.ALPHA`` can be generated using the Apache2 tool ``htdigest``
+(be carefull *NOT* to use ``htpasswd`` here).
 
 Feedback and bug reports
 ------------------------
+
 Please provide feedback on tracd using the issue tracker or the mailing list.
 
- Submit a bug report:  http://projects.edgewall.com/trac/newticket/
+ Submit a bug report:  http://projects.edgewall.com/trac/newticket?component=tracd
    Mailing list info:  http://projects.edgewall.com/trac/wiki/MailingList
 
 
diff --git a/THANKS b/THANKS
@@ -1,56 +1,59 @@
-Brad Anderson           brad@dsource.org
-Christopher Armstrong   radix
-Jani Averbach           jaa@jaa.iki.fi
-Juanma Barranquero      lektu@terra.es
-Christian Boos          cboos@bct-technology.com
-Rocky Burt              rocky.burt@myrealbox.com
-Toni Brkic              toni.brkic@switchcore.com
-Wesley Crucius          wcrucius@sandc.com
-Daragh Fitzpatrick      Daragh@i2i-Tech.com
-dju'
-Felix Colins            felix@keyghost.com
-Eric Gillespie          epg@netbsd.org
-Matthew Good            trac@matt-good.net
-Shun-ichi Goto          gotoh@taiyo.co.jp
-Mikael Hallendal        micke@imendio.com
-Stephen Hansen          shansen@advpubtech.com
-Laurie Harper           zodiac@holoweb.net
-Francois Harvey         fharvey@securiweb.net
-Michael Hope            michael.hope@hamjet.co.nz
-Richard Hult            richard@imendio.com
-Nuutti Kotivuori        naked@iki.fi
-Ian Leader              ian.leader@line.co.uk
-Christopher Lenz        cmlenz@gmx.de
-Ivo Looser              ivo.looser@login.ch
-Angel Marin             anmar@gmx.net
-James Moger             jamesm@transonic.com
-Tim Moloney             moloney@mrsl.com
-Jennifer Murtell        jen@jmurtell.com
-Jacob Norda             jacobnorda@gmail.com
-Juracy Filho            juracy@gmail.com
-Cap Petschulat          cap@cdres.com
-Nicholas Riley          sabi
-Manuzhai                manuzhai@gmail.com
-Mark Rowe               mrowe@bluewire.net.nz
-Olliver Rutherfurd      ollie
-pkou                    pkou@ua.fm
-Michael Scherer         misc@mandrake.org
-Andreas Schrattenecker  vittorio
-Emmeran Seehuber        rototor@rototor.de
-Noah Slater             nslater@gmail.com
-Bill Soudan             bill@soudan.net
-Ludvig Strigeus
-Alec Thomas             alec@swapoff.org
-Zilvinas Valinskas      zilvinas@gemtek.lt
-Jason Vasquez           jason@mugfu.com
-Dmitry Yusupov          dmitry_yus@yahoo.com
+ * Brad Anderson           brad@dsource.org
+ * Christopher Armstrong   radix
+ * Jani Averbach           jaa@jaa.iki.fi
+ * Juanma Barranquero      lektu@terra.es
+ * Christian Boos          cboos@bct-technology.com
+ * Rocky Burt              rocky.burt@myrealbox.com
+ * Toni Brkic              toni.brkic@switchcore.com
+ * Wesley Crucius          wcrucius@sandc.com
+ * Daragh Fitzpatrick      Daragh@i2i-Tech.com
+ * dju'
+ * Felix Colins            felix@keyghost.com
+ * Eric Gillespie          epg@netbsd.org
+ * Matthew Good            trac@matt-good.net
+ * Shun-ichi Goto          gotoh@taiyo.co.jp
+ * Mikael Hallendal        micke@imendio.com
+ * Stephen Hansen          shansen@advpubtech.com
+ * Laurie Harper           zodiac@holoweb.net
+ * Francois Harvey         fharvey@securiweb.net
+ * Michael Hope            michael.hope@hamjet.co.nz
+ * Richard Hult            richard@imendio.com
+ * Nuutti Kotivuori        naked@iki.fi
+ * Ian Leader              ian.leader@line.co.uk
+ * Christopher Lenz        cmlenz@gmx.de
+ * Ivo Looser              ivo.looser@login.ch
+ * Angel Marin             anmar@gmx.net
+ * James Moger             jamesm@transonic.com
+ * Tim Moloney             moloney@mrsl.com
+ * Jennifer Murtell        jen@jmurtell.com
+ * Jacob Norda             jacobnorda@gmail.com
+ * Juracy Filho            juracy@gmail.com
+ * Cap Petschulat          cap@cdres.com
+ * Nicholas Riley          sabi
+ * Manuzhai                manuzhai@gmail.com
+ * Mark Rowe               mrowe@bluewire.net.nz
+ * Olliver Rutherfurd      ollie
+ * pkou                    pkou@ua.fm
+ * Michael Scherer         misc@mandrake.org
+ * Andreas Schrattenecker  vittorio
+ * Emmeran Seehuber        rototor@rototor.de
+ * Noah Slater             nslater@gmail.com
+ * Bill Soudan             bill@soudan.net
+ * Ludvig Strigeus
+ * Alec Thomas             alec@swapoff.org
+ * Zilvinas Valinskas      zilvinas@gemtek.lt
+ * Jason Vasquez           jason@mugfu.com
+ * Dmitry Yusupov          dmitry_yus@yahoo.com
 
 The ever so elusive Anonymous.
 
-Diggs and Lula (official pawprint contributors)
+`Diggs and Lula`_ (official pawprint contributors)
 
 And everyone who keeps sending feedback, helping us improve Trac.
 
--- 
+----
+
 Our apologies to everyone we forgot to mention, but without whose invaluable
 help, Trac would not continue to rapidly evolve.
+
+.. _Diggs and Lula: http://people.edgewall.com/~daniel/lula_diggs.jpg
