= InterTrac Links  =

''(since [milestone: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.

For convenience, there's also an 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 ==

{{{
#!comment
 Besides the other environments run by the same server process
 (called ''sibling'' environments), which are automatically detected,
Support for sibling environments has been disabled.
See http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/157
}}}

It is necessary to setup a configuration for the InterTrac facility:
 * in order to refer to a remote Trac
 * for defining environment aliases

This is done quite simply in an `[intertrac]` section
within the `trac.ini` file.

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://projects.edgewall.com/trac
}}}

Now, given this 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]: ''whoops, still doesn't work, why?''
   * `trac:log:3300:3330` trac:log:3300:3330
   * `[trac 3300:3330]` [trac 3300:3330] 

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.

----
=== Discussion ===

I think that the `trac` prefix could even be set as a default in the `[intertrac]` TracIni section. --CB

----
See also: TracLinks, InterWiki