commit 05a2adf0a899ff7e858751c0d84f6e467cb8205e
parent 7541e2c181e44c1ddfd15fc77e8c8c9ea889305b
Author: Antoine Amarilli <a3nm@a3nm.net>
Date: Mon, 11 Jun 2012 19:51:03 +0200
update doc
Diffstat:
| README | | | 56 | ++++++++++++++++++++++++++++++++++++++++++++------------ |
1 file changed, 44 insertions(+), 12 deletions(-)
diff --git a/README b/README
@@ -1,16 +1,48 @@
wikifirc -- filter irc.wikimedia.org on specific pages and users
Copyright (C) 2012 by Antoine Amarilli
-Run as wikifirc ADMIN [DUMP]. DUMP should be a file to dump the currently
-followed pages, it will be read at startup. ADMIN should be the name of an
-administrator who will send commands to the program. Events from
-irc.wikimedia.org should be provided in the irctk format on standard input, the
-data of matching lines will be sent on standard output and added pages on
-standard error.
-
-The list of pages and users to follow is initially empty. ADMIN can send the
-name of new users to follow as the body of a IRC message to the program. The
-user and user talk pages of an user are followed. Whenever a followed user
-modifies a page, the page is followed. The program will display modifications
-that are performed on a followed page or performed by a followed user.
+wikifirc is a tool to filter changes from irc.wikimedia.org on specific pages
+and users. All events on followed pages, all events by followed users, and all
+events on followed users' user and user talk pages are kept and the rest is
+discarded; besides, when a followed user edits a page, the page becomes
+followed.
+
+Run as wikifirc ADMIN [DUMP]. DUMP is a file that will be read at startup to
+populate the list of followed users and pages. ADMIN should be the nick of the
+program administrator or irc.wikimedia.org. Events from irc.wikimedia.org should
+be provided in the irctk format on standard input, the data of matching lines
+will be sent on standard output (to be piped in irctk) and newly followed pages
+on standard error.
+
+The administrator can send the following messages to the program via an IRC
+query:
+
+- exit: Exit the program.
+- page PAGE: Follow page PAGE.
+- user USER: Follow user USER.
+
+The administrator is only authentified by their nick, so keep potential security
+risks in mind.
+
+Here is an example of how you can use the program, using irctk
+<http://gitorious.org/irctk/>, sponge <http://joeyh.name/code/moreutils/> and
+the provided ircfilter.py:
+
+ irctk -q uniquebotnick@irc.wikimedia.org \#fr.wikipedia \#en.wikipedia |
+ ./ircfilter.py |
+ ./wikifirc adminnick pagelist 2> >(sponge pagelist) |
+ ./irctk -q botnick@yourserver \#yourchannel
+
+This call reads recent changes on the English and French Wikipedia, pipes it to
+ircfilter.py to avoid encoding issues, then pipes it to wikifirc (followed pages
+are read from pagelist at startup and written to pagelist on exit) and pipes it
+to your own IRC server. The bot can be controlled by /msg'ing uniquebotnick as
+adminnick on irc.wikimedia.org.
+
+A few things can easily be tweaked in the code:
+
+- add support for different languages
+- disable coloring
+- formatting changes differently
+- using a custom URL shortener, or no URL shortener
