avandu/doc/avandu.texinfo

\input texinfo                  @c -*- texinfo -*-
@c %**start of header
@setfilename avandu.info
@documentlanguage nl
@settitle Avandu
@c %**end of header

@node Top, Installation, (dir), (dir)
@top Avandu

Avandu is an emacs application that connects to a
@uref{http://tt-rss.org, Tiny Tiny RSS} instance and allows you to
read the articles it has gathered locally.

The name avandu was taken from a random web 2.0 business name
generator, as I am very bad at thinking up names.  If you have a
suggestion for a better one, please let me know.

@menu
* Installation::  Downloading and installing avandu
* Configuration:: Setting it up to work
* Usage::         Reading some news
@end menu

@node Installation, Configuration, Top, Top
@chapter Installing Avandu

Installing avandu should be easiest when using package.el, the package
manager for emacs 24.  Once this package is uploaded to
@uref{http://marmalade-repo.org/,Marmalade} it should be as simple as
calling

@lisp
(package-install "avandu")
@end lisp

@noindent
but as long as that is not the case, of if you can't use it for some
other reason, another way is to download it, either with
@uref{http://git-scm.com/,git}:

@example
git clone git://ryuslash.org/emacs/avandu.git
@end example

@noindent
or a
@uref{http://code.ryuslash.org/cgit.cgi/emacs/avandu/snapshot/avandu-master.tar.gz,snapshot},
which should then be unpacked.

If you still have package.el available to you, you could use

@lisp
(package-install-file "/location/of/avandu.el")
@end lisp

@noindent
to install it, or you could byte-compile it, place its location
somewhere in your @code{load-path} and either @code{autoload} or
@code{require} it.

@lisp
(add-to-list 'load-path "/path/to/avandu/")

;; And then either:
(autoload 'avandu-list "avandu" "Show a list of feeds." t)
;; or:
(require 'avandu)
@end lisp

@node Configuration, Usage, Installation, Top
@chapter Configuring Avandu

Now that it is installed, it needs to be configured
(@pxref{Installation}), otherwise it won't work at all.

Avandu only has one option at this time.

@defopt avandu-tt-rss-api-url
This option should contain a string.  It tells avandu where to look
for the api to your Tiny Tiny RSS instance.  This needs to be the
complete url to the api, for example
@indicateurl{http://tt-rss.org/demo/api/}.  Before this option is set
avandu won't be able to do anything.
@end defopt

@defopt avandu-user
This option should contain a string.  It is the username that is used
to log in to your Tiny Tiny RSS instance.  If it is @code{nil} it will
get asked for when avandu tries to connect, and once a succesful
connection has been made it will remember it until you log out.
@end defopt

Other than this, it is possible, but unnecessary to set the following
variables.

@defvar avandu-password
The password to use to log in to your Tiny Tiny RSS instance.  This
option shouldn't really be set, it is mostly used to remember the
password so that when a session ends, it can easily be restarted.

Setting this variable manually in your emacs init file will make it
easier for others to find, be careful if you do.
@end defvar

@node Usage,  , Configuration, Top
@chapter Using Avandu

Once it has been installed (@pxref{Installation}) and configured
(@pxref{Configuration}) it is ready to be used.

Avandu currently offers two things one can do with the stored feeds on
the server.  View an overview of all the articles and see how many
unread articles there are.

@menu
* Article overview:: A list of all unread articles
* Other commands::   Anything else
@end menu

@node Article overview, Other commands, Usage, Usage
@section Viewing unread articles

The avandu overview lets you see a list of all the unread articles in
Tiny Tiny RSS.

@deffn Command avandu-list
Show a list of all the unread articles that your Tiny Tiny RSS
instance has stored, grouped by feed.  Due to certain
@dfn{limitations} of Tiny Tiny RSS, this will only be at most 60
articles at once, or less if the user/admin has changed this setting.

Grouping is done very naively in avandu, as long as articles come from
the same feed, they will be grouped together, if the articles are not
already sorted by feed when avandu downloads them many headings might
be created.
@end deffn

The overview can be used to view these articles.  Pressing @kbd{r} on
any article title will mark that article as read, pressing @kbd{o}
will try to open it in your browser (using @code{browse-url}) and mark
it as read.  Using @kbd{c} on any feed heading will @dfn{catch up}
this feed, meaning it will mark all the articles in this feed as read.

Anywhere in the buffer, pressing @kbd{n} or @kbd{p} will move the
cursor to the next or previous article title respectively, and @kbd{N}
and @kbd{P} will do the same, but move to feed headings.

Explanations of all the related commands:

@deffn Command avandu-browse-article
Call @code{browse-url} to try and open the URL at point in your
preferred browser.  This only works when the cursor is placed on an
article title.

In @code{avandu-list} this command gets bound to the @kbd{o} key in
the article title's keymap, so pressing @kbd{o} on any article title
will try and browse to it.
@end deffn

@deffn Command avandu-mark-article-read &optional button
Ask Tiny Tiny RSS to mark the article associated with BUTTON as read.
If BUTTON is omitted or @code{nil} it will try to use whatever is at
@code{point}.

In @code{avandu-list} this command gets bound to the @kbd{r} key in
the article title's keymap.
@end deffn

@deffn Command avandu-next-article
Search through the buffer for the next article header and move point
to it.  This command wraps around the buffer, so when using it at the
end of the buffer it will return to the top.

In @code{avandu-list} this command gets bound to the @kbd{n} key in
the major-mode's keymap, so pressing @kbd{n} anywhere in the buffer
will go to the next article title.
@end deffn

@deffn Command avandu-previous-article
Exactly like @code{avandu-next-article} except it looks for the
previous article title.

In @code{avandu-list} this command gets bound to the @kbd{p} key in
the major-mode's keymap.
@end deffn

@deffn Command avandu-feed-catchup
Ask the Tiny Tiny RSS instance to catch this feed up, meaning it will
mark all the articles in it as read.  This command doesn't check
which articles are being shown, it only sends the request to catch up
and which feed to do that with, so if you leave your buffer open for a
while you might mark articles you wish to read as read.  This only
works when the cursor is placed on a feed title.

In @code{avandu-list} this command gets bound to the @kbd{c} key in
the feed title's keymap, so pressing @kbd{c} on any feed title will
try and catch up the feed.
@end deffn

@deffn Command avandu-next-feed
Exactly like @code{avandu-next-article} except it looks for the next
feed title.

In @code{avandu-list} this command gets bound to the @kbd{N} key in
the major-mode's keymap.
@end deffn

@deffn Command avandu-previous-feed
Exactly like @code{avandu-next-article} except it looks for the
previous feed title.

In @code{avandu-list} this command gets bound to the @kbd{P} key in
the major-mode's keymap.
@end deffn

@node Other commands,  , Article overview, Usage
@section All the others

Apart from viewing unread articles there are a number of other things
that can be done.

@deffn Command avandu-new-articles-count
Ask Tiny Tiny RSS for the total number of unread articles.  If this
function is called interactively in any way it shows a message en the
echo area like:

@example
There are # unread articles
@end example

and it returns the number of unread articles as a string.
@end deffn

@deffn Command avandu-logged-in-p
Asks Tiny Tiny RSS if the user with the currently known session id is
still logged in.
@end deffn

@deffn Command avandu-login
Log in to the Tiny Tiny RSS instance specified by the user (with
@code{avandu-tt-rss-api-url}, @pxref{Configuration}), ask for the
user's username and password if they're not already known and remember
the session variable that was returned by the api.
@end deffn

@deffn Command avandu-logout
Log out of the Tiny Tiny RSS instance, reset the session id, username
and password used by avandu.
@end deffn

@deffn Command avandu-tt-rss-api-level
Request the api level of the Tiny Tiny RSS instance.  If called
interactively in any way it will print a message like:

@example
API Level: #
@end example

and it returns the api level as an integer.

This does not currently serve any purpose, but it might be used in the
future to determine which functions are available.
@end deffn

@deffn Command avandu-tt-rss-version
Get the version of the Tiny Tiny RSS instance.  If called
interactively in any way it will print a message like:

@example
Tiny Tiny RSS Version: #
@end example

and it returns the version as a string.
@end deffn

@deffn avandu-feeds &optional category unread limit offset
Get a list of all the feeds in CATEGORY.  If CATEGORY is @code{nil},
unspicified or 0, show uncategorized feeds.

If UNREAD is non-@code{nil} only get feeds with unread articles in
them.

If LIMIT is non-@code{nil} only get LIMIT number of feeds and if
OFFSET is non-@code{nil} start at OFFSET.

Returns a vector of all the feeds.  This is not useful for users on
its own, but if will be used in the future to make more views
available.
@end deffn