changeset 181:013e79e36f1a

work in progress README for 0.7.0

--- a/README	Mon Aug 04 19:05:53 2008 +0900
+++ b/README	Tue Aug 05 04:10:02 2008 +0900
@@ -1,37 +1,37 @@
-pidgin-twitter-0.7.0 alpha1
+pidgin-twitter-0.7.0
 
 
 1. What is this?
 
-pidgin-twitter is a pidgin plugin to help twittering via pidgin. This
-plugin translates any @username and the sender name to the link to the
-user respectively. pidgin-twitter also can play a sound when an
-incoming message contains any recipient name or sender name which is
-listed in the each dedicated lists.
+pidgin-twitter is a pidgin plugin to help posting and reading micro
+blogs such as Twtter. Currently, pidgin-twitter supports Twitter,
+Wassr and identi.ca.
 
-From version 0.5.0, pidgin-twitter automatically escapes annoying
-"pseudo command" in sending message. A pseudo command is a message
-like "にほんごw" or "....w" and it will be wrongly interpreted as an
-incomplete command message so that twitter gives us an error massage.
+Features:
+General
+    * display user icon (size configurable)
+    * translate sender's name and @<username> to link to the user's
+      home
+    * play sounds for specific senders/recipients
+    * show letter counter on the format toolbar
 
-In version 0.6.0, various new features have been added. Letter counter
-for composing message is useful for keeping track of the length limit
-of twitter message and oops suppression will give users who mainly use
-multi byte characters comfortable twittering. And also, from version
-0.6.0, pidgin-twitter strips any markup elements from sending message,
-so the posts from pidgin-twitter are always kept sane.
+Twitter specific
+    * get/post twitter statuses via API
+    * escape pseudo commands like "w"
+    * suppress oops message return
 
-*update*
-In version 0.7.0 alpha1, show icon feature and API based posting
-feature have been added. Although these new features are under
-development, they seem to be very useful in the current twitter
-situation. This is the reason why we decide to release this alpha
-version.
+Wassr specific
+    * Translate #<channel name> to link to the channel
+    * eliminate annoying post completion messages
+
+identi.ca specific
+    * eliminate annoying echo backed messages.
 
 
 2. Dependency
 
-This plugin requires pidgin 2.4.0 or newer and glib-2.14.0 or newer.
+This plugin requires pidgin 2.4.0 or newer, glib-2.14.0 or newer and
+libxml-2.6.27 or newer.
 
 
 3. How to build
@@ -45,23 +45,105 @@
 
 4. Usage
 
-To enable pidgin-twitter, please check it "Enabled" in pidgin's
-plugins window. If it is enabled, it replaces each @username string
-and sender string with the link to the corresponding user, by
-default. You can enable/disable these via plugin's configure window.
+To enable pidgin-twitter, please check it as "Enabled" in pidgin's
+plugins window. Almost all of features can be configured through
+pidgin-twitter's paged preferences window. In this chapter, we explain
+the features in page by page basis.
+
+
+4.1 Account page
+
+4.1.1 Screen Name
+
+You can specify your account names for each service here. These names
+will be used for showing your icon in a conversation, and more, in
+twitter, it will be used for authentication when API based access is
+enabled.
+
+4.1.2 Get/post statuses via API
+
+Since pidgin is an instant message client, it is natural that pidgin
+uses XMPP protcol to access twitter. However, twitter has suspended
+theier IM gateway service for long time, for maintenance reason. So we
+had decided to provide the other way to access to twitter using
+twitter's public API.
+
+If you enables this feature, pidgin-twitter will get your timeline
+and put your update via twitter API.
+
+4.1.3 Password
+
+This password is used for basic authentication which is required to
+access twitter via API.
+
+4.1.4 Retrieve interval
+
+You can specify the interval between each retrivals by ten seconds.
+
+4.2 Translation page
+
+4.2.1 Translate @username to link
+
+It toggles translation from a recipient name to the link to the
+recipient.
+
+4.2.2 Translate sender name to link
 
-Play sound for matched recipients or sender is also enabled by
-default, however it might not work until you specify user lists for
-this feature.
+It toggles translation from a sender name to the link to the sender.
+
+4.2.3 Translate channel name to link
+
+It toggles translation from a channel name to the link to the
+channel. This feature is available only for Wassr.
+
+4.3 Icon page
+
+4.3.1 Show icon in conversation
+
+It toggles show/hide icons for users in conversations.
+
+4.3.2 Icon size
+
+Icon size in conversaions can be specified by this spin button.
+
+4.3.3 Enable update
+
+It toggles enable/disable update for icons by the specified
+period. See bellow for the period.
 
-Recipient list accommodates names of watched recipients. Usually, the
-first name might be your user name. Sender list accommodates names of
-watched senders, instead.  These lists are independent to each other
-so that you can maintain different groups to be watched. An user list
+4.3.4 Update period
+
+You can specify update period here in two ways. The first is times of
+showing one particular icon before update. The later is days before
+update.
+
+
+4.4 Sound page
+
+4.4.1 Play sound on a reply to a recipient in the list
+
+It toggles play
+
+This functionality is also able to be toggled
+on/off via configuration window.
+
+
+
+Usually, the first name might be your user name.
+
+
+4.4.2 Recipient list
+
+Recipient list accommodates names of watched recipients. An user list
 is a enumeration of usernames separated by a letter in ",:;". For
 example, "foo bar" or "foo,bar" is a valid user list and a list like
-"foo, bar" also works. This functionality is also able to be toggled
-on/off via configuration window.
+"foo, bar" also works.
+
+These lists are independent to each other
+so that you can maintain different groups to be watched.
+
+
+4.4.3 Sound type
 
 Event type of sound to play is also configurable. By default, the
 "Pounce Default" sound is specified since it may not be disabled by
@@ -69,9 +151,29 @@
 but be aware, you have to enable the event type of sound which you
 specified for pidgin-twitter in pidgin's preferences.
 
-Escape pseudo command functionality is enabled by default. To disable
-this feature, please uncheck it in the plugin configuration window. I
-recommend you to leave it always enabled.
+
+4.4.4 Play sound if the sender of the message is in the list
+
+This is same to 4.4.1 except that it is for senders.
+
+4.4.5 Sender list
+
+This is same to 4.4.2 except that it is for senders.
+
+Sender list accommodates names of
+watched senders, instead.
+
+4.4.6 Sound type
+
+This is same to 4.4.3 except that it is for senders.
+
+4.5 Utility page
+
+4.5.1 Show text counter widget
+
+Letter counter for composing message is useful for keeping track of
+the length limit of twitter message and oops suppression will give
+users who mainly use multi byte characters comfortable twittering.
 
 Letter counter will appear on the format bar in a pidgin conversation
 window. This counter keeps track of length of composing string in
@@ -81,6 +183,21 @@
 This feature is enabled by default. You can disable this via configure
 window.
 
+
+4.5.2 Escape pseudo command in twitter
+
+Escape pseudo command functionality is enabled by default. To disable
+this feature, please uncheck it in the plugin configuration window. I
+recommend you to leave it always enabled.
+
+From version 0.5.0, pidgin-twitter automatically escapes annoying
+"pseudo command" in sending message. A pseudo command is a message
+like "にほんごw" or "....w" and it will be wrongly interpreted as an
+incomplete command message so that twitter gives us an error massage.
+
+
+4.5.3 Suppress oops message
+
 Suppress oops message feature may require explanation. If we send a
 message which is longer than 140 bytes, twitter will send us back an
 oops message to notify the excess of the limit. However, the actual
@@ -90,9 +207,16 @@
 oops message in this situation. This feature can also be configured
 via configure window.
 
-Strip markup feature is for keeping posts sane by striping excess
-markup in sending message. This feature is always enabled and cannot
-be configured.
+4.5.4 Do not notify incoming message
+
+(xxx)
+
+
+4.5.5 Output log message
+
+It toggles log messages for debugging. If you have any trouble, we
+sugest to enable this and examine what is happening and report us your
+problem with this information.
 
 
 5. History
@@ -124,11 +248,20 @@
 - Annoying completion message which is returned from wassr service
   will be automatically ignored.
 
+0.7.0 (Aug 5 2008)
+- Support for identi.ca has been added.
+- Icon support for wassr and identi.ca have been added.
+- Icon size and icon visiblitiy are now configurable.
+- Automatic icon update has been implemented.
+- Translation from channel name to the link to the channel in wassr
+  has been added.
+- Disabling notifications on message arrival now works for wassr and
+  identi.ca too.
 
 6. Acknowledgments
 
-I got some valuable feedbacks from nosuke (@konosuke) and mojin
-(@mojin).
+In the begining of development, I (yazuuchi) got a number of valuable
+feedbacks from nosuke (@konosuke) and mojin (@mojin).
 
 The original letter counter has been developed by Dossy Shiobara in
 convcharcount plugin.
@@ -137,6 +270,10 @@
 contributed numerous efforts. The original strip markup feature and
 the disable markup widgets feature has been developed by him.
 
+API based posting has been contributed by nosuke in development for
+0.7.0.
+
+We got numerous feedbacks from users in the #pidgin_twitter channel.
 
 Yoshiki Yazawa (@yazuuchi) and the pidgin-twitter team
 [e-mail]