[[PageOutline(2-5,Contents,pullout)]]

= General link syntax plugin =
{{{
#!html
<div class="system-message" float="left" overflow="auto">
This plugin is deprecated in Trac 0.10. <a href="http://trac-hacks.org/wiki/InterMapTxt">InterMapTxt</a> provides the same functionality.
</div>
}}}

== Description ==

This is wiki syntax provider to make user defined
link as trac link style embedding. You can use
trac link like "{{{link:mylink:123}}}" which is
rendered as anchor to user defined URL with parameter.

This syntax is mainly developed to make link to mailing-list
archive. For example, "link:dev:123" means "link to archived message
having X-Ml-Count: is 123" and it will be expanded like this:
{{{
<a href='http://www.some-where.org/archive/dev/123'>dev:123</a>
}}}

== Bugs/Feature Requests == 

Existing bugs and feature requests for GeneralLinkSyntaxPlugin are 
[report:9?COMPONENT=GeneralLinkSyntaxPlugin here].

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=GeneralLinkSyntaxPlugin&owner=gotoh new ticket].

== Download ==

Download the zipped source from [download:generallinksyntaxplugin here].

== Source ==

You can check out GeneralLinkSyntaxPlugin from [http://trac-hacks.org/svn/generallinksyntaxplugin here] using Subversion, or [source:generallinksyntaxplugin browse the source] with Trac.

== Install ==

This plugin is Python Egg and requires
[http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install EasyInstall]
package to build. See following page to get and install.

There are two ways to install this plugin.

=== Project local install ===

build python egg by this command:
{{{
#!sh
python setup.py bdist_egg
}}}
Then copy egg file in dist directory into your 'plugins' directory in
desired environment directory.

=== Site wide install ===

To install to use by every projects, do like this: 
{{{
#!sh
python setup.py install
}}}
By this installation, no need to copy python egg files into 'plugins'
directory. Trac can find installed python eggs automatically.

=== Configure ===

{{{
#!ini
[link]
names=dev
dev_url = http://www.some-where.org/archive/dev/%s
}}}

With this configuration, you can use "link:dev:123", "[link:dev:123]"
or "![link:dev:123 description for message 123]" style of trac link is
enabled.

You can also specify display string by xxx_disp entry.
{{{
#!ini
[link]
names=dev
dev_url = http://www.some-where.org/archive/dev/%s
dev_disp = (dev-%s)
}}}

With this configuration, "link:dev:123" is rendered with "(dev-123)" as
anchor text. If label is specified, like "![link:dev:123 label]",
dev_disp is not used.

You can define more links like this:
{{{
#!ini
[link]
names=dev, announce, top
dev_url = http://www.some-where.org/archive/dev/%s
announce_url = http://www.some-where.org/archive/announce/%s
top_url = http://www.some-where.org/
}}}
'dev_url' and 'announce_url' takes one paremter and 'top' takes no
paremeter.

=== Exposing Names ===

As default, the prefix "link:" is always required.
But you can expose 'link name' part into public, thus you can use
"dev:123" instead of "link:dev:123". Note that you should not conflict
other existing one.

Trac allows only alphabets and numbers for trac link name.
So trac does not render exposed style of link like "foo-bar:123" or "[foo-bar:123]".
Because my primary purpose of making this plugin is embedding link to mailing list,
this limitation is not good.
There is a [source:/generallinksyntaxplugin/0.9/formatter.patch patch] to allow such case.
The change of this patch is not official and it may cause problem on your existing wiki pages.
Use it with with your own risk.

== Example ==

This is an example to make search link to Google.
{{{
#!ini
[link]
names=google,tracticket
expose=google
google_url=http://www.google.com/search?&ie=UTF-8&q=%s
trac-ticket_url=http://projects.edgewall.com/trac/ticket/%s
trac-ticket_disp=trac-ticket:%s
}}}

With this configuration, you can use "google:trac+bts",
"![google:trac+subversion Trac]", "link:trac-!ticket:123", etc.

=== Syntax ===

Trac link consists by two parts: 'ns' and 'target' joined by ':'.
This plugin uses 'link' as 'ns' and 'target' part is splitted into
two parts: 'name' and 'id' separated by ':'.
For example, 'link:dev:123' is parsed as name is "dev" and
id is "123".

== Recent Changes ==

[[ChangeLog(generallinksyntaxplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:gotoh gotoh] [[BR]]
'''Maintainer:''' ''none'' [[BR]]
'''Contributors:'''