diff options
| -rw-r--r-- | INSTALL | 254 |
1 files changed, 254 insertions, 0 deletions
@@ -0,0 +1,254 @@ +ErbotInstallation + +Other sections: + + ErbotInstallationItalian — A (slightly dated) Italian version translated graciously by Enrico Bandiera. + +Disclaimer: Please note that ErBot does not come in a nice packaged form for install yet. :). Nonetheless, if you want to install it and run it for some +channels, here are step-by-step instructions that should be pretty easy. ErBot is most specially suited to lispy channels like #emacs and may not necessarily be +suited for your needs. Have a look at the bot apt in #debian, and its package bobot++, to see if that suits you better– in fact, a lot of ErBot’s english +interface is inspired from apt’s. Having said that, I think I like fsbot’s design and syntax more — allow the user a similar fuzzy english syntax that apt does, +but that fuzzy syntax is just an interface to an accurate lisp syntax, which is also available to the user. Also, fsbot does a much smarter search-lookup, has +tons of other features and is also a minor lisp interpreter. + +IF YOU ARE UPGRADING YOUR BOT FROM A PREVIOUS, DON’T FORGET TO MAKE BACKUPS OF YOUR botbbdb, userfunctions.el, ETC. BEFORE RUNNING THE NEW VERSIONS. fledermaus +has ensured proper encoding going forward, but you should probably check that your old botbbdb works well with the upgraded version. + +Please let me know if there are any steps missing from here or anything is incomplete, and also feel free to edit anything in this page. – DeepakGoel +Contents + + Basic Installation + Erbot can google. Want google? + Wiki Training + Alternate Method of Wiki Training + Other Advanced Customization + More help + +Basic Installation + +The following are geared towards emacs newbies who are using debian. ~ refers to /home/mybot throughout this section. + +X/Emacs versions: Erbot is developed on and for the stable debian emacs: (21.4.1 as of dec, 2005). It works on later emacsen, but some googling does not work on +Emacs 22.1 ATM. SebastianFreundt has ensured that erbot works on xemacs too – 21.4 and 21.5 + + Install emacs, say: apt-get -u install [-t sarge] emacs21, and apt-get -u install [-t stable] emacs21-el. The package emacs21-el helps with ErBot’s +“find-function” functionality. + Install ERC (su and then type apt-get [-t sid] -u install erc, or when you know what you are doing, preferably get the CVS). It is HIGHLY recommended to use +ERC 5.1 or greater due to its superior flood-protection algorithm. At some point in the future, support for earlier versions of ERC will be dropped. + Install BBDB: apt-get -u install bbdb. + Install Calc: apt-get -u install calc. (There doesn’t seem to be a calc package in Debian? --JohnSullivan) + Install dictionary-el (apt-get [-t sarge] -u install dictionary-el), optional, if you don’t, the dictionary funtions of the bot will not work.. + adduser mybot, and su to mybot. Please note that you need to do actually “su - mybot”, so that you get a login shell. If you don’t, you’ll get all your +paths messed up, and you’ll never be sure of what .emacs you actually load. For the rest of the page, whenever you see su mybot, keep in mind that it’s “su - +mybot”. Add all needed directories. Here are some of them: + cd ~, mkdir elisp, mkdir public_html, ln -s public_html pub, mkdir public_html/karma. You should make the karma directory even if you don’t want the normal +karma—the bot shall store the frequency of referred terms in this directory. + mkdir ~/public_html/data, mkdir ~/.url, touch ~/.emacs.private + Optionally, ensure that the programs wget, w3m (used for training the bot), fortune are installed on your machine. Fsbot has functions for different types +of fortunes, for access to all of them, (optionally) install all these (debian) fortunes packages: display-dhammapada, dopewars, fortunes, fortunes-min, +fortunes-debian-hints, fortunes-mario, libfortune-perl, fortune-bofh-excuses, twisted-quotes. + erbot files: Fetch all the erbot files and the README to ~/elisp/erbot, as in the CVS instructions below. Make sure that the contents of the contrib +subdirectory are saved to ~/elisp/contrib. + OR: Simply wget the latest tar.gz dated dev “release” and gunzip it and untar it to ~/elisp/erbot. + Here are the files in CVS: + http://savannah.nongnu.org/cgi-bin/viewcvs/erbot/erbot/ + http://savannah.nongnu.org/projects/erbot/ + cd ~/elisp/erbot + export CVS_RSH=“ssh” + cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/erbot co erbot + These files from CVS will then go in mybot’s ~/elisp/erbot/erbot. + Or the files can be gotten from deego’s current fsbot install, + .el’s from http://gnufans.net/~deego/pub/emacspub/lisp-mine/erbot/erbot/ or + .gz snapshots from http://gnufans.net/~deego/pub/emacspub/lisp-mine/erbot/ + +Place all these files in ~/elisp/. + + su - to mybot and copy the file examples/dotemacs-mybot (included with ErBot) to ~/.emacs. Make sure that the folowing entries appear in that .emacs: + (setq bbdb-case-fold-search t) + (setq erc-auto-query t) + (setq erc-server-flood-penalty 2) + (setq erc-server-flood-margin 10) + (setq erbot-paranoid-p nil) + (setq erbn-url-functions-p t) + Optionally, if you want to use the alternative method of wiki training (see below), add the following line, (require 'erburl) in ~/.emacs immediately after +(require 'erball) line. Technically, it needs to be added before (erbot-install) so the ffi-* functions are mapped to the appropriate ff-* functions. This +library uses the url package which can be found in this debian package: apt-get install w3-url-e21. + Optionally, if you want to permit users to let the bot learn javadoc pages (see ErBot page), add the following line, (require 'erbjavadoc) in ~/.emacs +immediately after (require 'erball) line. Technically, it needs to be added before (erbot-install) so the ffi-* functions are mapped to the appropriate ff-* +functions. This library uses the url package which can be found in this debian package: apt-get install w3-url-e21. + Optionally, when users paste URLs into a channel, erbot can automatically download them and scan for a TITLE element in HTML and then send a note to the +channel with the description. This can be useful for other readers on the channel. To enable, add the following line to your .emacs: (setq fs-web-page-title-p +t). Care is taken to not download binaries or mp3s and such. + I recommend that you use the small sample provided at: http://gnufans.net/~mybot/data/botbbdb as your bot’s datafile at first, so just copy this file to +mybot’s ~/pub/data/botbbdb. This sample contains some iniital “help” data, which botusers will find useful. This is also in public domain, so that you can use +whatever license you want. Please not that fsbot’s botbbdb, on the other hand, is NOT in public domain. If you use that, you are bound to keep your botbbdb’s +license as GFDL (with no invariant sections). If that is what you desire, you are welcome to get the data from http://users.pepperfish.net/fsbot/data/. + If you want to byte-compile the ErBot source for speed, run make. + To install the files to a particular place, edit Makefile to change the PREFIX and ELISPDIR options (if desired), and then run make install. + That’s it. Congrats. Your bot is ready. Su to mybot, start emacs (type emacs) and now run it by typing any of these: + f9 f1 + Control-c j SPACE + ESC x erbot-join-servers RETURN + M-x erbot-join-servers RETURN + +Erbot can google. Want google? + + Write to google to request a license-key (expect immediate automated reply) and a permission (don’t really expect a reply, IME, YMMV) for your bot to serve +google search results. Check out http://www.google.com/apis/ . Put that license key into mybot’s ~/.emacs.private, like this: (setq google-license-key +“foodfhjdkjdfkMYLicensekeylkfgnjkfgkjfkj”) + apt-get install w3-url-e21 + BTW, If you want to enable the silly magic-8-ball, add (setq fs-m8b-p t) to its .emacs. Then it answers any questions ending in ?? using a magic-8-ball. + +Wiki Training + +What good is an infobot unless it knows a few thousand pages. You can, of course, train it by talking to it, but wouldn’t you like that it automatically learn a +few wikis? The good (bad?) thing about this automated training-through-IRC is that anyone can use this to train anyone’s bot through IRC. Thus, this section is +currently a bit geared towards those somewhat familiar with elisp. If you are a bit lost by this section(shouldn’t be), catch hold of me or any lisp expert and +ask them to use erbwiki.el to train your bot on a particular wiki. + +In this section, ~ refers to your account, you being the person who is training someone’s bot on some channel, say on #somebot. Again, when you train the bot, +you use your own Emacs as yourself, not the bot’s. Both you and the bot would be connected to irc, where you will (automatedly) train the bot. + + add some directies to your account: mkdir ~/pub/, mkdir ~/pub/pub, mkdir ~/pub/pub/fsbot-train, mkdir ~/elisp, mkdir ~/elisp/erbot. + Install w3m. (apt-get -u install w3m). + See the file erbwiki.el, see in particular the variable, erbwiki-index-pages. Customize it to add your favorite wiki (or website) and give it a name, say +“mfw” for “my favorite wiki” Launch erc and join the channel in which you train (I train, for example, in #fsbot). Customize erbtrain-buffer in your .emacs to +point to that buffer. Start a new Emacs – start it in the -nw mode -- don’t do wiki training with an Emacs that you normally use to connect to IRC, since active +channels constantly make that Emacs “inactive”, thus delaying idledo-actions forever. Then, in this new emacs, type M-x erbwiki-connect-my (if needed for your +configuaration, this just ensures that you are connected to irc) followed by M-x erbwiki-main-doit-all-one-wiki mfw RET to make your emacs slowly train the bot +present on that channel. That function will train the bot on the current wiki, it will also keep a record of the entries the bot has been trained on, so that +future invocation of the function trains the bot only on the newer entries. The reason we asked to start emacs as -nw: Otherwise, any “X” thing you do, like +switching workspaces, moving mouse focus, etc. will disturb the emacs’ idle time and the idledo’s may never get a chance to run. For the same reason, we ask +that you start a NEW emacs. + Notice that the third field of erbwiki-index-pages can be a function—this can be one of the various ebrwiki-get-fields-* functions. The default (nil) should +probably work for you, but depending on how your wiki’s index pages look like, you might need to use one of the others, or even create your own. If you need +advice on this, please let me know. IF you create your own, please definitely do contribute your function to the main erbwiki.el + Having done that, you probably want to simplify the process for yourself, so that you can type one command in a fresh emacs, say once a week and emacs takes +care of the training. Look at some existing erbwiki-main-main-* functions and define your own for your own wiki and from then on, you just need to call that. + Now, you probably don’t want to have to manually connect by hand every time you want to train. A workaround is to setq erbwiki-before-train-hooks to +(erbwiki-connect-my) in your .emacs, where: + + (defun erbwiki-connect-my () + (interactive) + (unless (or (buffer-name-p-my "#somebot") erbwiki-connected-p-my) + (setq erbwiki-connected-p-my t) + (setq utils-erc-channels-list utils-erc-channels-list-train) + (erc-select-noninteractive-my))) + +Those intermediate functions for me are here: + + (setq utils-erc-channels-list-train + '(("irc.freenode.net" + ( + "#somebot" + )))) + + ;;;###autoload + (defun buffer-name-p-my (name &optional matchfn) + "Whether name is the name of a buffer.." + (unless matchfn (setq matchfn 'string=)) + (member-if + (lambda (arg) + (funcall matchfn name + (buffer-name arg))) + (buffer-list))) + ;;;###autoload + (defun erc-select-noninteractive-my (&optional server port nick + user-full-name + not-connect-arg passwd) + "Interactively run ERC, while trying to do a minimal prompting. + Optional argument SERVER uses server as default for the input query. + Optional argument PORT uses passed port as default for the input query. + Optional argument NICK uses the passed nick as default for the input query." + (interactive) + (require 'erc) + (if (and (null server) (listp erc-servers-my)) + (mapcar + '(lambda (arg) + (erc-select-noninteractive-my + arg port nick user-full-name not-connect-arg passwd) + (sit-for 1) + ) + erc-servers-my) + (progn + (if (null server) + (setq server erc-server)) + ;; 2002-08-21 T11:22:35-0400 (Wednesday) D. Goel + (setq erc-current-server-my server) + + (if (null port) (setq port erc-port)) + (setq nick (erc-compute-nick nick)) + (let* ( + (nick + (if (erc-already-logged-in server port nick) + (read-from-minibuffer + (erc-format-message 'nick-in-use ?n nick) + nick + nil nil 'erc-nick-history-list) + nick))) + (if (and passwd (string= "" passwd)) + (setq passwd nil)) + (while (erc-already-logged-in server port nick) + (setq nick (read-from-minibuffer + (erc-format-message 'nick-in-use ?n nick) + nick + nil nil 'erc-nick-history-list))) + (run-hook-with-args 'erc-before-connect server port nick) + (erc + server port nick user-full-name (not not-connect-arg) passwd))))) + + Finally, If you want the bot to forget, rename, or process large chunks of data, see erbforget.el and extend it to your needs.. + +Alternate Method of Wiki Training + +If you want a fairly simple method of wiki training, try the following instead (requires the url package which can be found in this debian package: apt-get +install w3-url-e21): + + (require 'erburl) + (erburl-scrape-terms + "http://www.emacswiki.org/cgi-bin/wiki?action=index") + +The above will load all of the terms from this wiki along with links back to the appropriate pages in very little time (compared to the previous training +method). This call is asynchronous although you will not be able to do anything on the emacs console because it will be busy, but erbot will still be able to +respond to user requests in a channel if connected. + +It should be noted that this method of training does not remember what has been added (like the previous method); however, scraping the same page more than once +will not add duplicate entries. + +Finally, any URL can be scraped for data as you can pass your own parser to the above function. See the quickhelp in erburl.el and the docstring for +erburl-scrape-terms. +Other Advanced Customization + + To enable logging, look at ErcLogging. + This bot has uses defined for several extra libraries, when they are present. Most are available from http://gnufans.net/~deego/pub/emacspub/ or else, from +the wepages of their authors: + faith.el + oct.el + geek.el + if your bot plans to hang out on lispy channels, do comment out the line of mybot’s .emacs that says (erbunlisp-install). Here’s the whole boring story: + +erbot usually defines its functions to not conflict with existing lisp functions. Thus, the usual way to remove bot entries is RM and FORGET, but not REMOVE. +The latter is a lisp function and gets passed to emacs’s own lisp for processing. + +However, many people (esp. on nonlispy channels) don’t care much for elisp’s functions, and the first thing they try for removing entries is (remove). Mybot’s +default .emacs makes that (remove) work through (erbunlisp-install).. That function takes special care of these rare “conflicts”. IOW, (erbunlisp-install) +ensures that (remove) gets passed to ERBOT’s (fs-rm) function instead of lisp’s (remove). REMOVE is just an example, (erbunlisp-install) shall seek to usually +take care of all similar issues. + + .emacs.private is probably the right place to edit erbot-ignore-nicks, which is a list of regexps which erbot will not reply to. The primary purpose of that +variable is to avoid bots getitng into infinite loops with other bots :) + See the .emacs of mybot, it has useful stuff bound to f6 f6. This helps keep track of channels in which mybot’s circuits got triggerred in response to +something, (whether or not it replied anything is a different matter). Pressing f6 f7 resets this list. + Defun functions like (fs-foo) to the bot’s ~/.emacs to add any more functions to your bot. To disable a pre-existing function, (fmakunbound ‘fs-foo) should +work. Note that anyone and everyone on irc will be able to execute your defunned function, so be careful when defining new functions for your bot. A rule of +thumb to ensure safety: Make your function use only other pre-existing fs- functions. If your function makes recursive cals, don’t forget to add a (sit-for 0) +in front of the definition, else timeout will never get a chance to act, and your bot may hang if someone manages to request an infinite recursion on your +function. + To add any additional immutable functions, use the format (fsi-foo) instead of fs-foo. Defun these functions at the top of your .emacs. When loading, the +engine converts all such functions to fs-foo but marks them immutable. + This might be useful. To the end of mybot’s .bashrc, add umask 022. Add yourself to mybot’s group, say via: adduser deego mybot. Also su to mybot and “chmod +-R -g+rw .”. Now log back out and login, Now you (deego)should be able to edit mybot’s .emacs etc. without having to su to mbot. + While it is best for you, the bot operator, to learn how to do edit botdata by talking to the bot (See the manual at ErBot), you can also edit them more +easily by going to bot’s emacs and typing M-x bbdb … if you know what you are doing… + ErBot has many other undocumented or work-in-progress features, just chat with the author(s) for what you may have in mind, or explore the sources. If you +add/improve something or complete a feature in your sources, please contribute it back upstream :). |