annotate README @ 188:275872001d52

completed README. please check.

pidgin-twitter-0.7.0


1. What is this?

pidgin-twitter is a pidgin plugin to help posting and reading micro
blogs such as Twitter. Currently, pidgin-twitter supports Twitter,
Wassr and identi.ca.

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

Twitter specific
    * get/post twitter statuses via API
    * escape pseudo commands like "w"
    * suppress oops message return

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, glib-2.14.0 or newer and
libxml-2.6.27 or newer.


3. How to build

Building pidgin-twitter plugin is very simple. Please do;

./configure
make
sudo make install


4. Usage

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 section, 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 conversations. In a twitter
conversation, the screen name will be also 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 protocol to access twitter. However, twitter has suspended
their IM gateway 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 gets 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. Note that the twitter password is saved in
configuration file, e.g. ~/.purple/prefs.xml, as plain text and sent
to twitter API without encryption.

4.1.4 Retrieve interval

You can specify the interval between each retrievals by ten seconds.

4.2 Translation page

4.2.1 Translate @username to link

This checkbox toggles translation from a recipient name to the link to
the recipient.

4.2.2 Translate sender name to link

This checkbox toggles translation from a sender name to the link to
the sender.

4.2.3 Translate channel name to link

This checkbox 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 conversations

This checkbox toggles show/hide icons for users in conversations.

4.3.2 Icon size

Icon size in conversations can be specified by this spin button.

4.3.3 Enable update

This checkbox toggles update for icons by the specified period. See
bellow for the period.

4.3.4 Update period

You can specify update period here in two ways. The first is the
number of times showing one particular icon before update. The second
is days before update.

4.4 Sound page

4.4.1 Play sound on a reply to a specified recipient

This checkbox toggles play sound for a specified recipient.

pidgin-twitter can play a sound when an incoming message contains any
recipient name in the recipient list explained bellow.

It is convenient that add your screen name to the recipient list and
turn this feature on so that you can audibly notice each arrival or
message to you.

4.4.2 Recipient list

Recipient list accommodates names of watched recipients. This 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.

4.4.3 Sound type

You can specify Event type of sound to play here. The "Pounce Default"
sound is the default sound type because it may not be disabled by
configuration in pidgin's preferences. You can specify other sounds,
but be aware, you have to enable the event type of sound which you
specified for pidgin-twitter in pidgin's preferences.

4.4.4 Play sound on a message from a specified sender

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 sender list accommodates names of
watched senders.

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

This checkbox toggles letter counter. If it is enabled, a small letter
counter widget will appear on the format bar in a pidgin conversation
window. This counter keeps track of length of composing string in
character. Each service has its own limit of length for posting
messages; 140 characters in twitter, 255 characters in wassr and 140
bytes in identi.ca. If the composing message exceeds limit, the
displayed number will turn red to notify you the excess.

4.5.2 Escape pseudo command for twitter

This checkbox toggles escape pseudo command functionality.

A pseudo command is a message composed of leading non Latin string and
trailing an alphabet letter which can be interpreted as a command in
short form. Twitter wrongly interpreted it as an incomplete command
message so that twitter gives you an error massage.

If this feature is enabled, pidgin-twitter automatically escapes any
pseudo command by prepend ". " at the beginning of a message.

4.5.3 Suppress oops message

This checkbox toggles suppress oops message feature for twitter
conversation.

This 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, twitter computes the actual
hard limit in internal representation of characters so that the
messages which does not exceed 140 letters will actually be
accepted. This feature will silently discards *false* oops message in
this situation.

4.5.4 Do not notify incoming message (Windows only)

Suppress blinking Pidgin's task bar button for new incoming message 
when Pidgin window is not active. 

4.5.5 Output log message

This checkbox toggles log messages for debugging. If you have any
trouble, we suggest to enable this feature and report us your problem
with obtained information.


5. History

0.4.0 (May 01 2008)
First public release.

0.5.0 (May 05 2008)
Added escape pseudo command functionality.

0.5.1 (May 05 2008)
Fixed a crash bug that each unload and reload pidgin-twitter cycle
resulted in crash.

0.6.0 (May 16 2008)
- Letter counter has been added.
- Suppress "false positive oops message" when sending message which
  exceeds 140 bytes but within 140 characters.
- Pidgin-twitter now strips all markup elements from sending message.
  This feature prevents this plugin from posting unexpected
  excessively marked up message.
- Since pidgin-twitter no longer sends any marked up message, all
  markup widgets in conversation window have been disabled.

0.7.0 alpha1 (June 28 2008)
- Show icon feature has been added.
- API based posting has been added.
- Notification on message arrival can be disabled now.
- Annoying completion message which is returned from wassr service
  will be automatically ignored.

0.7.0 (August 5 2008)
- Support for identi.ca has been added.
- Icon support for wassr and identi.ca have been added.
- Icon size and icon visibility 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 notification on message arrival now works for wassr and
  identi.ca too.

6. Acknowledgments

In the beginning 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.

In development for 0.6.0, mikanbako (@mikanbako) joined our team and
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 uncountable feedbacks from users in the #pidgin_twitter channel.

Yoshiki Yazawa (@yazuuchi) and the pidgin-twitter team
[e-mail]