Changes between Version 2 and Version 3 of InterTrac

Timestamp:

09/17/06 21:44:11 (18 years ago)

Author:

trac

Comment:

--

InterTrac

@@ -1 @@
-= InterTrac Extension for TracLinks =
+= InterTrac Links  =
 
-''(since [milestone:0.10])''
+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 is used for referring to a Trac object 
+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.
@@ -15 +16 @@
 == 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 link is composed by the target environment name, 
-followed by a colon (e.g. `trac:`),
-followed by a regular TracLinks, of any flavor.
+The other resource is specified using a regular TracLinks, of any flavor.
 
 That target environment name is either the real name of the 
@@ -28 +30 @@
 The prefix is case insensitive.
 
-For convenience, there's also an alternative short-hand form, 
+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]`, ...)
 
-== Configuration ==
+== Examples ==
 
-It is necessary to setup a specific `[intertrac]` section in the TracIni for the InterTrac facility, in order to associate a prefix to other Trac sites, and for defining environment aliases.
+{{{
+#!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.
+This configuration has to be done in the TracIni file, `[intertrac]` section.
 
 Example configuration:
@@ -41 +52 @@
 ...
 [intertrac]
-## -- Example of setting up an alias:
+# -- Example of setting up an alias:
 t = trac
 
-## -- Link to an external 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...
+trac.compat = false
 }}}
 
-Now, given this configuration, one could create the following links:
- * to the current InterTrac page:
-   * `trac:wiki:InterTrac` ->
-     [http://projects.edgewall.com/trac/wiki/InterTrac trac:wiki:InterTrac]
-   * `t:wiki:InterTrac` ->
-     [http://projects.edgewall.com/trac/wiki/InterTrac t:wiki:InterTrac]
-   * Keys are case insensitive: `T:wiki:InterTrac` -> 
-     [http://projects.edgewall.com/trac/wiki/InterTrac T:wiki:InterTrac]
+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 ''compatbility'' mode:
+ * If the targeted Trac is running a version below milestone:0.10 
+   (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 explicitely 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` ->
-     [http://projects.edgewall.com/trac/ticket/234 trac:ticket:234]
-   * `trac:#234` ->
-     [http://projects.edgewall.com/trac/ticket/234 trac:#234]
-   * `#T234` ->
-     [http://projects.edgewall.com/trac/search?q=#234 #T234]
+   * `trac:ticket:234` trac:ticket:234
+   * `trac:#234` trac:#234 
+   * `#T234` #T234
  * to the changeset [1912]:
-   * `trac:changeset:1912` ->
-     [http://projects.edgewall.com/trac/changeset/1912 trac:changeset:1912]
-   * `trac:[1912]` ->
-     [http:"//projects.edgewall.com/trac/search?q=[1912]" "trac:[1912]"]
-   * `[T1912]` ->
-     [http://projects.edgewall.com/trac/changeset/1912 "[T1912]"]
+   * `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] 
 
-Anything not given as explicit links (intertrac_prefix:module:id)
-is interpreted by the remote Trac, relying on its quickjump
-facility.
+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
 
 ----