327 lines
11 KiB
Text
327 lines
11 KiB
Text
\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-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
|