# wiki

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 integer), 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 integer), 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 integer), 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 integer), 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 integer), 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 integer) 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 integer), 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 (COALESCE(owner, '') = $USER) DESC, CAST(p.value AS integer), milestone, t.type, time

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


