Anonymous avatar Anonymous committed 675ed4c

* Update/cleanup `INSTALL` file
* Remove stale Docbook version of the TracGuide

Comments (0)

Files changed (13)

 Trac Installation Guide
 =======================
-The Trac web-based project management tool is implemented as a server side
-cgi-program. Trac is written in the Python programming language and uses SQLite
-as an embedded database. For HTML rendering, Trac uses the Clearsilver template
-system.
+Trac is a lightweight project management tool that is implemented as a
+web-based application. Trac is written in the Python programming language and
+can use SQLite or PostgreSQL as  database. For HTML rendering, Trac uses the
+Clearsilver templating system.
+
 
 Requirements
 ------------
 To install Trac, the following software packages must be installed:
 
- * Python, version >= 2.2.
+ * Python, version >= 2.3.
    + 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, version >= 1.0. (>= 1.1.x 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)
+ * A web server capable of executing CGI/FastCGI scripts, or Apache HTTPD with
+   mod_python. (Trac also comes with a standalone server, but its use is not
+   recommended for use in a production environment.)
 
 
 Installing Trac
 ---------------
+The command:
 
   $ python ./setup.py install
 
-This will byte-compile the python source code and install it in the
+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/``.
 
 
 Note: you'll need root permissions or equivalent for this step.
 
-Advanced Users
---------------
-To install Trac in a different location, and other advanced installation
+To install Trac in a different location, or use other advanced installation
 options, run:
 
   $ 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. 
+matter of running the installer.  After running the installer, configuration
+and installation is the same as for other platforms.
 
- * NOTE: The windows installer also includes the Clearsilver DLL, so you do
-   *NOT* have to install it manually when using the installer.
-
-After running the installer, configuration and installation is the same as
-for other platforms.
 
 Creating a Project Environment
 ------------------------------
-Trac Environment is the backend storage format where Trac stores information
-like wiki pages, tickets, reports, settings, etc. A Trac environment consist of
-a directory containing an SQLite database, human-readable configuration file,
-log-files and attachments.
+A Trac environment is the backend storage format where Trac stores information
+like wiki pages, tickets, reports, settings, etc. A Trac environment consists
+of the environment configuration file (trac.ini), custom templates, log files,
+and more.
 
 A new Trac environment is created with trac-admin:
 
   $ trac-admin /path/to/projectenv initenv
 
-Note: The web server user need write permission to the environment directory
-and all the files inside.
+Note: The user account under which the web server is run needs write permission
+to the environment directory and all the files inside.
 
-trac-admin will ask you where your subversion repository is located and where
-it can find the trac templates directory (the default value should be fine).
+trac-admin will prompt you for the name of the project, where your subversion
+repository is located, what database you want to use, etc.
 
-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
-directly if you like, it's a matter of taste.
 
-Finally edit the apache config and add this config snippet, with filenames
-edited to match your installation:
+Running the Standalone Server
+-----------------------------
+After having created a Trac environment, you can easily try the web interface
+by running the standalone server tracd:
 
-::
-  
-  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>
+  $ tracd --port 8000 /path/to/projectenv
 
-Note: When creating a new environment, trac-admin will print a config snippet
-customized for your project.
+Then, fire up a browser and visit http://localhost:8000/. You should get a
+simple listing of all environments that tracd knows about. Follow the link
+to the environment you just created, and you should see Trac in action.
+
+
+Running Trac on a Web Server
+----------------------------
+Trac provides three options for connecting to a "real" web server: CGI, FastCGI
+and mod_python. For decent performance, it is recommended that you use either
+FastCGI or mod_python.
+
+Please refer to the TracInstall page for details on these setups. You can find
+it either in the wiki of the Trac project you just created, or on the main Trac
+site.
+
 
 Using Trac
 ----------
-You should now have a working Trac installation at:
+Once you have your Trac site up and running, you should be able to browse your
+subversion repository, create tickets, view the timeline, etc.
 
-  http://<yourhostname>/cgi-bin/trac.cgi
+Keep in mind that anonymous (not logged in) users can by default access most
+but not all of the features. You will need to configure authentication and
+grant additional permissions to authenticated users to see the full set of
+features.
 
-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
-only access a restricted subset of all Trac features.
-
-Please continue to TracPermissions to learn how to grant additional privileges
-to authenticated users.
-
-For further user-documentation, see TracGuide.
+For further documentation, see the TracGuide wiki page.
 
 Enjoy!
 

doc/trac-guide/Makefile

-DOCFILE_BASE_DEFAULT:=trac-guide
-DOCFILE_EXT_DEFAULT:=xml
-
-SVNVERSION = svnversion
-BOOK_VERSION_SOURCE =  version.xml
-
-# Standard docfile processing as copied from UFFI
-# Placed into public domain by author Kevin Rosenberg
-
-ifndef DOCFILE_BASE
-DOCFILE_BASE=${DOCFILE_BASE_DEFAULT}
-endif
-
-ifndef DOCFILE_EXT
-DOCFILE_EXT=${DOCFILE_EXT_DEFAULT}
-endif
-
-DOCFILE:=${DOCFILE_BASE}.${DOCFILE_EXT}
-FOFILE:=${DOCFILE_BASE}.fo
-PDFFILE:=${DOCFILE_BASE}.pdf
-PSFILE:=${DOCFILE_BASE}.ps
-DVIFILE:=${DOCFILE_BASE}.dvi
-TXTFILE:=${DOCFILE_BASE}.txt
-HTMLFILE:=${DOCFILE_BASE}.html
-TMPFILES:=${DOCFILE_BASE}.aux ${DOCFILE_BASE}.out ${DOCFILE_BASE}.log
-DOCFILES:=$(shell echo *.xml *.xsl)
-
-ifeq ($(XSLTPROC),)
-  XSLTPROC:=xsltproc
-endif
-
-CATALOG:=`pwd`/catalog-debian.xml
-CHECK:=XML_CATALOG_FILES="$(CATALOG)" xmllint --noout --xinclude --postvalid $(DOCFILE) || exit 1
-
-.PHONY: all
-all: html 
-
-.PHONY: dist
-dist: html pdf
-
-.PHONY: doc
-doc: html pdf
-
-.PHONY: check
-check:
-	@$(CHECK)
-
-.PHONY: html_chunked
-html_chunked: html-stamp
-
-html-stamp: $(DOCFILES) Makefile 
-	@rm -rf html
-	@mkdir html
-	@XML_CATALOG_FILES="$(CATALOG)" $(XSLTPROC) --stringparam chunker.output.encoding ISO-8859-1 \
-		 --xinclude --output html/ html_chunk.xsl $(DOCFILE)
-	touch html-stamp
-
-.PHONY: html
-html: ${HTMLFILE}
-
-${HTMLFILE}: $(DOCFILES) Makefile 
-	@XML_CATALOG_FILES="$(CATALOG)" $(XSLTPROC) \
-		 --xinclude --output ${HTMLFILE} html.xsl $(DOCFILE)
-
-.PHONY: fo
-fo: ${FOFILE}
-
-${FOFILE}: $(DOCFILES) Makefile 
-	@XML_CATALOG_FILES="$(CATALOG)" $(XSLTPROC) --xinclude --output $(FOFILE) fo.xsl $(DOCFILE)
-
-.PHONY: pdf
-pdf: ${PDFFILE}
-
-${PDFFILE}: ${DOCFILES} Makefile
-	@$(MAKE) fo
-	@fop $(FOFILE) -pdf $(PDFFILE) > /dev/null
-
-.PHONY: dvi
-dvi: ${DVIFILE}
-
-.PHONY: ps
-ps: ${PSFILE}
-
-${PSFILE}: ${DOCFILES} Makefile
-	@$(MAKE) fo
-	@fop $(FOFILE) -ps $(PSFILE) > /dev/null
-
-
-.PHONY: txt
-txt: ${TXTFILE}
-
-${TXTFILE}: ${HTMLFILE}
-	@XML_CATALOG_FILES="$(CATALOG)" $(XSLTPROC) --xinclude --output ${HTMLFILE} html.xsl $(DOCFILE)
-	w3m -dump ${HTMLFILE} > ${TXTFILE}
-
-.PHONY: clean
-clean: 
-	@rm -f *~ *.bak *.orig \#*\# .\#* texput.log
-	@rm -rf html $(PSFILE) $(HTMLFILE) $(PDFFILE) html-stamp
-	@rm -f $(TMPFILES) $(FOFILE)
-	@rm -f  $(DVIFILE) $(TXTFILE)
-
-.PHONY: distclean
-distclean: clean
-
-$(BOOK_VERSION_SOURCE): book-version
-
-book-version:
-	@if $(SVNVERSION) . > /dev/null; then \
-	echo '<!ENTITY svn.version "Draft Revision '`$(SVNVERSION) .`'">' > $(BOOK_VERSION_SOURCE).tmp; \
-	else \
-	echo '<!ENTITY svn.version "Draft">' > $(BOOK_VERSION_SOURCE).tmp; \
-	fi
-	@if cmp -s $(BOOK_VERSION_SOURCE) $(BOOK_VERSION_SOURCE).tmp; then \
-	rm $(BOOK_VERSION_SOURCE).tmp; \
-	else \
-	mv $(BOOK_VERSION_SOURCE).tmp $(BOOK_VERSION_SOURCE); \
-	fi

doc/trac-guide/admin.xml

-<chapter id="tg-admin">
-
-  <title>Administration</title>
-
-  <simplesect>
-    <para>
-    </para>
-  </simplesect>
-
-
-  <sect1 id="tg-admin-sect-1">
-    <title>Introduction</title>
-    <para>
-    </para>
-  </sect1>
-
-  <sect1 id="tg-admin-sect-2">
-    <title>Configuration</title>
-    <para>
-    </para>
-  </sect1>
-
-</chapter>

doc/trac-guide/catalog-debian.xml

-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE catalog
-   PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
-   "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
-
-<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
-
-  <!-- The directory DTD and stylesheet files are installed under -->
-  <group  xml:base="file:///usr/share/sgml/docbook/" >
-
-    <!-- Resolve DTD URL system ID to local file -->
-    <rewriteSystem
-        systemIdStartString="http://www.oasis-open.org/docbook/xml/4.1/"
-        rewritePrefix="dtd/xml/4.1/" />
-    <!-- Resolve stylesheet URL to local file -->
-    <rewriteURI
-        uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
-        rewritePrefix="stylesheet/xsl/nwalsh/" />
-
-    <!-- Resolve DTD PUBLIC identifiers -->
-    <nextCatalog  catalog="dtd/xml/4.1/catalog.xml" />
-
-    <!-- To resolve simple DTD SYSTEM identifiers. -->
-    <!-- Note: this does not work with Java resolver -->
-    <!--   classes in Saxon or Xalan -->
-    <system
-         systemId="docbook.dtd"
-         uri="dtd/xml/4.1/xml/docbookx.dtd" />
-
-    <!-- To resolve short stylesheet references -->
-    <uri
-        name="docbook_html.xsl"
-        uri="stylesheet/xsl/nwalsh/xhtml/docbook.xsl" />
-    <uri 
-        name="docbook_chunk.xsl"
-        uri="stylesheet/xsl/nwalsh/xhtml/chunk.xsl" />
-    <uri
-        name="docbook_fo.xsl"
-        uri="stylesheet/xsl/nwalsh/fo/docbook.xsl" />
-
-  </group>
-
-</catalog>

doc/trac-guide/fo.xsl

-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0">
-
-<xsl:import href="docbook_fo.xsl"/>
-<xsl:param name="fop.extensions" select="1"/>
-</xsl:stylesheet>
-

doc/trac-guide/html.xsl

-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0">
-
-<xsl:import href="docbook_html.xsl"/>
-<xsl:param name="use.id.as.filename" select="1"/>
-<xsl:output encoding="ISO-8859-1" method="html" />
-
-</xsl:stylesheet>
-

doc/trac-guide/html_chunk.xsl

-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0">
-
-<xsl:import href="docbook_chunk.xsl"/>
-<xsl:param name="use.id.as.filename" select="1"/>
-
-</xsl:stylesheet>
-

doc/trac-guide/install.xml

-<chapter id="tg-install">
- <title>Installation</title>
-
-  <simplesect>
-    <para>How to install Trac.
-    </para>
-  </simplesect>
-
-
-  <sect1 id="tg-install-sect-1">
-    <title>Getting Trac</title>
-    <para>Where to get it ...
-    </para>
-
-   <sect2>
-    <title>Download using FTP or HTTP</title>
-   </sect2>
-
-   <sect2>
-    <title>Development Releases</title>
-   </sect2>
-
-   <sect2>
-    <title>Physical Media</title>
-    <para>Trac is mainly and foremost distributed over the internet through
-      HTTP, FTP and Subversion protocols.</para>
-
-    <para>However, if you cannot access the regular distribution using the
-      internet,  please contact Edgewall directly for options to receive Trac
-      source code , documentation and related software on CDROM, Floppy or
-      some other media.</para>
-   </sect2>
-
-  </sect1>
-
-  <sect1 id="tg-install-sect-2">
-    <title>Apache Configuration</title>
-    <para>
-    </para>
-  </sect1>
-
-  <sect1 id="tg-install-sect-3">
-    <title>Creating Your First Database</title>
-    <para>
-    </para>
-  </sect1>
-
-</chapter>

doc/trac-guide/intro.xml

-<chapter id="tg-intro">
-
-  <title>Introduction</title>
-
-  <simplesect>
-    <para>
-    </para>
-  </simplesect>
-
-
-  <sect1 id="tg-intro-sect-1">
-
-    <title>What is Trac?</title>
-
-    <para>
-    </para>
-
-  </sect1>
-
-  <sect1 id="tg-intro-sect-2">
-
-    <title>The History and Origins of Trac</title>
-    <para>Where Jonas and Daniel came from, CodeFactory through to
-      Edgewall. Keep it short.</para>
-
-    <para>CVSTrac heritage, differences in goals, python vs c, modularity
-      etc etc</para>
-
-  </sect1>
-
-
-
-
-</chapter>

doc/trac-guide/preface.xml

-<preface id="tg-pre">
-  <title>Preface</title>
-  <simplesect>
-    <para>
-      A gentle introduction
-    </para>
-  </simplesect>
-
- <sect1 id="tg-pre-sect-1">
-    <title>Purpose of This Book</title>
-    <para>
-    </para>
-  </sect1>
-
- <sect1 id="tg-pre-sect-2">
-    <title>Edgewall Software</title>
-    <para>
-     The short descr of Edgewall.
-    </para>
-  </sect1>
-
- <sect1 id="tg-pre-sect-3">
-    <title>Acknowledgments</title>
-    <para>
-    </para>
-  </sect1>
-
-</preface>

doc/trac-guide/trac-guide.xml

-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBookk XML V4.2//EN"
-"/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd"
-[
-<!ENTITY % vers   SYSTEM "version.xml">
-%vers;
-<!ENTITY preface     SYSTEM "preface.xml">
-<!ENTITY intro       SYSTEM "intro.xml">
-<!ENTITY install     SYSTEM "install.xml">
-<!ENTITY admin     SYSTEM "admin.xml">
-<!ENTITY user     SYSTEM "user.xml">
-]>
-
-<book id="tracguide">
-  <title>The Trac Guide</title>
-  <subtitle>&svn.version;</subtitle>
-
-  <bookinfo>
-    <edition>Draft</edition>
-    <authorgroup>
-      
-      <author>
-        <firstname>Daniel</firstname>
-        <surname>Lundin</surname>
-        <email>daniel@edgewall.com</email>
-      </author>
-
-      <author>
-        <firstname>Jonas</firstname>
-        <surname>Borgstr�m</surname>
-        <email>jonas@edgewall.com</email>
-      </author>
-
-    </authorgroup>
-
-    <editor>
-      <firstname>Jennifer</firstname>
-      <surname>Murtell</surname>
-      <email>jen@edgewall.com</email>
-    </editor>
-
-    <date>2004/01/11</date>
-    <copyright>
-      <year>2004</year>
-      <holder>Edgewall HB</holder>
-    </copyright>
-    <copyright>
-      <year>2004</year>
-      <holder>Daniel Lundin</holder>
-    </copyright>
-    <copyright>
-      <year>2004</year>
-      <holder>Jonas Borgstr�m</holder>
-    </copyright>
-
-    <legalnotice>
-      <simpara>
-      (Some license)
-      </simpara>
-    </legalnotice>
-  </bookinfo>
-
-  <!-- External entities -->
-
-  &preface;
-  &intro;
-  &install;
-  &admin;
-  &user;
-
-</book>
-

doc/trac-guide/trac-manual.xml

-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBookk XML V4.2//EN"
-"/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd"
-[
-<!ENTITY % vers   SYSTEM "version.xml">
-%vers;
-]>
-
-<book id="tracguide">
-  <title>The Trac Guide</title>
-  <subtitle>&svn.version;</subtitle>
-
-  <bookinfo>
-    <edition>Draft</edition>
-    <authorgroup>
-
-      <author>
-        <firstname>Daniel</firstname>
-        <surname>Lundin</surname>
-        <email>daniel@edgewall.com</email>
-      </author>
-
-      <author>
-        <firstname>Jonas</firstname>
-        <surname>Borgstr�m</surname>
-        <email>jonas@edgewall.com</email>
-      </author>
-
-    </authorgroup>
-
-    <editor>
-      <firstname>Jennifer</firstname>
-      <surname>Murtell</surname>
-      <email>jen@edgewall.com</email>
-    </editor>
-
-    <date>2004/01/11</date>
-    <copyright>
-      <year>2004</year>
-      <holder>Edgewall HB</holder>
-    </copyright>
-    <copyright>
-      <year>2004</year>
-      <holder>Daniel Lundin</holder>
-    </copyright>
-    <copyright>
-      <year>2004</year>
-      <holder>Jonas Borgstr�m</holder>
-    </copyright>
-
-    <legalnotice>
-      <simpara>
-      (Some license)
-      </simpara>
-    </legalnotice>
-  </bookinfo>
-
-</book>
-

doc/trac-guide/user.xml

-<chapter id="tg-user">
-  <title>User Guide</title>
-
-  <simplesect>
-    <para>
-    </para>
-  </simplesect>
-
-
-  <sect1 id="tg-user-sect-1">
-    <title>Basic Concepts</title>
-    <para>
-    </para>
-  </sect1>
-
-  <sect1>
-    <title>Modules</title>
-    <para></para>
-
-    <sect2 id="tg-user-sect-1-2">
-      <title>Bug/Issue Tracking Database</title>
-      <para> </para>
-    </sect2>
-
-    <sect2 id="tg-user-sect-1-3">
-      <title>Wiki</title>
-      <para> </para>
-    </sect2>
-
-    <sect2 id="tg-user-sect-1-4">
-      <title>Timeline</title>
-      <para> </para>
-    </sect2>
-
-    <sect2 id="tg-user-sect-1-4">
-      <title>Reports</title>
-      <para> </para>
-    </sect2>
-  </sect1>
-
-</chapter>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.