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 The `sar` plugin is useful to make global or local search and replace operations
   6 using common or specific terms.
   7
   8 The characteristics are:
   9
  10 - Support for a global dictionary page (optional but recommended).
  11 - Is possible to replace the first appearance with a text and the rest with
  12 other.
  13
  14 The global dictionary page is like this:
  15
  16     ## Sites and projects
  17
  18     - [[sar search="ikiwiki" first="[IkiWiki](http://ikiwiki.info)" next="_IkiWiki_"]]
  19     - [[sar search="debian" first="[Debian](http://debian.org)" next="_Debian_"]]
  20     - [[sar search="perl" first="[Perl](http://perl.org)" next="_Perl_"]]
  21     - [[sar search="linux" replace="GNU/Linux"]]
  22
  23     ## Persons
  24     - [[sar search="joey" first="[Joey Hess](http://ikiwiki.info/users/joey]]" next="_Joey_" ]]
  25     - [[sar search="angel" first="[Angel](http://triptico.com)" next="Angel"]]
  26
  27     ## Technical terms
  28
  29     - [[sar search="smtp" first="\[[wp SMTP]]" next="‘SMTP‘"]]
  30     - [[sar search="pop3" first="\[[wp POP3]]" next="’POP3’"]]
  31
  32 The search expressions must be surrounded by double dashes in a source ikiwiki
  33 page, like this:
  34
  35     Mis programas están escritos en lenguaje --perl--, funcionando con el
  36     sistema --debian--, y mis páginas web funcionan con --ikiwiki-- cuyo autor
  37     es --joey--.
  38
  39     --ikiwiki-- es un buen software.
  40
  41 After a filter operation the content is:
  42
  43     Mis programas están escritos en lenguaje [Perl](http://perl.org),
  44     funcionando con el sistema [Debian](http://debian.org), y mis páginas web
  45     funcionan con [IkiWiki](http://ikiwiki.info) cuyo autor es [Joey
  46     Hess](http://ikiwiki.info/users/joey).
  47
  48     _IkiWiki_ es un buen software.
  49
  50 _Note_: I chose this syntax because don't clashes with markdown and it is easy to write.
  51
  52 A _search and replace_ directive has the following parameters:
  53
  54 - `search`: define the text to search.
  55 - `first`: define the replace text in the first match.
  56 - `next`: define the replace text in all matches except the first.
  57 - `replace`: define the replace text in all matches.
  58
  59 Now the code is used at my site without problems, and the author will
  60 appreciate any help with his development or his english.
  61
  62 ## Configuration
  63
  64 The plugin need the following global values:
  65
  66 - `sar_mainpage`: define the global dictionary page. The default value is `sar`.
  67 - `sar_pagespec`: enable the plugin with a selection of pages. The default
  68 value is `*`, but a recommended value is `link(tag/sar)`.
  69
  70 ## Sinopsys
  71
  72 In a ikiwiki source page we can write this
  73
  74     \[[sar search=debian replace="__Debian__"]]
  75
  76 for define a global replace for the term `--debian--` or
  77
  78     \[[sar search=ibm first=’[IBM](http://www.ibm.com)’
  79             next="_IBM_"]]
  80
  81 to define a replace for the first match of the string `--ibm--` and a different
  82 replace for the rest.
  83
  84 ## Changelog
  85
  86 ### version 0.8
  87
  88 - First functional version with the new sar expressions.
  89
  90 ### version 0.7
  91
  92 - New design for the search expressions.
  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