--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Modules.mdwn	Sun May 14 20:58:00 2017 +0300
@@ -0,0 +1,334 @@
+
+[[!toc levels=2]]
+
+# Overview
+
+Starting from version 0.10.0, mcabber supports dynamic loading of modules. It
+introduces the command `/module` with subcommands to load, unload and obtain
+info on modules. This command is allowed during initialization time, so you can
+specify it in your mcabberrc. Modules are searched in the directory specified in
+mcabber variable `modules_dir`, that you should set before issuing these
+commands. Default module installation/loading directory is `/usr/lib/mcabber`.
+
+The API is still experimental and likely to be changed, but there is a short
+HOWTO about writing your own modules in `doc/` subdirectory of mcabber source.
+It contains up-to-date information on module-related routines that mcabber
+offers and some examples.
+
+# Existing modules
+
+Right now the following modules are available (if you know of some other
+modules, feel free to add them to list below):
+
+## antispam
+
+* URL: <https://bitbucket.org/georgri/mcabber-modules/>
+
+Enables simple question-based antispam-bot which asks predefined question to
+every unsubscribed buddy, expecting them to give the right predefined answer.
+Currently you may change the standard question/answer only by changing the
+source code.
+
+## avatar
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-avatar/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-avatar/index/>
+* Mirror: <http://hg.lilotux.net/mod-mcabber-avatar/>
+
+This module implements avatar publishing/retrieving via pep/pubsub. It informs
+you when your buddies publish their avatars via pep and provides command
+`/avatar` to publish your own. But this is not all: It also will actually show
+you buddy's avatar! Yes, it is aalib :)
+
+Note: this module should eventually merge with pep (at least partially)
+
+## avv
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-avv/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-avv/index/>
+
+Advanced version verification (or something like that, I now cannot recollect
+initial meaning of this abbreviature). Alternative module loading system, that
+allows flexible module compatibility determination. It splits API, provided by
+mcabber into a set of smaller APIs. This allows to omit module update, when
+major API change have not changed used by this module mini-APIs. Also, module
+information is now stored separately, in usual text file, that may be adapted by
+hand to user environment. Fallback legacy module loading scheme is not yet
+implemented :(
+
+## beep
+
+* URL: <http://mcabber.com/hg/>
+
+Simple module to beep on **all** messages. Available in mcabber 0.10.0. Serves the
+purpose of example for module writing HOWTO.
+
+## clock
+
+* URL: <http://hg.lilotux.net/mcabber-modules/>
+
+This module uses the 'info' option to display the date and time in the status
+bar. This module is part of the mcabber-modules repository.
+
+## cmd
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-cmd/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-cmd/index/>
+* Mirror: <http://hg.lilotux.net/mod-mcabber-cmd/>
+
+Provides command `/cmd`, that sends output of specified shell command to current buddy.
+
+## commands (custom)
+
+* URL: <https://github.com/hirthwork/mcabber-commands/>
+
+Allows to add commands with dynamic completion lists, based on regexp-matching
+over incoming buddy messages (a bit similar to urlopen). Useful for
+microblogging.
+
+## comment
+
+* URL: <http://hg.lilotux.net/mcabber-modules/>
+
+Trivial module; adds a command `#` to ignore a line. This module is part of the
+mcabber-modules repository.
+
+## disco
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-disco/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-disco/index/>
+* Mirror: <http://hg.lilotux.net/mod-mcabber-disco/>
+
+Module adds `/disco` command, that sends service discovery requests.
+
+## env
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-env/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-env/index/>
+* Mirror: <http://hg.lilotux.net/mod-mcabber-env/>
+
+Tampering with mcabber's environment. This module can be useful for development
+and debugging, as well as for on-the-fly changing of some parameters, like
+`AAOPTS` for aalib, used in avatar module. Also provides way to change current
+working directory.
+
+## eventcmd
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-patches/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-patches/index/>
+* Mirror: <http://hg.lilotux.net/mcabber-experimental/>
+
+Modularization of legacy mcabber eventcmd script. Available in experimental
+version of mcabber.
+
+## eventcmd-ng
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-eventcmd-ng/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-eventcmd-ng/index/>
+
+Another approach for eventcmd. It passes arguments to script as environment
+variables, so, you can use `$jid` instead of `$1`. Because of this it is more
+flexible for future changes (see hooks description in HOWTO). Though, it is not
+officially approved new interface for eventcmd - it is only my vision of it.
+
+## extsay
+
+* URL: <http://hg.lilotux.net/mcabber-modules/>
+
+If you use the [screen][] utility, this module will let you open your editor in
+a new screen window, and will send the message once you exit the editor. Check
+the [README][extsay-readme] file! This module is part of the mcabber-modules
+repository.
+
+## fifo
+
+Modularization of mcabber FIFO. Allows recreation of fifo in run-time by
+reloading module. This module has been merged into mcabber development tree
+(0.10.2-dev).
+
+## info_msgcount
+
+* URL: <http://hg.lilotux.net/mcabber-modules/>
+
+Displays the number of unread messages (buffers) in the status bar. This module
+relies on the `info` option, so it cannot be used with the clock module
+described above. This module is part of the mcabber-modules repository.
+
+## ignore_auth
+
+* URL: <http://www.freakysoft.de/repos/mcabber-modules/>
+
+Ignores subscription requests from every jid matching configurable regexs. Adds
+the command ignore_auth to add a regex to the list (`/ignore_auth .*@icq`). The
+option ignore_auth can be used to disable/enable this feature temporily
+(`/set ignore_auth = 1`). This module is part of the forked mcabber-modules 
+repository from franky.
+
+## jingle
+
+* URL: <https://github.com/alkino/mcabber-jingle>
+* HG Mirror: <http://hg.lilotux.net/mod-mcabber-jingle/>
+
+Jingle modules written by Alkino during the GSoC 2010. Contains a file transfer
+module (IBB support).
+
+## killpresence
+
+* URL: <http://hg.lilotux.net/mcabber-modules/>
+
+Adds two commands, killpresence and killchatstates, that can be used repectively
+to ignore the current presence from a fulljid (e.g. to kill a "ghost") and to
+reset the chat state status of an online contact. This module is part of the
+mcabber-modules repository.
+
+## lastmsg
+
+* URL: <http://hg.lilotux.net/mcabber-modules/>
+
+Stores highlighted messages received in MUC rooms while you are away. When
+you're back, you can use the command `/lastmsg` you display them. This module is
+part of the mcabber-modules repository.
+
+## lua
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-lua/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-lua/index/>
+* Mirror: <http://hg.lilotux.net/mod-mcabber-lua/>
+
+Lua interface module for mcabber. Adds `/lua` command (and much more in example
+scripts). Needs much more work, but already usable.
+
+Example scripts for this module extensively use lua bindings for loudmouth,
+`lua-lm`. It can be found here:
+
+* URL: <http://isbear.org.ua/hg/isbear/lua-lm/>
+* Homepage: <http://isbear.org.ua/docs/lua-lm/index/>
+* Mirror: <http://hg.lilotux.net/lua-lm/>
+
+## marking
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-marking/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-marking/index/>
+* Mirror: <http://hg.lilotux.net/mod-mcabber-marking/>
+
+Adds ability to mark several buddies and do some command for each of these
+buddies. Provides commands `/mark` and `/marked`.
+
+## mpd
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-mpd/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-mpd/index/>
+
+Provides information about currently playing song for modules like PEP.
+
+## mucignore
+
+* URL: <https://github.com/hirthwork/mcabber-mucignore/>
+
+Simple plugin to ignore users in MUC conferences.
+
+## pep
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-pep/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-pep/index/>
+* Mirror: <http://hg.lilotux.net/mod-mcabber-pep/>
+
+Suite of modules to publish and process PEP (Personal Eventing Protocol) tune,
+mood, geoloc and activity events.
+
+## si
+
+Stream initiation (file transfer profile) module. Uses streams module for its
+transfer methods, thus, it now supports both IBB and SOCKS5 Bytestreams.
+Provides command `/si`.
+
+**Note:** Stalled in the process of rewrite/update, contact
+[me](xmpp:isbear@jabber.kiev.ua), if you are interested in picking it up.
+
+## streams
+
+In-Band and SOCKS5 Bytestreams implementation. Adds command `/stream`. It
+supports IBB native session initiation and bare SCOKS5 Bytestream requests and
+can send/receive files this way. Though, this module is, probably, the only
+implementation, that supports such file transfer methods, so you will be unable
+to use this module alone to exchange files with, other clients. However this
+module is designed with ability to be used by other modules as transfer pipe,
+so, there is si/file-transfer module to transfer files in more convenient way.
+This module should be considered still in beta stage, but yet already usable.
+
+**Note:** Stalled in the process of rewrite/update, contact
+[me](xmpp:isbear@jabber.kiev.ua), if you are interested in picking it up.
+
+## templatecmd
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-templatecmd/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-templatecmd/index/>
+
+Allows to define alias-like commands with shell-like positional arguments
+substitution. Provides command `/templatecmd`. If you're searching for a way to
+define alias for `/send_to -f <filename_here> .` - this module is for you.
+
+## uptime
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-uptime/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-uptime/index/>
+* Mirror: <http://hg.lilotux.net/mod-mcabber-uptime/>
+
+Module to show mcabber uptime. It can either determine full mcabber process
+uptime from linux `/proc` filesystem or just count time from module loading
+moment.
+
+## urlopen
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-urlopen/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-urlopen/index/>
+
+Looks for urls in incoming messages and prints them to log and/or calls shell
+command to handle them.
+
+## xttitle
+
+* URL: <http://mcabber.com/hg/>
+
+Displays the number of unread messages in the X Terminal Title. The option
+`xttitle_short_format` can be set to use a very short title.
+
+## yaubil
+
+* URL: <http://isbear.org.ua/hg/isbear/mcabber-yaubil/>
+* Homepage: <http://isbear.org.ua/docs/mcabber-yaubil/index/>
+* Mirror: <http://hg.lilotux.net/mod-mcabber-yaubil/>
+
+Yet Another Useless Built-In Language. Provides `/eval`, `/if`, `/then`,
+`/else`, `/let` and `/multi` commands. Probably most useful amongst them is
+`/multi`. If, breaking my expectations, this module becomes useful and famous
+(presence of beard may cause this), I promise, that I'll improve
+string/parentheses parsing, add loops and maybe even switch to tree-producing
+parser with operators precedence.
+
+# Notes on modules, written by isbear, aka Mykhailo Danylenko
+
+* I use cmake as build system, it allows me to quickly generate debian packages
+  (not too accurate, but at least it is package). See README for a brief
+  description how to build module.
+* Most modules need more work - to add flexibility, providing mcabber variables,
+  that control module behaviour, to check for resource releasing in extreme
+  situations, etc.
+* Most modules, that provide some command also include help file for them (in
+  English). You may need to adjust variable help_dirs, if you have installed
+  module with another prefix than mcabber itself to be able to use this help
+  files.
+* Every module contains file modulename.rc (by default it will be installed into
+  `<install prefix>/share/doc/libmcabber-<modulename>/`), that contains list of
+  all mcabber variables introduced by this module with descriptions and load
+  commands, necessary to get this module loaded (i.e. first load commands for
+  modules, that are required for this module to work, then load command for this
+  module itself).
+* If you have found a bug in module, please contact me by mail or jabber (both
+  can be found in README file).
+* Unfortunately, most of the modules are now kinda unmaintained (if you need
+  something - ping me, and I'll try to do something about that, but no
+  guarantees). Adoption requests are warmly welcomed.
+
+[screen]:        http://www.gnu.org/software/screen/
+[extsay-readme]: http://hg.lilotux.net/mcabber-modules/raw-file/tip/extsay-ng/README