# wiki

name: TracGuide
author: trac
ipnr: 127.0.0.1
text:
  = The Trac User and Administration Guide =
  [[TracGuideToc]]
  {{{#!span style="font-size:90%"
  //The TracGuide is meant to serve as a starting point for all documentation regarding Trac usage and development. The guide is a free document, a collaborative effort, and a part of the [http://trac.edgewall.org Trac Project] itself.//
  }}}

  == Introduction

  Trac is an enhanced wiki and issue tracking system for software development projects. Trac uses a minimalistic approach to web-based software project management. It strives to help developers write great software while staying out of the way. Trac should impose as little as possible on a team's established development process and policies.

  It provides an interface to Subversion (and other version control systems), an integrated Wiki and convenient reporting facilities.

  Trac allows wiki markup in issue descriptions and commit messages, creating links and seamless references between bugs, tasks, changesets, files and wiki pages. A timeline shows all current and past project events in order, making the acquisition of an overview of the project and tracking progress very easy. The roadmap shows the road ahead, listing the upcoming milestones.
  == User Guide
     * Using the Wiki subsystem
       * TracWiki — How to use the built-in Wiki.
       * WikiFormatting — Reference to the wiki syntax used throughout.
     * Using the Version Control subsystem
       * TracBrowser — Browsing source code with Trac.
       * TracChangeset — Viewing changes to source code.
       * TracRevisionLog — Viewing change history.
     * Using the Ticket subsystem
       * TracTickets — Using the issue tracker.
       * TracRoadmap — The roadmap helps tracking project progress.
       * TracReports — Writing and using reports.
       * TracQuery — Executing custom ticket queries.
       * TracBatchModify - Modifying a batch of tickets in one request.
     * Other modules and general topics
       * TracSearch — Full text search in all content.
       * TracTimeline — The timeline provides a historic perspective on a project.
       * TracRss — RSS content syndication in Trac.
       * TracAccessibility — Accessibility keys support


  == Administrator Guide
     * Installation and upgrade
       * TracInstall — How to install and run Trac.
       * TracUpgrade — How to upgrade existing installations.
       * TracImport — Importing tickets from other bug databases.
       * TracPlugins — Installing and managing Trac extensions.
     * Configuration and customization
       * TracIni — Trac configuration file reference. 
       * TracPermissions — Access control and permissions.
       * TracNavigation — Customize main navigation menus.
       * TracInterfaceCustomization — Customizing the Trac interface.
       * TracLogging — The Trac logging facility.
     * Administering the Version Control subsystem
       * TracRepositoryAdmin — Management of Source Code Repositories.
     * Administering the Ticket subsystem
       * TracTicketsCustomFields — Expanding tickets with customized fields.
       * TracNotification — Email notification.
       * TracWorkflow — Configurable Ticket Workflow.
     * Reference
       * TracEnvironment — All you need to know about Trac environments
       * TracAdmin — Administering a Trac project via the command-line.

  == Support and Other Sources of Information ==

   * [trac:TracFaq Trac FAQ] — A collection of Frequently Asked Questions (on the project website).
   * [trac:TracDev] and [trac:TracDev/ApiDocs API docs] — Trac Developer documentation
   * TracSupport — How to get more information

  If you are looking for a good place to ask a question about Trac, look no further than the [http://trac.edgewall.org/wiki/MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers.


name: TracModPython
author: trac
ipnr: 127.0.0.1
text:
  = Trac and mod_python =
  [[TracGuideToc]]

  Trac supports [http://www.modpython.org/ mod_python], which speeds up Trac's response times considerably, especially compared to [TracCgi CGI], and permits use of many Apache features not possible with [wiki:TracStandalone tracd]/mod_proxy.

  {{{#!div class="important"
  ** A Word of Warning **

  As of 16^th^ June 2010, the mod_python project is officially dead.  If you are considering using mod_python for a new installation, '''please don't'''!  There are known issues which will not be fixed and there are now better alternatives.  Check out the main TracInstall pages for your target version for more information.
  }}}


  These instructions are for Apache 2; if you are still using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7], but you'll be totally on your own.

  [[PageOutline(2-3,Overview,inline)]]

  == Simple configuration: single project == #Simpleconfiguration

  If you just installed mod_python, you may have to add a line to load the module in the Apache configuration:
  {{{
  LoadModule python_module modules/mod_python.so
  }}}

  ''Note: The exact path to the module depends on how the HTTPD installation is laid out.''

  On Debian using apt-get
  {{{
  apt-get install libapache2-mod-python libapache2-mod-python-doc
  }}}
  (Still on Debian) after you have installed mod_python, you must enable the modules in apache2 (equivalent of the above Load Module directive):
  {{{
  a2enmod python
  }}}
  On Fedora use, using yum:
  {{{
  yum install mod_python
  }}}
  You can test your mod_python installation by adding the following to your httpd.conf.  You should remove this when you are done testing for security reasons. Note: mod_python.testhandler is only available in mod_python 3.2+.
  {{{
  #!xml
  <Location /mpinfo>
     SetHandler mod_python
     PythonInterpreter main_interpreter
     PythonHandler mod_python.testhandler
     Order allow,deny
     Allow from all
  </Location>
  }}}

  A simple setup of Trac on mod_python looks like this:
  {{{
  #!xml
  <Location /projects/myproject>
     SetHandler mod_python
     PythonInterpreter main_interpreter
     PythonHandler trac.web.modpython_frontend 
     PythonOption TracEnv /var/trac/myproject
     PythonOption TracUriRoot /projects/myproject
     Order allow,deny
     Allow from all
  </Location>
  }}}

  The option '''`TracUriRoot`''' may or may not be necessary in your setup. Try your configuration without it; if the URLs produced by Trac look wrong, if Trac does not seem to recognize URLs correctly, or you get an odd "No handler matched request to..." error, add the '''`TracUriRoot`''' option.  You will notice that the `Location` and '''`TracUriRoot`''' have the same path.

  The options available are
  {{{
      # For a single project
      PythonOption TracEnv /var/trac/myproject

      # For multiple projects
      PythonOption TracEnvParentDir /var/trac/myprojects

      # For the index of multiple projects
      PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html

      # A space delimitted list, with a "," between key and value pairs.
      PythonOption TracTemplateVars key1,val1 key2,val2

      # Useful to get the date in the wanted order
      PythonOption TracLocale en_GB.UTF8

      # See description above        
      PythonOption TracUriRoot /projects/myproject
  }}}

  === Python Egg Cache ===

  Compressed python eggs like Genshi are normally extracted into a directory named `.python-eggs` in the users home directory. Since apache's home usually is not writable an alternate egg cache directory can be specified like this:
  {{{
  PythonOption PYTHON_EGG_CACHE /var/trac/myprojects/egg-cache
  }}}

  or you can uncompress the Genshi egg to resolve problems extracting from it.

  === Configuring Authentication ===

  See corresponding section in the [wiki:TracModWSGI#ConfiguringAuthentication] page.


  == Advanced Configuration

  === Setting the Python Egg Cache ===

  If the Egg Cache isn't writeable by your Web server, you'll either have to change the permissions, or point Python to a location where Apache can write. This can manifest itself as a ''500 internal server error'' and/or a complaint in the syslog. 

  {{{
  #!xml
  <Location /projects/myproject>
    ...
    PythonOption PYTHON_EGG_CACHE /tmp 
    ...
  </Location>
  }}}


  === Setting the !PythonPath ===

  If the Trac installation isn't installed in your Python path, you'll have to tell Apache where to find the Trac mod_python handler  using the `PythonPath` directive:
  {{{
  #!xml
  <Location /projects/myproject>
    ...
    PythonPath "sys.path + ['/path/to/trac']"
    ...
  </Location>
  }}}

  Be careful about using the !PythonPath directive, and ''not'' `SetEnv PYTHONPATH`, as the latter won't work.

  === Setting up multiple projects ===

  The Trac mod_python handler supports a configuration option similar to Subversion's `SvnParentPath`, called `TracEnvParentDir`:
  {{{
  #!xml
  <Location /projects>
    SetHandler mod_python
    PythonInterpreter main_interpreter
    PythonHandler trac.web.modpython_frontend 
    PythonOption TracEnvParentDir /var/trac
    PythonOption TracUriRoot /projects
  </Location>
  }}}

  When you request the `/projects` URL, you will get a listing of all subdirectories of the directory you set as `TracEnvParentDir` that look like Trac environment directories. Selecting any project in the list will bring you to the corresponding Trac environment.

  If you don't want to have the subdirectory listing as your projects home page you can use a
  {{{
  #!xml
  <LocationMatch "/.+/">
  }}}

  This will instruct Apache to use mod_python for all locations different from root while having the possibility of placing a custom home page for root in your !DocumentRoot folder.

  You can also use the same authentication realm for all of the projects using a `<LocationMatch>` directive:
  {{{
  #!xml
  <LocationMatch "/projects/[^/]+/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /var/trac/.htpasswd
    Require valid-user
  </LocationMatch>
  }}}

  === Virtual Host Configuration ===

  Below is the sample configuration required to set up your trac as a virtual server (i.e. when you access it at the URLs like
  !http://trac.mycompany.com):

  {{{
  #!xml
  <VirtualHost * >
      DocumentRoot /var/www/myproject
      ServerName trac.mycompany.com
      <Location />
          SetHandler mod_python
          PythonInterpreter main_interpreter
          PythonHandler trac.web.modpython_frontend
          PythonOption TracEnv /var/trac/myproject
          PythonOption TracUriRoot /
      </Location>
      <Location /login>
          AuthType Basic
          AuthName "MyCompany Trac Server"
          AuthUserFile /var/trac/myproject/.htpasswd
          Require valid-user
      </Location>
  </VirtualHost>
  }}}

  This does not seem to work in all cases. What you can do if it does not:
   * Try using `<LocationMatch>` instead of `<Location>`
   * <Location /> may, in your server setup, refer to the complete host instead of simple the root of the server. This means that everything (including the login directory referenced below) will be sent to python and authentication does not work (i.e. you get the infamous Authentication information missing error). If this applies to you, try using a sub-directory for trac instead of the root (i.e. /web/ and /web/login instead of / and /login).
   * Depending on apache's `NameVirtualHost` configuration, you may need to use `<VirtualHost *:80>` instead of `<VirtualHost *>`.

  For a virtual host that supports multiple projects replace "`TracEnv`" /var/trac/myproject with "`TracEnvParentDir`" /var/trac/

  Note: !DocumentRoot should not point to your Trac project env. As Asmodai wrote on #trac: "suppose there's a webserver bug that allows disclosure of !DocumentRoot they could then leech the entire Trac environment".

  == Troubleshooting ==

  In general, if you get server error pages, you can either check the Apache error log, or enable the `PythonDebug` option:
  {{{
  #!xml
  <Location /projects/myproject>
    ...
    PythonDebug on
  </Location>
  }}}

  For multiple projects, try restarting the server as well.

  === Login Not Working ===
  If you've used `<Location />` directive, it will override any other directives, as well as `<Location /login>`.
  The workaround is to use negation expression as follows (for multi project setups):
  {{{
  #!xml
  #this one for other pages
  <Location ~ "/*(?!login)">
     SetHandler mod_python
     PythonHandler trac.web.modpython_frontend
     PythonOption TracEnvParentDir /projects
     PythonOption TracUriRoot /

  </Location>
  #this one for login page
  <Location ~ "/[^/]+/login">
     SetHandler mod_python
     PythonHandler trac.web.modpython_frontend
     PythonOption TracEnvParentDir /projects
     PythonOption TracUriRoot /

     #remove these if you don't want to force SSL
     RewriteEngine On 
     RewriteCond %{HTTPS} off
     RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}

     AuthType Basic
     AuthName "Trac"
     AuthUserFile /projects/.htpasswd
     Require valid-user
  </Location>
  }}}

  === Expat-related segmentation faults === #expat

  This problem will most certainly hit you on Unix when using Python 2.4.
  In Python 2.4, some version of Expat (an XML parser library written in C) is used, 
  and if Apache is using another version, this results in segmentation faults.
  As Trac 0.11 is using Genshi, which will indirectly use Expat, that problem
  can now hit you even if everything was working fine before with Trac 0.10.

  See Graham Dumpleton's detailed [http://www.dscpl.com.au/wiki/ModPython/Articles/ExpatCausingApacheCrash explanation and workarounds] for the issue.

  === Form submission problems ===

  If you're experiencing problems submitting some of the forms in Trac (a common problem is that you get redirected to the start page after submission), check whether your {{{DocumentRoot}}} contains a folder or file with the same path that you mapped the mod_python handler to. For some reason, mod_python gets confused when it is mapped to a location that also matches a static resource.

  === Problem with virtual host configuration ===

  If the <Location /> directive is used, setting the `DocumentRoot` may result in a ''403 (Forbidden)'' error. Either remove the `DocumentRoot` directive, or make sure that accessing the directory it points is allowed (in a corresponding `<Directory>` block).

  Using <Location /> together with `SetHandler` resulted in having everything handled by mod_python, which leads to not being able download any CSS or images/icons. I used <Location /trac> `SetHandler None` </Location> to circumvent the problem, though I do not know if this is the most elegant solution.

  === Problem with zipped egg ===

  It's possible that your version of mod_python will not import modules from zipped eggs. If you encounter an `ImportError: No module named trac` in your Apache logs but you think everything is where it should be, this might be your problem. Look in your site-packages directory; if the Trac module appears as a ''file'' rather than a ''directory'', then this might be your problem. To rectify, try installing Trac using the `--always-unzip` option, like this:

  {{{
  easy_install --always-unzip Trac-0.12b1.zip
  }}}

  === Using .htaccess ===

  Although it may seem trivial to rewrite the above configuration as a directory in your document root with a `.htaccess` file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation.

  It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth. Stick to the provided instructions. :)

  A success story: For me it worked out-of-box, with following trivial config:
  {{{#!xml
  SetHandler mod_python
  PythonInterpreter main_interpreter
  PythonHandler trac.web.modpython_frontend 
  PythonOption TracEnv /system/path/to/this/directory
  PythonOption TracUriRoot /path/on/apache

  AuthType Basic
  AuthName "ProjectName"
  AuthUserFile /path/to/.htpasswd
  Require valid-user
  }}}

  The `TracUriRoot` is obviously the path you need to enter to the browser to get to the trac (e.g. domain.tld/projects/trac)

  === Additional .htaccess help ===

  If you are using the .htaccess method you may have additional problems if your trac directory is inheriting .htaccess directives from another.  This may also help to add to your .htaccess file:

  {{{
  <IfModule mod_rewrite.c>
    RewriteEngine Off
  </IfModule>
  }}}

  === Platform specific issues
  ==== Win32 Issues ====
  If you run trac with mod_python < 3.2 on Windows, uploading attachments will '''not''' work. This problem is resolved in mod_python 3.1.4 or later, so please upgrade mod_python to fix this.


  ==== OS X issues ====

  When using mod_python on OS X you will not be able to restart Apache using `apachectl restart`. This is apparently fixed in mod_python 3.2, but there's also a patch available for earlier versions [http://www.dscpl.com.au/projects/vampire/patches.html here].

  ==== SELinux issues ====

  If Trac reports something like: ''Cannot get shared lock on db.lock''
  The security context on the repository may need to be set:

  {{{
  chcon -R -h -t httpd_sys_content_t PATH_TO_REPOSITORY
  }}}

  See also [http://subversion.tigris.org/faq.html#reposperms]

  ==== FreeBSD issues ====
  Pay attention to the version of the installed mod_python and sqlite packages. Ports have both the new and old ones, but earlier versions of pysqlite and mod_python won't integrate as the former requires threaded support in python, and the latter requires a threadless install.

  If you compiled and installed apache2, apache wouldn´t support threads (cause it doesn´t work very well on FreeBSD). You could force thread support when running ./configure for apache, using --enable-threads, but this isn´t recommendable.
  The best option [http://modpython.org/pipermail/mod_python/2006-September/021983.html seems to be] adding to /usr/local/apache2/bin/ennvars the line 

  {{{
  export LD_PRELOAD=/usr/lib/libc_r.so
  }}}


  ==== Fedora 7 Issues ====
  Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython but not for tracd


  === Subversion issues ===

  If you get the following Trac Error `Unsupported version control system "svn"` only under mod_python, though it works well on the command-line and even with TracStandalone, chances are that you forgot to add the path to the Python bindings with the [TracModPython#ConfiguringPythonPath PythonPath] directive. (The better way is to add a link to the bindings in the Python `site-packages` directory, or create a `.pth` file in that directory.)

  If this is not the case, it's possible that you're using Subversion libraries that are binary incompatible with the apache ones (an incompatibility of the `apr` libraries is usually the cause). In that case, you also won't be able to use the svn modules for Apache (`mod_dav_svn`).

  You also need a recent version of `mod_python` in order to avoid a runtime error ({{{argument number 2: a 'apr_pool_t *' is expected}}}) due to the default usage of multiple sub-interpreters. 3.2.8 ''should'' work, though it's probably better to use the workaround described in [trac:#3371 #3371], in order to force the use of the main interpreter:
  {{{
  PythonInterpreter main_interpreter
  }}}
  This is anyway the recommended workaround for other well-known issues seen when using the Python bindings for Subversion within mod_python ([trac:#2611 #2611], [trac:#3455 #3455]). See in particular Graham Dumpleton's comment in [trac:comment:9:ticket:3455 #3455] explaining the issue.

  === Page layout issues ===

  If the formatting of the Trac pages look weird chances are that the style sheets governing the page layout are not handled properly by the web server. Try adding the following lines to your apache configuration:
  {{{
  #!xml
  Alias /myproject/css "/usr/share/trac/htdocs/css"
  <Location /myproject/css>
      SetHandler None
  </Location>
  }}}

  Note: For the above configuration to have any effect it must be put after the configuration of your project root location, i.e. {{{<Location /myproject />}}}.

  Also, setting `PythonOptimize On` seems to mess up the page headers and footers, in addition to hiding the documentation for macros and plugins (see #Trac8956). Considering how little effect the option has, it is probably a good idea to leave it `Off`.

  === HTTPS issues ===

  If you want to run Trac fully under https you might find that it tries to redirect to plain http. In this case just add the following line to your apache configuration:
  {{{
  #!xml
  <VirtualHost * >
      DocumentRoot /var/www/myproject
      ServerName trac.mycompany.com
      SetEnv HTTPS 1
      ....
  </VirtualHost>
  }}}


  === Segmentation fault with php5-mhash or other php5 modules ===
  You may encounter segfaults (reported on debian etch) if php5-mhash module is installed. Try to remove it to see if this solves the problem. See debian bug report [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487]

  Some people also have troubles when using php5 compiled with its own 3rd party libraries instead of system libraries. Check here [http://www.djangoproject.com/documentation/modpython/#if-you-get-a-segmentation-fault]

  ----
  See also:  TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI],  [trac:TracNginxRecipe TracNginxRecipe]


name: TracInterfaceCustomization
author: trac
ipnr: 127.0.0.1
text:
  = Customizing the Trac Interface =
  [[TracGuideToc]]
  [[PageOutline]]

  == Introduction ==
  This page is meant to give users suggestions on how they can customize the look of Trac.  Topics on this page cover editing the HTML templates and CSS files, but not the program code itself.  The topics are intended to show users how they can modify the look of Trac to meet their specific needs.  Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page.

  == Project Logo and Icon ==
  The easiest parts of the Trac interface to customize are the logo and the site icon.  Both of these can be configured with settings in [wiki:TracIni trac.ini].

  The logo or icon image should be put in a folder named "htdocs" in your project's environment folder.  (''Note: in projects created with a Trac version prior to 0.9 you will need to create this folder'')

   ''Note: you can actually put the logo and icon anywhere on your server (as long as it's accessible through the web server), and use their absolute or server-relative URLs in the configuration.''

  Now configure the appropriate section of your [wiki:TracIni trac.ini]:

  === Logo ===
  Change the `src` setting to `site/` followed by the name of your image file.  The `width` and `height` settings should be modified to match your image's dimensions (the Trac chrome handler uses "`site/`" for files within the project directory `htdocs`, and "`common/`" for the common `htdocs` directory belonging to a Trac installation). Note that 'site/' is not a placeholder for your project name, it is the actual prefix that should be used (literally). For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'.

  {{{
  [header_logo]
  src = site/my_logo.gif
  alt = My Project
  width = 300
  height = 100
  }}}

  === Icon ===
  Icons should be a 32x32 image in `.gif` or `.ico` format.  Change the `icon` setting to `site/` followed by the name of your icon file.  Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu.

  {{{
  [project]
  icon = site/my_icon.ico
  }}}

  Note though that this icon is ignored by Internet Explorer, which only accepts a file named ``favicon.ico`` at the root of the host. To make the project icon work in both IE and other browsers, you can store the icon in the document root of the host, and reference it from ``trac.ini`` as follows:

  {{{
  [project]
  icon = /favicon.ico
  }}}

  Should your browser have issues with your favicon showing up in the address bar, you may put a "?" (less the quotation marks) after your favicon file extension. 

  {{{
  [project]
  icon = /favicon.ico?
  }}}

  == Custom Navigation Entries ==
  The new [mainnav] and [metanav] can now be used to customize the text and link used for the navigation items, or even to disable them (but not for adding new ones).

  In the following example, we rename the link to the Wiki start "Home", and hide the "!Help/Guide". We also make the "View Tickets" entry link to a specific report .
  {{{
  [mainnav]
  wiki.label = Home
  tickets.href = /report/24

  [metanav]
  help = disabled
  }}}

  See also TracNavigation for a more detailed explanation of the mainnav and metanav terms.

  == Site Appearance == #SiteAppearance

  Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Documentation is yet to be written, in the meantime the following tip should work.

  Say you want to add a link to a custom stylesheet, and then your own
  header and footer. Save the following content as `site.html` inside your projects `templates/` directory (each Trac project can have their own `site.html`), e.g. {{{/path/to/env/templates/site.html}}}:

  {{{
  #!xml
  <html xmlns="http://www.w3.org/1999/xhtml"
        xmlns:py="http://genshi.edgewall.org/"
        py:strip="">

    <!--! Add site-specific style sheet -->
    <head py:match="head" py:attrs="select('@*')">
      ${select('*|comment()|text()')}
      <link rel="stylesheet" type="text/css"
            href="${href.chrome('site/style.css')}" />
    </head>

    <body py:match="body" py:attrs="select('@*')">
      <!--! Add site-specific header -->
      <div id="siteheader">
        <!--! Place your header content here... -->
      </div>

      ${select('*|text()')}

      <!--! Add site-specific footer -->
      <div id="sitefooter">
        <!--! Place your footer content here... -->
      </div>
    </body>
  </html>
  }}}

  Those who are familiar with XSLT may notice that Genshi templates bear some similarities. However, there are some Trac specific features - for example `${href.chrome('site/style.css')}` attribute references a CSS file placed into environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-config|[trac] htdocs_location]] configuration setting.

  `site.html` is one file to contain all your modifications. It usually works using the `py:match` directive (element or attribute), and it allows you to modify the page as it renders - the matches hook onto specific sections depending on what it tries to find
  and modify them.
  See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example `site.html`.
  A `site.html` can contain any number of such `py:match` sections for whatever you need to modify. This is all Genshi, so the [http://genshi.edgewall.org/wiki/Documentation/xml-templates.html docs on the exact syntax] can be found there.


  Example snippet of adding introduction text to the new ticket form (but not shown during preview):

  {{{#!xml
  <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')">
    <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">
      <p>Please make sure to search for existing tickets before reporting a new one!</p>
    </py:if>
    ${select('*')} 
  </form>
  }}}

  This example illustrates a technique of using `req.environ['PATH_INFO']` to limit scope of changes to one view only. For instance, to make changes in `site.html` only for timeline and avoid modifying other sections - use  `req.environ['PATH_INFO'] == '/timeline'` condition in `<py:if>` test.

  More examples snippets for `site.html` can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml].

  Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss].

  If the environment is upgraded from 0.10 and a `site_newticket.cs` file already exists, it can actually be loaded by using a workaround - providing it contains no ClearSilver processing. In addition, as only one element can be imported, the content needs some sort of wrapper such as a `<div>` block or other similar parent container. The XInclude namespace must be specified to allow includes, but that can be moved to document root along with the others:
  {{{
  #!xml
  <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')"
          xmlns:xi="http://www.w3.org/2001/XInclude">
    <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> 
      <xi:include href="site_newticket.cs"><xi:fallback /></xi:include>
    </py:if>
    ${select('*')} 
  </form>
  }}}

  Also note that the `site.html` (despite its name) can be put in a common templates directory - see the [[TracIni#inherit-section|[inherit] templates_dir]] option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global `site.html` file can be made to include any existing header, footer and newticket snippets.

  == Project List == #ProjectList

  You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects.  

  The following is the basic template used by Trac to display a list of links to the projects.  For projects that could not be loaded it displays an error message. You can use this as a starting point for your own index template.

  {{{
  #!text/html
  <!DOCTYPE html
      PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  <html xmlns="http://www.w3.org/1999/xhtml"
        xmlns:py="http://genshi.edgewall.org/"
        xmlns:xi="http://www.w3.org/2001/XInclude">
    <head>
      <title>Available Projects</title>
    </head>
    <body>
      <h1>Available Projects</h1>
      <ul>
        <li py:for="project in projects" py:choose="">
          <a py:when="project.href" href="$project.href"
             title="$project.description">$project.name</a>
          <py:otherwise>
            <small>$project.name: <em>Error</em> <br /> ($project.description)</small>
          </py:otherwise>
        </li>
      </ul>
    </body>
  </html>
  }}}

  Once you've created your custom template you will need to configure the webserver to tell Trac where the template is located (pls verify ... not yet changed to 0.11):

  For [wiki:TracModWSGI mod_wsgi]:
  {{{
  os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template.html'
  }}}

  For [wiki:TracFastCgi FastCGI]:
  {{{
  FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \
                -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template
  }}}

  For [wiki:TracModPython mod_python]:
  {{{
  PythonOption TracEnvParentDir /parent/dir/of/projects
  PythonOption TracEnvIndexTemplate /path/to/template
  }}}

  For [wiki:TracCgi CGI]:
  {{{
  SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template
  }}}

  For [wiki:TracStandalone], you'll need to set up the `TRAC_ENV_INDEX_TEMPLATE` environment variable in the shell used to launch tracd:
   - Unix
     {{{
  #!sh
  $ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template
     }}}
   - Windows
     {{{
  #!sh
  $ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template
     }}}

  == Project Templates ==

  The appearance of each individual Trac environment (that is, instance of a project) can be customized independently of other projects, even those hosted by the same server. The recommended way is to use a `site.html` template (see [#SiteAppearance]) whenever possible. Using `site.html` means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of `theme.html` or any other Trac template, you need to migrate your modifiations to the newer version - if not, new Trac features or bug fixes may not work as expected.

  With that word of caution, any Trac template may be copied and customized. The default Trac templates are located inside the installed Trac egg (`/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, .../trac/ticket/templates, .../trac/wiki/templates, ++`). The [#ProjectList] template file is called `index.html`, while the template responsible for main layout is called `theme.html`. Page assets such as images and CSS style sheets are located in the egg's `trac/htdocs` directory.

  However, do not edit templates or site resources inside the Trac egg - installing Trac again can completely delete your modifications. Instead use one of two alternatives:
   * For a modification to one project only, copy the template to project `templates` directory.
   * For a modification shared by several projects, copy the template to a shared location and have each project point to this location using the `[inherit] templates_dir =` trac.ini option.

  Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg.

  Trac caches templates in memory by default to improve performance. To apply a template you need to restart the server.

  ----
  See also TracGuide, TracIni


name: InterWiki
author: trac
ipnr: 127.0.0.1
text:
  = Support for InterWiki links =

  ''(since [trac:milestone:0.10 0.10])''

  == Definition ==

  An InterWiki link can be used for referring to a Wiki page
  located in another Wiki system, and by extension, to any object
  located in any other Web application, provided a simple URL 
  mapping can be done.

  At the extreme, InterWiki prefixes can even be used to simply introduce
  links to new protocols, such as `tsvn:` used by [trac:TortoiseSvn TortoiseSvn].

  == Link Syntax ==

  {{{
  <target_wiki>(:<identifier>)+
  }}}

  The link is composed by the targeted Wiki (or system) name,
  followed by a colon (e.g. `MeatBall:`),
  followed by a page specification in the target.
  Note that, as for InterTrac prefixes, '''InterWiki prefixes are case insensitive'''.

  The target Wiki URL is looked up in the `[interwiki]` section of TracIni or in the InterMapTxt wiki page, modeled after MeatBall:InterMapTxt. If a prefix is defined in both the `[interwiki]` section and InterMapTxt, the `[interwiki]` section takes precedence.

  In addition to traditional InterWiki links, where the target
  is simply ''appended'' to the URL, 
  Trac supports parametric InterWiki URLs:
  identifiers `$1`, `$2`, ... in the URL
  will be replaced by corresponding arguments.
  The argument list is formed by splitting the page identifier
  using the ":" separator.

  === [interwiki] ===
  Every option in the `[interwiki]` section in TracIni defines one InterWiki prefix. The option name defines the prefix. The option value defines the URL, optionally followed by a description separated from the URL by whitespace. Parametric URLs are supported as well.

  '''Example:'''
  {{{
  [interwiki]
  MeatBall = http://www.usemod.com/cgi-bin/mb.pl?
  PEP = http://www.python.org/peps/pep-$1.html Python Enhancement Proposal $1
  tsvn = tsvn: Interact with TortoiseSvn
  }}}

  == Examples ==

  If the following is an excerpt of the InterMapTxt page:

  {{{
  = InterMapTxt =
  == This is the place for defining InterWiki prefixes ==

  Currently active prefixes: [[InterWiki]]

  This page is modelled after the MeatBall:InterMapTxt page.
  In addition, an optional comment is allowed after the mapping.
  ----
  {{{
  PEP      http://www.python.org/peps/pep-$1.html           # Python Enhancement Proposal $1 
  Trac-ML  http://thread.gmane.org/gmane.comp.version-control.subversion.trac.general/$1  # Message $1 in Trac Mailing List

  tsvn     tsvn:                                            # Interact with TortoiseSvn
  ...
  MeatBall http://www.usemod.com/cgi-bin/mb.pl?
  MetaWiki http://sunir.org/apps/meta.pl?
  MetaWikiPedia http://meta.wikipedia.org/wiki/
  MoinMoin http://moinmoin.wikiwikiweb.de/
  ...
  }}}
  }}}

  Then, 
   * `MoinMoin:InterWikiMap` should be rendered as MoinMoin:InterWikiMap
     and the ''title'' for that link would be "!InterWikiMap in !MoinMoin"
   * `Trac-ML:4346` should be rendered as Trac-ML:4346
     and the ''title'' for that link would be "Message 4346 in Trac Mailing List"

  ----
  See also: InterTrac, InterMapTxt


name: WikiRestructuredText
author: trac
ipnr: 127.0.0.1
text:
  = reStructuredText Support in Trac =

  Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used.

  From the reStucturedText webpage:
   "''reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser   system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating  simple web pages, and for standalone documents. reStructuredText is designed for extensibility for  specific application domains. ''"

  If you want a file from your Subversion repository be displayed as reStructuredText in Trac's source browser, set `text/x-rst` as value for the Subversion property `svn:mime-type`. See [trac:source:/trunk/INSTALL this example].

  === Requirements ===
  Note that to activate RST support in Trac, the python docutils package must be installed. 
  If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].

  Install docutils using `easy_install docutils`. Do not use the package manager of your OS (e.g. `apt-get install python-docutils`), because Trac will not find docutils then.

  === More information on RST ===

   * reStructuredText Website -- http://docutils.sourceforge.net/rst.html
   * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html

  ----

  == Using RST in Trac ==
  To specify that a block of text should be parsed using RST, use the ''rst'' processor. 

  === TracLinks in reStructuredText ===

   * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
     ||= Wiki Markup ||= Display ||
     {{{#!td
       {{{
       {{{
       #!rst
       This is a reference to |a ticket|

       .. |a ticket| trac:: #42
       }}}
       }}}
     }}}
     {{{#!td
       {{{
       #!rst
       This is a reference to |a ticket|

       .. |a ticket| trac:: #42
       }}}
     }}}

   * Trac allows an even easier way of creating TracLinks in RST, using the custom `:trac:` role.
     ||= Wiki Markup ||= Display ||
     {{{#!td
       {{{
       {{{
       #!rst
       This is a reference to ticket `#12`:trac:

       To learn how to use Trac, see `TracGuide`:trac:
       }}}
       }}}
     }}}
     {{{#!td
       {{{
       #!rst
       This is a reference to ticket `#12`:trac:

       To learn how to use Trac, see `TracGuide`:trac:
       }}}
     }}}

   For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks. 


  === Syntax highlighting in reStructuredText ===

  There is a directive for doing TracSyntaxColoring in RST as well. The directive is called
  code-block

  ||= Wiki Markup ||= Display ||
  {{{#!td
    {{{
    {{{
    #!rst

    .. code-block:: python

       class Test:

           def TestFunction(self):
               pass
    
    }}}
    }}}
  }}}
  {{{#!td
    {{{
    #!rst

    .. code-block:: python

       class Test:

           def TestFunction(self):
               pass

    }}}
  }}}
  Note the need to indent the code at least one character after the `.. code-block` directive.

  === Wiki Macros in reStructuredText ===

  For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e code-block.

  ||= Wiki Markup ||= Display ||
  {{{#!td
    {{{
    {{{
    #!rst

    .. code-block:: RecentChanges

       Trac,3

    }}}
    }}}
  }}}
  {{{#!td
    {{{
    #!rst

    .. code-block:: RecentChanges

       Trac,3

    }}}
  }}}

  Or a more concise Wiki Macro like syntax is also available, using the `:code-block:` role:

  ||= Wiki Markup ||= Display ||
  {{{#!td
    {{{
    {{{
    #!rst

    :code-block:`RecentChanges:Trac,3`
    }}}
    }}}
  }}}
  {{{#!td
    {{{
    #!rst

    :code-block:`RecentChanges:Trac,3`
    }}}
  }}}

  === Bigger RST Example ===
  The example below should be mostly self-explanatory:

  ||= Wiki Markup ||= Display ||
  {{{#!td
  {{{
  #!html
  <pre class="wiki">{{{
  #!rst
  FooBar Header
  =============
  reStructuredText is **nice**. It has its own webpage_.

  A table:

  =====  =====  ======
     Inputs     Output
  ------------  ------
    A      B    A or B
  =====  =====  ======
  False  False  False
  True   False  True
  False  True   True
  True   True   True
  =====  =====  ======

  RST TracLinks
  -------------

  See also ticket `#42`:trac:.

  .. _webpage: http://docutils.sourceforge.net/rst.html
  }}}</pre>
  }}}
  }}}
  {{{#!td
  {{{
  #!rst
  FooBar Header
  =============
  reStructuredText is **nice**. It has its own webpage_.

  A table:

  =====  =====  ======
     Inputs     Output
  ------------  ------
    A      B    A or B
  =====  =====  ======
  False  False  False
  True   False  True
  False  True   True
  True   True   True
  =====  =====  ======

  RST TracLinks
  -------------

  See also ticket `#42`:trac:.

  .. _webpage: http://docutils.sourceforge.net/rst.html
  }}}
  }}}

  ----
  See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting


name: CamelCase
author: trac
ipnr: 127.0.0.1
text:
  = !CamelCase =
  New words created by smashing together capitalized words.

  CamelCase is the original wiki convention for creating hyperlinks, with the additional requirement that the capitals are followed by a lower-case letter; hence “AlabamA” and “ABc” will not be links.

  == Customizing the Wiki behavior ==

  Some people dislike linking by CamelCase.  While Trac remains faithful to the original Wiki style, it provides a number of ways to accomodate users with different preferences:
   * There's an option (`ignore_missing_pages` in the [wiki:TracIni#wiki-section "[wiki]"] section of TracIni) to simply ignore links to missing pages when the link is written using the CamelCase style, instead of that word being replaced by a gray link followed by a question mark.[[BR]]
     That can be useful when CamelCase style is used to name code artifacts like class names and there's no corresponding page for them.
   * There's an option (`split_page_names` in the  [wiki:TracIni#wiki-section "[wiki]"] section of TracIni) to automatically insert space characters between the words of a CamelCase link when rendering the link.
   * Creation of explicit Wiki links is also easy, see WikiPageNames for details.
   * In addition, Wiki formatting can be disabled completely in some places (e.g. when rendering commit log messages). See `wiki_format_messages` in the [wiki:TracIni#changeset-section "[changeset]"] section of TracIni.

  See TracIni for more information on the available options.

  == More information on !CamelCase ==

   * http://c2.com/cgi/wiki?WikiCase
   * http://en.wikipedia.org/wiki/CamelCase

  ----
  See also: WikiPageNames, WikiNewPage, WikiFormatting, TracWiki


name: TracSearch
author: trac
ipnr: 127.0.0.1
text:
  = Using Search =

  Trac has a built-in search engine to allow finding occurrences of keywords and substrings in wiki pages, tickets and changeset properties (author, revision and log message).

  Using the Trac search facility is straightforward and its interface should be familiar to most users.

  Apart from the [search: Search module], you will also find a small search field above the navigation bar at all time. It provides convenient access to the search module from all pages.

  The search results show the most recent modifications ranked first in the results rather than the most relevant result.

  == "Quickjump" searches ==
  For quick access to various project resources, the quick-search field at the top of every page can be used to enter a [TracLinks wiki link], which will take you directly to the resource identified by that link.

  For example:

   * ![42] -- Opens change set 42
   * !#42 -- Opens ticket number 42
   * !{1} -- Opens report 1
   * /trunk -- Opens the browser for the `trunk` directory

  == Advanced ==

  === Disabling Quickjumps ===
  To disable the quickjump feature for a search keyword - for example when searching for occurences of the literal word !TracGuide - begin the query with an exclamation mark (`!`).

  === Search Links ===
  From the Wiki, it is possible to link to a specific search, using
  `search:` links:
   * `search:?q=crash` will search for the string "crash" 
   * `search:?q=trac+link&wiki=on` will search for "trac" and "link" 
     in wiki pages only

  ----
  See also: TracGuide, TracLinks, TracQuery


name: TracRoadmap
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Roadmap =
  [[TracGuideToc]]

  The roadmap provides a view on the [wiki:TracTickets ticket system] that helps planning and managing the future development of a project.

  == The Roadmap View ==

  Basically, the roadmap is just a list of future milestones. You can add a description to milestones (using WikiFormatting) describing main objectives, for example. In addition, tickets targeted for a milestone are aggregated, and the ratio between active and resolved tickets is displayed as a milestone progress bar.  It is possible to further [trac:TracRoadmapCustomGroups customise the ticket grouping] and have multiple ticket statuses shown on the progress bar.

  The roadmap can be filtered to show or hide ''completed milestones'' and ''milestones with no due date''. In the case that both ''show completed milestones'' and ''hide milestones with no due date'' are selected, ''completed'' milestones with no due date __will__ be shown.

  == The Milestone View ==

  You can add a description for each milestone (using WikiFormatting) describing main objectives, for example. In addition, tickets targeted for a milestone are aggregated, and the ratio between active and resolved tickets is displayed as a milestone progress bar.  It is possible to further [trac:TracRoadmapCustomGroups customise the ticket grouping] and have multiple ticket statuses shown on the progress bar.

  It is possible to drill down into this simple statistic by viewing the individual milestone pages. By default, the active/resolved ratio will be grouped and displayed by component. You can also regroup the status by other criteria, such as ticket owner or severity. Ticket numbers are linked to [wiki:TracQuery custom queries] listing corresponding tickets.

  == Roadmap Administration ==

  With appropriate permissions it is possible to add, modify and remove milestones using either the web interface (roadmap and milestone pages), web administration interface or by using `trac-admin`. 

  '''Note:''' Milestone descriptions can not currently be edited using 'trac-admin'.

  == iCalendar Support ==

  The Roadmap supports the [http://www.ietf.org/rfc/rfc2445.txt iCalendar] format to keep track of planned milestones and related tickets from your favorite calendar software. Many calendar applications support the iCalendar specification including
   * [http://www.apple.com/ical/ Apple iCal] for Mac OS X
   * the cross-platform [http://www.mozilla.org/projects/calendar/ Mozilla Calendar]
   * [http://chandlerproject.org Chandler]
   * [http://kontact.kde.org/korganizer/ Korganizer] (the calendar application of the [http://www.kde.org/ KDE] project)
   * [http://www.novell.com/de-de/products/desktop/features/evolution.html Evolution] also support iCalendar
   * [http://office.microsoft.com/en-us/outlook/ Microsoft Outlook] can also read iCalendar files (it appears as a new static calendar in Outlook)
   * [https://www.google.com/calendar/ Google Calendar] 

  To subscribe to the roadmap, copy the iCalendar link from the roadmap (found at the bottom of the page) and choose the "Subscribe to remote calendar" action (or similar) of your calendar application, and insert the URL just copied.

  '''Note:''' For tickets to be included in the calendar as tasks, you need to be logged in when copying the link. You will only see tickets assigned to yourself, and associated with a milestone.

  '''Note:''' To include the milestones in Google Calendar you might need to rewrite the URL.
  {{{
  RewriteEngine on
  RewriteRule ([^/.]+)/roadmap/([^/.]+)/ics /$1/roadmap?user=$2&format=ics
  }}}

  More information about iCalendar can be found at [http://en.wikipedia.org/wiki/ICalendar Wikipedia].
  ----
  See also: TracTickets, TracReports, TracQuery, [trac:TracRoadmapCustomGroups]


name: TracUnicode
author: trac
ipnr: 127.0.0.1
text:
  = Unicode Support in Trac =
  [[TracGuideToc]]

  Trac stores all text using UTF-8 encoding, including text in tickets and wiki pages. Internal processing of text uses true Unicode representations.

  As such, it supports most (all?) commonly used character encodings.

  If the default encoding in your source code repository is not UTF-8, you can specify it in the [TracIni#trac-section trac.ini], for example:
  {{{
  default_charset = gbk
  }}}

  You also must make sure that your [trac:DatabaseBackend database backend] stores its data in UTF-8; otherwise strange things will happen.

  To convert your database to UTF-8, the easiest way is to dump the database, convert the dump into UTF-8 and then import the converted dump back into the database.[[BR]]
  You can use [http://www.gnu.org/software/libiconv/documentation/libiconv/iconv.1.html iconv] to convert the dump.


  == Examples ==

  === Arabic ===
  تراك يقوم بحفظ كل الكلمات باستخدام صيغة UTF-8، بما في ذلك الكلمات المستخدمة في صفحات  التيكت والويكي.

  === Bulgarian ===
  Българският език работи ли?

  === Česky ===
  Čeština v kódování UTF-8, žádný problém.

  === Chinese ===
  Traditional: 繁體中文, 漢字測試; Simplified: 简体中文，汉字测试

  === Croatian ===
  Ako podržava srpski i slovenski mora podržavati i Hrvatski - čćžšđ ČĆŽŠĐ 

  === English ===
  Yes indeed, Trac supports English. Fully.

  === Français ===
  Il est possible d'écrire en Français : à, ç, û, ...

  === German ===
  Trac-Wiki muß auch deutsche Umlaute richtig anzeigen: ö, ä, ü, Ä, Ö, Ü; und das scharfe ß

  === Greek ===
  Τα Ελληνικά υποστηρίζονται επαρκώς επίσης.

  === Hebrew ===
  אני יכול לאכול זכוכית וזה לא מזיק לי

  === Hindi ===
  अब हिन्दी में।

  === Hungarian ===
  Árvíztűrő tükörfúrógép

  === Icelandic ===
  Ævar sagði við ömmu sína: Sjáðu hvað ég er stór!

  === Japanese ===
  漢字 ひらがな カタカナ ﾊﾝｶｸｶﾅ 日本語試験

  === Korean ===
  이번에는 한글로 써보겠습니다. 잘 보이나요? 한글

  === Latvian ===

  Latviešu valoda arī strādā!

  === Lithuanian ===
  Sudalyvaukime ir mes. Ar veikia lietuviškos raidės? ąčęėįšųūž ĄČĘĖĮŠŲŪŽ Žinoma, kad veikia :)
  Kas tie mes?

  === Persian (Farsi) ===
  این یک متن فارسی است ولی امکان نوشتن مستقیم فارسی نیست چون حالت متن از راست به چپ و جود ندارد برای فارسی نوشتن باید از HTML استفاده کنید.
  {{{
  #!html
  <div dir="rtl">
  }}}
  این نمونه یک متن از راست به چپ فارسی است که در HTML نوشته شده تا اعداد 12345 و حروف لاتین ABCDEF در محل خودشان نمایش داده شوند.
  {{{
  #!html
  </div>
  }}}

  === Polish ===
  Pchnąć w tę łódź jeża lub osiem skrzyń fig; Nocna gżegżółka zawsze dzienną przekuka.

  === Portuguese ===
  É possível guardar caracteres especias da língua portuguesa, incluindo o símbolo da moeda européia '€', trema 'ü', crase 'à', agudos 'áéíóú', circunflexos 'âêô', til 'ãõ', cedilha 'ç', ordinais 'ªº', grau '°¹²³'.

  === Russian ===
  Проверка русского языка: кажется работает... И буква "ё" есть...

  === Serbian ===
  Podržan, uprkos činjenici da se za njegovo pisanje koriste чак два алфабета.

  === Slovenian ===
  Ta suhi škafec pušča vodo že od nekdaj!

  === Spanish ===
  Esto es un pequeño texto en Español, donde el veloz murciélago hindú comía cardlllo y kiwi

  === Swedish ===
  Räven raskar över isen med luva på.

  === Thai ===
  Trac แสดงภาษาไทยได้อย่างถูกต้อง!

  === Ukrainian ===
  Перевірка української мови...

  === Urdu ===
  ٹریک اردو بھی سپورٹ کرتا ہے۔

  === Vietnamese ===
  Viết tiếng Việt cũng được.


name: TracStandalone
author: trac
ipnr: 127.0.0.1
text:
  = Tracd =

  Tracd is a lightweight standalone Trac web server.
  It can be used in a variety of situations, from a test or development server to a multiprocess setup behind another web server used as a load balancer.

  == Pros ==

   * Fewer dependencies: You don't need to install apache or any other web-server.
   * Fast: Should be almost as fast as the [wiki:TracModPython mod_python] version (and much faster than the [wiki:TracCgi CGI]), even more so since version 0.12 where the HTTP/1.1 version of the protocol is enabled by default
   * Automatic reloading: For development, Tracd can be used in ''auto_reload'' mode, which will automatically restart the server whenever you make a change to the code (in Trac itself or in a plugin).

  == Cons ==

   * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd.
   * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead,
     or [http://trac.edgewall.org/wiki/STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.

  == Usage examples ==

  A single project on port 8080. (http://localhost:8080/)
  {{{
   $ tracd -p 8080 /path/to/project
  }}}
  Stricly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use ''--hostname'' option.
  {{{
   $ tracd --hostname=localhost -p 8080 /path/to/project
  }}}
  With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/)
  {{{
   $ tracd -p 8080 /path/to/project1 /path/to/project2
  }}}

  You can't have the last portion of the path identical between the projects since Trac uses that name to keep the URLs of the
  different projects unique. So if you use `/project1/path/to` and `/project2/path/to`, you will only see the second project.

  An alternative way to serve multiple projects is to specify a parent directory in which each subdirectory is a Trac project, using the `-e` option. The example above could be rewritten:
  {{{
   $ tracd -p 8080 -e /path/to
  }}}

  To exit the server on Windows, be sure to use {{{CTRL-BREAK}}} -- using {{{CTRL-C}}} will leave a Python process running in the background.

  == Installing as a Windows Service ==

  === Option 1 ===
  To install as a Windows service, get the [http://www.google.com/search?q=srvany.exe SRVANY] utility and run:
  {{{
   C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe
   reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd-script.py\" <your tracd parameters>"
   net start tracd
  }}}

  '''DO NOT''' use {{{tracd.exe}}}.  Instead register {{{python.exe}}} directly with {{{tracd-script.py}}} as a parameter.  If you use {{{tracd.exe}}}, it will spawn the python process without SRVANY's knowledge.  This python process will survive a {{{net stop tracd}}}.

  If you want tracd to start automatically when you boot Windows, do:
  {{{
   sc config tracd start= auto
  }}}

  The spacing here is important.

  {{{#!div
  Once the service is installed, it might be simpler to run the Registry Editor rather than use the `reg add` command documented above.  Navigate to:[[BR]]
  `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\tracd\Parameters`

  Three (string) parameters are provided:
  ||!AppDirectory ||C:\Python26\ ||
  ||Application ||python.exe ||
  ||!AppParameters ||scripts\tracd-script.py -p 8080 ... ||

  Note that, if the !AppDirectory is set as above, the paths of the executable ''and'' of the script name and parameter values are relative to the directory.  This makes updating Python a little simpler because the change can be limited, here, to a single point.
  (This is true for the path to the .htpasswd file, as well, despite the documentation calling out the /full/path/to/htpasswd; however, you may not wish to store that file under the Python directory.)
  }}}

  For Windows 7 User, srvany.exe may not be an option, so you can use [http://www.google.com/search?q=winserv.exe WINSERV] utility and run:
  {{{
  "C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd-script.py <your tracd parameters>"

  net start tracd
  }}}

  === Option 2 ===

  Use [http://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [http://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service.

  === Option 3 ===

  also cygwin's cygrunsrv.exe can be used:
  {{{
  $ cygrunsrv --install tracd --path /cygdrive/c/Python27/Scripts/tracd.exe --args '--port 8000 --env-parent-dir E:\IssueTrackers\Trac\Projects'
  $ net start tracd
  }}}

  == Using Authentication ==

  Tracd allows you to run Trac without the need for Apache, but you can take advantage of Apache's password tools (htpasswd and htdigest) to easily create a password file in the proper format for tracd to use in authentication. (It is also possible to create the password file without htpasswd or htdigest; see below for alternatives)

  Tracd provides support for both Basic and Digest authentication. Digest is considered more secure. The examples below use Digest; to use Basic authentication, replace `--auth` with `--basic-auth` in the command line.

  The general format for using authentication is:
  {{{
   $ tracd -p port --auth="base_project_dir,password_file_path,realm" project_path
  }}}
  where:
   * '''base_project_dir''': the base directory of the project specified as follows:
     * when serving multiple projects: ''relative'' to the `project_path`
     * when serving only a single project (`-s`): the name of the project directory
   Don't use an absolute path here as this won't work. ''Note:'' This parameter is case-sensitive even for environments on Windows.
   * '''password_file_path''': path to the password file
   * '''realm''': the realm name (can be anything)
   * '''project_path''': path of the project

   * **`--auth`** in the above means use Digest authentication, replace `--auth` with `--basic-auth` if you want to use Basic auth.  Although Basic authentication does not require a "realm", the command parser does, so the second comma is required, followed directly by the closing quote for an empty realm name.

  Examples:

  {{{
   $ tracd -p 8080 \
     --auth="project1,/path/to/passwordfile,mycompany.com" /path/to/project1
  }}}

  Of course, the password file can be be shared so that it is used for more than one project:
  {{{
   $ tracd -p 8080 \
     --auth="project1,/path/to/passwordfile,mycompany.com" \
     --auth="project2,/path/to/passwordfile,mycompany.com" \
     /path/to/project1 /path/to/project2
  }}}

  Another way to share the password file is to specify "*" for the project name:
  {{{
   $ tracd -p 8080 \
     --auth="*,/path/to/users.htdigest,mycompany.com" \
     /path/to/project1 /path/to/project2
  }}}

  === Basic Authorization: Using a htpasswd password file ===
  This section describes how to use `tracd` with Apache .htpasswd files.

    Note: It is necessary (at least with Python 2.6) to install the fcrypt package in order to
    decode some htpasswd formats.  Trac source code attempt an `import crypt` first, but there
    is no such package for Python 2.6. Only `SHA-1` passwords (since Trac 1.0) work without this module.

  To create a .htpasswd file use Apache's `htpasswd` command (see [#GeneratingPasswordsWithoutApache below] for a method to create these files without using Apache):
  {{{
   $ sudo htpasswd -c /path/to/env/.htpasswd username
  }}}
  then for additional users:
  {{{
   $ sudo htpasswd /path/to/env/.htpasswd username2
  }}}

  Then to start `tracd` run something like this:
  {{{
   $ tracd -p 8080 --basic-auth="projectdirname,/fullpath/environmentname/.htpasswd,realmname" /fullpath/environmentname
  }}}

  For example:
  {{{
   $ tracd -p 8080 --basic-auth="testenv,/srv/tracenv/testenv/.htpasswd,My Test Env" /srv/tracenv/testenv
  }}}
  ''Note:'' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD).

  === Digest authentication: Using a htdigest password file ===

  If you have Apache available, you can use the htdigest command to generate the password file. Type 'htdigest' to get some usage instructions, or read [http://httpd.apache.org/docs/2.0/programs/htdigest.html this page] from the Apache manual to get precise instructions.  You'll be prompted for a password to enter for each user that you create.  For the name of the password file, you can use whatever you like, but if you use something like `users.htdigest` it will remind you what the file contains. As a suggestion, put it in your <projectname>/conf folder along with the [TracIni trac.ini] file.

  Note that you can start tracd without the `--auth` argument, but if you click on the ''Login'' link you will get an error.

  === Generating Passwords Without Apache ===

  Basic Authorization can be accomplished via this [http://aspirine.org/htpasswd_en.html online HTTP Password generator] which also supports `SHA-1`.  Copy the generated password-hash line to the .htpasswd file on your system. Note that Windows Python lacks the "crypt" module that is the default hash type for htpasswd ; Windows Python can grok MD5 password hashes just fine and you should use MD5.

  You can use this simple Python script to generate a '''digest''' password file:

  {{{
  #!python
  from optparse import OptionParser
  # The md5 module is deprecated in Python 2.5
  try:
      from hashlib import md5
  except ImportError:
      from md5 import md5
  realm = 'trac'

  # build the options
  usage = "usage: %prog [options]"
  parser = OptionParser(usage=usage)
  parser.add_option("-u", "--username",action="store", dest="username", type = "string",
                    help="the username for whom to generate a password")
  parser.add_option("-p", "--password",action="store", dest="password", type = "string",
                    help="the password to use")
  parser.add_option("-r", "--realm",action="store", dest="realm", type = "string",
                    help="the realm in which to create the digest")
  (options, args) = parser.parse_args()

  # check options
  if (options.username is None) or (options.password is None):
     parser.error("You must supply both the username and password")
  if (options.realm is not None):
     realm = options.realm
     
  # Generate the string to enter into the htdigest file
  kd = lambda x: md5(':'.join(x)).hexdigest()
  print ':'.join((options.username, realm, kd([options.username, realm, options.password])))
  }}}

  Note: If you use the above script you must set the realm in the `--auth` argument to '''`trac`'''. Example usage (assuming you saved the script as trac-digest.py):

  {{{
   $ python trac-digest.py -u username -p password >> c:\digest.txt
   $ tracd --port 8000 --auth=proj_name,c:\digest.txt,trac c:\path\to\proj_name
  }}}

  ==== Using `md5sum`
  It is possible to use `md5sum` utility to generate digest-password file:
  {{{
  user=
  realm=
  password=
  path_to_file=
  echo ${user}:${realm}:$(printf "${user}:${realm}:${password}" | md5sum - | sed -e 's/\s\+-//') > ${path_to_file}
  }}}

  == Reference ==

  Here's the online help, as a reminder (`tracd --help`):
  {{{
  Usage: tracd [options] [projenv] ...

  Options:
    --version             show program's version number and exit
    -h, --help            show this help message and exit
    -a DIGESTAUTH, --auth=DIGESTAUTH
                          [projectdir],[htdigest_file],[realm]
    --basic-auth=BASICAUTH
                          [projectdir],[htpasswd_file],[realm]
    -p PORT, --port=PORT  the port number to bind to
    -b HOSTNAME, --hostname=HOSTNAME
                          the host name or IP address to bind to
    --protocol=PROTOCOL   http|scgi|ajp|fcgi
    -q, --unquote         unquote PATH_INFO (may be needed when using ajp)
    --http10              use HTTP/1.0 protocol version instead of HTTP/1.1
    --http11              use HTTP/1.1 protocol version (default)
    -e PARENTDIR, --env-parent-dir=PARENTDIR
                          parent directory of the project environments
    --base-path=BASE_PATH
                          the initial portion of the request URL's "path"
    -r, --auto-reload     restart automatically when sources are modified
    -s, --single-env      only serve a single project without the project list
    -d, --daemonize       run in the background as a daemon
    --pidfile=PIDFILE     when daemonizing, file to which to write pid
    --umask=MASK          when daemonizing, file mode creation mask to use, in
                          octal notation (default 022)
    --group=GROUP         the group to run as
    --user=USER           the user to run as
  }}}

  Use the -d option so that tracd doesn't hang if you close the terminal window where tracd was started.

  == Tips ==

  === Serving static content ===

  If `tracd` is the only web server used for the project, 
  it can also be used to distribute static content 
  (tarballs, Doxygen documentation, etc.)

  This static content should be put in the `$TRAC_ENV/htdocs` folder,
  and is accessed by URLs like `<project_URL>/chrome/site/...`.

  Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file,
  the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`, 
  which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax). 

   ''Support for `htdocs:` TracLinks syntax was added in version 0.10''

  === Using tracd behind a proxy

  In some situations when you choose to use tracd behind Apache or another web server.

  In this situation, you might experience issues with redirects, like being redirected to URLs with the wrong host or protocol. In this case (and only in this case), setting the `[trac] use_base_url_for_redirect` to `true` can help, as this will force Trac to use the value of `[trac] base_url` for doing the redirects.

  If you're using the AJP protocol to connect with `tracd` (which is possible if you have flup installed), then you might experience problems with double quoting. Consider adding the `--unquote` parameter.

  See also [trac:TracOnWindowsIisAjp], [trac:TracNginxRecipe].

  === Authentication for tracd behind a proxy
  It is convenient to provide central external authentication to your tracd instances, instead of using {{{--basic-auth}}}. There is some discussion about this in #9206.

  Below is example configuration based on Apache 2.2, mod_proxy, mod_authnz_ldap.

  First we bring tracd into Apache's location namespace.

  {{{
  <Location /project/proxified>
          Require ldap-group cn=somegroup, ou=Groups,dc=domain.com
          Require ldap-user somespecificusertoo
          ProxyPass http://localhost:8101/project/proxified/
          # Turns out we don't really need complicated RewriteRules here at all
          RequestHeader set REMOTE_USER %{REMOTE_USER}s
  </Location>
  }}}

  Then we need a single file plugin to recognize HTTP_REMOTE_USER header as valid authentication source. HTTP headers like '''HTTP_FOO_BAR''' will get converted to '''Foo-Bar''' during processing. Name it something like '''remote-user-auth.py''' and drop it into '''proxified/plugins''' directory:
  {{{
  #!python
  from trac.core import *
  from trac.config import BoolOption
  from trac.web.api import IAuthenticator

  class MyRemoteUserAuthenticator(Component):

      implements(IAuthenticator)

      obey_remote_user_header = BoolOption('trac', 'obey_remote_user_header', 'false', 
                 """Whether the 'Remote-User:' HTTP header is to be trusted for user logins 
                  (''since ??.??').""") 

      def authenticate(self, req):
          if self.obey_remote_user_header and req.get_header('Remote-User'): 
              return req.get_header('Remote-User') 
          return None

  }}}

  Add this new parameter to your TracIni:
  {{{
  ...
  [trac]
  ...
  obey_remote_user_header = true
  ...
  }}}

  Run tracd:
  {{{
  tracd -p 8101 -r -s proxified --base-path=/project/proxified
  }}}

  Note that if you want to install this plugin for all projects, you have to put it in your [TracPlugins#Plugindiscovery global plugins_dir] and enable it in your global trac.ini.

  Global config (e.g. `/srv/trac/conf/trac.ini`):
  {{{
  [components]
  remote-user-auth.* = enabled
  [inherit]
  plugins_dir = /srv/trac/plugins
  [trac]
  obey_remote_user_header = true
  }}}

  Environment config (e.g. `/srv/trac/envs/myenv`):
  {{{
  [inherit]
  file = /srv/trac/conf/trac.ini
  }}}

  === Serving a different base path than / ===
  Tracd supports serving projects with different base urls than /<project>. The parameter name to change this is
  {{{
   $ tracd --base-path=/some/path
  }}}

  ----
  See also: TracInstall, TracCgi, TracModPython, TracGuide, [trac:TracOnWindowsStandalone#RunningTracdasservice Running tracd.exe as a Windows service]


name: TracTickets
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Ticket System =
  [[TracGuideToc]]

  The Trac ticket database provides simple but effective tracking of issues and bugs within a project.

  As the central project management element of Trac, tickets can be used for '''project tasks''', '''feature requests''', '''bug reports''', '''software support issues''' among others. 

  As with the TracWiki, this subsystem has been designed with the goal of making user contribution and participation as simple as possible. It should be as easy as possible to report bugs, ask questions, suggest improvements and discuss resolutions.

  An issue is assigned to a person who must resolve it or reassign the ticket to someone else.
  All tickets can be edited, annotated, assigned, prioritized and discussed at any time.

  [=#edit-permissions]
  However, some Trac installations may put restrictions in place about who can change what. For example, the default installation doesn't permit to non-authenticated users ("anonymous" users) to change anything, even to comment on an issue, for obvious spam prevention reasons. Check the local contributing policy, which you can usually find on the front page WikiStart, or contact your local Trac administrator.

  == Ticket Fields ==

  A  ticket contains the following information attributes:
   
   * '''Reporter''' — The author of the ticket.
   * '''Type''' — The nature of the ticket (for example, defect or enhancement request). See TicketTypes for more details.
   * '''Component''' — The project module or subsystem this ticket concerns.
   * '''Version''' — Version of the project that this ticket pertains to.
   * '''Keywords''' — Keywords that a ticket is marked with. Useful for searching and report generation.
   * '''Priority''' — The importance of this issue, ranging from ''trivial'' to ''blocker''. A pull-down if different priorities where defined.
   * '''Milestone''' — When this issue should be resolved at the latest. A pull-down menu containing a list of milestones.
   * '''Assigned to/Owner''' — Principal person responsible for handling the issue.
   * '''Cc''' — A comma-separated list of other users or E-Mail addresses to notify. ''Note that this does not imply responsiblity or any other policy.''
   * '''Resolution''' — Reason for why a ticket was closed. One of {{{fixed}}}, {{{invalid}}}, {{{wontfix}}}, {{{duplicate}}}, {{{worksforme}}}.
   * '''Status''' — What is the current status? One of {{{new}}}, {{{assigned}}}, {{{closed}}}, {{{reopened}}}.
   * '''Summary''' — A brief description summarizing the problem or issue. Simple text without WikiFormatting.
   * '''Description''' — The body of the ticket. A good description should be specific, descriptive and to the point. Accepts WikiFormatting.

  '''Notes:''' 
   - Versions of Trac prior to 0.9 did not have the ''type'' field, but instead provided a ''severity'' field and different default values for the ''priority'' field. This change was done to simplify the ticket model by removing the somewhat blurry distinction between ''priority'' and ''severity''. However, the old model is still available if you prefer it: just add/modify the default values of the ''priority'' and ''severity'', and optionally hide the ''type'' field by removing all the possible values through [wiki:TracAdmin trac-admin].

   - the [trac:TicketTypes type], [trac:TicketComponent component], version, priority and severity fields can be managed with [wiki:TracAdmin trac-admin] or with the [trac:WebAdmin WebAdmin] plugin.

   - Description of the builtin ''priority'' values is available at [trac:TicketTypes#Whyistheseverityfieldgone TicketTypes]

  == Changing and Commenting Tickets ==

  With appropriate permissions, as already mentioned [#edit-permissions above], a ticket entered into Trac can at any time be modified by '''annotating'''.

  Then, annotations like changes and comments to the ticket are logged as a part of the ticket itself. When viewing a ticket, the history of changes will appear below the main ticket area.

  Comment editing (available since 0.12) is meant to be used to make small corrections to comments, like fixing formatting, forgotten WikiFormatting or spelling errors, not major edits. For longer edits, you should be adding a new comment instead. Editing a comment will not produce a new entry on [/timeline] while entering a new comment or other changes will do.

  All edits (field changes, new comments, comment edits) update the "last changed" time of the ticket.


  '''Notes:''' 
   - An important feature is being able to use TracLinks and WikiFormatting in ticket descriptions and comments. Use TracLinks to refer to other issues, changesets or files to make your ticket more specific and easier to understand.

   - See TracNotification for how to configure email notifications of ticket changes.

   - See TracWorkflow for information about the state transitions (ticket lifecycle), and how this workflow can be customized.

  == Default Values for Drop-Down Fields ==

  The option selected by default for the various drop-down fields can be set in [wiki:TracIni trac.ini], in the `[ticket]` section:

   * `default_component`: Name of the component selected by default
   * `default_milestone`: Name of the default milestone
   * `default_priority`: Default priority value
   * `default_severity`: Default severity value
   * `default_type`: Default ticket type
   * `default_version`: Name of the default version
   * `default_owner`: Name of the default owner. If set to the text "< default >" (the default value), the component owner is used.

  If any of these options are omitted, the default value will either be the first in the list, or an empty value, depending on whether the field in question is required to be set.  Some of these can be chosen through the [trac:WebAdmin WebAdmin] plugin in the "Ticket System" section (others in the [[wiki:TracIni#ticket-section|"[ticket]"]] section in `trac.ini`).


  == Hiding Fields and Adding Custom Fields ==

  Many of the default ticket fields can be hidden from the ticket web interface simply by removing all the possible values through [wiki:TracAdmin trac-admin]. This of course only applies to drop-down fields, such as ''type'', ''priority'', ''severity'', ''component'', ''version'' and ''milestone''.

  Trac also lets you add your own custom ticket fields. See TracTicketsCustomFields for more information.


  == Assign-to as Drop-Down List ==

  If the list of possible ticket owners is finite, you can change the ''assign-to'' ticket field from a text input to a drop-down list. This is done by setting the `restrict_owner` option of the `[ticket]` section in [wiki:TracIni trac.ini] to “true”. In that case, Trac will use the list of all users who have accessed the project to populate the drop-down field.

  To appear in the dropdown list, a user needs be registered with the project, ''i.e.'' a user session should exist in the database. Such an entry is automatically created in the database the first time the user submits a change in the project, for example when editing the user's details in the ''Settings'' page, or simply by authenticating if the user has a login. Also, the user must have `TICKET_MODIFY` [TracPermissions permissions].

  '''Notes:''' 
   - See [http://pacopablo.com/wiki/pacopablo/blog/set-assign-to-drop-down Populating Assign To Drop Down] on how to add user entries at database level

   - If you need serious flexibility and aren't afraid of a little plugin coding of your own, see [http://trac-hacks.org/wiki/FlexibleAssignToPlugin FlexibleAssignTo] (disclosure: I'm the author)

   -  Activating this option may cause some performance degradation, read more about this in the [trac:TracPerformance#Configuration Trac performance] page.

  == Preset Values for New Tickets ==

  To create a link to the new-ticket form filled with preset values, you need to call the `/newticket?` URL with `variable=value` separated by `&`. 

  Possible variables are :

   * '''type''' — The type droplist
   * '''reporter''' — Name or email of the reporter
   * '''summary''' — Summary line for the ticket
   * '''description''' — Long description of the ticket
   * '''component''' — The component droplist
   * '''version''' — The version droplist
   * '''severity''' — The severity droplist
   * '''keywords''' — The keywords 
   * '''priority''' — The priority droplist
   * '''milestone''' — The milestone droplist
   * '''owner''' — The person responsible for the ticket
   * '''cc''' — The list of emails for notifying about the ticket change

  Example: ''`[/newticket?summary=Compile%20Error&version=1.0&component=gui]`''[[BR]]

  ----
  See also:  TracGuide, TracWiki, TracTicketsCustomFields, TracNotification, TracReports, TracQuery


name: TracBackup
author: trac
ipnr: 127.0.0.1
text:
  = Trac Backup =
  [[TracGuideToc]]

  Since Trac uses a database backend, some extra care is required to safely create a backup of a [wiki:TracEnvironment project environment]. Luckily, [wiki:TracAdmin trac-admin] has a command to make backups easier: `hotcopy`.

    ''Note: Trac uses the `hotcopy` nomenclature to match that of [http://subversion.tigris.org/ Subversion], to make it easier to remember when managing both Trac and Subversion servers.''

  == Creating a Backup ==

  To create a backup of a live TracEnvironment, simply run:
  {{{

    $ trac-admin /path/to/projenv hotcopy /path/to/backupdir

  }}}

  [wiki:TracAdmin trac-admin] will lock the database while copying.''

  The resulting backup directory is safe to handle using standard file-based backup tools like `tar` or `dump`/`restore`.

  Please, note, that hotcopy command does not overwrite target directory and when such exists, hotcopy ends with error: `Command failed: [Errno 17] File exists:` This is discussed in [trac:ticket:3198 #3198].

  === Restoring a Backup ===

  Backups are simply a copied snapshot of the entire [wiki:TracEnvironment project environment] directory, including the SQLite database. 

  To restore an environment from a backup, stop the process running Trac (i.e. the Web server or [wiki:TracStandalone tracd]), restore the contents of your backup (path/to/backupdir) to your [wiki:TracEnvironment project environment] directory and restart the service.

  ----
  See also: TracAdmin, TracEnvironment, TracGuide, [trac:TracMigrate TracMigrate]


name: WikiNewPage
author: trac
ipnr: 127.0.0.1
text:
  = Steps to Add a New Wiki Page =
  [[TracGuideToc]]

  Note: make sure you actually have the rights to edit wiki pages. If you don't see the **Edit this page** button, read the information relative to the editing policy for your Trac installation (usually on the front page WikiStart), or contact your local Trac administrator.

   1. Choose a name for your new page. See WikiPageNames for naming conventions.
   2. Edit an existing page (or any other resources that support WikiFormatting and add a [TracLinks link] to your new page. Save your changes.
   3. Follow the link you created to take you to the new page. Trac will display a "describe !PageName here" message.
   4. Click the "Edit this page" button to edit and add content to your new page. Save your changes.
   5. All done. Your new page is published.

  You can skip the second step by entering the CamelCase name of the page in the quick-search field at the top of the page. But note that the page will effectively be "orphaned" unless you link to it from somewhere else.

  == Rename a page #renaming

  While picking up good WikiPageNames is important, you can always change your mind
  and rename the page later.

  You'll need to ask for the WIKI_RENAME permission in order to be allowed to do this.
  When renaming a page, you'll be offered the possibility to create a redirection page, so that links pointing to the old location will not be left dangling.

  ----
  See also: TracWiki, PageTemplates, WikiFormatting, TracLinks, WikiDeletePage


name: TracRevisionLog
author: trac
ipnr: 127.0.0.1
text:
  = Viewing Revision Logs =
  [[TracGuideToc]]

  When you browse the repository, it's always possible to query the 
  ''Revision Log'' view corresponding to the path you're currently seeing.
  This will display a list of the most recent changesets in which the 
  current path or any other path below it has been modified.

  == The Revision Log Form ==

  It's possible to set the revision at which the revision log should
  start, using the ''View log starting at'' field. An empty value
  or a value of ''head'' is taken to be the newest changeset. 

  It's also possible to specify the revision at which the log should
  stop, using the ''back to'' field. By default, it's left empty, 
  which means the revision log will stop as soon as 100 revisions have 
  been listed.

  Also, there are three modes of operation of the revision log.

  By default, the revision log ''stops on copy'', which means that 
  whenever an ''Add'', ''Copy'' or ''Rename'' operation is detected, 
  no older revision will be shown. That's very convenient when working
  with branches, as one only sees the history corresponding to what
  has been done on the branch.

  It's also possible to indicate that one wants to see what happened
  before a ''Copy'' or ''Rename'' change, by selecting the 
  ''Follow copies'' mode. This will cross all copies or renames changes.
  Each time the name of the path changes, there will be an additional
  indentation level. That way, the changes on the different paths
  are easily grouped together visually.

  It's even possible to go past an ''Add'' change, in order to see 
  if there has been a ''Delete'' change on that path, before 
  that ''Add''. This mode corresponds to the mode called 
  ''Show only adds, moves and deletes''. 
  While quite useful at times, be aware that this operation is quite 
  resource intensive.

  Finally, there's also a checkbox ''Show full log messages'',
  which controls whether the full content of the commit log message
  should be displayed for each change, or only a shortened version of it.

  == The Revision Log Information ==

  For each revision log entry, there are 7 columns:
   1. The first column contains a pair of radio buttons and should be used 
      for selecting the ''old'' and the ''new'' revisions that will be 
      used for [wiki:TracRevisionLog#viewingtheactualchanges viewing the actual changes].
   1. A color code (similar to the one used for the
      [wiki:TracChangeset#ChangesetHeader changesets]) indicating kind of change.
      Clicking on this column refreshes the revision log so that it restarts
      with this change.
   1. The '''Revision''' number, displayed as `@xyz`.
      This is a link to the TracBrowser, using the displayed revision as the base line.
   Next to it, you can see a little "wheel" icon [[Image(htdocs:../common/changeset.png)]],  which is clickable and leads to the TracChangeset view for that revision.
   1. The '''Date''' at which the change was made.
      The date is displayed as the time elapsed from the date of the revision. The time
      elapsed is displayed as the number of hours, days, weeks, months, or years.
   1. The '''Author''' of the change.
   1. The '''Log Message''', which contains either the truncated or full commit 
      log message, depending on the value of the ''Show full log messages'' 
      checkbox in the form above.
      

  == Inspecting Changes Between Revisions ==

  The ''View changes...'' buttons (placed above and below the list
  of changes, on the left side) will show the set of differences
  corresponding to the aggregated changes starting from the ''old''
  revision (first radio-button) to the ''new'' revision (second
  radio-button), in the TracChangeset view.

  Note that the ''old'' revision doesn't need to be actually 
  ''older'' than the ''new'' revision: it simply gives a base
  for the diff. It's therefore entirely possible to easily 
  generate a ''reverse diff'', for reverting what has been done
  in the given range of revisions.

  Finally, if the two revisions are identical, the corresponding
  changeset will be shown (same effect as clicking on the !ChangeSet number).

  == Alternative Formats ==

  === The !ChangeLog Text ===

  At the bottom of the page, there's a ''!ChangeLog'' link
  that will show the range of revisions as currently shown,
  but as a simple text, matching the usual conventions for
  !ChangeLog files.

  === RSS Support ===

  The revision log also provides a RSS feed to monitor the changes.
  To subscribe to a RSS feed for a file or directory, open its
  revision log in the browser and click the orange 'XML' icon at the bottom
  of the page. For more information on RSS support in Trac, see TracRss.

  ----
  See also: TracBrowser, TracChangeset, TracGuide


name: TracAdmin
author: trac
ipnr: 127.0.0.1
text:
  = TracAdmin =
  [[TracGuideToc]]

  Trac is distributed with a powerful command-line configuration tool. This tool can be used  to configure and customize your Trac-installation to better fit your needs.

  Some of those operations can also be performed via the ''Admin'' web interface, an updated version of the [trac:WebAdmin] plugin now integrated within Trac (since version 0.11).

  == Usage ==

  For nearly every `trac-admin` command, you'll need to specify the path to the TracEnvironment that you want to administer as the first argument, for example:
  {{{
  trac-admin /path/to/projenv wiki list
  }}}

  The only exception is for the `help` command, but even in this case if you omit the environment, you'll only get a very succinct list of commands (`help` and `initenv`), the same list you'd get when invoking `trac-admin` alone.
  Also, `trac-admin --version` will tell you about the Trac version (e.g. 0.12) corresponding to the program.

  If you want to get a comprehensive list of the available commands and sub-commands, you need to specify an existing environment:
  {{{
  trac-admin /path/to/projenv help
  }}}

  Some commands have a more detailed help, which you can access by specifying the command's name as a subcommand for `help`:

  {{{
  trac-admin /path/to/projenv help <command>
  }}}

  === `trac-admin <targetdir> initenv` === #initenv

  This subcommand is very important as it's the one used to create a TracEnvironment in the specified `<targetdir>`. That directory must not exist prior to the call.

  [[TracAdminHelp(initenv)]]

  It supports an extra `--inherit` option, which can be used to specify a global configuration file which can be used share settings between several environments. You can also inherit from a shared configuration afterwards, by setting the `[inherit] file` option in the `conf/trac.ini` file in your newly created environment, but the advantage of specifying the inherited configuration file at environment creation time is that only the options ''not'' already specified in the global configuration file will be written in the created environment's `conf/trac.ini` file.
  See TracIni#GlobalConfiguration.

  Note that in version 0.11 of Trac, `initenv` lost an extra last argument `<templatepath>`, which was used in previous versions to point to the `templates` folder. If you are using the one-liner '`trac-admin /path/to/trac/ initenv <projectname> <db> <repostype> <repospath>`' in the above and getting an error that reads ''''`Wrong number of arguments to initenv: 4`'''', then this is because you're using a `trac-admin` script from an '''older''' version of Trac.

  == Interactive Mode ==

  When passing the environment path as the only argument, `trac-admin` starts in interactive mode.
  Commands can then be executed on the selected environment using the prompt, which offers tab-completion
  (on non-Windows environments, and when the Python `readline` module is available) and automatic repetition of the last command issued.

  Once you're in interactive mode, you can also get help on specific commands or subsets of commands:

  For example, to get an explanation of the `resync` command, run:
  {{{
  > help resync
  }}}

  To get help on all the Wiki-related commands, run:
  {{{
  > help wiki
  }}}

  == Full Command Reference ==

  You'll find below the detailed help for all the commands available by default in `trac-admin`. Note that this may not match the list given by `trac-admin <yourenv> help`, as the commands  pertaining to components disabled in that environment won't be available and conversely some plugins activated in the environment can add their own commands.

  [[TracAdminHelp()]]

  ----
  See also: TracGuide, TracBackup, TracPermissions, TracEnvironment, TracIni, [trac:TracMigrate TracMigrate]


name: TracFastCgi
author: trac
ipnr: 127.0.0.1
text:
  [[PageOutline]]

  = Trac with FastCGI =

  [http://www.fastcgi.com/ FastCGI] interface allows Trac to remain resident much like with [wiki:TracModPython mod_python] or [wiki:TracModWSGI mod_wsgi]. It is faster than external CGI interfaces which must start a new process for each request.  Additionally, it is supported by much wider variety of web servers.

  Note that unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], i.e. run with different permissions than web server running with (`mod_wsgi` supports the `WSGIDaemonProcess` with user / group parameters to achieve the same effect).

  '''Note for Windows:''' Trac's FastCGI does not run under Windows, as Windows does not implement `Socket.fromfd`, which is used by `_fcgi.py`. If you want to connect to IIS, you may want to try [trac:TracOnWindowsIisAjp AJP]/[trac:TracOnWindowsIisAjp ISAPI].

  [[PageOutline(2-3,Overview,inline)]]


  == Simple Apache configuration ==

  There are two FastCGI modules commonly available for Apache: `mod_fastcgi` and
  `mod_fcgid` (preferred). The latter is more up-to-date.

  The following sections focus on the FCGI specific setup, see also [wiki:TracModWSGI#ConfiguringAuthentication] for configuring the authentication in Apache.

  Regardless of which cgi module is used, be sure the web server has executable permissions on the cgi-bin folder. While FastCGI will throw specific permissions errors, mod_fcgid will throw an ambiguous error if this has not been done. (Connection reset by peer: mod_fcgid: error reading data from FastCGI server) 

  === Set up with `mod_fastcgi` ===
  `mod_fastcgi` uses `FastCgiIpcDir` and `FastCgiConfig` directives that should be added to an appropriate Apache configuration file:
  {{{
  # Enable fastcgi for .fcgi files
  # (If you're using a distro package for mod_fcgi, something like
  # this is probably already present)
  <IfModule mod_fastcgi.c>
     AddHandler fastcgi-script .fcgi
     FastCgiIpcDir /var/lib/apache2/fastcgi 
  </IfModule>
  LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so
  }}}
  Setting `FastCgiIpcDir` is optional if the default is suitable. Note that the `LoadModule` line must be after the `IfModule` group.

  Configure `ScriptAlias` or similar options as described in TracCgi, but
  calling `trac.fcgi` instead of `trac.cgi`.

  Add the following to the Apache configuration file (below the `FastCgiIpcDir` line) if you intend to set up the `TRAC_ENV` as an overall default:
  {{{
  FastCgiConfig -initial-env TRAC_ENV=/path/to/env/trac
  }}}

  Alternatively, you can serve multiple Trac projects in a directory by adding this:
  {{{
  FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects
  }}}

  === Set up with `mod_fcgid` ===
  Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi`
  instead of `trac.cgi`. Note that slash at the end - it is important.
  {{{
  ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.fcgi/
  }}}

  To set up Trac environment for `mod_fcgid` it is necessary to use
  `DefaultInitEnv` directive. It cannot be used in `Directory` or
  `Location` context, so if you need to support multiple projects, try
  alternative environment setup below.

  {{{
  DefaultInitEnv TRAC_ENV /path/to/env/trac/
  }}}

  === alternative environment setup ===
  A better method to specify path to Trac environment is to embed the path
  into `trac.fcgi` script itself. That doesn't require configuration of server
  environment variables, works for both FastCgi modules
  (and for [http://www.lighttpd.net/ lighttpd] and CGI as well):
  {{{
  import os
  os.environ['TRAC_ENV'] = "/path/to/projectenv"
  }}}
  or
  {{{
  import os
  os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/project/parent/dir"
  }}}

  With this method different projects can be supported by using different
  `.fcgi` scripts with different `ScriptAliases`.

  See [https://coderanger.net/~coderanger/httpd/fcgi_example.conf this fcgid example config] which uses a !ScriptAlias directive with trac.fcgi with a trailing / like this:
  {{{
  ScriptAlias / /srv/tracsite/cgi-bin/trac.fcgi/
  }}}

  == Simple Cherokee Configuration ==

  The configuration on Cherokee's side is quite simple. You will only need to know that you can spawn Trac as an SCGI process.
  You can either start it manually, or better yet, automatically by letting Cherokee spawn the server whenever it is down.
  First set up an information source in cherokee-admin with a local interpreter.

  {{{
  Host:
  localhost:4433

  Interpreter:
  /usr/bin/tracd —single-env —daemonize —protocol=scgi —hostname=localhost —port=4433 /path/to/project/
  }}}

  If the port was not reachable, the interpreter command would be launched. Note that, in the definition of the information source, you will have to manually launch the spawner if you use a ''Remote host'' as ''Information source'' instead of a ''Local interpreter''.

  After doing this, we will just have to create a new rule managed by the SCGI handler to access Trac. It can be created in a new virtual server, trac.example.net for instance, and will only need two rules. The '''default''' one will use the SCGI handler associated to the previously created information source.
  The second rule will be there to serve the few static files needed to correctly display the Trac interface. Create it as ''Directory rule'' for ''/common'' and just set it to the ''Static files'' handler and with a ''Document root'' that points to the appropriate files: ''$TRAC_LOCAL/htdocs/'' (where $TRAC_LOCAL is a directory defined by the user or the system administrator to place local trac resources).

  Note:\\
  If the tracd process fails to start up, and cherokee displays a 503 error page, you might be missing the [http://trac.saddi.com/flup python-flup] package.\\
  Python-flup is a dependency which provides trac with SCGI capability. You can install it on debian based systems with:
  {{{
  sudo apt-get install python-flup
  }}}


  == Simple Lighttpd Configuration ==

  The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ lighttpd].

  lighttpd is a secure, fast, compliant and very flexible web-server that has been optimized for high-performance
  environments.  It has a very low memory footprint compared to other web servers and takes care of CPU load.

  For using `trac.fcgi`(prior to 0.11) / fcgi_frontend.py (0.11) with lighttpd add the following to your lighttpd.conf:
  {{{
  #var.fcgi_binary="/usr/bin/python /path/to/fcgi_frontend.py" # 0.11 if installed with easy_setup, it is inside the egg directory
  var.fcgi_binary="/path/to/cgi-bin/trac.fcgi" # 0.10 name of prior fcgi executable
  fastcgi.server = ("/trac" =>
     
                     ("trac" =>
                       ("socket" => "/tmp/trac-fastcgi.sock",
                        "bin-path" => fcgi_binary,
                        "check-local" => "disable",
                        "bin-environment" =>
                          ("TRAC_ENV" => "/path/to/projenv")
                       )
                     )
                   )
  }}}

  Note that you will need to add a new entry to `fastcgi.server` for each separate Trac instance that you wish to run. Alternatively, you may use the `TRAC_ENV_PARENT_DIR` variable instead of `TRAC_ENV` as described above,
  and you may set one of the two in `trac.fcgi` instead of in `lighttpd.conf`
  using `bin-environment` (as in the section above on Apache configuration).

  Note that lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example (see [trac:#2418]). This is fixed in lighttpd 1.5, and under lighttpd 1.4.23 or later the workaround is to add `"fix-root-scriptname" => "enable"` as a parameter of fastcgi.server.

  For using two projects with lighttpd add the following to your `lighttpd.conf`:
  {{{
  fastcgi.server = ("/first" =>
                     ("first" =>
                      ("socket" => "/tmp/trac-fastcgi-first.sock",
                       "bin-path" => fcgi_binary,
                       "check-local" => "disable",
                       "bin-environment" =>
                         ("TRAC_ENV" => "/path/to/projenv-first")
                      )
                    ),
                    "/second" =>
                      ("second" =>
                      ("socket" => "/tmp/trac-fastcgi-second.sock",
                       "bin-path" => fcgi_binary,
                       "check-local" => "disable",
                       "bin-environment" =>
                         ("TRAC_ENV" => "/path/to/projenv-second")
                      )
                    )
                  )
  }}}
  Note that field values are different.  If you prefer setting the environment
  variables in the `.fcgi` scripts, then copy/rename `trac.fcgi`, e.g., to
  `first.fcgi` and `second.fcgi`, and reference them in the above settings.
  Note that the above will result in different processes in any event, even
  if both are running from the same `trac.fcgi` script.

  {{{
  #!div class=important
  '''Note''' It's very important the order on which server.modules are loaded, if mod_auth is not loaded '''BEFORE''' mod_fastcgi, then the server will fail to authenticate the user.
  }}}

  For authentication you should enable mod_auth in lighttpd.conf 'server.modules', select auth.backend and auth rules:
  {{{
  server.modules              = (
  ...
    "mod_auth",
  ...
  )

  auth.backend               = "htpasswd"

  # Separated password files for each project
  # See "Conditional Configuration" in
  # http://trac.lighttpd.net/trac/file/branches/lighttpd-merge-1.4.x/doc/configuration.txt

  $HTTP["url"] =~ "^/first/" {
    auth.backend.htpasswd.userfile = "/path/to/projenv-first/htpasswd.htaccess"
  }
  $HTTP["url"] =~ "^/second/" {
    auth.backend.htpasswd.userfile = "/path/to/projenv-second/htpasswd.htaccess"
  }

  # Enable auth on trac URLs, see
  # http://trac.lighttpd.net/trac/file/branches/lighttpd-merge-1.4.x/doc/authentication.txt

  auth.require = ("/first/login" =>
                  ("method"  => "basic",
                   "realm"   => "First project",
                   "require" => "valid-user"
                  ),
                  "/second/login" =>
                  ("method"  => "basic",
                   "realm"   => "Second project",
                   "require" => "valid-user"
                  )
                 )


  }}}
  Note that lighttpd (I use version 1.4.3) stopped if password file doesn't exist.

  Note that lighttpd doesn't support 'valid-user' in versions prior to 1.3.16.

  Conditional configuration is also useful for mapping static resources, i.e. serving out images and CSS directly instead of through FastCGI:
  {{{
  # Aliasing functionality is needed
  server.modules += ("mod_alias")

  # Set up an alias for the static resources
  alias.url = ("/trac/chrome/common" => "/usr/share/trac/htdocs")

  # Use negative lookahead, matching all requests that ask for any resource under /trac, EXCEPT in
  # /trac/chrome/common, and use FastCGI for those
  $HTTP["url"] =~ "^/trac(?!/chrome/common)" {
  # Even if you have other fastcgi.server declarations for applications other than Trac, do NOT use += here
  fastcgi.server = ("/trac" =>
                     ("trac" =>
                       ("socket" => "/tmp/trac-fastcgi.sock",
                        "bin-path" => fcgi_binary,
                        "check-local" => "disable",
                        "bin-environment" =>
                          ("TRAC_ENV" => "/path/to/projenv")
                       )
                     )
                   )
  }
  }}}
  The technique can be easily adapted for use with multiple projects by creating aliases for each of them, and wrapping the fastcgi.server declarations inside conditional configuration blocks.
  Also there is another way to handle multiple projects and it's to use TRAC_ENV_PARENT_DIR instead of TRAC_ENV and use global auth, let's see an example:
  {{{
  #  This is for handling multiple projects
    alias.url       = ( "/trac/" => "/path/to/trac/htdocs/" )

    fastcgi.server += ("/projects"  =>
                        ("trac" =>
                          (
                            "socket" => "/tmp/trac.sock",
                            "bin-path" => fcgi_binary,
                            "check-local" => "disable",
                            "bin-environment" =>
                              ("TRAC_ENV_PARENT_DIR" => "/path/to/parent/dir/of/projects/" )
                          )
                        )
                      )
  #And here starts the global auth configuration
    auth.backend = "htpasswd"
    auth.backend.htpasswd.userfile = "/path/to/unique/htpassword/file/trac.htpasswd"
    $HTTP["url"] =~ "^/projects/.*/login$" {
      auth.require = ("/" =>
                       (
                         "method"  => "basic",
                         "realm"   => "trac",
                         "require" => "valid-user"
                       )
                     )
    }
  }}}

  Changing date/time format also supported by lighttpd over environment variable LC_TIME
  {{{
  fastcgi.server = ("/trac" =>
                     ("trac" =>
                       ("socket" => "/tmp/trac-fastcgi.sock",
                        "bin-path" => fcgi_binary,
                        "check-local" => "disable",
                        "bin-environment" =>
                          ("TRAC_ENV" => "/path/to/projenv",
                          "LC_TIME" => "ru_RU")
                       )
                     )
                   )
  }}}
  For details about languages specification see [trac:TracFaq TracFaq] question 2.13.

  Other important information like the [wiki:TracInstall#MappingStaticResources mapping static resources advices] are useful for non-fastcgi specific installation aspects.
  ]

  Relaunch lighttpd, and browse to `http://yourhost.example.org/trac` to access Trac.

  Note about running lighttpd with reduced permissions:

  If nothing else helps and trac.fcgi doesn't start with lighttpd settings `server.username = "www-data"`, `server.groupname = "www-data"`, then in the `bin-environment` section set `PYTHON_EGG_CACHE` to the home directory of `www-data` or some other directory accessible to this account for writing.


  == Simple !LiteSpeed Configuration ==

  The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.litespeedtech.com/ LiteSpeed].

  !LiteSpeed web server is an event-driven asynchronous Apache replacement designed from the ground-up to be secure, scalable, and operate with minimal resources. !LiteSpeed can operate directly from an Apache config file and is targeted for business-critical environments.

   1. Please make sure you have first have a working install of a Trac project. Test install with “tracd” first.

   2. Create a Virtual Host for this setup. From now on we will refer to this vhost as !TracVhost. For this tutorial we will be assuming that your trac project will be accessible via:

  {{{
  http://yourdomain.com/trac/
  }}}

   3. Go “!TracVhost → External Apps” tab and create a new “External Application”.

  {{{
  Name: MyTracFCGI	
  Address: uds://tmp/lshttpd/mytracfcgi.sock
  Max Connections: 10
  Environment: TRAC_ENV=/fullpathto/mytracproject/ <--- path to root folder of trac project
  Initial Request Timeout (secs): 30
  Retry Timeout (secs): 0
  Persistent Connection	Yes
  Connection Keepalive Timeout: 30
  Response Bufferring: No	
  Auto Start: Yes
  Command: /usr/share/trac/cgi-bin/trac.fcgi  <--- path to trac.fcgi
  Back Log: 50
  Instances: 10
  }}}

   4. Optional. If you need to use htpasswd based authentication. Go to “!TracVhost → Security” tab and create a new security “Realm”.

  {{{
  DB Type: Password File
  Realm Name: MyTracUserDB               <--- any name you wish and referenced later
  User DB Location: /fullpathto/htpasswd <--- path to your htpasswd file
  }}}

  If you don’t have a htpasswd file or don’t know how to create the entries within one, go to http://sherylcanter.com/encrypt.php, to generate the user:password combos.

   5. Go to “!PythonVhost → Contexts” and create a new “FCGI Context”.

  {{{
  URI: /trac/                              <--- URI path to bind to python fcgi app we created	
  Fast CGI App: [VHost Level] MyTractFCGI  <--- select the trac fcgi extapp we just created
  Realm: TracUserDB                        <--- only if (4) is set. select realm created in (4)
  }}}

   6. Modify `/fullpathto/mytracproject/conf/trac.ini`

  {{{
  #find/set base_rul, url, and link variables
  base_url = http://yourdomain.com/trac/ <--- base url to generate correct links to
  url = http://yourdomain.com/trac/      <--- link of project
  link = http://yourdomain.com/trac/     <--- link of graphic logo
  }}}

   7. Restart !LiteSpeed, “lswsctrl restart”, and access your new Trac project at: 

  {{{
  http://yourdomain.com/trac/
  }}}


  == Simple Nginx Configuration ==

  Nginx is able to communicate with FastCGI processes, but can not spawn them. So you need to start FastCGI server for Trac separately.

   1. Nginx configuration with basic authentication handled by Nginx - confirmed to work on 0.6.32
  {{{
      server {
          listen       10.9.8.7:443;
          server_name  trac.example;

          ssl                  on;
          ssl_certificate      /etc/ssl/trac.example.crt;
          ssl_certificate_key  /etc/ssl/trac.example.key;

          ssl_session_timeout  5m;

          ssl_protocols  SSLv2 SSLv3 TLSv1;
          ssl_ciphers  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
          ssl_prefer_server_ciphers   on;

          # (Or ``^/some/prefix/(.*)``.
          if ($uri ~ ^/(.*)) {
               set $path_info /$1;
          }

          # it makes sense to serve static resources through Nginx
          location /chrome/ {
               alias /home/trac/instance/static/htdocs/;
          }

          # You can copy this whole location to ``location [/some/prefix]/login``
          # and remove the auth entries below if you want Trac to enforce
          # authorization where appropriate instead of needing to authenticate
          # for accessing the whole site.
          # (Or ``location /some/prefix``.)
          location / {
              auth_basic            "trac realm";
              auth_basic_user_file /home/trac/htpasswd;

              # socket address
              fastcgi_pass   unix:/home/trac/run/instance.sock;

              # python - wsgi specific
              fastcgi_param HTTPS on;

              ## WSGI REQUIRED VARIABLES
              # WSGI application name - trac instance prefix.
  	    # (Or ``fastcgi_param  SCRIPT_NAME  /some/prefix``.)
              fastcgi_param  SCRIPT_NAME        "";
              fastcgi_param  PATH_INFO          $path_info;

              ## WSGI NEEDED VARIABLES - trac warns about them
              fastcgi_param  REQUEST_METHOD     $request_method;
              fastcgi_param  SERVER_NAME        $server_name;
              fastcgi_param  SERVER_PORT        $server_port;
              fastcgi_param  SERVER_PROTOCOL    $server_protocol;
              fastcgi_param  QUERY_STRING       $query_string;

              # For Nginx authentication to work - do not forget to comment these
              # lines if not using Nginx for authentication
              fastcgi_param  AUTH_USER          $remote_user;
              fastcgi_param  REMOTE_USER        $remote_user;

              # for ip to work
              fastcgi_param REMOTE_ADDR         $remote_addr;

              # For attchments to work
              fastcgi_param    CONTENT_TYPE     $content_type;
              fastcgi_param    CONTENT_LENGTH   $content_length;
          }
      }
  }}}

   2. Modified trac.fcgi:

  {{{
  #!/usr/bin/env python
  import os
  sockaddr = '/home/trac/run/instance.sock'
  os.environ['TRAC_ENV'] = '/home/trac/instance'

  try:
       from trac.web.main import dispatch_request
       import trac.web._fcgi

       fcgiserv = trac.web._fcgi.WSGIServer(dispatch_request, 
            bindAddress = sockaddr, umask = 7)
       fcgiserv.run()

  except SystemExit:
      raise
  except Exception, e:
      print 'Content-Type: text/plain\r\n\r\n',
      print 'Oops...'
      print
      print 'Trac detected an internal error:'
      print
      print e
      print
      import traceback
      import StringIO
      tb = StringIO.StringIO()
      traceback.print_exc(file=tb)
      print tb.getvalue()

  }}}

   3. reload nginx and launch trac.fcgi like that:

  {{{
  trac@trac.example ~ $ ./trac-standalone-fcgi.py 
  }}}

  The above assumes that:
   * There is a user named 'trac' for running trac instances and keeping trac environments in its home directory.
   * `/home/trac/instance` contains a trac environment
   * `/home/trac/htpasswd` contains authentication information
   * `/home/trac/run` is owned by the same group the nginx runs under
    * and if your system is Linux the `/home/trac/run` has setgid bit set (`chmod g+s run`)
    * and patch from ticket #T7239 is applied, or you'll have to fix the socket file permissions every time

  Unfortunately nginx does not support variable expansion in fastcgi_pass directive. 
  Thus it is not possible to serve multiple trac instances from one server block. 

  If you worry enough about security, run trac instances under separate users. 

  Another way to run trac as a FCGI external application is offered in ticket #T6224

  ----
  See also:  TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracCgi CGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]


name: WikiPageNames
author: trac
ipnr: 127.0.0.1
text:
  = Wiki Page Names =
  [[TracGuideToc]]

  Wiki page names commonly use the CamelCase convention. Within wiki text, any word in CamelCase automatically becomes a hyperlink to the wiki page with that name.

  CamelCase page names must follow these rules:

   1. The name must consist of '''alphabetic characters only'''. No digits, spaces, punctuation, or underscores are allowed.
   2. A name must have at least two capital letters.
   3. The first character must be capitalized.
   4. Every capital letter must be followed by one or more lower-case letters. 
   5. The use of slash ( / ) is permitted in page names (possibly representing a hierarchy).

  If you want to create a wiki page that doesn't follow CamelCase rules you can use the following syntax:
  {{{
   * [wiki:Wiki_page], [wiki:ISO9000],
     and with a label: [wiki:ISO9000 ISO 9000 standard]
   * [wiki:"Space Matters"]
     and with a label: [wiki:"Space Matters" all about white space]
   * or simply: ["WikiPageName"]s
   * even better, the new [[WikiCreole link style]]
     and with a label: [[WikiCreole link style|WikiCreole style links]]
  }}}

  This will be rendered as:
   * [wiki:Wiki_page], [wiki:ISO9000],
     and with a label: [wiki:ISO9000 ISO 9000 standard]
   * [wiki:"Space Matters"] ''(that page name embeds space characters)''
     and with a label: [wiki:"Space Matters" all about white space]
   * or simply: ["WikiPageName"]s ''(old !MoinMoin's internal free links style)''
   * even better, the new [[WikiCreole link style]]
     and with a label: [[WikiCreole link style|WikiCreole style links]]
     ''(since 0.12, also now adopted by !MoinMoin)''


  Starting with Trac 0.11, it's also possible to link to a specific ''version'' of a Wiki page, as you would do for a specific version of a file, for example: WikiStart@1.

  You can also prevent a CamelCase name to be interpreted as a TracLinks, by quoting it. See TracLinks#EscapingLinks.

  As visible in the example above, one can also append an anchor to a Wiki page name, in order to link to a specific section within that page. The anchor can easily be seen by hovering the mouse over a section heading, then clicking on the [[html(&para;)]] sign that appears at its end. The anchor is usually generated automatically, but it's also possible to specify it explicitly: see WikiFormatting#using-explicit-id-in-heading.
  ----
  See also: WikiNewPage, WikiFormatting, TracWiki, TracLinks


name: TracSyntaxColoring
author: trac
ipnr: 127.0.0.1
text:
  = Syntax Coloring of Source Code =
  Trac supports language-specific syntax highlighting of source code within wiki formatted text in [WikiProcessors#CodeHighlightingSupport wiki processors] blocks and in the [TracBrowser repository browser].

  To do this, Trac uses external libraries with support for a great number of programming languages.

  Currently Trac supports syntax coloring using one or more of the following packages:

   * [http://pygments.pocoo.org/ Pygments], by far the preferred system, as it covers a wide range of programming languages and other structured texts and is actively supported
   * [http://www.codento.com/people/mtr/genscript/ GNU Enscript], commonly available on Unix but somewhat unsupported on Windows
   * [http://silvercity.sourceforge.net/ SilverCity], legacy system, some versions can be [http://trac.edgewall.org/wiki/TracFaq#why-is-my-css-code-not-being-highlighted-even-though-i-have-silvercity-installed problematic]


  To activate syntax coloring, simply install either one (or more) of these packages (see [#ExtraSoftware] section below).
  If none of these packages is available, Trac will display the data as plain text. 


  === About Pygments ===

  Starting with trac 0.11 [http://pygments.org/ pygments] will be the new default highlighter. It's a highlighting library implemented in pure python, very fast, easy to extend and [http://pygments.org/docs/ well documented].

  The Pygments default style can specified in the [TracIni#mimeviewer-section mime-viewer] section of trac.ini. The default style can be overridden by setting a Style preference on the [/prefs/pygments preferences page]. 

  It's very likely that the list below is outdated because the list of supported pygments lexers is growing weekly. Just have a look at the page of [http://pygments.org/docs/lexers/ supported lexers] on the pygments webpage.


  == Syntax Coloring Support ==

  === Known MIME Types

  [[KnownMimeTypes]]

  Note that the rich content may be directly //rendered// instead of syntax highlighted. This usually depends on which auxiliary packages are installed and on which components are activated in your setup. For example a `text/x-rst` document will be rendered via `docutils` if it is installed and the `trac.mimeview.rst.ReStructuredTextRenderer` is not disabled, and will be syntax highlighted otherwise.

  In a similar way, a document with the mimetype `text/x-trac-wiki` is rendered using the Trac wiki formatter, unless the `trac.mimeview.api.WikiTextRenderer` component is disabled.

  HTML documents are directly rendered only if the `render_unsafe_html` settings are enabled in the TracIni (those settings are present in multiple sections, as there are different security concerns depending where the document comes from). If you want to ensure that an HTML document gets syntax highlighted and not rendered, use the `text/xml` mimetype.

  If mimetype such as 'svn:mime-type' is set to 'text/plain', there is no coloring even if file is known type like 'java'.

  === List of Languages Supported, by Highlighter #language-supported

  This list is only indicative.

  ||                 ||= !SilverCity   =||= Enscript      =||= Pygments =||
  || Ada             ||                 ||  ✓              ||     ||
  || Asm             ||                 ||  ✓              ||     ||
  || Apache Conf     ||                 ||                 ||  ✓  ||
  || ASP             ||  ✓              ||  ✓              ||     ||
  || C               ||  ✓              ||  ✓              ||  ✓  ||
  || C#              ||                 ||  ✓ ^[#a1 (1)]^  ||  ✓  ||
  || C++             ||  ✓              ||  ✓              ||  ✓  ||
  || CMake           ||  ?              ||  ?              ||  ✓  ||
  || Java            ||  ✓ ^[#a2 (2)]^  ||  ✓              ||  ✓  ||
  || Awk             ||                 ||  ✓              ||     ||
  || Boo             ||                 ||                 ||  ✓  ||
  || CSS             ||  ✓              ||                 ||  ✓  ||
  || Python Doctests ||                 ||                 ||  ✓  ||
  || Diff            ||                 ||  ✓              ||  ✓  ||
  || Eiffel          ||                 ||  ✓              ||     ||
  || Elisp           ||                 ||  ✓              ||     ||
  || Fortran         ||                 ||  ✓ ^[#a1 (1)]^  ||  ✓  ||
  || Haskell         ||                 ||  ✓              ||  ✓  ||
  || Genshi          ||                 ||                 ||  ✓  ||
  || HTML            ||  ✓              ||  ✓              ||  ✓  ||
  || IDL             ||                 ||  ✓              ||     ||
  || INI             ||                 ||                 ||  ✓  ||
  || Javascript      ||  ✓              ||  ✓              ||  ✓  ||
  || Lua             ||                 ||                 ||  ✓  ||
  || m4              ||                 ||  ✓              ||     ||
  || Makefile        ||                 ||  ✓              ||  ✓  ||
  || Mako            ||                 ||                 ||  ✓  ||
  || Matlab ^[#a3 (3)]^  ||             ||  ✓              ||  ✓  ||
  || Mygthy          ||                 ||                 ||  ✓  ||
  || Objective-C     ||                 ||  ✓              ||  ✓  ||
  || OCaml           ||                 ||                 ||  ✓  ||
  || Pascal          ||                 ||  ✓              ||  ✓  ||
  || Perl            ||  ✓              ||  ✓              ||  ✓  ||
  || PHP             ||  ✓              ||                 ||  ✓  ||
  || PSP             ||  ✓              ||                 ||     ||
  || Pyrex           ||                 ||  ✓              ||     ||
  || Python          ||  ✓              ||  ✓              ||  ✓  ||
  || Ruby            ||  ✓              ||  ✓ ^[#a1 (1)]^  ||  ✓  ||
  || Scheme          ||                 ||  ✓              ||  ✓  ||
  || Shell           ||                 ||  ✓              ||  ✓  ||
  || Smarty          ||                 ||                 ||  ✓  ||
  || SQL             ||  ✓              ||  ✓              ||  ✓  ||
  || Troff           ||                 ||  ✓              ||  ✓  ||
  || TCL             ||                 ||  ✓              ||     ||
  || Tex             ||                 ||  ✓              ||  ✓  ||
  || Verilog         ||  ✓ ^[#a2 (2)]^  ||  ✓              ||     ||
  || VHDL            ||                 ||  ✓              ||     ||
  || Visual Basic    ||                 ||  ✓              ||  ✓  ||
  || VRML            ||                 ||  ✓              ||     ||
  || XML             ||  ✓              ||                 ||  ✓  ||



  ''[=#a1 (1)] Not included in the Enscript distribution.  Additional highlighting rules can be obtained for
  [http://neugierig.org/software/ruby/ Ruby],
  [http://wiki.hasno.info/index.php/Csharp.st C#],
  [http://wiki.hasno.info/index.php/F90.st Fortran 90x/2003]

  ''[=#a2 (2)] since Silvercity 0.9.7 released on 2006-11-23

  ''[=#a3 (3)] By default `.m` files are considered Objective-C files. In order to treat `.m` files as MATLAB files, add "text/matlab:m" to the "mime_map" setting in the [wiki:TracIni#mimeviewer-section "[mimeviewer] section of trac.ini"].

  == Extra Software ==
   * GNU Enscript — http://directory.fsf.org/GNU/enscript.html
   * GNU Enscript for Windows — http://gnuwin32.sourceforge.net/packages/enscript.htm
   * !SilverCity — http://silvercity.sf.net/
   * **Pygments — http://pygments.org/**

  ----
  See also: WikiProcessors, WikiFormatting, TracWiki, TracBrowser


name: TracModWSGI
author: trac
ipnr: 127.0.0.1
text:
  = Trac and mod_wsgi =


  [http://code.google.com/p/modwsgi/ mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of the Apache webserver. The mod_wsgi adapter is written completely in C and provides very good performances.

  [[PageOutline(2-3,Overview,inline)]]

  == The `trac.wsgi` script

  Trac can be run on top of mod_wsgi with the help of the following application script, which is just a Python file, though usually saved with a `.wsgi` extension). 

  === A very basic script
  In its simplest form, the script could be:

  {{{#!python
  import os

  os.environ['TRAC_ENV'] = '/usr/local/trac/mysite'
  os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'

  import trac.web.main
  application = trac.web.main.dispatch_request
  }}}

  The `TRAC_ENV` variable should naturally be the directory for your Trac environment (if you have several Trac environments in a directory, you can also use `TRAC_ENV_PARENT_DIR` instead), while the `PYTHON_EGG_CACHE` should be a directory where Python can temporarily extract Python eggs.

  === A more elaborate script

  If you're using multiple `.wsgi` files (for example one per Trac environment) you must ''not'' use `os.environ['TRAC_ENV']` to set the path to the Trac environment. Using this method may lead to Trac delivering the content of another Trac environment, as the variable may be filled with the path of a previously viewed Trac environment. 

  To solve this problem, use the following `.wsgi` file instead:
  {{{#!python
  import os

  os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'

  import trac.web.main
  def application(environ, start_response):
    environ['trac.env_path'] = '/usr/local/trac/mysite' 
    return trac.web.main.dispatch_request(environ, start_response)
  }}}

  For clarity, you should give this file a `.wsgi` extension. You should probably put the file in its own directory, since you will expose it to Apache. 

  If you have installed Trac and eggs in a path different from the standard one you should add that path by adding the following code at the top of the wsgi script:

  {{{#!python
  import site
  site.addsitedir('/usr/local/trac/lib/python2.4/site-packages')
  }}}

  Change it according to the path you installed the Trac libs at.

  === Recommended `trac.wsgi` script

  A somewhat robust and generic version of this file can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths (see TracInstall#cgi-bin).


  == Mapping requests to the script

  After you've done preparing your .wsgi script, add the following to your Apache configuration file (`httpd.conf` for example).

  {{{
  WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi

  <Directory /usr/local/trac/mysite/apache>
      WSGIApplicationGroup %{GLOBAL}
      Order deny,allow
      Allow from all
  </Directory>
  }}}

  Here, the script is in a subdirectory of the Trac environment.

  If you followed the directions [http://trac.edgewall.org/wiki/TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:

  {{{
  WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi

  <Directory /usr/share/trac/cgi-bin>
      WSGIApplicationGroup %{GLOBAL}
      Order deny,allow
      Allow from all
  </Directory>
  }}}

  In order to let Apache run the script, access to the directory in which the script resides is opened up to all of Apache. Additionally, the `WSGIApplicationGroup` directive ensures that Trac is always run in the first Python interpreter created by mod_wsgi; this is necessary because the Subversion Python bindings, which are used by Trac, don't always work in other sub-interpreters and may cause requests to hang or cause Apache to crash as a result. After adding this configuration, restart Apache, and then it should work.

  To test the setup of Apache, mod_wsgi and Python itself (ie. without involving Trac and dependencies), this simple wsgi application can be used to make sure that requests gets served (use as only content in your `.wsgi` script):

  {{{#!python
  def application(environ, start_response):
          start_response('200 OK',[('Content-type','text/html')])
          return ['<html><body>Hello World!</body></html>']
  }}}

  For more information about using the mod_wsgi specific directives, see the [http://code.google.com/p/modwsgi/wiki/ mod_wsgi's wiki] and more specifically the [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac IntegrationWithTrac] page.


  == Configuring Authentication

  We describe in the the following sections different methods for setting up authentication.

  See also [http://httpd.apache.org/docs/2.2/howto/auth.html Authentication, Authorization and Access Control] in the Apache guide.

  === Using Basic Authentication ===

  The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program to create the password file:
  {{{
  $ htpasswd -c /somewhere/trac.htpasswd admin
  New password: <type password>
  Re-type new password: <type password again>
  Adding password for user admin
  }}}

  After the first user, you dont need the "-c" option anymore:
  {{{
  $ htpasswd /somewhere/trac.htpasswd john
  New password: <type password>
  Re-type new password: <type password again>
  Adding password for user john
  }}}

    ''See the man page for `htpasswd` for full documentation.''

  After you've created the users, you can set their permissions using TracPermissions.

  Now, you'll need to enable authentication against the password file in the Apache configuration:
  {{{
  <Location "/trac/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /somewhere/trac.htpasswd
    Require valid-user
  </Location>
  }}}

  If you're hosting multiple projects you can use the same password file for all of them:
  {{{
  <LocationMatch "/trac/[^/]+/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /somewhere/trac.htpasswd
    Require valid-user
  </LocationMatch>
  }}}
  Note that neither a file nor a directory named 'login' needs to exist.[[BR]]
  See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html mod_auth_basic] documentation.

  === Using Digest Authentication ===

  For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”. 

  You'll have to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows:
  {{{
  # htdigest -c /somewhere/trac.htpasswd trac admin
  }}}

  The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive:

  {{{
  <Location "/trac/login">

      AuthType Digest
      AuthName "trac"
      AuthDigestDomain /trac
      AuthUserFile /somewhere/trac.htpasswd
      Require valid-user
  </Location>
  }}}

  For multiple environments, you can use the same `LocationMatch` as described with the previous method.

  Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system:
  {{{
      LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
  }}}


  See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_digest.html mod_auth_digest] documentation.

  === Using LDAP Authentication 

  Configuration for [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap] authentication in Apache is a bit tricky (httpd 2.2.x and OpenLDAP: slapd 2.3.19)

  1. You need to load the following modules in Apache httpd.conf
  {{{
  LoadModule ldap_module modules/mod_ldap.so
  LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
  }}}

  2. Your httpd.conf also needs to look something like:

  {{{
  <Location /trac/>
    # (if you're using it, mod_python specific settings go here)
    Order deny,allow
    Deny from all
    Allow from 192.168.11.0/24
    AuthType Basic
    AuthName "Trac"
    AuthBasicProvider "ldap"
    AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=co,dc=ke?uid?sub?(objectClass=inetOrgPerson)"
    authzldapauthoritative Off
    Require valid-user
  </Location>
  }}}


  3. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory:


  Use the following as your LDAP URL:
  {{{
      AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)"
  }}}

  You will also need to provide an account for Apache to use when checking
  credentials. As this password will be listed in plaintext in the
  config, you should be sure to use an account specifically for this task:
  {{{
      AuthLDAPBindDN ldap-auth-user@example.com
      AuthLDAPBindPassword "password"
  }}}

  The whole section looks like:
  {{{
  <Location /trac/>
    # (if you're using it, mod_python specific settings go here)
    Order deny,allow
    Deny from all
    Allow from 192.168.11.0/24
    AuthType Basic
    AuthName "Trac"
    AuthBasicProvider "ldap"
    AuthLDAPURL "ldap://adserver.company.com:3268/DC=company,DC=com?sAMAccountName?sub?(objectClass=user)"
    AuthLDAPBindDN       ldap-auth-user@company.com
    AuthLDAPBindPassword "the_password"
    authzldapauthoritative Off
    # require valid-user
    require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
  </Location>
  }}}

  Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to Global Catalog Server portion of AD (Notice the port is 3268, not the normal LDAP 389). The GCS is basically a "flattened" tree which allows searching for a user without knowing to which OU they belong.

  Note 2: You can also require the user be a member of a certain LDAP group, instead of
  just having a valid login:
  {{{
      Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com
  }}}

  See also:
    - [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap
      
   - [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap], documentation for mod_ldap, which provides connection pooling and a shared cache.
   - [http://trac-hacks.org/wiki/LdapPlugin TracHacks:LdapPlugin] for storing TracPermissions in LDAP.

  === Using SSPI Authentication

  If you are using Apache on Windows, you can use mod_auth_sspi to provide
  single-sign-on. Download the module from the !SourceForge [http://sourceforge.net/projects/mod-auth-sspi/ mod-auth-sspi project] and then add the
  following to your !VirtualHost:
  {{{
      <Location /trac/login>
          AuthType SSPI
          AuthName "Trac Login"
          SSPIAuth On
          SSPIAuthoritative On
          SSPIDomain MyLocalDomain
          SSPIOfferBasic On
          SSPIOmitDomain Off
          SSPIBasicPreferred On
          Require valid-user
      </Location>
  }}}

  Using the above, usernames in Trac will be of the form `DOMAIN\username`, so
  you may have to re-add permissions and such. If you do not want the domain to
  be part of the username, set `SSPIOmitDomain On` instead.

  Some common problems with SSPI authentication: [trac:#1055], [trac:#1168] and [trac:#3338].

  See also [trac:TracOnWindows/Advanced].

  === Using Apache authentication with the Account Manager plugin's Login form ===

  To begin with, see the basic instructions for using the Account Manager plugin's [http://trac-hacks.org/wiki/AccountManagerPlugin/Modules#LoginModule Login module] and its [http://trac-hacks.org/wiki/AccountManagerPlugin/AuthStores#HttpAuthStore HttpAuthStore authentication module].

  '''Note:''' If is difficult to get !HttpAuthStore to work with WSGI when using any Account Manager version prior to acct_mgr-0.4. Upgrading is recommended.

  Here is an example (from the !HttpAuthStore link) using acct_mgr-0.4 for hosting a single project:
  {{{
  [components]
  ; be sure to enable the component
  acct_mgr.http.HttpAuthStore = enabled

  [account-manager]
  ; configure the plugin to use a page that is secured with http authentication
  authentication_url = /authFile
  password_store = HttpAuthStore
  }}}
  This will generally be matched with an Apache config like:
  {{{
  <Location /authFile>
     …HTTP authentication configuration…
     Require valid-user
  </Location>
  }}}
  Note that '''authFile''' need not exist. See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server.

  === Example: Apache/mod_wsgi with Basic Authentication, Trac being at the root of a virtual host

  Per the mod_wsgi documentation linked to above, here is an example Apache configuration that a) serves the Trac instance from a virtualhost subdomain and b) uses Apache basic authentication for Trac authentication.


  If you want your Trac to be served from e.g. !http://trac.my-proj.my-site.org, then from the folder e.g. `/home/trac-for-my-proj`, if you used the command `trac-admin the-env initenv` to create a folder `the-env`, and you used `trac-admin the-env deploy the-deploy` to create a folder `the-deploy`, then first:

  Create the htpasswd file:
  {{{
  cd /home/trac-for-my-proj/the-env
  htpasswd -c htpasswd firstuser
  ### and add more users to it as needed:
  htpasswd htpasswd seconduser
  }}}
  (keep the file above your document root for security reasons)

  Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following contents:

  {{{
  <Directory /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi>
    WSGIApplicationGroup %{GLOBAL}
    Order deny,allow
    Allow from all
  </Directory>

  <VirtualHost *:80>
    ServerName trac.my-proj.my-site.org
    DocumentRoot /home/trac-for-my-proj/the-env/htdocs/
    WSGIScriptAlias / /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi
    <Location '/'>
      AuthType Basic
      AuthName "Trac"
      AuthUserFile /home/trac-for-my-proj/the-env/htpasswd
      Require valid-user
    </Location>
  </VirtualHost>

  }}}

  Note: for subdomains to work you would probably also need to alter `/etc/hosts` and add A-Records to your host's DNS.


  == Troubleshooting

  === Use a recent version

  Please use either version 1.6, 2.4 or later of `mod_wsgi`. Versions prior to 2.4 in the 2.X branch have problems with some Apache configurations that use WSGI file wrapper extension. This extension is used in Trac to serve up attachments and static media files such as style sheets. If you are affected by this problem attachments will appear to be empty and formatting of HTML pages will appear not to work due to style sheet files not loading properly. Another frequent symptom is that binary attachment downloads are truncated. See mod_wsgi tickets [http://code.google.com/p/modwsgi/issues/detail?id=100 #100] and [http://code.google.com/p/modwsgi/issues/detail?id=132 #132].

  ''Note: using mod_wsgi 2.5 and Python 2.6.1 gave an Internal Server Error on my system (Apache 2.2.11 and Trac 0.11.2.1). Upgrading to Python 2.6.2 (as suggested [http://www.mail-archive.com/modwsgi@googlegroups.com/msg01917.html here]) solved this for me[[BR]]-- Graham Shanks''

  If you plan to use `mod_wsgi` in embedded mode on Windows or with the MPM worker on Linux, then you'll even need version 0.3.4 or greater (see [trac:#10675] for details).

  === Getting Trac to work nicely with SSPI and 'Require Group' ===
  If like me you've set Trac up on Apache, Win32 and configured SSPI, but added a 'Require group' option to your apache configuration, then the SSPIOmitDomain option is probably not working.  If its not working your usernames in trac are probably looking like 'DOMAIN\user' rather than 'user'.

  This WSGI script 'fixes' things, hope it helps:
  {{{#!python
  import os
  import trac.web.main

  os.environ['TRAC_ENV'] = '/usr/local/trac/mysite'
  os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'

  def application(environ, start_response):
      if "\\" in environ['REMOTE_USER']:
          environ['REMOTE_USER'] = environ['REMOTE_USER'].split("\\", 1)[1]
      return trac.web.main.dispatch_request(environ, start_response)
  }}}


  === Trac with PostgreSQL ===

  When using the mod_wsgi adapter with multiple Trac instances and PostgreSQL (or MySQL?) as a database back-end, the server ''may'' create a lot of open database connections and thus PostgreSQL processes.

  A somewhat brutal workaround is to disabled connection pooling in Trac. This is done by setting `poolable = False` in `trac.db.postgres_backend` on the `PostgreSQLConnection` class.

  But it's not necessary to edit the source of Trac, the following lines in `trac.wsgi` will also work:

  {{{
  import trac.db.postgres_backend
  trac.db.postgres_backend.PostgreSQLConnection.poolable = False
  }}}

  or

  {{{
  import trac.db.mysql_backend
  trac.db.mysql_backend.MySQLConnection.poolable = False
  }}}

  Now Trac drops the connection after serving a page and the connection count on the database will be kept minimal.

  //This is not a recommended approach though. See also the notes at the bottom of the [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac mod_wsgi's IntegrationWithTrac] wiki page.//

  === Other resources

  For more troubleshooting tips, see also the [TracModPython#Troubleshooting mod_python troubleshooting] section, as most Apache-related issues are quite similar, plus discussion of potential [http://code.google.com/p/modwsgi/wiki/ApplicationIssues application issues] when using mod_wsgi. The wsgi page also has a [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac Integration With Trac] document.


  ----
  See also:  TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]


name: TracWiki
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Wiki System =
  [[TracGuideToc]]

  Trac has a built-in wiki system which you can use for organizing knowledge and information in a very flexible way by [WikiNewPage creating pages] containing an intuitive and easy to learn textual markup. This text markup is also used in all other parts of the system, not only in [wiki:TitleIndex wiki pages], but also in [wiki:TracTickets ticket] description and comments, [wiki:TracChangeset check-in log messages], [wiki:TracRoadmap milestone] descriptions and [wiki:TracReports report] descriptions, even in third-party extensions.
  It allows for formatted text and hyperlinks in and between all Trac modules.

  Editing wiki text is easy, using any web browser and a simple [WikiFormatting formatting system], rather than more complex markup languages like HTML.  The reasoning behind its design is that HTML, with its large collection of nestable tags, is too complicated to allow fast-paced editing, and distracts from the actual content of the pages. Note though that Trac also supports [WikiHtml HTML], [WikiRestructuredText reStructuredText] and [http://www.textism.com/tools/textile/ Textile] as alternative markup formats, which can eventually be used in parts of a page (so called wiki “blocks”).

  The main goal of the wiki is to make editing text easier and ''encourage'' people to contribute and annotate text content for a project. Trac also provides a simple toolbar to make formatting text even easier, and supports the [http://universaleditbutton.org/Universal_Edit_Button universal edit button] of your browser.

  The wiki itself does not enforce any structure, but rather resembles a stack of empty sheets of paper, where you can organize information and documentation as you see fit, and later reorganize if necessary. 
  As contributing to a wiki is essentially building hypertext, 
  general advice regarding HTML authoring apply here as well.
  For example, the ''[http://www.w3.org/Provider/Style Style Guide for online hypertext]'' explains how to think about the
  [http://www.w3.org/Provider/Style/Structure.html overall structure of a work] 
  and how to organize information [http://www.w3.org/Provider/Style/WithinDocument.html within each document]. One of the most important tip is “make your HTML page such that you can read it even if you don't follow any links.”

  Learn more about:
   * WikiFormatting rules, including advanced topics like WikiMacros and WikiProcessors
   * How to use WikiPageNames and other forms of TracLinks which are used to refer in a precise way to any resource within Trac

  If you want to practice editing, please use the SandBox. Note that not all Trac wikis are editable by anyone, this depends on the local policy; check with your Trac administrators.

  Before saving your changes, you can ''Preview'' the page or ''Review the Changes'' you've made.
  You can get an automatic preview of the formatting as you type when you activate the ''Edit Side-by-side'' mode (you have to Preview the page for the setting to take effect). '' There is a [wiki:/TracIni#trac-section configurable delay] between when you make your edit and when the automatic preview will update.''

  Some more information about wikis on the web:
   * A definition of [http://wikipedia.org/wiki/Wiki Wiki], in a famous wiki encyclopedia
   * The [http://c2.com/cgi/wiki?WikiHistory History] of the original wiki
   * A wiki page explaining [http://www.usemod.com/cgi-bin/mb.pl?WhyWikiWorks why wiki works]

  ----
  See also: TracGuide


name: TracLogging
author: trac
ipnr: 127.0.0.1
text:
  = Trac Logging =
  [[TracGuideToc]]

  Trac supports logging of system messages using the standard [http://docs.python.org/library/logging.html logging module] that comes with Python.

  Logging is configured in the `[logging]` section in [wiki:TracIni#logging-section trac.ini].

  == Supported Logging Methods ==

  The log method is set using the `log_type` option in [wiki:TracIni#logging-section trac.ini], which takes any of the following values:

   '''none'':: Suppress all log messages.
   '''file''':: Log messages to a file, specified with the `log_file` option in [wiki:TracIni#logging-section trac.ini]. Relative paths in `log_file` are resolved relative to the `log` directory of the environment.
   '''stderr''':: Output all log entries to console ([wiki:TracStandalone tracd] only).
   '''syslog''':: (UNIX) Send all log messages to the local syslogd via named pipe `/dev/log`. By default, syslog will write them to the file /var/log/messages.
   '''eventlog''':: (Windows) Use the system's NT Event Log for Trac logging.

  == Log Levels ==

  The verbosity level of logged messages can be set using the `log_level` option in [wiki:TracIni#logging-section trac.ini]. The log level defines the minimum level of urgency required for a message to be logged, and those levels are:

   '''CRITICAL''':: Log only the most critical (typically fatal) errors.
   '''ERROR''':: Log failures, bugs and errors. 
   '''WARN''':: Log warnings, non-interrupting events.
   '''INFO''':: Diagnostic information, log information about all processing.
   '''DEBUG''':: Trace messages, profiling, etc.

  Note that starting with Trac 0.11.5 you can in addition enable logging of SQL statements, at debug level. This is turned off by default, as it's very verbose (set `[trac] debug_sql = yes` in TracIni to activate).

  == Log Format ==

  Starting with Trac 0.10.4 (see [trac:#2844 #2844]), it is possible to set the output format for log entries. This can be done through the `log_format` option in [wiki:TracIni#logging-section trac.ini]. The format is a string which can contain any of the [http://docs.python.org/library/logging.html#logrecord-attributes Python logging Formatter variables]. Additonally, the following Trac-specific variables can be used:
   '''$(basename)s''':: The last path component of the current environment.
   '''$(path)s''':: The absolute path for the current environment.
   '''$(project)s''':: The originating project's name.

  Note that variables are identified using a dollar sign (`$(...)s`) instead of percent sign (`%(...)s`).

  The default format is:
  {{{
  log_format = Trac[$(module)s] $(levelname)s: $(message)s
  }}}

  In a multi-project environment where all logs are sent to the same place (e.g. `syslog`), it makes sense to add the project name. In this example we use `basename` since that can generally be used to identify a project:
  {{{
  log_format = Trac[$(basename)s:$(module)s] $(levelname)s: $(message)s
  }}}

  ----
  See also: TracIni, TracGuide, TracEnvironment


name: WikiFormatting
author: trac
ipnr: 127.0.0.1
text:
  = WikiFormatting =
  [[TracGuideToc]]

  Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and powerful whole.

  Trac has a built in small and powerful wiki rendering engine. This wiki engine implements an ever growing subset of the commands from other popular Wikis,
  especially [http://moinmo.in/ MoinMoin] and [trac:WikiCreole].


  This page will give you an in-depth explanation of the wiki markup available anywhere WikiFormatting is allowed.

  The ''Cheat sheet'' below gives you a quick overview for the most common syntax, each link in the ''Category'' column will lead you to the more detailed explanation later in this page.

  A few other wiki pages present the advanced features of the Trac wiki markup in more depth: 
   - TracLinks covers all the possible ways to refer precisely to any Trac resource or parts thereof,
   - WikiPageNames talks about the various names a wiki page can take, CamelCase or not
   - WikiMacros lists the macros available for generating dynamic content,
   - WikiProcessors and WikiHtml details how parts of the wiki text can be processed in special ways


  == Cheat sheet ==

  ||= '''Category''' =||= '''Wiki Markup''' =||= '''Display''' =||
  |-----------------------------------------------------------
  {{{#!th rowspan=3
  [#FontStyles Font Styles]
  }}}
  || `'''bold'''`, `''italic''`, `'''''Wikipedia style'''''` || \
  || '''bold''', ''italic'', '''''Wikipedia style''''' ||
  || {{{`monospaced (''other markup ignored'')`}}} || \
  || `monospaced (''other markup ignored'')` ||
  || `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \
  || **bold**, //italic//, **//!WikiCreole style//** ||
  |-----------------------------------------------------------
  ||= [#Headings Headings] =||\
  {{{#!td 
   {{{
   == Level 2 ==
   === Level 3 ^([#hn note])^
   }}}
  }}}
  {{{#!td style="padding-left: 2em"
  == Level 2 ==
  === Level 3 ^([#hn note])^
  }}}
  |-----------------------------------------------------------
  ||= [#Paragraphs Paragraphs]  =||\
  {{{#!td
   {{{
   First paragraph
   on multiple lines.

   Second paragraph.
   }}}
  }}}
  {{{#!td
  First paragraph
  on multiple lines.

  Second paragraph.
  }}}
  |-----------------------------------------------------------
  ||= [#Lists Lists] =||\
  {{{#!td
   {{{
   * bullets list
     on multiple lines
     1. nested list
       a. different numbering 
          styles
   }}}
  }}}
  {{{#!td
  * bullets list
    on multiple lines
    1. nested list
      a. different numbering
         styles
  }}}
  |-----------------------------------------------------------
  {{{#!th
  [#DefinitionLists Definition Lists]
  }}}
  {{{#!td
   {{{
    term:: definition on
           multiple lines
   }}}
  }}}
  {{{#!td
   term:: definition on
          multiple lines
  }}}
  |-----------------------------------------------------------
  ||= [#PreformattedText Preformatted Text] =||\
  {{{#!td
   {{{
   {{{
   multiple lines, ''no wiki''
         white space respected
   }}}
   }}}
  }}}
  {{{#!td
   {{{
   multiple lines, ''no wiki''
         white space respected
   }}}
  }}}
  |-----------------------------------------------------------
  ||= [#Blockquotes Blockquotes] =||\
  {{{#!td
   {{{
     if there's some leading
     space the text is quoted
   }}}
  }}}
  {{{#!td
   if there's some leading
   space the text is quoted
  }}}
  |-----------------------------------------------------------
  ||= [#DiscussionCitations Discussion Citations] =||\
  {{{#!td
   {{{
   >> ... (I said)
   > (he replied)
   }}}
  }}}
  {{{#!td
  >>... (I said)
  > (he replied)
  }}}
  |-----------------------------------------------------------
  ||= [#Tables Tables] =||\
  {{{#!td
   {{{
   ||= Table Header =|| Cell ||
   ||||  (details below)  ||
   }}}
  }}}
  {{{#!td
  ||= Table Header =|| Cell ||
  ||||  (details below)  ||
  }}}
  |-----------------------------------------------------------
  {{{#!th rowspan=2
  [#Links Links]
  }}}
  || `http://trac.edgewall.org` ||\
  || http://trac.edgewall.org ||
  || `WikiFormatting (CamelCase)` ||\
  || WikiFormatting (CamelCase) ||
  |-----------------------------------------------------------
  {{{#!th rowspan=5
  [#TracLinks TracLinks]
  }}}
  || `wiki:WikiFormatting`, `wiki:"WikiFormatting"` ||\
  || wiki:WikiFormatting, wiki:"WikiFormatting" ||
  || `#1 (ticket)`, `[1] (changeset)`, `{1} (report)` ||\
  || #1 (ticket), [1] (changeset), {1} (report) ||
  || `ticket:1, ticket:1#comment:1` ||\
  || ticket:1, ticket:1#comment:1 ||
  || `Ticket [ticket:1]`, `[ticket:1 ticket one]` ||\
  || Ticket [ticket:1], [ticket:1 ticket one] ||
  || `Ticket [[ticket:1]]`, `[[ticket:1|ticket one]]` ||\
  || Ticket [[ticket:1]], [[ticket:1|ticket one]] ||
  |-----------------------------------------------------------
  {{{#!th rowspan=2 
  [#SettingAnchors Setting Anchors]
  }}}
  || `[=#point1 (1)] First...` ||\
  || [=#point1 (1)] First... ||
  || `see [#point1 (1)]` ||\
  || see [#point1 (1)] ||
  |-----------------------------------------------------------
  {{{#!th rowspan=3
  [#Escaping Escaping Markup]
  }}}
  || `!'' doubled quotes` ||\
  || !'' doubled quotes ||
  || `!wiki:WikiFormatting`, `!WikiFormatting` ||\
  || !wiki:WikiFormatting, !WikiFormatting ||
  || {{{`}}}`{{{-}}}`{{{`}}}` triple curly brackets` ||\
  || `{{{-}}}` triple curly brackets ||
  |-----------------------------------------------------------
  ||= [#Images Images] =|| `[[Image(`''link''`)]]` || [[Image(htdocs:../common/trac_logo_mini.png)]] ||
  |-----------------------------------------------------------
  {{{#!th rowspan=2
  [#Macros Macros]
  }}}
  || `[[MacroList(*)]]` ||  ''(short list of all available macros)''  ||
  || `[[Image?]]` ||  ''(help for the Image macro)''  ||
  |-----------------------------------------------------------
  ||= [#Processors Processors] =||\
  {{{#!td
   {{{
   {{{
   #!div style="font-size: 80%"
   Code highlighting:
     {{{#!python
     hello = lambda: "world"
     }}}
   }}}
   }}}
  }}}
  {{{#!td style="padding-left: 2em"
   {{{
   #!div style="font-size: 80%"
   Code highlighting:
     {{{#!python 
     hello = lambda: "world"
     }}}
   }}}
  }}}
  |-----------------------------------------------------------
  ||= [#Comments Comments] =||\
  {{{#!td
   {{{
   {{{#!comment
   Note to Editors: ...
   }}}
   }}}
  }}}
  {{{#!td style="padding-left: 2em"
   {{{#!comment
   Note to Editors: ...
   }}}
  }}}
  |-----------------------------------------------------------
  ||= [#Miscellaneous Miscellaneous] =||\
  {{{#!td
   {{{
   Line [[br]] break 
   Line \\ break
   ----
   }}}
  }}}
  {{{#!td style="padding-left: 2em"
  Line [[br]] break
  Line \\ break
  ----
  }}}


  == Font Styles ==

  The Trac wiki supports the following font styles:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     * '''bold''', 
       ''' triple quotes !''' 
       can be bold too if prefixed by ! ''', 
     * ''italic''
     * '''''bold italic''''' or ''italic and
       ''' italic bold ''' ''
     * __underline__
     * {{{monospace}}} or `monospace`
       (hence `{{{` or {{{`}}} quoting)
     * ~~strike-through~~
     * ^superscript^ 
     * ,,subscript,,
     * **also bold**, //italic as well//, 
       and **'' bold italic **'' //(since 0.12)//
    }}}
  }}}
  {{{#!td
   * '''bold''', 
     ''' triple quotes !''' 
     can be bold too if prefixed by ! ''', 
   * ''italic''
   * '''''bold italic''''' or ''italic and
     ''' italic bold ''' ''
   * __underline__
   * {{{monospace}}} or `monospace`
     (hence `{{{` or {{{`}}} quoting)
   * ~~strike-through~~
   * ^superscript^ 
   * ,,subscript,,
   * **also bold**, //italic as well//, 
     and **'' bold italic **'' //(since 0.12)//
  }}}

  Notes:
   * `{{{...}}}` and {{{`...`}}} commands not only select a monospace font, but also treat their content as verbatim text, meaning that no further wiki processing is done on this text.
   * {{{ ! }}} tells wiki parser to not take the following characters as wiki format, so pay attention to put a space after !, e.g. when ending bold.
   * all the font styles marks have to be used in opening/closing pairs, 
     and they must nest properly (in particular, an `''` italic can't be paired 
     with a `//` one, and `'''` can't be paired with `**`)


  == Headings ==

  You can create heading by starting a line with one up to six ''equal'' characters ("=")
  followed by a single space and the headline text. 

  [=#hn]
  The headline text can be followed by the same number of "=" characters, but this is no longer mandatory.

  Finally, the heading might optionally be followed by an explicit id. If not, an implicit but nevertheless readable id will be generated.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    = Heading =
    == Subheading
    === About ''this'' ===
    === Explicit id === #using-explicit-id-in-heading
    == Subheading #sub2
  }}}
  }}}
  {{{#!td style="padding: 1em;"
    {{{
    #!div
    = Heading =
    == Subheading
    === About ''this'' ===
    === Explicit id === #using-explicit-id-in-heading
    == Subheading #sub2
    }}}
  }}}

  == Paragraphs ==

  A new text paragraph is created whenever two blocks of text are separated by one or more empty lines.

  A forced line break can also be inserted, using:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    Line 1[[BR]]Line 2
    }}}
    {{{
    Paragraph
    one

    Paragraph 
    two
    }}}
  }}}
  {{{#!td
    Line 1[[BR]]Line 2

    Paragraph 
    one

    Paragraph 
    two
  }}}

  == Lists ==

  The wiki supports both ordered/numbered and unordered lists.

  Example:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     * Item 1
       * Item 1.1
          * Item 1.1.1   
          * Item 1.1.2
          * Item 1.1.3
       * Item 1.2
     * Item 2
    - items can start at the beginning of a line
      and they can span multiple lines
      - be careful though to continue the line 
      with the appropriate indentation, otherwise
    that will start a new paragraph...
    
     1. Item 1
       a. Item 1.a
       a. Item 1.b
          i. Item 1.b.i
          i. Item 1.b.ii
     1. Item 2
    And numbered lists can also be restarted
    with an explicit number:
     3. Item 3
    }}}
  }}}
  {{{#!td
   * Item 1
     * Item 1.1
        * Item 1.1.1   
        * Item 1.1.2
        * Item 1.1.3
     * Item 1.2
   * Item 2
  - items can start at the beginning of a line
    and they can span multiple lines
    - be careful though to continue the line 
    with the appropriate indentation, otherwise
  that will start a new paragraph...

   1. Item 1
     a. Item 1.a
     a. Item 1.b
        i. Item 1.b.i
        i. Item 1.b.ii
   1. Item 2
  And numbered lists can also be restarted with an explicit number:
   3. Item 3
  }}}


  == Definition Lists ==

  The wiki also supports definition lists.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     llama::
       some kind of mammal, with hair
     ppython::
       some kind of reptile, without hair
       (can you spot the typo?)
    }}}
  }}}
  {{{#!td
   llama::
     some kind of mammal, with hair
   ppython::
     some kind of reptile, without hair
     (can you spot the typo?)
  }}}

  Note that you need a space in front of the defined term.


  == Preformatted Text ==

  Block containing preformatted text are suitable for source code snippets, notes and examples. Use three ''curly braces'' wrapped around the text to define a block quote. The curly braces need to be on a separate line.
    
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    {{{
    def HelloWorld():
        print '''Hello World'''
    }}}
    }}}
  }}}
  {{{#!td
    {{{
    def HelloWorld():
        print '''Hello World'''
    }}}
  }}}

  Note that this kind of block is also used for selecting lines that should be processed through WikiProcessors.

  == Blockquotes ==

  In order to mark a paragraph as blockquote, indent that paragraph with two spaces.

  ||= Wiki Markup =||= Display =||
  {{{#!td
  {{{
  Paragraph
    This text is a quote from someone else.
  }}}
  }}}
  {{{#!td
  Paragraph
    This text is a quote from someone else.
  }}}

  == Discussion Citations ==

  To delineate a citation in an ongoing discussion thread, such as the ticket comment area, e-mail-like citation marks (">", ">>", etc.) may be used.  

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    >> Someone's original text
    > Someone else's reply text
    >  - which can be any kind of Wiki markup
    My reply text
    }}}
  }}}
  {{{#!td
  >> Someone's original text
  > Someone else's reply text
  >  - which can be any kind of Wiki markup
  My reply text
  }}}


  == Tables ==
  === Simple Tables ===
  Simple tables can be created like this:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    ||Cell 1||Cell 2||Cell 3||
    ||Cell 4||Cell 5||Cell 6||
    }}}
  }}}
  {{{#!td style="padding: 2em;"
  ||Cell 1||Cell 2||Cell 3||
  ||Cell 4||Cell 5||Cell 6||
  }}}

  Cell headings can be specified by wrapping the content in a pair of '=' characters.
  Note that the '=' characters have to stick to the cell separators, like this:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    ||        ||= stable =||= latest =||
    ||= 0.10 =||  0.10.5  || 0.10.6dev||
    ||= 0.11 =||  0.11.6  || 0.11.7dev||
    }}}
  }}}
  {{{#!td style="padding: 2em;"
  ||        ||= stable =||= latest =||
  ||= 0.10 =||  0.10.5  || 0.10.6dev||
  ||= 0.11 =||  0.11.6  || 0.11.7dev||
  }}}

  Finally, specifying an empty cell means that the next non empty cell will span the empty cells. For example:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    || 1 || 2 || 3 ||
    |||| 1-2 || 3 ||
    || 1 |||| 2-3 ||
    |||||| 1-2-3 ||
    }}}
  }}}
  {{{#!td style="padding: 2em;"
  || 1 || 2 || 3 ||
  |||| 1-2 || 3 ||
  || 1 |||| 2-3 ||
  |||||| 1-2-3 ||
  }}}

  Note that if the content of a cell "sticks" to one side of the cell and only one, then the text will be aligned on that side. Example:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    ||=Text =||= Numbers =||
    ||left align    ||        1.0||
    ||  center      ||        4.5||
    ||      right align||     4.5||
    || default alignment ||   2.5||
    ||default||         2.5||
    ||  default ||      2.5||
    || default ||       2.5||
    }}}
  }}}
  {{{#!td style="padding: 2em;"
  ||=Text =||= Numbers =||
  ||left align    ||        1.0||
  ||  center      ||        4.5||
  ||      right align||     4.5||
  || default alignment ||   2.5||
  ||default||         2.5||
  ||  default ||      2.5||
  || default ||       2.5||
  }}}

  If contrary to the example above, the cells in your table contain more text, it might be convenient to spread a table row over multiple lines of markup. The `\` character placed at the end of a line after a cell separator tells Trac to not start a new row for the cells on the next line.

  ||= Wiki Markup =||
  {{{#!td
    {{{
    || this is column 1 [http://trac.edgewall.org/newticket new ticket] || \
    || this is column 2 [http://trac.edgewall.org/roadmap the road ahead] || \
    || that's column 3 and last one ||
    }}}
  }}}
  |-------------
  ||= Display =||
  {{{#!td style="padding: 2em;"
  || this is column 1 [http://trac.edgewall.org/newticket new ticket] || \
  || this is column 2 [http://trac.edgewall.org/roadmap the road ahead] || \
  || that's column 3 and last one ||
  }}}

  === Complex Tables ===

  If the possibilities offered by the simple "pipe"-based markup for tables described above are not enough for your needs, you can create more elaborated tables by using [#Processors-example-tables WikiProcessor based tables].


  == Links ==

  Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark "!" character, such as {{{!WikiPageLink}}}.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    TitleIndex, http://www.edgewall.com/, !NotAlink
    }}}
  }}}
  {{{#!td
  TitleIndex, http://www.edgewall.com/, !NotAlink
  }}}

  Links can be given a more descriptive title by writing the link followed by a space and a title and all this inside square brackets. 
  If the descriptive title is omitted, then the explicit prefix is discarded, unless the link is an external link. This can be useful for wiki pages not adhering to the WikiPageNames convention.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     * [http://www.edgewall.com Edgewall Software]
     * [wiki:TitleIndex Title Index] 
     * [wiki:TitleIndex] 
     * [wiki:ISO9000]
    }}}
  }}}
  {{{#!td
     * [http://www.edgewall.com Edgewall Software]
     * [wiki:TitleIndex Title Index] 
     * [wiki:TitleIndex] 
     * [wiki:ISO9000]
  }}}

  Following the [trac:WikiCreole] trend, the descriptive title can also be specified by writing the link followed by a pipe ('|') and a title and all this inside //double// square brackets. 

  {{{#!td
    {{{
     * [[http://www.edgewall.com|Edgewall Software]]
     * [[wiki:TitleIndex|Title Index]]
       or even [[TitleIndex|Title Index]]
     * [[wiki:TitleIndex]]
       ''' but not ![[TitleIndex]]! '''
     * [[ISO9000]]
    }}}
  }}}
  {{{#!td
     * [[http://www.edgewall.com|Edgewall Software]]
     * [[wiki:TitleIndex|Title Index]]
       or even [[TitleIndex|Title Index]]
     * [[wiki:TitleIndex]]
       ''' but not ![[TitleIndex]]! '''
     * [[ISO9000]]
  }}}

  '''Note''': the [trac:WikiCreole] style for links is quick to type and
  certainly looks familiar as it's the one used on Wikipedia and in many
  other wikis. Unfortunately it conflicts with the syntax for [#Macros macros].
  So in the rare case when you need to refer to a page which is named after
  a macro (typical examples being TitleIndex, InterTrac and InterWiki), 
  by writing `[[TitleIndex]]` you will actually call the macro instead of linking
  to the page.

  == Trac Links ==

  Wiki pages can link directly to other parts of the Trac system. Pages can refer to tickets, reports, changesets, milestones, source files and other Wiki pages using the following notations:

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     * Tickets: #1 or ticket:1
     * Reports: {1} or report:1
     * Changesets: r1, [1] or changeset:1
     * ...
     * targeting other Trac instances, 
       so called InterTrac links:
       - Tickets: #Trac1 or Trac:ticket:1
       - Changesets: [Trac1] or Trac:changeset:1
    }}}
  }}}
  {{{#!td
   * Tickets: #1 or ticket:1
   * Reports: {1} or report:1
   * Changesets: r1, [1] or changeset:1
   * ... 
   * targeting other Trac instances, 
     so called InterTrac links:
     - Tickets: #Trac1 or Trac:ticket:1
     - Changesets: [Trac1] or Trac:changeset:1
  }}}

  There are many more flavors of Trac links, see TracLinks for more in-depth information and a reference for all the default link resolvers.


  == Setting Anchors ==

  An anchor, or more correctly speaking, an [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.2.1 anchor name] can be added explicitly at any place in the Wiki page, in order to uniquely identify a position in the document:

  {{{
  [=#point1]
  }}}

  This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]. For example:
  {{{
  == Long title == #title
  }}}

  It's also very close to the syntax for the corresponding link to that anchor:
  {{{
  [#point1]
  }}}

  Optionally, a label can be given to the anchor:
  {{{
  [[=#point1 '''Point 1''']]
  }}}

  ||= Wiki Markup =||= Display =||
  |----------------------------------
  {{{#!td
    {{{
    [#point2 jump to the second point]

    ...

    Point2:  [=#point2] Jump here
    }}}
  }}}
  {{{#!td
    [#point2 jump to the second point]

    ...

    Point2:  [=#point2] Jump here
  }}}

  For more complex anchors (e.g. when a custom title is wanted), one can use the Span macro, e.g. `[[span(id=point2, class=wikianchor, title=Point 2, ^(2)^)]]`.


  == Escaping Links, WikiPageNames and other Markup == #Escaping

  You may avoid making hyperlinks out of TracLinks by preceding an expression with a single "!" (exclamation mark).

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     !NoHyperLink
     !#42 is not a link
    }}}
    {{{
  Various forms of escaping for list markup:
   `-` escaped minus sign \\
   ``1. escaped number  \\
   {{{*}}} escaped asterisk sign
    }}}
  }}}
  {{{#!td
   !NoHyperLink
   !#42 is not a link

  Various forms of escaping for list markup:
   `-` escaped minus sign \\
   ``1. escaped number  \\
   {{{*}}} escaped asterisk sign
  }}}

  == Images ==

  Urls ending with `.png`, `.gif` or `.jpg` are no longer automatically interpreted as image links, and converted to `<img>` tags.

  You now have to use the ![[Image]] macro. The simplest way to include an image is to upload it as attachment to the current page, and put the filename in a macro call like `[[Image(picture.gif)]]`.

  In addition to the current page, it is possible to refer to other resources:
   * `[[Image(wiki:WikiFormatting:picture.gif)]]` (referring to attachment on another page)
   * `[[Image(ticket:1:picture.gif)]]` (file attached to a ticket)
   * `[[Image(htdocs:picture.gif)]]` (referring to a file inside the [TracEnvironment environment] `htdocs` directory)
   * `[[Image(source:/trunk/trac/htdocs/trac_logo_mini.png)]]` (a file in repository)

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    [[Image(htdocs:../common/trac_logo_mini.png)]]
    }}}
  }}}
  {{{#!td
  [[Image(htdocs:../common/trac_logo_mini.png)]]
  }}}

  See WikiMacros for further documentation on the `[[Image()]]` macro, which has several useful options (`title=`, `link=`, etc.)


  == Macros ==

  Macros are ''custom functions'' to insert dynamic content in a page.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    [[RecentChanges(Trac,3)]]
    }}}
  }}}
  {{{#!td style="padding-left: 2em"
  [[RecentChanges(Trac,3)]]
  }}}

  See WikiMacros for more information, and a list of installed macros.

  The detailed help for a specific macro can also be obtained more directly by appending a "?" to the macro name.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    [[MacroList?]]
    }}}
  }}}
  {{{#!td style="padding-left: 2em"
  [[MacroList?]]
  }}}


  == Processors ==

  Trac supports alternative markup formats using WikiProcessors. For example, processors are used to write pages in 
  [wiki:WikiRestructuredText reStructuredText] or [wiki:WikiHtml HTML]. 

  ||= Wiki Markup =||= Display =||
  |--------------------------------------------------------
  {{{#!td align="center" colspan=2 style="border: 0px; font-size: 90%"

     [=#Processors-example-html Example 1:] HTML

  }}}
  |--------------------------------------------------------
  {{{#!td style="border: 0px"
    {{{
    {{{
    #!html
    <h1 style="text-align: right; color: blue">
     HTML Test
    </h1>
    }}}
    }}}
  }}}
  {{{#!td valign="top"  style="border: 0px"

  {{{
  #!html
  <h1 style="text-align: right; color: blue">HTML Test</h1>
  }}}

  }}}
  |--------------------------------------------------------
  {{{#!td align="center" colspan=2 style="border: 0px; font-size: 90%"

     [=#Processors-example-highlight Example 2:] Code Highlighting

  }}}
  |--------------------------------------------------------
  {{{#!td style="border: 0px"
    {{{
    {{{
    #!python
    class Test:
    
        def __init__(self):
            print "Hello World"
    if __name__ == '__main__':
       Test()
    }}}
    }}}
  }}}
  {{{
  #!td valign="top"  style="border: 0px"

  {{{
  #!python
  class Test:
      def __init__(self):
          print "Hello World"
  if __name__ == '__main__':
     Test()
  }}}

  }}}
  |--------------------------------------------------------
  {{{#!td align="center" colspan=2 style="border: 0px; font-size: 90%"

         [=#Processors-example-tables Example 3:] Complex Tables

  }}}
  |--------------------------------------------------------
  {{{#!td style="border: 0px"
    {{{
    {{{#!th rowspan=4 align=justify
    With the `#td` and `#th` processors,
    table cells can contain any content:
    }}}
    |----------------
    {{{#!td
      - lists
      - embedded tables
      - simple multiline content
    }}}
    |----------------
    {{{#!td
    As processors can be easily nested, 
    so can be tables:
      {{{#!th
      Example:
      }}}
      {{{#!td style="background: #eef"
      || must be at the third level now... ||
      }}}
    }}}
    |----------------
    {{{#!td
    Even when you don't have complex markup,
    this form of table cells can be convenient
    to write content on multiple lines.
    }}}
    }}}
  }}}
  {{{
  #!td  valign="top"  style="border: 0px"

    {{{#!th rowspan=4 align=justify
    With the `#td` and `#th` processors,
    table cells can contain any content:
    }}}
    |----------------
    {{{#!td
      - lists
      - embedded tables
      - simple multiline content
    }}}
    |----------------
    {{{#!td
    As processors can be easily nested, 
    so can be tables:
      {{{#!th
      Example:
      }}}
      {{{#!td style="background: #eef"
      || must be at the third level now... ||
      }}}
    }}}
    |----------------
    {{{#!td
    Even when you don't have complex markup,
    this form of table cells can be convenient
    to write content on multiple lines.
    }}}

  }}}

  See WikiProcessors for more information.


  == Comments ==

  Comments can be added to the plain text. These will not be rendered and will not display in any other format than plain text.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    Nothing to
    {{{
    #!comment
    Your comment for editors here
    }}}
    see ;-)
    }}}
  }}}
  {{{#!td
    Nothing to
    {{{
    #!comment
    Your comment for editors here
    }}}
    see ;-)
  }}}

  == Miscellaneous ==

  An horizontal line can be used to separated different parts of your page:

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    Four or more dashes will be replaced 
    by an horizontal line (<HR>)
    ----
    See?
    }}}
  }}}
  {{{#!td
  Four or more dashes will be replaced
  by an horizontal line (<HR>)
  ----
  See?
  }}}
  |----------------------------------
  {{{#!td
    {{{
    "macro" style [[br]] line break
    }}}
  }}}
  {{{#!td
  "macro" style [[br]] line break
  }}}
  |----------------------------------
  {{{#!td
    {{{
    !WikiCreole style \\ line\\break
    }}}
  }}}
  {{{#!td
  !WikiCreole style \\ line\\break
  }}}


name: TracIni
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Configuration File =

   ''[Note To Editors] Please discuss documentation changes in the [#Discussion] section. Even better, send us [TracDev/SubmittingPatches documentation patches] against the ''code'' (i.e. where the configuration entries are documented), either on Trac-dev or on new tickets. ''

  [[TracGuideToc]]
  [[PageOutline]]

  Trac configuration is done by editing the '''`trac.ini`''' config file, located in `<projectenv>/conf/trac.ini`.  Changes to the configuration are usually reflected immediately, though changes to the `[components]` or `[logging]` sections will require restarting the web server. You may also need to restart the web server after creating a global configuration file when none was previously present.

  The `trac.ini` configuration file and its parent directory should be writable by the web server, as Trac currently relies on the possibility to trigger a complete environment reload to flush its caches.

  == Global Configuration ==

  In versions prior to 0.11, the global configuration was by default located in `$prefix/share/trac/conf/trac.ini` or /etc/trac/trac.ini, depending on the distribution. If you're upgrading, you may want to specify that file to inherit from.  Literally, when you're upgrading to 0.11, you have to add an `[inherit]` section to your project's `trac.ini` file. Additionally, you have to move your customized templates and common images from `$prefix/share/trac/...` to the new location.

  Global options will be merged with the environment-specific options, where local options override global options. The options file is specified as follows:
  {{{
  [inherit]
  file = /path/to/global/trac.ini
  }}}
  Multiple files can be specified using a comma-separated list.

  Note that you can also specify a global option file when creating a new project,  by adding the option `--inherit=/path/to/global/trac.ini` to [TracAdmin#initenv trac-admin]'s `initenv` command.  If you do not do this but nevertheless intend to use a global option file with your new environment, you will have to go through the newly generated `conf/trac.ini` file and delete the entries that will otherwise override those set in the global file.

  There are two more entries in the [[#inherit-section| [inherit] ]] section, `templates_dir` for sharing global templates and `plugins_dir`, for sharing plugins. Those entries can themselves be specified in the shared configuration file, and in fact, configuration files can even be chained if you specify another `[inherit] file` there.

  Note that the templates found in the `templates/` directory of the TracEnvironment have precedence over those found in `[inherit] templates_dir`. In turn, the latter have precedence over the installed templates, so be careful about what you put there, notably if you override a default template be sure to refresh your modifications when you upgrade to a new version of Trac (the preferred way to perform TracInterfaceCustomization being still to write a custom plugin doing an appropriate `ITemplateStreamFilter` transformation).

  == Reference for settings

  This is a brief reference of available configuration options, and their default settings.

  [[TracIni]]

  ----
  See also: TracGuide, TracAdmin, TracEnvironment


name: TracCgi
author: trac
ipnr: 127.0.0.1
text:
  = Installing Trac as CGI =

  {{{
  #!div class=important
    ''Please note that using Trac via CGI is the slowest deployment method available. It is slower than [TracModPython mod_python], [TracFastCgi FastCGI] and even [trac:TracOnWindowsIisAjp IIS/AJP] on Windows.''
  }}}

  CGI script is the entrypoint that web-server calls when a web-request to an application is made. To generate the `trac.cgi` script run:
  {{{
  trac-admin /path/to/env deploy /path/to/www/trac
  }}}
  `trac.cgi` will be in the `cgi-bin` folder inside the given path. ''Make sure it is executable by your web server''. This command also copies `static resource` files to a `htdocs` directory of a given destination.

  == Apache web-server configuration ==

  In [http://httpd.apache.org/ Apache] there are two ways to run Trac as CGI:

   1. Use a `ScriptAlias` directive that maps an URL to the `trac.cgi` script (recommended)
   2. Copy the `trac.cgi` file into the directory for CGI executables used by your web server (commonly named `cgi-bin`). You can also create a symbolic link, but in that case make sure that the `FollowSymLinks` option is enabled for the `cgi-bin` directory.

  To make Trac available at `http://yourhost.example.org/trac` add `ScriptAlias` directive to Apache configuration file, changing `trac.cgi` path to match your installation:
  {{{
  ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.cgi
  }}}

   ''Note that this directive requires enabled `mod_alias` module.''

  If you're using Trac with a single project you need to set its location using the `TRAC_ENV` environment variable:
  {{{
  <Location "/trac">
    SetEnv TRAC_ENV "/path/to/projectenv"
  </Location>
  }}}

  Or to use multiple projects you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` variable:
  {{{
  <Location "/trac">
    SetEnv TRAC_ENV_PARENT_DIR "/path/to/project/parent/dir"
  </Location>
  }}}

   ''Note that the `SetEnv` directive requires enabled `mod_env` module. It is also possible to set TRAC_ENV in trac.cgi. Just add the following code between "try:" and "from trac.web ...":''

  {{{
      import os
      os.environ['TRAC_ENV'] = "/path/to/projectenv"
  }}}

   '' Or for TRAC_ENV_PARENT_DIR: ''

  {{{
      import os
      os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/project/parent/dir"
  }}}

  If you are using the [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature please see [http://trac.edgewall.org/wiki/ApacheSuexec].

  On some systems, you ''may'' need to edit the shebang line in the `trac.cgi` file to point to your real Python installation path. On a Windows system you may need to configure Windows to know how to execute a .cgi file (Explorer -> Tools -> Folder Options -> File Types -> CGI).

  === Using WSGI ===

  You can run a [http://henry.precheur.org/python/how_to_serve_cgi WSGI handler] [http://pythonweb.org/projects/webmodules/doc/0.5.3/html_multipage/lib/example-webserver-web-wsgi-simple-cgi.html under CGI].  You can [wiki:TracModWSGI#Thetrac.wsgiscript write your own application function], or use the deployed trac.wsgi's application.

  == Mapping Static Resources ==

  See TracInstall#MappingStaticResources.

  == Adding Authentication ==

  See TracInstall#ConfiguringAuthentication.

  ----
  See also:  TracGuide, TracInstall, [wiki:TracModWSGI], TracFastCgi, TracModPython


name: InterTrac
author: trac
ipnr: 127.0.0.1
text:
  = InterTrac Links  =

  Trac supports a convenient way to refer to resources of other Trac servers, from within the Wiki markup, since version 0.10.

  == Definitions ==

  An InterTrac link can be seen as a scoped TracLinks.
  It is used for referring to a Trac resource 
  (Wiki page, changeset, ticket, ...) located in another
  Trac environment.

  == List of Active InterTrac Prefixes ==

  [[InterTrac]]

  == Link Syntax ==

  Simply use the name of the other Trac environment as a prefix, 
  followed by a colon, ending with the resource located in the other environment.

  {{{
  <target_environment>:<TracLinks>
  }}}

  The other resource is specified using a regular TracLinks, of any flavor.

  That target environment name is either the real name of the 
  environment, or an alias for it. 
  The aliases are defined in `trac.ini` (see below).
  The prefix is case insensitive.

  If the InterTrac link is enclosed in square brackets (like `[th:WikiExtrasPlugin]`), the InterTrac prefix is removed in the displayed link, like a normal link resolver would be (i.e. the above would be displayed as `WikiExtrasPlugin`).

  For convenience, there's also some alternative short-hand form, 
  where one can use an alias as an immediate prefix 
  for the identifier of a ticket, changeset or report:
  (e.g. `#T234`, `[T1508]`, `[trac 1508]`, ...)

  == Examples ==

  It is necessary to setup a configuration for the InterTrac facility.
  This configuration has to be done in the TracIni file, `[intertrac]` section.

  Example configuration:
  {{{
  ...
  [intertrac]
  # -- Example of setting up an alias:
  t = trac

  # -- Link to an external Trac:
  trac.title = Edgewall's Trac for Trac
  trac.url = http://trac.edgewall.org
  }}}

  The `.url` is mandatory and is used for locating the other Trac.
  This can be a relative URL in case that Trac environment is located 
  on the same server.

  The `.title` information will be used for providing an useful tooltip
  when moving the cursor over an InterTrac links.

  Finally, the `.compat` option can be used to activate or disable
  a ''compatibility'' mode:
   * If the targeted Trac is running a version below [trac:milestone:0.10 0.10] 
     ([trac:r3526 r3526] to be precise), then it doesn't know how to dispatch an InterTrac 
     link, and it's up to the local Trac to prepare the correct link. 
     Not all links will work that way, but the most common do. 
     This is called the compatibility mode, and is `true` by default. 
   * If you know that the remote Trac knows how to dispatch InterTrac links, 
     you can explicitly disable this compatibility mode and then ''any'' 
     TracLinks can become an InterTrac link.

  Now, given the above configuration, one could create the following links:
   * to this InterTrac page:
     * `trac:wiki:InterTrac` trac:wiki:InterTrac
     * `t:wiki:InterTrac` t:wiki:InterTrac
     * Keys are case insensitive: `T:wiki:InterTrac` T:wiki:InterTrac
   * to the ticket #234:
     * `trac:ticket:234` trac:ticket:234
     * `trac:#234` trac:#234 
     * `#T234` #T234
   * to the changeset [1912]:
     * `trac:changeset:1912` trac:changeset:1912
     * `[T1912]` [T1912]
   * to the log range [3300:3330]: '''(Note: the following ones need `trac.compat=false`)'''
     * `trac:log:@3300:3330` trac:log:@3300:3330  
     * `[trac 3300:3330]` [trac 3300:3330] 
   * finally, to link to the start page of a remote trac, simply use its prefix followed by ':', inside an explicit link. Example: `[th: Trac Hacks]` (''since 0.11; note that the ''remote'' Trac has to run 0.11 for this to work'')

  The generic form `intertrac_prefix:module:id` is translated
  to the corresponding URL `<remote>/module/id`, shorthand links
  are specific to some modules (e.g. !#T234 is processed by the
  ticket module) and for the rest (`intertrac_prefix:something`),
  we rely on the TracSearch#quickjump facility of the remote Trac.

  ----
  See also: TracLinks, InterWiki


name: TracChangeset
author: trac
ipnr: 127.0.0.1
text:
  = Trac Changeset Module =
  [[TracGuideToc]]

  Trac has a built-in functionality for visualizing “diffs” - changes to files.

  There are different kinds of ''change sets''. 
  Some can correspond to revisions made in the repositories,
  others can aggregate changes made in several revisions, 
  but in the end, any kind of differences can be shown.

  The changeset view consists of two parts, the ''header'' 
  and the ''diff views''.

  == Changeset Header ==

  The header shows an overview of the whole changeset.
  Here you will find information such as:

   * Timestamp — When the changeset was commited
   * Author — Who commited the changeset
   * Message — A brief description from the author (the commit log message)
   * Location — Parent directory of all files affected by this changeset
   * Files — A list of files affected by this changeset

  If more than one revision is involved in the set of changes being
  displayed, the ''Timestamp'', ''Author'' and ''Message'' fields 
  won't be shown.

  In front of each listed file, you'll find  a colored rectangle. The color
  indicates how the file is affected by the changeset.
   
   [[span(style=background:#bfb;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Green: Added \\
   [[span(style=background:#f88;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Red: Removed \\
   [[span(style=background:#fd8;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Yellow: Modified \\
   [[span(style=background:#88f;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Blue: Copied \\
   [[span(style=background:#ccc;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Gray: Moved \\
  The color legend is located below the header as a reminder.

  == Diff Views ==

  Below the header is the main part of the changeset, the diff view. Each file is shown in a separate section, each of which will contain only the regions of the file that are affected by the changeset. There are two different styles of displaying the diffs: ''inline'' or ''side-by-side'' (you can switch between those styles using the preferences form):

   * The ''inline'' style shows the changed regions of a file underneath each other. A region removed from the file will be colored red, an added region will be colored green. If a region was modified, the old version is displayed above the new version. Line numbers on the left side indicate the exact position of the change in both the old and the new version of the file.
   * The ''side-by-side'' style shows the old version on the left and the new version on the right (this will typically require more screen width than the inline style.) Added and removed regions will be colored in the same way as with the inline style (green and red, respectively), but modified regions will have a yellow background.

  In addition, various advanced options are available in the preferences form for adjusting the display of the diffs:
   * You can set how many lines are displayed before and after every change
     (if the value ''all'' is used, then the full file will be shown)
   * You can toggle whether blank lines, case changes and white space changes are ignored, thereby letting you find the functional changes more quickly


  == The Different Ways to Get a Diff ==

  === Examining a Changeset ===

  When viewing a repository check-in, such as when following a
  changeset [wiki:TracLinks link] or a changeset event in the 
  [wiki:TracTimeline timeline], Trac will display the exact changes
  made by the check-in.

  There will be also navigation links to the ''Previous Changeset''
  to and ''Next Changeset''.

  === Examining Differences Between Revisions ===

  Often you'll want to look at changes made on a file 
  or on a directory spanning multiple revisions. The easiest way
  to get there is from the TracRevisionLog, where you can select
  the ''old'' and the ''new'' revisions of the file or directory, and
  then click the ''View changes'' button.

  === Examining Differences Between Branches ===

  One of the core features of version control systems is the possibility
  to work simultaneously on different ''Lines of Developments'', commonly
  called “branches”. Trac enables you to examine the exact differences
  between such branches.

  Using the '''View changes ...''' button in the TracBrowser allows you to enter
  ''From:'' and ''To:'' path/revision pairs. The resulting set of differences consist
  of the changes that should be applied to the ''From:'' content in order
  to get to the ''To:'' content.

  For convenience, it is possible to invert the roles of the ''old'' and the ''new''
  path/revision pairs by clicking the ''Reverse Diff'' link on the changeset page.

  === Checking the Last Change ===

  The last possibility for examining changes is to use the ''Last Change''
  link provided by the TracBrowser.

  This link will take you to the last change that was made on that path.
  From there, you can use the ''Previous Change'' and ''Next Change'' links
  to traverse the change history of the file or directory.

  ----
  See also: TracGuide, TracBrowser


# report

title: Active Tickets
description:
  * List all active tickets by priority.
  * Color each row based on priority.

query:
  SELECT p.value AS __color__,
     id AS ticket, summary, component, version, milestone, t.type AS type, 
     owner, status,
     time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE status <> 'closed'
    ORDER BY CAST(p.value AS int), milestone, t.type, time


title: Active Tickets by Version
query:
  SELECT p.value AS __color__,
     version AS __group__,
     id AS ticket, summary, component, version, t.type AS type, 
     owner, status,
     time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE status <> 'closed'
    ORDER BY (version IS NULL),version, CAST(p.value AS int), t.type, time

description:
  This report shows how to color results by priority,
  while grouping results by version.

  Last modification time, description and reporter are included as hidden fields
  for useful RSS export.


title: Active Tickets by Milestone
query:
  SELECT p.value AS __color__,
     'Milestone '||milestone AS __group__,
     id AS ticket, summary, component, version, t.type AS type, 
     owner, status,
     time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE status <> 'closed' 
    ORDER BY (milestone IS NULL),milestone, CAST(p.value AS int), t.type, time

description:
  This report shows how to color results by priority,
  while grouping results by milestone.

  Last modification time, description and reporter are included as hidden fields
  for useful RSS export.


title: Accepted, Active Tickets by Owner
description: List accepted tickets, group by ticket owner, sorted by priority.
query:
  SELECT p.value AS __color__,
     owner AS __group__,
     id AS ticket, summary, component, milestone, t.type AS type, time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE status = 'accepted'
    ORDER BY owner, CAST(p.value AS int), t.type, time


title: Accepted, Active Tickets by Owner (Full Description)
query:
  SELECT p.value AS __color__,
     owner AS __group__,
     id AS ticket, summary, component, milestone, t.type AS type, time AS created,
     description AS _description_,
     changetime AS _changetime, reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE status = 'accepted'
    ORDER BY owner, CAST(p.value AS int), t.type, time

description:
  List tickets accepted, group by ticket owner.
  This report demonstrates the use of full-row display.


title: All Tickets By Milestone (Including closed)
description: A more complex example to show how to make advanced reports.
query:
  SELECT p.value AS __color__,
     t.milestone AS __group__,
     (CASE status 
        WHEN 'closed' THEN 'color: #777; background: #ddd; border-color: #ccc;'
        ELSE 
          (CASE owner WHEN $USER THEN 'font-weight: bold' END)
      END) AS __style__,
     id AS ticket, summary, component, status, 
     resolution,version, t.type AS type, priority, owner,
     changetime AS modified,
     time AS _time,reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    ORDER BY (milestone IS NULL), milestone DESC, (status = 'closed'), 
          (CASE status WHEN 'closed' THEN changetime ELSE (-1) * CAST(p.value AS int) END) DESC


title: My Tickets
query:
  SELECT p.value AS __color__,
     (CASE status WHEN 'accepted' THEN 'Accepted' ELSE 'Owned' END) AS __group__,
     id AS ticket, summary, component, version, milestone,
     t.type AS type, priority, time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE t.status <> 'closed' AND owner = $USER
    ORDER BY (status = 'accepted') DESC, CAST(p.value AS int), milestone, t.type, time

description:
  This report demonstrates the use of the automatically set 
  USER dynamic variable, replaced with the username of the
  logged in user when executed.


title: Active Tickets, Mine first
query:
  SELECT p.value AS __color__,
     (CASE owner 
       WHEN $USER THEN 'My Tickets' 
       ELSE 'Active Tickets' 
      END) AS __group__,
     id AS ticket, summary, component, version, milestone, t.type AS type, 
     owner, status,
     time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE status <> 'closed' 
    ORDER BY (owner = $USER) DESC, CAST(p.value AS int), milestone, t.type, time

description:
   * List all active tickets by priority.
   * Show all tickets owned by the logged in user in a group first.


