BASIC CONFIGURATION

Before using IdentiCurse, you can manually configure it with your
account login credentials. Alternatively, since 0.6, you can simply
start IdentiCurse, and let it walk you through a few questions to set
up a basic config for you.  This will be saved in your home directory
as .identicurse.

If you would still rather do it manually (for example, if you would
like to configure some of the more advanced settings that the
automatic config doesn't touch), you can do so as follows:

Edit your config file in your favourite editor, changing
"username": "user" and "password": "test" to appropriate values.
You can also use IdentiCurse with other StatusNet instances by
changing "api_path" to the API home for the instance you wish to use.

Important note:
IdentiCurse looks for your config file in two locations. First it
checks .identicurse in your home directory, and then it checks
config.json in its installed directory. It is highly recommended,
if you intend to manually edit it, that you copy the supplied
config.json (found in conf/ in the tarball) to $HOME and rename it to
.identicurse before modifying this copy, as that way future updates
(which *will* overwrite config.json with the newest version of it)
will not erase any customisation you have made.


USING IDENTICURSE

Once you've configured IdentiCurse for your account, start it by
running the 'identicurse' command. You will see a message, "Welcome to
IdentiCurse!", and then after a short while, IdentiCurse itself will
load (this delay is due to fetching all the initial dents). Once you
are at this screen, you can press various keys to do the following:
    
    KEY             ACTION
    1               Switch to tab 1 (initial tab: Personal Timeline).
    2               Switch to tab 2 (initial tab: Mentions).
    3               Switch to tab 3 (initial tab: DM Inbox).
    4               Switch to tab 4 (initial tab: Public Timeline).
    5               Switch to tab 5 (no initial tab).
    6               Switch to tab 6 (no initial tab).
    7               Switch to tab 7 (no initial tab).
    8               Switch to tab 8 (no initial tab).
    9               Switch to tab 9 (no initial tab).
    <               Switch to the previous tab.
    >               Switch to the next tab.
    x               Close the currently visible tab.
    r               Refresh.
    q               Quit IdentiCurse.
    h               Open a tab that displays this README.
    i               Switch to text entry mode.
    /               Do an in-page search.
    n               Move to the next match for latest in-page search.
    N               Move to the previous match for latest in-page search.
    l               Followed by a number between 1 and 9,
                     quickly reply to that notice on the timeline.
    d               Reply to currently selected dent.
    f               Favourite currently selected dent.
    e               Repeat currently selected dent.
    c               View context for currently selected dent.
    s               Move selected dent down (indicated by * character).
    a               Move selected dent up (indicated by * character).
    z               Move selected dent to first (indicated by *).
    UP or k         Scroll up one line (in the current tab).
    DOWN or j       Scroll down one line (in the current tab).
    PgUp or b       Scroll up one screen (in the current tab).
    PgDn or SPACE   Scroll down one screen (in the current tab).
    HOME or g       Scroll to the top of the current page.
    END or G        Scroll to the bottom of the current page.
    =               Move to the newest page (in current timeline tab).
    LEFT            Move to a newer page (in current timeline tab).
    RIGHT           Move to an older page (in current timeline tab).

The secondary keys listed above are configurable, and the choices
listed are only the defaults. See the 'ADVANCED CONFIGURATION, Key
shortcuts' section for information on how to change them. Also note
that key shortcuts are case-sensitive - g indicates a press of the G
key without shift, G a press of it with shift.

In text entry mode, the above key shortcuts are not available.
Instead, you type a message directly into the text entry field, and
then press enter to submit. A plain message will simply be posted as a
normal dent, but you can also use various commands by starting the
message with a / (for example "/reply 1 Hello!" would trigger the
/reply command rather than post "/reply 1 Hello!"  as a dent).
Available commands are as follows:

/reply [notice number] [message]                (aliases: /r)
   This will create a reply to the notice in your current view with
   the notice number specified. If your current tab is Directs or
   Sent Directs, the reply will be sent as a DM.

/reply [(@)username] [message]                  (aliases: /r)
   This will create a mention of the user specified. The username can
   be entered with or without a @ at the beginning, either will work.
   If your current tab is Directs or Sent Directs, the reply will be
   sent as a DM.

/favourite [notice number]            (aliases: /favorite, /fav, /f)
   This will add the notice with the notice number specified to your
   favourites.

/repeat [notice number]                         (aliases: /rt)
   This will create a repeat of the notice with the notice number
   specified.

/direct [(@)username] [message]                 (aliases: /dm, /d)
   This will send a direct message to the user specified. As with
   /reply, the username will work with or without the @.

/direct [post number] [message]                 (aliases: /dm, /d)
   This will send a direct message to the user who sent the notice
   or DM with the post number specified.

/delete [notice number]                         (aliases: /del)
   This will delete the notice with the notice number specified. It
   will only work for your notices, not those created by other users.

/profile [notice number]                        (aliases: /p)
   This will open a new tab showing the profile of the user who
   created the notice with the notice number specified.

/profile [(@)username]                          (aliases: /p)
   This will open a new tab showing the profile of the user specified.
   As with /reply and /direct, the @ is optional.

/user [notice number]                           (aliases: /u)
   This will open a new tab showing the timeline of the user who
   created the notice with the notice number specified.

/user [(@)username]                             (aliases: /u)
   This will open a new tab showing the timeline of the user
   specified. As with /reply and /direct, the @ is optional.

/context [notice number]                        (aliases: /c)
   This will open a new tab showing the context of the notice with the
   notice number specified. You can identify notices which have
   context by the fact that their "from X" message has a [+] after it.

/subscribe [notice number]                      (aliases: /sub)
   This will subscribe you to the user who created the notice with the
   notice number specified.

/subscribe [(@)username]                        (aliases: /sub)
   This will subscribe you to the user specified.  The @ is optional.

/unsubscribe [notice number]                    (aliases: /unsub)
   This will unsubscribe you from the user who created the notice with
   the notice number specified.

/unsubscribe [(@)username]                      (aliases: /unsub)
   This will unsubscribe you from the user specified.  The @ is
   optional.

/group [(!)group]                               (aliases: /g)
   This will open a new tab showing the timeline of the group
   specified.  Much like the @ in username-based commands, the ! is
   optional.

/groupjoin [(!)group]                           (aliases: /gjoin, /gj)
   This will add you as a member of the group specified.  The ! is
   optional.

/groupleave [(!)group]                          (aliases: /gleave, /gl)
   This will remove you from membership of the group specified.  The !
   is optional.

/groupmember [(!)group]                         (aliases: /gmember, /gm)
   This will check whether or not you are a member of the group
   specified. The ! is optional.

/tag [(#)tag]                                   (aliases: /t)
   This will open a new tab showing the timeline of the tag
   specified. Like the @ or ! in username-/group-based commands, the #
   is optional.

/home                                           (aliases: /personal)
   This will open a new tab showing your Home (a.k.a., Personal)
   timeline: that is, notices only from you and people/groups
   you follow.
   
/mentions                                       (aliases: /replies)
   This will open a new tab showing notices that mention you.
   
/public
   This will open a new tab showing the public timeline, which
   contains the 20 most recent notices from anyone on identi.ca (or
   whichever instance you are using).

/directs                                        (aliases: /inbox)
   This will open a new tab showing the direct messages other users
   have sent to you.

/sentdirects                                    (aliases: /outbox)
   This will open a new tab showing the direct messages you have sent
   to other users.

/favourites                          (aliases: /favorites, /favs, /fs)
   This will open a new tab showing the direct messages you have added
   to your favourites.

/search [query string]                          (aliases: /find, /?, /s)
   This will open a new tab showing notices that contain the query
   string specified.

/block [notice number]                          (aliases: /b)
   This will create a block against the user who created the notice
   with the notice number specified. You can also add additional
   notice numbers to block the users who created all of them.

/block [(@)username]                            (aliases: /b)
   This will create a block against of the user specified.  As usual,
   the @ is optional. You can also add additional usernames to block
   all of them.

/unblock [notice number]                        (aliases: /unb)
   This will remove a block against the user who created the notice
   with the notice number specified. You can also add additional
   notice numbers to unblock the users who created all of them.

/unblock [(@)username]                          (aliases: /unb)
   This will remove a block against of the user specified.  As usual,
   the @ is optional. You can also add additional usernames to
   unblock all of them.

/spamreport [notice number] [reason]      (aliases: /sr, /nuke)
   This will submit a spam report dent in Identi.ca support's
   preferred format and also create a block against the user who
   created the notice with the notice number specified.

/spamreport [(@)username] [reason]        (aliases: /sr, /nuke)
   This will submit a spam report dent in Identi.ca support's
   preferred format and also create a block against the user
   specified.

/link [link number] [notice number]
   This will open the specified link (numbered starting from 1) from
   the specified notice in your preferred browser, set in the config
   file, falling back to xdg-open (which should open your default
   browser) if you haven't got one specified in the config. You can
   also use * as the link number to open all links in the notice.
   There is also an alias for this: "/links [notice number]".
   (See also 'ADVANCED CONFIGURATION, Link opening' section below.)

/alias [alias] [command]
   This will create the alias given as an alias for the command
   given. For example:

        /alias /pme /profile @psquid
        This would make "/pme" an alias for "/profile @psquid"

   The / before both the alias and the resultant command is optional,
   as it will be added if it is not present. Therefore,
   "/alias rpt repeat" and "/alias /rpt /repeat" do exactly the same.

/config [key] [value]                           (aliases: /set)
   This will set the config item with the specified key to the
   specified value. The key can also contain .s to indicate subkeys,
   though so far only aliases require subkeys to configure.
   Since this isn't such an intuitive command, here are some simple
   examples:
        /config aliases./x /delete
        This would make /x an alias for the /delete command.

        /config username test
        This would set your logon username to "test". Note that this
        particular key is only read in on startup, so changing
        credentials this way would require a restart of IdentiCurse.

After submitting your message/command, you will be back in non-text
entry mode until you next press i. You can submit an empty text field
or press ESC to leave text entry mode without performing any action.


ADVANCED CONFIGURATION

Update interval:
The "update_interval" config setting sets how long, in whole seconds,
IdentiCurse should wait after an automatic refresh before starting the
next automatic refresh.

Notice limit:
The "notice_limit" config setting sets how many notices should be
fetched per page, on timeline types where the API allows choosing how
many notices to send (at the time of writing, most except public do).

Colours:
To use colours, the config setting "enable_colours" must be set to
true. This will already be the case if you first started with version
0.6 or later. With only this setting set, a default set of colours
will be used. If you want to configure individual colours, you will
need to configure the "colours" setting, which uses this format:
    
    "colours": {
        "fieldname": ["fg_colour", "bg_colour"],
        "fieldname": ["fg_colour", "bg_colour"],
        "fieldname": ["fg_colour", "bg_colour"],
        ...
    }

The possible field names are:
    "statusbar"         The status bar.
    "timelines"         Any part of the timeline view not already dealt
                            with by the fields below.
    "selector"          The '*' current notice indicator.
    "username"          Usernames, both in notice details and within
                            notices themselves.
    "group"             Groups within notices.
    "tag"               Tags within notices.
    "time"              Notice timestamps.
    "source"            Notice sources (e.g. 'from foo').
    "notice_count"      Notice numbers.
    "notice"            Notice text.
    "profile_title"     The title in profile tabs.
    "profile_fields"    Fields in profile tabs.
    "profile_values"    Values in profile tabs.
    "search_highlight"  Anything on the line of the currently
                            highlighted search result.

The possible colours differ depending on whether your system's curses
library was compiled with 16-colour support or not. You can check by
running identicurse with the --colour-check command-line option.

As long as colour is supported at all, the following are usable:
    "black", "red", "green", "brown", "blue", "magenta", "cyan",
    "white", and "none" ("none" means that default terminal colours
    should be used.)

If all 16 colours *are* supported, the following are also usable:
    "grey", "light_red", "light_green", "yellow", "light_blue",
    "light_magenta", "light_cyan", "light_white"

Initial tabs:
The tabs that are automatically loaded on startup can be configured by
editing the initial_tabs key. This key should contain tab names,
separated by vertical bars (|). The valid tab names are as follows:
          home             The personal timeline tab.
          mentions         The mentions tab.
          direct           The received direct messages tab.
          sentdirect       The sent direct messages tab.
          public           The public timeline tab.
          user:NAME        A user timeline tab for the user with
                           username @NAME.
          tag:TAG          A tag timeline tab for the #TAG tag.
          group:GROUP      A group timeline tab for the !GROUP group.
          help             A help tab, the same as is opened when h
                           is pressed during use.
          profile:NAME     A user profile tab for the user with
                           username @NAME.
          search:QUERY     A search tab with results from searching
                           for QUERY.
          context:ID       A context tab for the notice with id of ID.

Aliases:
In addition to the preset aliases, it is possible to add your own
custom aliases by editing the "aliases" record in your config
file. The preset aliases are stored in this way. and they are good
examples of how to correctly format an alias.  It is not recommended
that you edit this section without a basic understanding of JSON
syntax (for a good basic introduction, we recommend CouchDB's JSON
Primer: < http://guide.couchdb.org/editions/1/en/json.html >).

Long notice handling:
When IdentiCurse encounters a notice that is too long to send to the
current instance, there are three paths it can take, based on the
current value of the long_dent config key:

        1 - It simply does not send the notice, instead giving an
            error indicating how many characters the maximum length
            was exceeded by. This option is not recommended, as it
            discards the original message, which must therefore be
            rewritten from scratch. This will be chosen if long_dent
            is set to "drop".

        2 - The notice is semi-intelligently split into 2 or more
            notices of sendable length. This will be chosen if
            long_dent is set to "split".
        
        3 - The notice is truncated, stopping immediately after the
            last character that fits into the sendable length. This
            will be chosen if long_dent is set to "truncate".

Key shortcuts:
When you press a key, IdentiCurse first checks it against its built-in
keybindings, then against the bindings set in the config file (falling
back to the defaults if you don't have them set). The values to set
are all in the "keys" config key, and an example of the format
follows:

     "keys": {
             "scrollup": ["k"],
             "scrolldown": ["j"],
             "refresh": ["l", "m"]
     }

     This would make k and j keybindings for scrolling up and
     scrolling down, respectively, and make *both* l and m keybindings
     for refreshing.

The full range of keys you can set custom bindings for is as follows:
    
    KEYNAME        ACTION
    scrollup       Scroll up one line.
    scrolldown     Scroll down one line.
    pageup         Scroll up one screen.
    pagedown       Scroll down one screen.
    scrolltop      Scroll right to the top of the current page.
    scrollbottom   Scroll right to the bottom of the current page.
    firstpage      Move to the newest page.
    newerpage      Move to a newer page.
    olderpage      Move to an older page.
    refresh        Refresh.
    input          Go into input mode.
    quit           Quit IdentiCurse.
    closetab       Close the current tab.
    nexttab        Move to the next tab.
    prevtab        Move to the previous tab.
    help           Show the help.
    search         Start an in-page search.
    qreply         Start a reply to the notice with notice number
                   entered immediately after this key.
    cfirst         Move selected notice to first on current page.
    cnext          Move selected notice down.
    cprev          Move selected notice up.
    creply         Reply to selected notice.
    cfav           Favourite selected notice.
    crepeat        Repeat selected notice.
    ccontext       View context for selected notice.
    nextmatch      Move to next match for in-page search.
    prevmatch      Move to previous match for in-page search.

Link opening:
When opening a link, IdentiCurse will attempt to use your choice of
browser. This is set in the "browser" config key, and should be set as
the command to open a URL in the chosen browser, with '%s' instead of
the URL, for example:

    "browser": "firefox '%s'"
    (which would open URLs in Firefox)

GNU Screen users:  If you are running IdentiCurse within GNU Screen,
the following sample configuration may prove useful.  Suppose for
example that you want to open URLs/links using the Elinks text
browser.  In this case the following configuration line should work:

    "browser": "screen elinks '%s'"

Personalised slogans:
If you'd rather use your own slogans instead of the built-in ones,
you'll need to create a file called .identicurse_slogans in your home
directory. In this file, you should place slogans, one per line. These
will then be displayed on starting IdentiCurse. The default slogans
will not be used in this case, so if there are any you want to keep,
you will need to add them to your slogans file.


COMMAND-LINE OPTIONS

IdentiCurse takes the following command-line options:

  -h, --help               show the list of available options and exit
  -c FILE, --config=FILE   specify an alternative config file to use
  -s FILE, --slogans=FILE  specify an alternative slogans file to use
  --colour-check           check if system curses library supports
                               colours, and how many
