Getting started with Canto is easy. Most of this is covered in `man canto`, but it seems like it should be online as well.

[TOC]

# Quick Start

<div class="section">

Right after you download and install Canto, I'm sure you're eager to get going. If you just run `canto`, it will start up, generate an example configuration (~/.canto/conf.py.example), fetch those feeds, and startup the interface as usual. This is to let you get a feeling for the program quickly, before messing around with the configuration. Here's the output for conf.py.example:

    :::python
    # Auto-generated by canto because you don't have one.
    # Please copy to/create ~/.canto/conf.py

    add("http://rss.slashdot.org/slashdot/Slashdot")
    add("http://reddit.com/.rss")
    add("http://kerneltrap.org/node/feed")
    add("http://codezen.org/canto/feeds/latest")

You can find a list of the default keybinds on the [configuration page](../config/#default-binds), to help you navigate.

</div>

# Configuration

<div class="section">

So you've messed around with the interface and want to put a little effort into a config. The first place to check is the [configuration page](../config/), to help you get on your way.

The most basic config (like the conf.example generated if you ran without a config), is just a series of `add` calls, as you can see above.

If you store your feeds in *OPML* format, you can use `canto -i <filename>` to automatically import your feeds to your config, or `source_opml()` to add them from an OPML file at run time.

If you store your feeds in a *list of URLs*, you can use `source_urls()` to read the list from a file at run time.

</div>

# Fetching

<div class="section">

In order for canto to receive updates, it's fetching program, `canto-fetch` must be run often. You can achieve this either by adding

    * * * * * canto-fetch

to your crontab, meaning that `canto-fetch` will be run once a minute while the computer is running, or if you don't use cron you can add

    canto-fetch -db

to your startup scripts (.xinitrc, etc.), this will make canto-fetch into a daemon and run itself every minute. You can also run `canto-fetch -db` by hand, or just run `canto -u` to force an update every time you run. It's up to you. 

</div>

# Tips

<div class="section">

This covers some less obvious niceties of using the Canto interface that aren't really covered by [keybinds](../config/#default-binds) or anywhere else.

## Locale or "WTF are these ???? lines?"

If you're having trouble with the interface showing question marks all over the place instead of the nice lines shown in the screenshots, then you've got a locale problem, specifically you're running in a non-UTF-8 locale.

My first suggestion in this case is to switch your system locale to a UTF-8 compatible one. This affects a lot of things, like other terminal applications. For example:

* [This](http://codezen.org/static/good_elinks.png) is a screenshot of `elinks` running in a proper UTF-8 locale. Nice, real characters. Thetas look like thetas. Omegas look like omegas.
* [This](http://codezen.org/static/bad_elinks.png) is a screenshot of `elinks` running in iso-8859-1 which is a typical non-Unicode locale. Everything looks funny. Thetas are THs and omega is W*? 

So I don't mean to suggest that everyone's running around reading Greek in their terminal apps, but this is an illustration using the same program, with the same input ([wikipedia](http://en.wikipedia.org/wiki/List_of_unicode_characters)), but one looks much better than the other. And it's not just non-Latin languages either. Lots of RSS generating blogs use fancy symbols (some as basic as double-quote marks) that don't render correctly in non-UTF-8 locales.

### To use a proper locale

1. Run `locale -a` which will show you the installed locales on your system. If you see an appropriate UTF-8 line, skip to 4.

2. Edit `/etc/locale.gen` (or use `sudo dpkg-reconfigure locales` on Debian based systems) to add/uncomment your locale. It should be a line in the form of `language_territory.UTF-8 UTF-8` where language and country are abbreviations. For example: `en_US.UTF-8 UTF-8` for American English or `de_DE.UTF-8 UTF-8` for German.

3. Run `sudo locale-gen` to actually generate the locale data based in `/etc/locale.gen` .

4.  * TO CHANGE ALL PROGRAMS: Add `export LC_ALL=xx_XX.UTF-8` to your shell configuration (`~/.bashrc` for example) and restart your terminal/shell.
    * TO JUST RUN CANTO: Invoke Canto like this: `LC_ALL=xx_XX.UTF-8 canto`

Some alternate (and mostly distro agnostic) help from the Arch Wiki [here](http://wiki.archlinux.org/index.php/Locale)

That should make Canto, and all of your other terminal apps display nicely. Also note though that even with a UTF-8 locale actually displaying the right characters is still dependent on using a good font in your terminal. So, if you plan on reading any feeds in Arabic or Chinese or even Math, you may be interested in setting up your terminal with a font like [unifont](http://packages.debian.org/sid/unifont).

## Input Boxes

Throughout canto you might run into an input box or two. These boxes accept any sort of input (including UTF-8 characters). In addition to input though, it supports typical (Emacsy?) terminal control sequences.

<table>
<tr>
<td><pre>Ctrl + g (BEL)</pre></td>
<td>Cancel Input</td>
</tr>
<tr>
<td><pre>Ctrl + j (NL)</pre></td>
<td>Enter Input (same as Enter)</td>
</tr>
<tr>
<td><pre>Ctrl + a (SOH)</pre></td>
<td>Start of line (same as Home)</td>
</tr>
<tr>
<td><pre>Ctrl + e (ENQ)</pre></td>
<td>End of line (same as End)</td>
</tr>
</table>

Movement is also supported with the left and right arrows as well as their Emacsy equivalent. Ctrl + g is the only keybind that doesn't have an easily typable equivalent but is also probably the most useful.

## Goto Links ##

In addition to the above keybind, the reader "go to link" input box ('g' in the reader, by default) supports going to multiple links at once (very useful for posts that aggregate a number of cool links). In this input box **only** you can specify a comma delimited list of ranges. Some examples:

    1       # Goto link 1
    1,3     # Goto links 1 and 3
    1-3     # Goto links 1, 2, and 3
    1,4-6   # Goto links 1, 4, 5, 6

Also worth noting: link 0 is *always* the story's main link. Going to link 0 from the reader is equivalent to hitting 'g' (by default) in the main view.

</div>
