annotate README @ 187:80f7052de4fd

write section 4.5.4, might need more information or modification

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 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 protocol to access twitter. However, twitter has suspended
their 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.  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

It toggles translation from a recipient name to the link to the
recipient.

4.2.2 Translate sender name to link

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 conversations 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.

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 specified recipient

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.

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
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 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
character since the hard limit of message length is applied by
character count basis. If the composing message exceeds 140
characters, the displayed number will turn red to notify the excess.
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
limit is computed on internal representation of characters so that the
messages which does not exceed 140 letters will actually be
accepted. Suppress oops message feature will silently discards *false*
oops message in this situation. This feature can also be configured
via configure window.


4.5.4 Do not notify incoming message (Windows only)

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


4.5.5 Output log message

It 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.
- Notifications on message arrival can be disabled now.
- 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 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 notifications 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 numerous feedbacks from users in the #pidgin_twitter channel.

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