web commit by VictorMoral
[ikiwiki.git] / doc / plugins / contrib / shortcuts.mdwn
1 [[template id=plugin name=shortcuts included=0 author="[[VictorMoral]]"]]
2 [[tag type/format]]
3 [[meta title="shortcuts (third-party plugin)"]]
4
5 ## version 0.4 
6
7 Following the suggestions of Joey i'm rewriting the module and now the old syntax is not supported. 
8
9 The plugin process directives as 
10
11   [[shortcut deb ikiwiki "a good wiki"]] 
12
13 and transform it in 
14
15   \[a good wiki](http://packages.debian.org/ikiwiki)
16
17 It uses a special ikiwiki page named *shortcuts.mdwn* where to extract the shortcuts definitions from one list, similar to the smileys plugin. 
18
19   * DEB http://packages.debian.org 
20   * rfc http://www.ietf.org/rfc/rfc%s.txt
21   * docbook http://www.docbook.org/tdg/en/html/%s.html
22
23 If the shortcut name is in uppercase, it is register through *hook()* function (in lowercase) as a new preprocessor directive. In the above example the ikiwiki page should be
24
25   [[deb ikiwiki "a good wiki"]]
26   I need read [[shortcut rfc 14567 "this document"]] before ...
27
28 In the URL part of the definition, a **%s** string will be replaced with the first param of the directive. If it's missing that param will be added to the end of the URL.
29
30 By default, the module provides a few shortcuts (not preregistered):
31
32 * deb   http://packages.debian.org/%s
33 * wiki  http://en.wikipedia.org/wiki/%s
34 * google http://www.google.com/search?q=%s
35 * dbug   http://bugs.debian.org/%s
36 * cpan http://search.cpan.org/search?mode=dist&query=%s
37
38 The new version can be download from [here](http://taquiones.net/files/misc/IkiWiki-Plugin-shortcuts-0.4.tar.gz).
39
40 Joey, could be merge with your module in any form ? 
41
42 Again, my apologies for the duplicate efforts.
43
44 ----
45
46 Note: This plugin is different than the "shortcut" plugin now included in
47 ikiwiki. I'm leaving it here in case people prefer how this one works.
48 --[[Joey]]
49
50 *shortcuts* is a plugin for make external links easy in a ikiwiki page.
51 It filter the raw source code, searching *wafl expresions* and replacing it
52 for ikiwiki links and not for html links. 
53
54 *Note: my apologies for my poor english, my mother language is the spanish.
55 Any corrections are welcome :-).*
56
57 In the source page you need include the expresions as:
58
59     For my {wiki:UPS} APC i need the {deb:apcupsd} package installed. You can 
60     found {google:apc linux|many positive responses}.
61
62 and after filter this is the result:
63
64     For my [UPS](http://en.wikipedia.org/wiki/UPS) i need the 
65     [apcupsd](http://packages.debian.org/). You can found 
66     [many positive responses](http://www.google.com/search?q=apc+linux).
67
68 If you need escape a walf expression prefix with a backslash character as in:
69
70     This is a \{cpan:example}.
71
72 This module is inspired in Kwiki::Shortcuts with minor diferences. The wafl
73 expresions are strings between braces with the following elements:
74
75 * one name (followed by one colon character)
76 * one o many search terms
77 * an optional text for the link
78
79 The plugin provides some predefined shortcuts, and it can use a external
80 definitions file. This file is named *shortcuts.conf* by default, but it can
81 be set with the *shortcuts* parameter and configuration variable.
82
83 The next shortcuts are predefined:
84
85 -   google: http://www.google.com/search?q=
86 -   deb:    http://packages.debian.org/
87 -   dbug:   http://bugs.debian.org/
88 -   cpan:   http://search.cpan.org/search?mode=dist&query=
89 -   wiki:   http://en.wikipedia.org/wiki/
90
91 Use the external Perl module: URI::Escape and it can be found
92 [here](http://taquiones.net/files/misc/IkiWiki-Plugin-shortcuts-0.3.tar.gz).
93