'''''Testings'''''


= InterTrac and InterWiki Extension for TracLinks =

''Warning: this is a proposal for implementing #234, #40 and #1414''

== Definitions ==

=== InterTrac ===
An InterTrac link is used for referring to a Trac object 
(Wiki page, changeset, ticket, ...) located in another
Trac environment.

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

== Link Syntax ==

=== InterTrac ===
{{{
<target_environment>:<TracLinks>
}}}

The link is composed by the target environment name, 
followed by a colon (e.g. {{{trac:}}}),
followed by a regular TracLinks, of any flavor.

That target environment name is either the real name of the 
environment, or an alias for it.

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

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

The link is composed by the target Wiki (or system) name,
followed by a column (e.g. {{{MeatBall:}}}),
followed by a column separated list of identifiers.

The target Wiki URL is looked up in a page like [http://www.usemod.com/cgi-bin/mb.pl?InterMapTxt MeatBall:InterMapTxt].

Support for #1414: The URL could contain identifier references
(e.g. {{{$1}}}, {{{$2}}} ...),
that will be replaced by the corresponding identifiers found
in the link.
If the URL doesn't contain any identifier reference, the identifier
is simply appended to the URL (i.e. reverting to the ''traditional''
InterWiki scheme).


== Examples ==

=== InterTrac ===
Besides the other environments run by the same server process
(called ''sibling'' environments), which are automatically detected,
(''Note: currently only in {{{tracd}}}''),
it is necessary to setup a configuration for the InterTrac facility:
 * in order to refer to a remote Trac
 * for defining project keys

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

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

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

#trac.svn = http://repos.edgewall.com/projects/trac 
# Hint: .svn information could be used in the future to support svn:externals...
}}}

Now, given this configuration, one could create the following links:
 * to the current InterTrac page:
   * {{{trac:wiki:InterTrac}}}     trac:wiki:InterTrac
   * {{{t:wiki:InterTrac}}}        t:wiki:InterTrac
   * Keys are case insensitive: {{{T:wiki:InterTrac}}} &rarr; T:wiki:InterTrac
 * to the ticket #234:
   * {{{trac:ticket:234}}} trac:ticket:234
   * {{{trac:#234}}} trac:#234
   * {{{#T234}}} #T234
 * to the changeset [1508]:
   * {{{trac:changeset:1508}}} trac:changeset:1508
   * {{{trac:[1508]}}} trac:[1508]
   * {{{[T1508]}}} [T1508]

=== InterWiki ===

The following would be an excerpt of the InterMapTxt page:

{{{
= InterWiki Map =

This is the InterMapTxt wiki page,
modelled after the MeatBall:InterMapTxt page.
----
{{{
...
LiveJournal http://livejournal.com/users/
Login http://www.usemod.com/cgi-bin/mb.pl?action=login&p_userid=
MbTest http://www.usemod.com/cgi-bin/mbtest.pl?
MeatBall http://www.usemod.com/cgi-bin/mb.pl?
MetaWiki http://sunir.org/apps/meta.pl?
MetaWikiPedia http://meta.wikipedia.org/wiki/
Mineralienatlas http://www.mineralienatlas.de/lexikon/index.php/
MoinMoin http://moinmoin.wikiwikiweb.de/
...
}}}
}}}

== Implementation Notes ==

Currently, the {{{[intertrac]}}} configuration has to be repeated 
for each Trac environment, but there's work in progress concerning a 
[ticket:1051 centralized trac.ini], which would help greatly here.

This idea was first proposed as a patch for #234, and 
has been implemented in the following branch: 
source:branches/cboos-dev/intertrac-branch

In particular, [1508] should implement the behavior described 
in version 4 of this page.

The InterWiki specification is not yet implemented.
It is documented together with the InterTrac extension
because they need to be implemented together, as they 
share a similar syntax.

The general idea is that any {{{[a-zA-Z][a-zA-Z0-9]*:}}} prefix 
has to be interpreted as:
 1. either a ''module'' name (''module'' being a {{{Component}}}
    which supports some Wiki syntax)
 1. if not found, an environment name (!InterTrac link)
 1. if not found, an external system name (!InterWiki link)

This order enables to configure Trac for using another
ticket system by disabling the {{{[ticket]}}} component 
and setting a {{{ticket}}} !InterWiki link pointing to the other 
BugTrackingSystem.