doc/plugins/contrib/sar___40__third_party_plugin__41__.mdwn

   1 [[meta title="sar (third party plugin)" ]]
   2 [[template id=plugin name=sar author="[[VictorMoral]]"]]
   3 [[tag type/chrome type/slow ]]
   4
   5 >__Warning__: i'm using this plugin at my site and i have found too much problems with him. I discourage his use until a new version has been released. My apologies for the inconveniences. I think that is a good idea with a bad initial design.
   6
   7 The `sar` plugin is useful to make global or local search and replace operations
   8 using common or specific terms.
   9
  10 The characteristics are:
  11
  12 - Support for a global dictionary page (optional but recommended).
  13 - Is possible to replace the first appearance with a text and the rest with
  14 other.
  15 - Support for enable or disable sar engine in any page.
  16 - Support for disable sar engine on any term in any page.
  17
  18 The global dictionary page is like this:
  19
  20     ## Sites and projects
  21
  22     - [[sar search="ikiwiki" first="[IkiWiki](http://ikiwiki.info)" next="_IkiWiki_"]]
  23     - [[sar search="debian" first="[Debian](http://debian.org)" next="_Debian_"]]
  24     - [[sar search="perl" first="[Perl](http://perl.org)" next="_Perl_"]]
  25     - [[sar search="linux" replace="GNU/Linux"]]
  26
  27     ## Persons
  28     - [[sar search="joey" first="[Joey Hess](http://ikiwiki.info/users/joey]]" next="_Joey_" ]]
  29     - [[sar search="angel" first="[Angel](http://triptico.com)" next="Angel"]]
  30
  31     ## Technical terms
  32
  33     - [[sar search="smtp" first="\[[wp SMTP]]" next="‘SMTP‘"]]
  34     - [[sar search="pop3" first="\[[wp POP3]]" next="’POP3’"]]
  35
  36 The search parameter is a literal text; later will be used as part of the
  37 final regular expression.
  38
  39 A _search and replace_ directive has the following parameters:
  40
  41 - `search`: define the text to search.
  42 - `first`: define the replace text in the first match.
  43 - `next`: define the replace text in all matches except the first.
  44 - `replace`: define the replace text in all matches.
  45 - `disable`: disable the sar plugin in the current page or the current term if
  46 there is a search parameter.
  47
  48 ## Configuration
  49
  50 The plugin need the following global values:
  51
  52 - `sar_mainpage`: define the global dictionary page. The default value is `sar`.
  53 - `sar_pagespec`: enable the plugin with a selection of pages. The default
  54 value is `*`, but a recommended value is `link(tag/sar)`.
  55
  56 ## Caveats
  57
  58 This plugin works as a filter hook on the source markdown text; the dictionary
  59 terms must be carefully selected, because they could interfere with URLs and
  60 other preprocessor directives.
  61
  62 The code is highly experimental and the author will appreciate any help with
  63 his development or his english. I'm using at my site with minor problems.
  64
  65 ## sinopsys
  66
  67 In a ikiwiki source page we can write this
  68
  69     \[[sar]]
  70
  71 for enable the sar plugin in this page or
  72
  73     \[[sar disable = 1]]
  74
  75 for disable the sar plugin or
  76
  77     \[[sar search=debian replace="__Debian__"]]
  78
  79 to define a global replace for the term `debian` or
  80
  81     \[[sar search=ibm first=’[IBM](http://www.ibm.com)’
  82             next="_IBM_"]]
  83
  84 to define a replace for the first match of the string `ibm` and a different
  85 replace for the rest, and
  86
  87     \[[sar search=hp ]]
  88     \[[sar search=hp disable=1]]
  89
  90 to disable the sar plugin in the current page for the term `hp`.
  91
  92 ## Changelog
  93
  94 ### version 0.6
  95
  96 - Minor bugfixes in the pages selection.
  97 - Call to add_depends() for every page filtered
  98
  99 ### version 0.5
 100
 101 - This is the first functional version.
 102
 103 ## Download
 104
 105 The module can be downloaded from:
 106
 107 - [My personal site](http://taquiones.net/files/misc)
 108 - [My personal Debian repository](http://taquiones.net/files/debian)
 109
 110