Tyrs Reference Guide
====================
:author: Nicolas Paris

[[installation]]
Installation
------------

Easy way
~~~~~~~~

Tyrs is now available from pypi.python.org site, allowing you to use the
easy_install method, and quickly get it started.  If your using python2.7, all you need to do is:

[source,bash]
sudo easy_install http://pypi.python.org/packages/2.7/t/tyrs/tyrs-0.5.0-py2.7.egg

Or you may visit the http://pypi.python.org/pypi/tyrs and get the latest tarball
and proceed like so:

[source, bash]
tar xvf tyrs-0.3.2.tar.gz && cd tyrs
python setup.py build
python setup.py install

You may also use python-pip tool to easily install tyrs:
[source,bash]
sudo pip install tyrs

ArchLinux
~~~~~~~~~

As Tyrs is available in AUR, this installation is the most straightforward.
Just use an AUR helper such as 'Yaourt', and grab a copy from the user
repository:

[source,bash]
yaourt -S tyrs

Ubuntu
~~~~~~

[source,bash]
apt-get install python-setuptools python-distutils-extra
wget http://pypi.python.org/packages/source/t/tyrs/tyrs-0.5.0.tar.gz
tar xvf tyrs-0.5.0.tar.gz && cd tyrs
python setup.py build
sudo easy_install dist/tyrs-0.5.0-py2.7.egg

Ubuntu users may also use the `easy way` approach above.

Debian
~~~~~~

It seems that Tyrs works only with python2.7. You will need to use wheezy
instead of squeezy. If the .egg from pypi does not work, here is how to install manually.

Download and untar the latest Tyrs version.
There are some issues with SSL and the 0.7.0 version of python-httplib2, so you
may need to install the 0.6.0 version like:
[source,bash]
easy_install-2.7 http://httplib2.googlecode.com/files/httplib2-0.6.0.zip

After we generate the .egg with:
[source,bash]
python2.7 setup.py bdist_egg

And install it:
easy_install-2.7 dist/tyrs-{revision}-py2.7.egg




Frugalware
~~~~~~~~~~
Tyrs is now available on
link:http://frugalware.org/packages/119439[Frugalware], thanks to Devil505

[source,bash]
pacman -S tyrs

Gentoo
~~~~~~

You may install Tyrs on gentoo with the following
link:https://github.com/linkdd/linkdd-overlay/blob/master/net-misc/tyrs/tyrs-9999.ebuild[ebuild on github],
you may check the link:https://github.com/linkdd/linkdd-overlay/blob/master/README[README]
for more informations, and how to add the overlay with 'layman'. Thanks to linkdd.

OpenSuse
~~~~~~~~

I'm not very familiar with opensuse, but it seems available with:
http://r.opensu.se/network:utilities.repo

From source
~~~~~~~~~~~

Dependencies
^^^^^^^^^^^^

Tyrs requires the following dependencies

* Python 2
* link:http://pypi.python.org/pypi/setuptools[python-setuptools] or
link:http://pypi.python.org/pypi/distribute[python-distribute] to use the
setup.py install

Those dependencies are installed automatically with the setup.py script.
* link:http://code.google.com/p/python-twitter/[python-twitter]
* link:https://github.com/simplegeo/python-oauth2[python-oauth2]

Dependencies should be installed when you use the setup.py tool, but you may want
to install them yourself. Note that you need a recent python-twitter package to use the
oauth system.

Installation
^^^^^^^^^^^^

Once you have the package and dependencies, there are two ways to get Tyrs
installed:

* With _setup.py_, this allows a clean install, similar to the autotools for C
programs (`configure', `make', `make install')

First, get the latest tarball (curently, the latest one is the {revision}) +
http://src.nicosphere.net/tyrs/tyrs-{revision}.tar.gz

[source,bash]
tar xvf tyrs-0.3.1.tar.gz
cd tyrs

.With setup.py

python setup.py build
sudo python setup.py install

Those commands decompress the tarball, go to the directory, prepare the
installation (you can check the files that will be installed here), and then
install it. Note that _the last command must be issued as_ *root*. And that's
all, just run Tyrs with a simple:

[source,bash]
tyrs

Github
~~~~~~

The development of Tyrs is based at link:https://github.com/Nic0/tyrs[Github],
you can easily get the latest development version.

[source,bash]
git clone git://github.com/Nic0/tyrs.git

You may follow the same installation steps seen above to install and run from
the git repository.

.Arch Linux
[TIP]
=================================
A package is available from AUR to retrieve the latest verion from github.
[source,bash]
yaourt -S tyrs-git

=================================

Usage
-----

Please check the configuration section for a list of keybindings.

Activities bar
~~~~~~~~~~~~~~

The activities bar, is the bar containing information about your messages (the
'H:0 M:0 D:0 SUFTR' at the top), this displays new tweets in other buffers. For
example, if you have new mentions in your timeline, the 'M' counter will
increase.

The meaning of each timelines is:

* H: Home
* M: Mentions
* D: Direct messages
* S: Search results
* U: Users public timeline
* F: Favorite tweets
* T: Threads
* R: own retweets

A few  things to note:

* The current buffer is always set to zero, as you're actually reading it, there
is no need to increase it.
* On startup, other buffers are delayed initially, so they won't display new
counts until after the first update.

Icons
~~~~~

* ♻ Recycling icon, is a symbol to recognize retweets, the nick right after this
symbol is the person who retweeted it.
* ✉ Envelope icon, notify that the tweet is a response to another one, you may
read the whole thread, with the thread shortcut 'T'.

Url Shorter
~~~~~~~~~~~

You can shorter an URL automatically when you are editing a tweet. You have
first to write the url, and then press 'Ctrl-u' to shorter it. The default
behavior is to use the ur1.ca service, wich is an open-source project, but you
may change this, read the params section for full details.

Several shortener service are available:

* ur1.ca
* bit.ly
* goo.gl
* msud.pl

Log file
~~~~~~~~

A log file is stored in the '~/.config/tyrs/tyrs.log' for debugging purpose,
the verbosity may be increase by changing the logging_level params to 1 in the
configuration file. It might be useful to understing if somethings wrong or for
bugs repports

Console arguments
-----------------

There is more information on these commands in each section (configuration and
installation).

* '-a', or '--account': source another account
* '-c', or '--config': source another config file
* '-g', or '--generate-config': generate a default configuration file.
* '-h', or '--help': help

[[configuration]]
Configuration
-------------

Introduction
~~~~~~~~~~~~

Tyrs is quite customizable.

It's based on the 'ConfigParser' core module from python, and it's a very
readable and to understand the syntax. All the configuration is based on this
schema.

[source,conf]
------------
[section1]
param1 = string
param2 = 42
[section2]
other_param = otherValue
...
-----------------
A quick way to get started with configuration is to generate a config file
from the command line. with the '-g' option (or '--generate-config'), this
parameter takes one argument: the filename.

[source,bash]
tyrs -g ~/.config/tyrs/tyrs.cfg

There are four sections for configuration:

* *colors*: Customization of colors.
* *keybinding*: Customization of key shortcuts.
* *params*: Other parameters.
* *filter*: Filter tweets without URL.

[NOTE]
======================
* All sections and parameters are lower case. For params composed with two
words, they are separate with an underscore `'_'' (no camelCase).
* A default configuration file is generated if you don't have one yet on
the first start.
======================

Configuration file
~~~~~~~~~~~~~~~~~~

The configuration file is located at '~/.config/tyrs/tyrs.cfg'.
You may have several configuration files, or accounts,
passed as an argument when you start Tyrs. The argument
is appended to the filename of the configuration.

.Custom config file
[source,bash]
$ tyrs -c foo

This will read the configuration from the '~/.config/tyrs/tyrs.cfg.foo'.

CAUTION: You don't need to pass the full filename, as it will attempt to read
the file from 'tyrs.cfg.tyrs.cfg.foo' file if you do so.

TIP: You may add comments to your configuration file, you just need to
start the line with '#' or ';'.

Colors
~~~~~~

Values possible
^^^^^^^^^^^^^^^

The possibles values are determined by curses mode. The available
values are:

.List of possible values
[width="25%"]
|==================
| Value | Color
| 0     | Black
| 1     | Red
| 2     | Green
| 3     | Yellow
| 4     | Blue
| 5     | Magenta
| 6     | Cyan
| 7     | White
|==================

Overview
^^^^^^^^

These are the default values:

[source,conf]
----------------
[colors]
highlight      = 1
header         = 6
current_tweet  = 5
current_tab    = 6
other_tab      = 7
hashtag        = 3
attag          = 2
text           = 7
warning_msg    = 1
info_msg       = 2
unread         = 1
read           = 7
help           = 6
----------------

Bold font
^^^^^^^^^

You may activate bold with any of the color parameters.  You activate
them with one parameter, containing the list of elements you require to be
displayed as bold. +
As an example, to activate bold for highlight, warning_msg and
header. You would do:

[source,conf]
---------------
[colors]
bold = highlight warning_msg header
---------------

That's all you need!

[NOTE]
=================
* You need to leave a space between each one, otherwise it won't work.
* This works as well with RGB colors.
=================

Listing
^^^^^^^

highlight::
* Description: This will highlight when your nick is display in a tweet,
for example, a tweet « blabla @you blabla », @you will be color highlighted.
* Default: 1 (red)

header::
* Description: Corresponding to the display information above the tweet
such as user name of the tweeter, time, and any retweet information.
* Default: 6 (cyan)

current_tweet::
* Description: Corresponding to the header color of the current (selected)
tweet.
* Default: 5 (magenta)

current_tab::
* Description: Display the current timeline (home, mentions or direct message)
in highlighted color.
* Default: 1 (red)

other_tab::
* Description: Color of any other than the current buffer, in the activities bar.
* Default: 7 (white)

hashtag::
* Description: This will highlight the hashtag `#` word, useful to follow
specific subjects, like _#Tyrs_.
* Default: 3 (yellow)

attag::
* Description: This will highlight when a name is followed by a `@' tag like
_@nic0sphere_.
* Default: 2 (green)

warning_msg::
* Description: When something goes wrong, or unexpected, a warning message is
displayed on the top left of the console.
* Examples: `Couldn\'t retrieve tweets', `Couldn\'t send tweet'...
* Default: 1 (red)

info_msg::
* Description: When an action is successful or other feedback is required, Tyrs
lets you know. Similar to warning_msg.
* Examples: `Updating timeline', `Tweet send successfully'...
* Default: 2 (green)

text::
* Description: This is all the basic text, such as tweets (without highlight),
or input in the tweet edit box.
* Default: 7 (white)

read::
* Description: Color in the activities bar when its set to 0.
* Default: 7 (white)

unread::
* Description: Color in the activities bar when you have unread tweets.
* Default: 1 (red)

help::
* Description: Color of the main help screen.
* Default: 6

bold::
* Description: Activate bold, see above for more information.


Configuration 256 Colors
~~~~~~~~~~~~~~~~~~~~~~~~

To use 256 colors in your terminal, use the relevant RGB number, from 0 to 1000.
You must leave spaces between the numbers in the configuration file, for example:

[IMPORTANT]
=====================
The format used, is a RGB code, it is defined with three
numbers from 0 to 1000. You *must* leave spaces between numbers in the
configuration file, for example:
[source,conf]
color_set3 = 300 400 500

====================

color_set0::
Redefine the Black.
color_set1::
Redefine the Red.
color_set2::
Redefine the Green.
color_set3::
Redefine the Yellow.
color_set4::
Redefine the Blue.
color_set5::
Redefine the Magenta.
color_set6::
Redefine the Cyan.
color_set7::
Redefine the White.

[IMPORTANT]
If you turn off one of them, for example you redefine green, and then change
your mind and revert to the default green, this will take effect only if
you restart your terminal. Otherwise, it will stay as the last color
defined. +
You don't need to restart your terminal if you just change the color setup with
another one, it will take effect immediately after restarting Tyrs.


Key Binding
~~~~~~~~~~~

Overview
^^^^^^^^

This allows you to change keys shortcuts to suit your needs. These are the defaults:

[source,conf]
--------------
[keys]
up                = k
down              = j
left              = J
right             = K
back_to_top       = g
back_to_bottom    = G
quit              = q
tweet             = t
clear             = c
retweet           = r
retweet_and_edit  = R
update            = u
follow_selected   = f
unfollow_selected = l
follow            = F
unfollow          = L
openurl           = o
home              = h
mentions          = m
reply             = M
getDM             = d
sendDM            = D
search            = s
redraw            = ^L
search_user       = U
search_current_user = ^F
search_myself     = ^U
delete            = C
fav               = b
get_fav           = B
delete_fav        = ^B
thread            = T
open_image        = ^I
waterline         = w
---------------

Control keys support
^^^^^^^^^^^^^^^^^^^^^

You may activate control keys (Ctrl+something) in the configuration file, for
example, remap your reply with a Ctrl-r:

[source,conf]
---------------
[keys]
reply  = ^R
---------------

CAUTION: The letter followed by '^' *must* be upper case,
You can’t have a Ctrl-r and Ctrl-R, only '^R' will work.

Listing
^^^^^^^

up::
* Description: Navigation — moves up in the timeline.
* Alternative: Up arrow
* Default: *k*

down::
* Description: Navigation —  moves down in the timeline.
* Alternative: Down arrow
* Default: *j*

left::
* Description: Navigation — moves left in different timelines (home, mentions,
direct, search)
* Alternative: Left arrow
* Default: *J*

right::
* Description: Navigation — moves right in different timelines.
* Alternative: Right arrow
* Default: *K*

back_to_top::
* Description: Navigation — moves on top in the timeline.
* Default: *g*

back_to_bottom::
* Description: Navigation — moves on bottom of the screen.
* Default: *G*

quit::
* Description: Leave Tyrs, and return to a normal life.
* Default: *q*

tweet::
* Description: Open an input box to write your tweet.
* Default: *t*

clear::
* Description: Clear the timeline and leave only the last tweet.
* Default: *c*

retweet::
* Description: Retweet the current tweet.
* Default: *r*

retweet_and_edit::
* Description: This allows you to add some comment to a retweet, it will
display as: "RT @user_name: his_tweet<editable_part>".
* Default: *R*

[NOTE]
This kind of retweet is not realy a retweet, its more like a normal tweet but,
with the content of the original tweet and the tweeter's username added.

home::
* Description: Go back to your home timeline.
* Default: *h*

mentions::
* Description: Shows you all tweets that contain your nick (@you), meaning if someone
that you are not following puts your @name in a tweet, you will see it. You may
leave this timeline using 'h' (home) to go back on your home timeline.
* Default: *m*

reply::
* Description: Reply to the current tweet, open an edit box, with the name of
the current tweet preloaded. It will be show as a response to the current
selected tweet.
* Defaurt *M*

update::
* Description: Force the update of your timeline.
* Default: *u*

follow_selected::
* Description: Follow the currently highlighted tweeter.
* Default: *f*

unfollow_selected::
* Description: Unfollow (leave) the person who tweets (or retweets) the current
tweet.
* Default: *l*

follow::
* Description: Follow someone, but the difference with `follow_selected' is
that you will have a small input box, and can enter someone's nick to follow
them.
* Default: *F*

unfollow::
* Description: Unfollow someone, display an input box to enter their nick.
* Default: *L*

[NOTE]
You may enter the name to follow with or without the '@', so it's quicker to do
without.

open profile::
* Description: print the profile of the currently selected tweeter.
* Default: *i*

openurl::
* Description: will open the link in the selected tweet.
* Default: *o*

getDM::
* Description: Retrieve your direct messages
* Default: *d*

sendDM::
* Description: Send a direct message, Tyrs will prompt you to send a direct
message to the current tweeter, but you may change (or simply check) the user
before writing your message.
* Default: *D*

search::
* Description: Return a list of tweets that match your search,
a box will appear to let you enter a string to search for
* Default: *s*

search_user::
* Description: Retrieve the specified user's timeline (usually useful to review
someone's tweets before deciding to follow them or not).
* Default: *U*

search_user::
* Description: Retrieve the current twitter's timeline (usually useful to review
someone's tweets before deciding to follow them or not).
* Default: *^F*

search_myself::
* Description: Retrieve your own timeline (useful to delete a tweet).
* Default: *^U*

delete::
* Description: Destroy the selected tweet.
* Default: *C*

open avatar image::
* Description: open the avatar of the current selected tweeter in your image viewer.
* Default: *^I* (ctrl-i)

redraw::
* Description: Force Tyrs to be redrawn.
* Default: *^L* (ctrl-l)

fav::
* Description: Tag the current tweet as favorite.
* Default: *b*

get_fav::
* Description: Retrieve all your favorites in a timeline.
* Default: *B*

delete_fav::
* Description: Destroy the selected favorite.
* Default: *^B* (ctrl-b)

thread::
* Description: Prints the thread of mentions/responses for a tweet (with
an envelope icon)
* Default: *T*

open_image::
* Description: Retreive the avatar of the current twitter.
* Default: *^I*

waterline::
* Description: Allow to set the waterline, the doted line, at the latest read
tweet.
* Default: *w*

[TIP]
A good way to remember the favorites shortcut, think of them as your *b*est tweets.


[CAUTION]
Commands do not ask for comfirmation. Be careful when using commands such as
delete or unfollow.

Parameters
~~~~~~~~~~

Overview
^^^^^^^^

[source,conf]
-------------------
[params]
refresh          = 3
tweet_border     = 1
relative_time    = 0
retweet_by       = 1
openurl_command  = firefox %s
open_image_command = feh %s
transparency     = 1
activities       = 1
help             = 1
margin           = 1
padding          = 2
compress         = 0
source           = 0
url_shorter      = ur1ca
logging_level    = 3
header_template  = (see listing)
beep             = 1
-------------------

Listing
^^^^^^^

refresh::
* Description: Define the frequency that the timeline will be refreshed.
* Values: Any positive value.
* Unit: Minutes
* Default: 3

tweet_border::
* Description: Display a border around each tweet
* Values: 0 or 1
* Default: 1

relative_time::
* Description: If set to 1, this will display the time of each tweet like `xx
minutes ago', otherwise, will display a more classic format like `HH:MM'.
* Values: 0 or 1
* Default: 0

retweet_by::
* Description: Normally, if a tweet is a retweet the header will be:
`tweeter (some time ago) RT by retweeter', if you find
it too verbose, setting it to 0 will display only the retweeter.
* Values: 0 or 1
* Default: 1

openurl_command::
* Description: Lets you choose your favorite browser for opening urls, note
the %s is *required* to pass the corresponding url that will be opened.
* Values: any web browser
* Default: firefox %s

open_image_command::
* Description: Lets you choose your favorite image viewer. Note, the %s is
*required*.
* Values: any command that opens an image.
* Default: feh %s

activities::
* Description: Disable the activities bar if set to 0.
* Values: 0 or 1
* Default: 1

help::
* Description: Display commonly used commands at the bottom of the screen, set
to 0 to disable it.
* Values: 0 or 1
* Default: 1

[TIP]
If you are not familiar with margin and padding, it's taken from the CSS vocabulary.

margin::
* Description: Space between the border of a tweet, and the edge of the terminal
* Default: 1

padding::
* Description: Space between the border of a tweet, and the start on the text
himself.
* Default: 2

compress::
* Description: disable the blank line between tweets.
* Values 0, 1
* Default: 0

url_shorter::
* Description: Change the URL shortening service.
* Values: ur1ca, bitly, googl, msudpl
* Default: ur1ca

logging_level::
** Description: Increase informations stored in the log file, 1 is the most
verbose, 5 is the less.
* Values: 1 to 5
* Default: 3

header_template::
** Description: Let you chose the how the header of each tweet will be
displayed, following a template code.
* Values: string containing specials parameters with {}
* Default:

beep::
** Description: Do a console beep when receiving unread updates.
* Values: boolean, 0 or 1
* Default: 0

[source, conf]
-----------------
{time} - {nick}{retweeted}{retweeter}{reply}{retweet_count}
-----------------

With:

* time: hour, or 'time ago'
* nick: the twitter nick
* retweeted: the retweet icon, if needed.
* retweeter: the person who retweet.
* source: append tweeter's client to the header of a tweet (eg,. Tyrs, TTytter etc)
* reply: envelope icon, if the tweet is a reply to another one.
* retweet_count: the count of retweet for this tweet.

[NOTE]
=============================
If you are using a small terminal, and don't want waste any spaces, you may try
a configuration like:
[source, conf]
-----------------
[params]
tweet_border = 0
compress = 1
margin = 0
padding = 0
------------------
=============================

Filter
~~~~~~

This option allows you to have more control over tweets displayed in your
timeline. It filters tweets without a URL, leaving only those with links. There
are a few options to allow you to adjust the filter as you wish.


Overview
^^^^^^^^

[source,conf]
-------------------
[filter]
activate    = 1
behavior    = all
myself      = 0
except      = nick1 nick2
-------------------

Listing
^^^^^^^

activate::
* Description: Activate the filter system if set to 1
* Values: 0, 1
* Default: 0

behavior::
* Description: This option sets the behavior of the filter and exception. If set to
all, all tweets that don't contain a URL will be filtered except
the list passed in the except params. If set to none, it will print all
tweets, but you can still add some exceptions that will be filtered.
* Values: all, none
* Default: all

myself::
* Description: If a tweet doesn't contain a URL, but has your nick in
it, you may want read it. This option disables the filter on those tweets. Default value
allow to read them, set to 1 if you want to filter them.
* Values: 0, 1
* Default: 0

except::
* Description: It depends on the value of 'behavior.' If you have set it to a
restrictive value (all), except allows you to set some exceptions and read
tweets without URL from a list of nicks. If you set it to none, Tyrs will print
all tweets without a URL, but will only filter names that
you add to this list. Useful to just filter few nicks.
* Values: List of nicks
* Default: Empty list.
