dox/README.txt

   1 What is Guerilla Scripting?
   2 ===========================
   3
   4 GS is a userscript injecting engine, slightly similar to GreaseMonkey,
   5 but its primary audience are knowledgeable power users. GS was modelled
   6 after Opera 12 userscript engine, but with support for some GreaseMonkey
   7 API.
   8
   9 GS has absolutely no GUI controls.
  10
  11 GS also don't have any l10n, and probably will not have any. As there is
  12 no GUI and no user-visible dialogs, I don't see any real value in adding
  13 l10n to GS.
  14
  15 And last thing to say here: I know that it should be written "guerrilla".
  16 but do you really expect that guerrillas know how to spell such bizarre
  17 words? I found spelling error long after I released a preview to several
  18 people, and the name stuck. Let's say that one "r" is a trademark, like
  19 "ckr" for those you-know-them hipster sites.
  20
  21
  22 How Guerilla Scripting works?
  23 =============================
  24
  25 Contrary to GreaseMonkey, GS doesn't need any registration of userscripts.
  26 Simply copy your script in GS scripts directory with your file manager,
  27 and GS should find it. To remove script, simply delete it or change its
  28 extension to someting that is not ".js".
  29
  30 There is no itegration with any sites, nor automatic script updates from
  31 teh internets. GS will *never* connect to any internet site on it's own,
  32 it doesn't do any automatic installation or updating of userscripts.
  33
  34
  35 Is Guerilla Scripting secure?
  36 =============================
  37
  38 The only way to add a userscript to GS (besides packages) is to MANUALLY
  39 copy it in GS scripts directory (which is in your profile dir, named
  40 "guerillajs/scripts"). So if you wrote all the scripts by yourself, or
  41 got them from a friend whom you can trust, there should be no security
  42 risks.
  43
  44 GS will not do any connections to any sites on it's own. But note that
  45 userscripts are free to connect to any site they want (exactly as in
  46 GreaseMonkey), and additionally, userscripts are free to read you local
  47 files too. Please note that GreaseMonkey userscripts can't read your
  48 local files (they can try, but the request will fail), so you shouldn't
  49 simply copy GreaseMonkey userscripts to GS without understanging what
  50 they are doing under the hood.
  51
  52 The reason for giving GS userscripts access to local files is the
  53 difference in addon target group. While GreaseMonkey is aimed at casual
  54 users, GS is aimed at knowledgeable power users, who may want to squeeze
  55 some more power from their userscripts.
  56
  57 WARNING! You should NEVER EVER install userscripts downloaded from
  58 internet to GS, unless you know *for* *sure* what those scripts do, why
  59 and how. If you'll install some malicious script downloaded from internet,
  60 that script can breach your privacy, steal or alter your private data and
  61 so on.
  62
  63 Please note that GreaseMonkey scripts can do privacy violation to some
  64 extent too, that is nature of userscripts.
  65
  66
  67 API differences to GreaseMonkey
  68 ===============================
  69
  70 some GreaseMonkey API aren't implemented, and some implemented in
  71 slightly different way. Script @metas altered too.
  72
  73 API that should work the same in GS and GreaseMonkey:
  74   unsafeWindow (not really, it is more a hack)
  75   GM_log
  76   GM_getValue
  77   GM_setValue
  78   GM_deleteValue
  79   GM_listValues
  80   GM_xmlhttpRequest
  81   GM_addStyle
  82   GM_openInTab(url[, background]) -- if `background` is boolean
  83
  84 extended API:
  85   GM_openInTab(url, options)
  86   options is an object which can contain such fields:
  87     bool background -- open tab in background
  88     bool afterCurrent -- open tab after current one,
  89                          if current is userscript tab
  90
  91 API that doesn't work (i.e. exists, but does nothing):
  92   GM_getResourceText
  93   GM_getResourceURL
  94   GM_registerMenuCommand
  95   GM_setClipboard
  96
  97 additional API:
  98   conlog (same as GM_log)
  99   logError (logs error message to error console)
 100   GM_generateUUID (same as in Scriptish)
 101   GM_cryptoHash (same as in Scriptish)
 102   GM_safeHTMLParser (same as in Scriptish)
 103
 104
 105 requirelib(name) API
 106 ====================
 107
 108 `requirelib` includes file from GS library directory, if that file wasn't
 109 included yet.
 110
 111
 112 requireinc(name) API
 113 ====================
 114
 115 `requireinc` includes file from userscript includes directory (see
 116 @require), if that file wasn't included yet.
 117
 118
 119 @meta differences to GreaseMonkey
 120 =================================
 121
 122 GS understands very small amount of @metas, and simply skips all keywords
 123 it doesn't understand.
 124
 125 working:
 126   @include
 127   @exclude
 128   @noframe
 129   @run-at
 130
 131 different:
 132   @require -- this works COMPLETELY different, see below
 133
 134
 135 Changed @meta: @require
 136 =======================
 137
 138 @require now can require only js files. All js files you want to @require
 139 should be placed in the directory named after your script. Let me give a
 140 sample.
 141
 142 Let's assume you has script named "myscript.js" with such contents:
 143
 144 // ==UserScript==
 145 // @require somecode.js
 146 // ==/UserScript==
 147
 148 GS will look for file "./myscript/somecode.js", relative to "myscript.js"
 149 directory.
 150
 151 If any @required file is absent, GS will refuse to run such userscript.
 152
 153 Multiple @require for same file are allowed, but that file will be loaded
 154 only once, first time GS sees @require with it.
 155
 156
 157 Known bugs
 158 ==========
 159
 160 Some GM API is not supported.
 161
 162 pjaxed pages doesn't work right.
 163
 164 Probably many other bugs I didn't found yet.
 165
 166
 167 Good luck, and happy hacking!
 168 Remember, by downloading FOSS software you are downloading COMMUNISM!
 169 Ketmar Dark  <ketmar@ketmar.no-ip.org>