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-overview "avandu" "Show an overview of articles." 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

Other than this, it is possible, but unnecessary to set the following
variables.  These are unnecessary because Avandu also supports the use
of @ref{Top,Auth-source,Aut-source,auth,Auth-source}, which supersedes
these variables.  When using auth source be sure to use the
@code{avandu-tt-rss-api-url} as the @code{machine} value.

@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

@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
* Article view::                One or more articles in a buffer
* Other commands::              Anything else
@end menu

@node Article overview, Article view, 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-overview
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-overview} 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-overview} this command gets bound to the @kbd{r} key
in the article title's keymap.
@end deffn

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

In @code{avandu-overview} this command gets bound to the @kbd{u} 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-overview} 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-overview} 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-overview} 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-overview} 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-overview} this command gets bound to the @kbd{P} key
in the major-mode's keymap.
@end deffn

@node Article view, Other commands, Article overview, Usage
@section Viewing one or more articles

The avandu article view lets you read one or more articles with all
their content.

@deffn Command avandu-view-article id
Shows one or more articles with their content, possibly with its
content rendered by an external application, emacs' w3m mode or
anything you can think of/write yourself.

Although there is no real obstacle to calling this command yourself,
you will need an article id number, these are collected automatically
when using @ref{Article overview}.
@end deffn

In order to have the articles rendered at all you would need to set
@code{avandu-article-render-function}.

@defopt avandu-article-render-function
This setting should point to a function that takes two arguments, the
start and end of the region to render.
@end defopt

Two functions come with Avandu to enable rendering.

@defun avandu-view-possibly-external start end
Call a shell command on the region between @var{start} and @var{end}.
Which shell command should be called should be specified in
@code{avandu-html2text-command}.
@end defun

@defopt avandu-html2text-command
A string with a shell command.  This command will be called by
@code{avandu-view-possibly-external} to render the region given to
it. One example could be:

@example
w3m -dump -T text/HTML -cols 72
@end example
@end defopt

@defun avandu-view-w3m
This function requires the @code{w3m} module for emacs.  It sends the
region on to @code{w3m-region} and then start @code{w3m-minor-mode} to
give it the usual w3m viewing commands.
@end defun

@node Other commands,  , Article view, 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 Command avandu-subscribe-to-feed feed category
Ask Tiny Tiny RSS to subscribe to @var{feed} and put it in the
category @var{category}. @var{feed} should be a URL and @var{category}
the id of the category as known in Tiny Tiny RSS.

When used interactively the user will be prompted for both, and
completions will be offered for @var{category} to make things easier.
@end deffn

@deffn Command avandu-unsubscribe-from-feed id
Ask Tiny Tiny RSS to unsubscribe from the feed identified with
@var{id}. Completion is provided to make selection easier.
@end deffn