Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
273 lines (186 sloc) 9.54 KB
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 <mailto:chump@heddley.com>. If any of the examples in this
README get confusing, have a look at the original Daily Chump
<http://dailychump.org/> 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
<chump@heddley.com> 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 <http://pants.heddley.com/photos/>.
The keywords appear inside a <keywords> 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 <http://monkeyfist.com/DailyChurn/>. 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 <http://usefulinc.com/chump/>.
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
<http://joel.rosdahl.net/hacks/>.
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 <chump@heddley.com>.