Documentation for Baconbird, a Twitter Client

Andreas Krennmair <ak@synflood.at>

Introduction

Baconbird is a Twitter client for text terminals. Twitter is a popular microblogging service, allowing users to publish their own short messages called "tweets". Baconbird is intended to run on any Unix-like platform that is supported by the programming language Perl and the STFL library.

Installation

Downloading Baconbird

You can download baconbird releases from the baconbird website: http://synflood.at/baconbird.html The latest source code can be found on GitHub: http://github.com/akrennmair/baconbird

Dependencies

Baconbird depends on a number of packages and libraries to work correctly, as listed below:

Debian comes with ready-to-use packages for these dependencies and is thus the recommended distribution to use.

Installation

Installing baconbird is as simple as:

        perl Makefile.PL
        make
        make install

The first command will generate a Makefile and check BaconBird's dependencies. The second command will prepare BaconBird for installation and generate documentation, while the third command will install BaconBird.

When using "make install", you have the usual parameters "prefix" and "DESTDIR" available to control where your program will be installed and where the installation files will be copied to.

Using Baconbird

The first time you start, baconbird, it will inform you to authenticate with Twitter. Login to Twitter, then open the URL as printed on the screen, confirm that you want to allow Baconbird access to your Twitter account, and then enter the shown PIN into the baconbird prompt.

After you successfully accomplished that, baconbird's main screen will open. It is divided into several main components. The topmost line shows the program name and version, the view in which you currently are ("Home Timeline" by default), and on the top right corner, when the API rate limit is reset, how many API calls you still have available, and how many how have available in total per cycle. Don't worry, unless you send several hundred tweets or do several hundred searches by hour, baconbird will make sure that you never run out of API calls to the Twitter servers.

Below the topmost line, the screen is dominated by the list that displays the tweets of the currently selected timeline. Below that, you have additional information about the currently selected tweet, such as sender, the time when it was posted, and the original URL.

Below that, you have a quick reminder about the most important keystrokes that baconbird understands. Below that you find the "last line", which displays information about operations that are currently ongoing and where prompts are presented to the user.

Timelines

Home Timeline

The Home Timeline is selected by default, and shows your own tweets and the tweets of those users you are subscribed to. It can be selected by pressing 1.

Mentions

The Mentions timeline shows the tweets where your username is mentioned (i.e. prefixed with @). It can be selected by pressing 2.

Direct Messages

Twitter allows sending and receiving non-public direct messages between users. The Direct Messages timeline shows the latest direct messages. It can be selected by pressing 3.

Search Results

Baconbird offers the ability to run search queries. A user can do this by pressing the / key, and entering a search query. A list of matches is then presented and continuously updated. A user can then select another timeline, and switch back to the search result timeline by pressing 4. The updates on the search results are then continued.

User Timeline

There are two ways of showing an user's timeline. You can press u while having selected a tweet, and that user's timeline will be displayed. Also, you can press l, and a field to enter a user's screen name will appear. Once you press ENTER, and if that uses exists, that user's timeline will be loaded.

Favorites

You can see all your favorites by pressing V. These are the tweets that you've marked as favorites.

My Retweets

By pressing 6, you will load a timeline that shows all the tweets that you have retweeted.

Retweets of Me

7 will show you a timeline with all the tweets that you've posted that have been retweeted.

My Timeline

If you want to see all your tweets, you can press 8.

Friends

To see your friends (users you follow), press I.

Followers

To see who follows you, press E.

Functions

Automatic Reloads

The currently selected timeline is continuously updated, there is no need for the user to trigger such updates in any way.

Sending Tweets

To send a new tweet, a user simply needs to press the ENTER key. An input field will then open in the last line, where the user can then enter the text. On the right side, the number of remaining characters is displayed. The user is additionally warned by colors when the number of characters becomes more than what is allowed with Twitter.

To make tweets that contain URLs shorter, baconbird contains integration with the URL shortening service http://is.gd/. Users whose tweets contain URLs can press Ctrl-O, and all URLs in the tweet will be shortened. Baconbird always makes sure that the tweet doesn't get longer through this URL. Also, URLs that already are shortened by a previous operation will not be shortened again. This allows that users can press Ctrl-O more than once while posting a tweet.

In the Direct Messages timeline, the ENTER key will send a new direct message, first asking for the recipient and then for the message.

Retweeting

To retweet another user's tweet to your own timeline, a user only needs to select this tweet and press Ctrl-R. Direct messages can't be retweeted. Retweets will be marked with a "R" in the second leftmost column of the screen.

Replies

When a user presses r (reply) or R (public reply), baconbird will open a prompt to enter a reply to the currently selected tweet. It will prefix the message by addressing the sender of the tweet to which you reply. The difference between "regular" and public replies is that public replies are additionally prefixed with a dot (".") so that all your followers, even those who don't follow the addressed user, can read the reply.

Searching

As mentioned above, baconbird allows searching for phrases by pressing /. The search results will then be regularly updated. The latest result for the last search can be always retrieved by pressing 5.

Detail View

To see a complete, more detailed view of a tweet, press v and a panel will pop up on the lower part of the screen. Not only will it show the complete text of the tweet (line-wrapped, in case your terminal is not wide enough), you will also find additional information about the author, including name, screen name, location, description, URL and number of tweets, followers and friends. Pressing v again hides the detail view.

Favorites

If you want to favorite a tweet, you can select it and press Ctrl-F. Favorite tweets will be marked with a "!" in the leftmost column of the screen. To unfavorite a favorite tweet, press Ctrl-F again.

Following and Unfollowing

There are two ways to follow another user. You can either follow the author of the currently selected tweet or direct message (just press F), or you can follow any user by pressing f and entering the desired screen name.

To unfollow a user, select a tweet or direct message and press U.

Highlighting

You can highlight expressions on the screen by adding these terms to the configuration file. (See Configuration). You can press h and a prompt will be shown where you can enter an expression to be highlighted. Regular expressions are accepted. To stop highlighting those expressions again, you can press e again and enter the same expression.

Hiding

You can hide tweets that match a certain expression by adding the terms that you want hidden to the configuration file. (See Configuration). You can also press e to enter the expression you want hidden. To show those expressions again, you can press e again and enter the same expression.

Saved Searches

You can save a search by pressing s once you've searched for something. You can later press l to see what your saves search expressions are. You can reload a saved search by pressing ENTER or y over a saved search query. You can delete a saved search by pressing d. You can cancel by pressing ESC or n.

Keybindings

These are the default keybindings. You can always type ? to display the current bindings.

Configuration

baconbird is configured by $HOME/.baconbird/config. The following configuration options are supported:

License

MIT/X Consortium License

(C)opyright 2010-2011 Andreas Krennmair <ak@synflood.at>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.