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/config.json.

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
looks for config.json in .identicurse (a directory which is in your
home directory), and then it checks config.json in its installed
location. 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/.identicurse/ (create the directory first if it
doesn't exist yet) before modifying this copy, as that way future
updates (which *will* overwrite the original config.json with the
newest version) will not erase any customisation you have made.

Further note:
Prior to version 0.8, config was stored in a file called .identicurse
in the home directory. This is no longer the case. However, you do not
have to do anything about this, as IdentiCurse will move the config
to the correct place automatically the first time you run it after
updating. This note is just so that you're aware that there has been
a change. If you have not used any versions prior to 0.8, you don't
need to worry about this section, it doesn't affect you.


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. 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.
    ,               Move the current tab one place to the left.
    .               Move the current tab one place to the right.
    x               Close the currently visible tab.
    r               Refresh.
    q               Quit IdentiCurse.
    h               Open a tab that displays this README.
    i               Switch to input mode.
    /               Do an in-page search.
    :               Go into insert mode with an initial / already present.
    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, full reply editable.
    D               Reply to currently selected dent, name of the user whose
                     dent you are replying to is added before posting.
    f               Favourite currently selected dent.
    F               Unfavourite currently selected dent.
    e               Repeat currently selected dent.
    E               Quote currently selected dent.
    c               View context for currently selected dent.
    v               View timeline of the user who posted the currently selected dent.
    #               Attempt to delete the currently selected dent.
    s               Move dent selection down (indicated by * character).
    a               Move dent selection up (indicated by * character).
    z               Move dent selection to the 1st in the tab (indicated by *).
    Z               Move dent selection to the last in the tab (indicated by *).
    p               Toggle the current tab's pause state.
    P               Toggle all tabs' pause states.
    m               Mute the entire conversation which the currently selected
                     dent is a part of.
    M               Unmute the entire conversation which the currently selected
                     dent is a part of.
    L               Toggle display of notice links (the URLs to the notices).
    TAB or +        Move to the next tab, or to the first if on the last.
    Shift-TAB or -  Move to the previous tab, or to the last if on the first.
    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).

As of 0.7, there are multiple text entry modes. The standard one is
Input Mode, and this is the only one where commands work. Commands
will *not* work in Reply Mode and Quote Mode, and will instead be
posted exactly as entered. Reply Mode and Quote Mode both create
dents that are in context of their target dents, the only difference
is what text is initially present in the text entry.

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.

/reply [notice number]                          (aliases: /r)
   This will enter Reply Mode, with the notice indicated by your notice
   number as its target notice.

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

/unfavourite [notice number]        (aliases: /unfavorite, /unfav, /unf)
   This will remove the notice with the notice number specified
   from your favourites.

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

/quote  [notice number]
   This will enter Quote Mode, with the notice indicated by your notice
   number as its target notice.

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

/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.)

/link [notice number]
   As above, but the first link in the notice is selected.

/mute [notice number]
   Mutes the entire conversation to which the chosen notice belongs.
   This means that any notice in the same conversation will never be
   shown to you until/unless you unmute the conversation.

/unmute [notice number]
   Removes muting from the entire conversation to which the chosen
   notice belongs. The exact reverse of the above command.

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

        /alias /me /user @psquid
        This would make "/me" an alias for "/user @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.

/quit
   This will cause IdentiCurse to quit, exactly the same as if it
   were quit using the q keybinding.

While in text entry mode, you can press tab to attempt to auto-complete the
word before the cursor, if it matches any of the following:

   BEGINS WITH         IDENTICURSE WILL TRY TO COMPLETE IT AS A
   /                   command
   @ or no symbol      username, unless it's a URL (see below)
   #                   tag
   !                   group

For commands, all commands are known to IdentiCurse, so if it exists, it
can be tab-completed. For usernames, groups and tags, IdentiCurse keeps a
cache of all those that it has seen, so any that have not yet been used
during the current session will not be available. However, for usernames,
the "prefill_user_cache" setting can be set to true (it defaults to false),
which will have IdentiCurse, on start-up, fill the username cache with the
usernames of everyone you follow. This is somewhat slow, so it is not
recommended on slow connections.

The exception to this is that if the word before the cursor looks like a URL,
IdentiCurse will instead use the ur1.ca service to get a shortened version of
the URL, and replace it with that shorter URL.

There are two different matching modes for tab-completion, see the "Tab
Completion Modes" section of Advanced Configuration for more detail.

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

Length override:
The "length_override" config setting sets the minimum number of characters
that should be able to fit in the text entry box. So for example,

    "length_override": 280

would always give a text entry box that can hold 280 characters or more.
In practice, it may well give, for example, 300 or so, since the last line
will still fill the entire available width, but it cannot give _less than_
280, so you will be guaranteed the amount you want.
This setting is mainly of use on unlimited-length instances, where the text
entry box would otherwise be set to 3 lines high, which may be far more or
far less than desired.

Tab completion modes:
The "tab_complete_mode" config setting is used to switch between two
tab completion modes. These are:

"exact", which will match only possibilities which start with exactly the
characters given. For example, "win" would match "wind", but not "gwin".
This is the default if the setting is not given.

"fuzzy", which will match anything where the characters given all appear in
the same order. For example, "wgo" would match "windigo", even though other
letters do appear. It would also match "mightywargod", since that still has
all the letters, even though it doesn't start with w.

Filtering modes:
The "filter_mode" config setting is used to switch between two filtering
modes. These are:

"plain", which will match occurences of exactly the strings present in
the "filters" config key.

"regex", which will match any notice whose text is matched by the strings
present in filters, interpreted as regular expressions.


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.
    "tabbar"            The tab bar, except the active tab.
    "tabbar_active"     The active tab.
    "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_fields"    Fields in user/group profiles.
    "profile_values"    Values in user/group profiles.
    "search_highlight"  Anything on the line of the currently
                            highlighted search result.
    "notice_link"       The links added when show_notice_links is enabled.
    "warning"           Any error/warning messages.
    "pause_line"        The line(s) indicating which dents come before/after
                            a pause.

The possible colours differ depending on whether your system's curses
library can access 16-colour support or not. You can check by running
identicurse with the --colour-check command-line option.
For a sizable proportion of terminals, setting your TERM environment
variable to "xterm-256color" will give you full colour support.

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"

Border:
The "border" setting controls whether a border is drawn around the UI.
The default is false (no border).

UI order:
The "ui_order" config setting allows you to place the various sections
of the UI in a different vertical order to default. It is in the format of
an array of strings, like so:

    "ui_order": [                                                               
        "divider",                                                              
        "entry",                                                                
        "divider",                                                              
        "notices",                                                              
        "statusbar",                                                            
        "tabbar"                                                                                                                                                     
        ]

The valid UI elements you can use in this setting are as follows:

    ELEMENT         DESCRIPTION
    entry           The text entry field, height determined by notice length.
    notices         The notice window. This will expand to fill all vertical
                     space not taken by other elements.
    statusbar       The status bar. One line high.
    tabbar          The tab bar. One line high.
    divider         An empty line, used for spacing. One line high.

Any duplicate elements (except dividers) or unrecognised element names will be
ignored, and any element types omitted entirely (again, except dividers) will
be added to the bottom. So for example, the example setting given above would
produce the same layout with or without the tabbar line, since the tab bar
would simply be added there since it was missing.

Tab enumeration:
The "enumerate_tabs" config setting controls whether tabs are numbered. The
default is true (do display numbers). The numbers for tabs 1-9 correspond to
the keys that switch to those tabs (clarification: the keys still work
regardless of whether numbers are shown in the tab titles).

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.
          favourites       The favourites tab.
          user:NAME        A user timeline tab for the user with
                           username @NAME.
          @NAME            Same as user:NAME.
          tag:TAG          A tag timeline tab for the #TAG tag.
          #TAG             Same as tag:TAG.
          group:GROUP      A group timeline tab for the !GROUP group.
          !GROUP           Same as group:GROUP.
          help             A help tab, the same as is opened when h
                           is pressed during use.
          search:QUERY     A search tab with results from searching
                           for QUERY.
          ?QUERY           Same as search: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.
    commandinput   Go into input mode with an initial / already present.
    quit           Quit IdentiCurse.
    closetab       Close the current tab.
    nexttab        Move to the next tab.
    prevtab        Move to the previous tab.
    tabswapleft    Swap the current tab's place with the one to its left.
    tabswapright   Swap the current tab's place with the one to its right.
    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.
    clast          Move selected notice to last on current page.
    cnext          Move selected notice down.
    cprev          Move selected notice up.
    creply         Reply to selected notice.
    cfav           Favourite selected notice.
    cunfav         Unfavourite selected notice.
    crepeat        Repeat selected notice.
    ccontext       View context for selected notice.
    cuser          View profile of user who posted selected notice.
    creplymode     Go into Reply Mode, with selected notice as target.
    cquote         Go into Quote Mode, with selected notice as target.
    cdelete        Delete 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"

Notice links:
The "show_notice_links" config setting, if set to true (default false),
adds the web UI link for each notice below it.

Compact mode:
The "compact_notices" config setting determines whether to display
notices in a compact, single-line style (if set to true), or a slightly
less compact style (if set to false; this is the default).

Show source:
The "show_source" config setting, which can be either true or false
(true by default), determines whether or not to show which client was
used to post each notice. The main use of this is to free up additional
screen space in compact mode.

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.

Status bar slogans:
As of 0.9, slogans are displayed in the status bar when IdentiCurse is
idle. This is controlled by the "status_slogans" config setting, with
true (the default) setting them to be shown, and false setting them
not to be shown - the traditional "Doing nothing." status will be shown
instead.

OAuth:
If not enabled on first run, OAuth can be enabled at a later date using
the "use_oauth" config setting, which can be either true or false.

Additionally, the "oauth_token" and "oauth_token_secret" settings hold your
OAuth connection details if/when you have successfully used OAuth to connect.

To use OAuth with any instance, IdentiCurse should be registered with that
instance as an app, which will give it a consumer key/secret that identify
it to that instance as being IdentiCurse. As of version 0.7, the consumer
key/secret for identi.ca are built in, so anyone using that will not need to
read any more of this section. As of version 0.10, IdentiCurse will attempt to
fall back to the OAuth "anonymous app" profile where supported, allowing it
to operate when no consumer key/secret is available.

If you are using a public instance not already added to that list, please
contact @psquid with the name of the instance, and IdentiCurse will be added
to it as a valid app, and the consumer key/secret added to the online store at
http://identicurse.net/api_keys.json

If you are using a private/single-user instance, we will not be able to
access it to register IdentiCurse as an app, so you will need to do so
yourself, and add the consumer key/secret to your config file manually,
in the "consumer_key" and "consumer_secret" settings, as listed above.


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 can aceess colours,
                           and how many