Daily Chump Bot Readme: Chump Version 2.0 Contents 1. Overview 2. Installation 3. Using the bot 4. Advanced usage 5. Addressing and verbosity modes 6. XML and Archiving 7. Fancy tricks 8. Why the "Daily Chump"? 9. Chumps we know of 10. Credits 1. Overview This code allows you to run a collaborative weblog from your favourite IRC channel. A bot, written in Python, monitors URLs posted in the channel, and comments relating to those URLs. The bot automatically creates XML output from which you can create a web site, whose look-and-feel can be determined by your application of an XSLT stylesheet or other styling program. The XML files are automatically archived, with each day's comments and URLs assigned a permanent URL. Using additional programs in this distribution you can create links to recent days. Additionally, you may deploy a search engine of your choice to make the archives searchable. If you encounter problems and would like to get in touch with us, send email to . If any of the examples in this README get confusing, have a look at the original Daily Chump to see it in action. We'll do our best to help but please try hard to figure out your problems before contacting us. If you run a Chump with public pages, please send the URL to and we'll add the link into our pages. 2. Installation Please refer to the file INSTALL in this distribution to find out how to set up your Chump bot. 3. Using the bot The bot picks up on URLs and other keywords posted in the channel. For the sake of this example, our bot is called 'dc', our fictitious user is called 'fred', and we're in channel '#chump'. The simplest thing to do is to post a URL in, on a line on its own, like this: http://foo.com/bar.html The bot will reply with a label, say A, like this: -dc:#chump- A:http://foo.com/bar.html from fred Now you can then append comments about that URL by typing: A:This is my comment The URL will appear as a raw URL in the output, unless you give it a title. To do so, add a comment with a pipe in front of it, like this: A:|Foo.com - home of all things fooish You can change this title simply by posted a new piped comment, which will automatically over-ride the previous one. You can also use the Chump to post short notes that do not have a related URL. To start one of these, type: BLURB:My story about foo Again, the bot will assign a letter to this blurb, and you can add to it in the usual way. You can also use the bot to add some basic wiki-style markup to your comments. So, words within *asterisks* will appear emphasized. You can add an inline link (i.e., one within the text of a comment, rather than the title of a series of comments) using this markup: A:They also have [another site|http://foobar.com] ... this will make the words "another site" appear as a hyperlink to the URL immediately after them. You can also add inline images, which is occasionally handy, and frequently hilarious. These appear as though they are text comments from channel users. To include an image, you must first find its absolute URL, then post that as a comment like this: A:+[http://url.of.image.com/image.jpg] You can and should add alt-text to that inline image by inserting it before a pipe, like this: A:+[This is the alt text|http://url.of.image.com/image.jpg] The bot records the current IRC topic at the top. This means if you change the topic daily it gets used in indexes, so it serves as day-based metadata. The most recent topic will always be used in the day's XML file, and hence in a resulting page. One other useful feature is asking the bot what the status of posts is - especially useful if you have been away from the channel for a while and want to catch up. By typing dc:view ... the bot will show the titles and URLS of the last five (by default) posts. Alternatively, typing dc:view 2 ... will just show the last two posts, and so on. If you forget any of this, ask the bot for help or more help: dc:help dc:morehelp These commands can also be executed via querying the bot rather than in the public channel. 4. Advanced usage Since we first wrote the chump bot, it has become desirable to add a few more features to enhance usability and flexibility. These include the ability to edit and remove comments, and to assign keywords to an item. Comment editing is done via replacement. Simply type as would to add a comment, but instead of using, say 'A:', use 'A3:' to replace the third comment, for example. The numbers of the labels will be shown if you type "A:" on a line on its own in order to view the item. Deleting comments is also easy. To delete the third comment on item A:, you would type: A3:"" Note that all the comments renumber themselves after a deletion, so comment 4 will be at position 3, and so on. If you mistype a URL, it can be replaced like this: A:= http://newurl.example.com/ The ability to assign keywords allows more flexibility for an application that might process the XML coming from the chump. Keyword assignment is easy. To assign the keywords "xml" and "python" you might type: A:->xml,python To remove keywords, just type: A:-> Note that keywords is a free text field, you can put what you want in there. The Chump authors use this facility to pick out chump items for featuring in a photo-log at . The keywords appear inside a element in the output XML. There are some additional commands executed in the same manner as 'view'. These are: die Cause the bot to quit (synonyms: depart, leave) database Dump the bot's XML to the channel. Verbose! 5. Addressing and verbosity To suit the needs of various channels, the bot is configurable as to how much of an imposition it makes in public. If direct addressing is enabled (--address, see INSTALL for more details) then the bot will only respond to public messages prefixed with its name followed by a colon or comma, and optional space. For example: dc, view dc, A:|The Title Verbosity has three available levels. The default is to respond in public to each action a user takes. The second level, private, can be enabled with --private, and diverts all informational and error messages via private message to the user. The third level, quiet, can be enabled with --quiet, and only ever reports error messages. 6. XML and Archiving The bot creates an XML file from each day. During the day it writes to index.xml in the directory you specified on startup (see the -d option in the INSTALL documentation). When the first post to the bot after midnight GMT happens, the bot moves the index.xml file to YYYY/MM/DD/YYYY-MM-DD.xml and starts a new index.xml. The program extras/indexFiles.py can be used to index all these archived files and create index XML files. You will need to create XSLT stylesheets (or use your favourite XML styling mechanism) in order to show the world your weblog. We used our own version of the Apache mod_xslt module, which is included in this distribution in the extras directory. (** SEE NOTE BELOW) For help, we've included a bare bones XSLT sheet which uses both the main files and brings in the nav.xml file generated by indexFiles.py. Also included is a simple sheet to display the monthly indexes generated by indexFiles.py. (**) This method was used when we first made the bot. The best way to get the XML styled now is to use the --xsl and --web options to get the bot to serve styled HTML up itself. 7. Fancy tricks The 2.0 release of the Daily Chump incorporates some fancy tricks. * WEB SERVER: by means of Quixote, the bot is now able to serve the pages it creates. See the --xsl and the --web options in the man page (run man dailychump) for more details. * UPDATE NOTIFICATION: by using the --pingurl option, you can get the bot to send a notification to a web server when an XML file is updated. The filename is appended to the URL you specify. * MAKE THE BOT CHATTY: using the --formchat option, you can create a simple web form that makes the bot say things in a channel. This can either be used just for fun, or to tie other programs in that can cause the bot to send notifications to channel users. 8. Why the "Daily Chump"? The Daily Chump bot was inspired by work done by Bijan Parsia of Monkeyfist . Bijan's bot is written in Squeak, and called the DiaWebLogBot. We decided to copy his good ideas in Python and add XML output. 9. Chumps we know of The list of these is growing too fast to keep up to date in this manual. Instead consult . 10. Credits Matt Biddulph did the Python programming. Edd Dumbill did the XSLT and web server work, and some later Python hacking. Giles Turnbull wrote the first version of the manual. Matt Hunt encouraged, hooted and generally made us laugh. Thanks also to Joel Rosdahl, whose Python IRC library we used for the basis of this bot. You can find his library at . Bug fixes were sent in by Kendall Clark and Bijan Parsia. Patches and suggestions have been received from Phil McCarthy, Aaron Swartz, Josh Lucas, Kevin Burton. Contact us at .