From 5e9acf6f30accb492233c159c5feeebcf0bcae3c Mon Sep 17 00:00:00 2001 From: Tom Willemsen Date: Thu, 2 Aug 2012 22:22:34 +0200 Subject: [PATCH] Add some documentation --- README.org | 22 ++++++ avandu.el | 21 +++++- doc/.gitignore | 1 + doc/Makefile | 1 + doc/avandu.texinfo | 169 +++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 213 insertions(+), 1 deletion(-) create mode 100644 README.org create mode 100644 doc/.gitignore create mode 100644 doc/Makefile create mode 100644 doc/avandu.texinfo diff --git a/README.org b/README.org new file mode 100644 index 0000000..09187de --- /dev/null +++ b/README.org @@ -0,0 +1,22 @@ +Avandu is an emacs mode that connects to a Tiny Tiny RSS instance and +allows you to read the feeds it has gathered locally. + +The simplest way to install it is to use package.el: + +#+begin_src emacs-lisp + (package-install-file "/path/to/avandu.el") +#+end_src + +For further information I would like to refer you to the avandu info +file. + +Once installation is out of the way, it should get a value for +=avandu-tt-rss-api-url= (for example: http://tt-rss.org/demo/api/) and +then run =avandu-list=. + +Once in avandu:overview mode some key bindings will be: + +- ~r~:: Mark article at point as read. +- ~o~:: Open article at point in a browser. Uses =browse-url=. +- ~n~:: Next article. +- ~p~:: Previous article. diff --git a/avandu.el b/avandu.el index 5b36451..4b76de0 100644 --- a/avandu.el +++ b/avandu.el @@ -23,7 +23,26 @@ ;;; Commentary: -;; Still coming... +;; Avandu is an emacs mode that connects to a Tiny Tiny RSS instance +;; and allows you to read the feeds it has gathered locally. + +;; The simplest way to install it is to use package.el: + +;; (package-install-file "/path/to/avandu.el") + +;; For further information I would like to refer you to the avandu +;; info file. + +;; Once installation is out of the way, it should get a value for +;; `avandu-tt-rss-api-url' (for example: http://tt-rss.org/demo/api/) +;; and then run `avandu-list'. + +;; Once in avandu:overview mode some key bindings will be: + +;; - `r' :: Mark article at point as read. +;; - `o' :: Open article at point in a browser. Uses `browse-url'. +;; - `n' :: Next article. +;; - `p' :: Previous article. ;;; Code: (require 'json) diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..bf12a97 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +*.info diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..8cd2cdd --- /dev/null +++ b/doc/Makefile @@ -0,0 +1 @@ +avandu.info: diff --git a/doc/avandu.texinfo b/doc/avandu.texinfo new file mode 100644 index 0000000..4eb501f --- /dev/null +++ b/doc/avandu.texinfo @@ -0,0 +1,169 @@ +\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 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. + +@defvar avandu-user +The username that is used to log in to your Tiny Tiny RSS instance. +This will get asked for when avandu tries to connect, and once a +succesful connection has been made it will remember it. +@end defvar + +@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. + +@node Other commands, , Article overview, Usage +@section All the others + +There is also the possibility to see how many unread articles there +are and to manually login and logout of your Tiny Tiny RSS session, +though logging in is done whenever necessary as well. + +@deffn Command avandu-new-articles-count +Shows the total number of unread articles in Tiny Tiny RSS in the echo +area. +@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