| Index: trunk/extensions/Narayam/ext.narayam.core.js |
| — | — | @@ -8,6 +8,11 @@ |
| 9 | 9 | * License: GPLv3, CC-BY-SA 3.0 |
| 10 | 10 | */ |
| 11 | 11 | |
| | 12 | +/** |
| | 13 | + * NOTE: For documentation on writing schemes and rulesets, see the |
| | 14 | + * documentation for addScheme(). |
| | 15 | + */ |
| | 16 | + |
| 12 | 17 | ( function( $ ) { |
| 13 | 18 | $.narayam = new ( function() { |
| 14 | 19 | /* Private members */ |
| — | — | @@ -284,8 +289,41 @@ |
| 285 | 290 | /** |
| 286 | 291 | * Add a transliteration scheme. Schemes whose name is not in |
| 287 | 292 | * wgNarayamAvailableSchemes will be ignored. |
| | 293 | + * |
| | 294 | + * A scheme consists of rules used for transliteration. A rule is an |
| | 295 | + * array of three strings. The first string is a regex that is matched |
| | 296 | + * against the input string (the last few characters before the cursor |
| | 297 | + * followed by the character the user entered), the second string is a |
| | 298 | + * regex that is matched against the end of the key buffer (the last |
| | 299 | + * few keys the user pressed), and the third string is the replacement |
| | 300 | + * string (may contain placeholders like $1 for subexpressions). You do |
| | 301 | + * not need to add $ to the end of either of the regexes so they match |
| | 302 | + * at the end, this is done automagically. |
| | 303 | + * |
| | 304 | + * The transliteration algorithm processes the rules in the order they |
| | 305 | + * are specified, and applies the first rule that matches. For a rule |
| | 306 | + * to match, both the first and second regex have to match (the first |
| | 307 | + * for the input, the second for the key buffer). Most rules do not use |
| | 308 | + * the keybuffer and specify an empty string as the second regex. |
| | 309 | + * |
| | 310 | + * The scheme data object must have the following keys: |
| | 311 | + * namemsg: Message key for the name of the scheme |
| | 312 | + * extended_keyboard: Whether this scheme has an extended ruleset (bool) |
| | 313 | + * lookbackLength: Number of characters before the cursor to include |
| | 314 | + * when matching the first regex of each rule. This is |
| | 315 | + * usually the maximum number of characters a rule |
| | 316 | + * regex can match minus one. |
| | 317 | + * keyBufferLength: Length of the key buffer. May be zero if not needed |
| | 318 | + * rules: Array of rules, which themselves are arrays of three strings. |
| | 319 | + * rules_x: Extended ruleset. This is used instead of the normal |
| | 320 | + * ruleset when Alt is held. This key is only required if |
| | 321 | + * extended_keyboard is true |
| | 322 | + * |
| | 323 | + * NOTE: All keys are REQUIRED (except rules_x when not used). Missing |
| | 324 | + * keys may result in JS errors. |
| | 325 | + * |
| 288 | 326 | * @param name Name of the scheme, must be unique |
| 289 | | - * @param data Object with scheme data |
| | 327 | + * @param data Object with scheme data. |
| 290 | 328 | * @return True if added, false if not |
| 291 | 329 | */ |
| 292 | 330 | this.addScheme = function( name, data ) { |