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

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

Easy way
~~~~~~~~

Tyrs is now available from pypi.python.org site, allow you to use easy_install,
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.3.2-py2.7.egg

Or you may visite the http://pypi.python.org/pypi/tyrs and get the last tarball
to use something like:

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

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
~~~~~~

apt-get install python-setuptools python-distutils-extra
wget http://src.nicosphere.net/tyrs/tyrs-{revision}.tar.gz
tar xvf tyrs-{revision}.tar.gz && cd tyrs
python setup.py build
sudo easy_install dist/tyrs-{revision}-py2.7.egg

An alternative could be as it explain above in the `easy way`.

Debian
~~~~~~

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

downoad and untar latest Tyrs version.
Ssl have some problem with the 0.7.0 version of python-httplib2, so you may 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

OpenSuse
~~~~~~~~

I'm not very familiar with opensuse, but it seems available with:
http://r.opensu.se/network:utilities.repo
I will find out soon what it realy is.

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 automaticly 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 install when you use the setup.py tool, but you may want
install 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 way 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: Theads
* 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 reconize retweets, the nick right after this
symbol is the personne who retweet it.
* ✉ Envelope icon, notify that the tweet is a response to another one, you may
read the whole thread, with the thread shortcut 'T'.

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

So far, there are only three sections for configuration:

* *colors*: Customization of colors.
* *keybinding*: Customization of key shortcuts.
* *params*: Other parameters.

NOTE: All sections and parameters are lower case. For params composed with two
words, they are separate with an underscore `'_'' (no camelCase).

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

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)

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_myself     = ^U
delete            = C
fav               = b
get_fav           = B
delete_fav        = ^B
thread            = T
---------------

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.

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_myself::
* Description: Retrieve your own timeline (useful to delete a tweet).
* Default: *^U*

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

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: Allow to read a thread of mentions/responses from a tweet, that
contain an envelope icon
* Default: *T*

[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          = 10
tweet_border     = 1
relative_time    = 0
retweet_by       = 1
openurl_command  = firefox %s
transparency     = 1
activities       = 1
help             = 1
margin           = 1
padding          = 2
-------------------

Listing
^^^^^^^

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

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

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

[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
------------------
=============================
