v0.4.0

Housekeeping:

  * Update documentation.

  * Update authors.

  * Add obsolete aliases.

  * Version defcustoms.

README.md

@@ -1,35 +1,61 @@
 # Simple Hacker News Emacs Client
 
-It's simple because it doesn't actually interact with Hacker News. It
-uses a HTTP [API](https://hacker-news.firebaseio.com/v0) to get the
-data.
-
-
-## Navigation
-
-This version is able to list posts present in the main page, as well as
-their point and comment counts. You can also click (or `RET`) in the
-post titles to open them in a browser.
-
-Or you can press 't' to open the article in text only mode in emacs itself.
-It may not work for some articles due to the page structure.
-
-The next versions will implement the upvote command and the possibility
-to interact with comments.
+It's simple because it doesn't actually interact with [Hacker
+News](https://news.ycombinator.com/). It uses a HTTP
+[API](https://hacker-news.firebaseio.com/v0) to get the data.
+
+## Interface
+
+Version 0.4.0 of the `hackernews` package is able to fetch stories
+from six different Hacker News feeds, namely top, new, best, ask, show
+and job stories. The default feed is top stories, which corresponds to
+the Hacker News homepage.
+
+The score, title, and comments count of each story is presented on a
+line of its own (see screenshot below), though this format is
+customizable. Both the title and comments count strings are
+hyperlinked to the Hacker News page for the item (the one with the
+comments), unless the story links to an external page, in which case
+the title is hyperlinked to that instead.
+
+Clicking or typing <kbd>RET</kbd> on a link opens it with the command
+[`browse-url`](https://www.gnu.org/software/emacs/manual/html_node/emacs/Browse_002dURL.html),
+which selects a browser based on the user option
+`browse-url-browser-function`. This defaults to the system's default
+browser.
+
+Typing <kbd>t</kbd> on a link first tries to open it in
+[`eww`](https://www.gnu.org/software/emacs/manual/html_node/eww/index.html),
+if available, and otherwise passes it to the command
+`browse-url-text-emacs`, which consults the user option
+`browse-url-text-browser`. This defaults to running `lynx` within
+Emacs. Keep in mind that some websites do not render well in text
+mode.
+
+A future `hackernews` version may support upvoting and interacting
+with comments.
 
 ### Keymap
 
-Keybinding         | Description
--------------------|------------------------------------------------------------
-<kbd>RET</kbd>     | Open post in default browser
-<kbd>t</kbd>     | Open post in text-mode (may not work for all articles)
-<kbd>n</kbd>       | Navigate to next post
-<kbd>p</kbd>       | Navigate to previous post
-<kbd>TAB</kbd>     | Navigate to next comment
-<kbd>Shift-TAB</kbd>| Navigate to previous comment
-<kbd>m</kbd>       | Load more posts
-<kbd>g</kbd>       | Refresh posts
-<kbd>q</kbd>       | Quit
+Keybinding       | Description
+-----------------|-------------------------------------------------------
+<kbd>RET</kbd>   | Open link in default (external) browser
+<kbd>t</kbd>     | Open link in text-mode browser within Emacs
+<kbd>n</kbd>     | Move to next title link
+<kbd>p</kbd>     | Move to previous title link
+<kbd>TAB</kbd>   | Move to next comments count link
+<kbd>S-TAB</kbd> | Move to previous comments count link
+<kbd>m</kbd>     | Load more stories
+<kbd>g</kbd>     | Reload stories
+<kbd>f</kbd>     | Prompt user for a feed to switch to
+<kbd>q</kbd>     | Quit
+
+All feed re/loading commands accept an optional [numeric prefix
+argument](https://www.gnu.org/software/emacs/manual/html_node/emacs/Arguments.html)
+denoting how many stories to act on. For example, `M-5 0 g` refreshes
+the feed of the current `hackernews` buffer and fetches its top 50
+stories. With no prefix argument, the value of the user option
+`hackernews-items-per-page` is used instead.
 
 ## Screenshot
 
@@ -71,7 +97,23 @@ Alternatively, if you always want the package loaded at startup
 
 ## Usage
 
-Just run `M-x hackernews`.
+Just run `M-x hackernews RET`. This reads the feed specified by the
+user option `hackernews-default-feed`, which defaults to top stories,
+i.e. the Hacker News homepage. A direct command for each supported
+feed is also supported, e.g. `M-x hackernews-top-stories RET` or `M-x
+hackernews-ask-stories RET`. These direct commands are not autoloaded,
+however, so to use them before `hackernews` has been loaded you should
+autoload them yourself, e.g. by adding the following to your
+`user-init-file`:
+
+```el
+(autoload 'hackernews-ask-stories "hackernews" nil t)
+```
+
+### Customization
+
+You can list and modify all custom faces and variables by typing `M-x
+customize-group RET hackernews RET`.
 
 ## License
 

hackernews-pkg.el

@@ -1,3 +1,3 @@
-(define-package "hackernews" "0.3.1"
-  "Access the hackernews aggregator from Emacs"
+(define-package "hackernews" "0.4.0"
+  "Access the Hacker News aggregator from Emacs"
   '((json "1.2")))

hackernews.el

@@ -3,8 +3,9 @@
 ;; Copyright (C) 2012-2017 Lincoln de Sousa <lincoln@comum.org>
 
 ;; Author: Lincoln de Sousa <lincoln@comum.org>
-;; Version: 0.3.1
+;;         Basil L. Contovounesios <contovob@tcd.ie>
 ;; Keywords: comm hypermedia news
+;; Version: 0.4.0
 ;; Homepage: https://github.com/clarete/hackernews.el
 
 ;; This program is free software; you can redistribute it and/or modify
@@ -39,25 +40,38 @@
 
 ;;; Faces
 
+(define-obsolete-face-alias 'hackernews-link-face
+  'hackernews-link "0.4.0")
+
 (defface hackernews-link
   '((t :inherit link :foreground "green" :underline nil))
   "Face used for links to stories."
   :group 'hackernews)
 
+(define-obsolete-face-alias 'hackernews-comment-count-face
+  'hackernews-comment-count "0.4.0")
+
 (defface hackernews-comment-count
   '((t :inherit hackernews-link))
   "Face used for comment counts."
   :group 'hackernews)
 
+(define-obsolete-face-alias 'hackernews-score-face
+  'hackernews-score "0.4.0")
+
 (defface hackernews-score
   '((t :inherit default))
   "Face used for the score of a story."
   :group 'hackernews)
 
 ;;; User options
 
+(define-obsolete-variable-alias 'hackernews-top-story-limit
+  'hackernews-items-per-page "0.4.0")
+
 (defcustom hackernews-items-per-page 20
   "Default number of stories to retrieve in one go."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'integer)
 
@@ -75,6 +89,7 @@
 (defcustom hackernews-default-feed "top"
   "Default story feed to load.
 See `hackernews-feed-names' for supported feed types."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type `(radio ,@(mapcar (lambda (feed)
                             `(const :tag ,(cdr feed) ,(car feed)))
@@ -90,51 +105,59 @@ arguments to `format-spec':
 %s - Item score;    see `hackernews-score-format'.
 %t - Item title;    see `hackernews-title-format'.
 %c - Item comments; see `hackernews-comments-format'."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'string)
 
 (defcustom hackernews-score-format "[%s]"
   "Format specification for displaying the score of an item.
 The result is obtained by passing this string and the score count
 to `format'."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'string)
 
 (defcustom hackernews-title-format "%s"
   "Format specification for displaying the title of an item.
 The result is obtained by passing this string and the title to
 `format'."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'string)
 
 (defcustom hackernews-comments-format "(%s comments)"
   "Format specification for displaying the comments of an item.
 The result is obtained by passing this string and the comments
 count to `format'."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'string)
 
 (defcustom hackernews-preserve-point t
   "Whether to preserve point when loading more stories.
 When nil, point is placed on first new item retrieved."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'boolean)
 
 (defcustom hackernews-before-render-hook ()
   "Hook called before rendering any new items."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'hook)
 
 (defcustom hackernews-after-render-hook ()
   "Hook called after rendering any new items.
 The position of point will not have been affected by the render."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'hook)
 
 (defcustom hackernews-finalize-hook ()
   "Hook called as final step of loading any new items.
 The position of point may have been adjusted after the render and
 buffer-local feed state will have been updated."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'hook)
 
@@ -144,6 +167,7 @@ When nil, `url-show-status' determines whether certain status
 messages are displayed when retrieving online data. This is
 suppressed by default so that the hackernews progress reporter is
 not interrupted."
+  :package-version '(hackernews . "0.4.0")
   :group 'hackernews
   :type 'boolean)
 
@@ -184,6 +208,9 @@ not interrupted."
     map)
   "Keymap used in hackernews buffer.")
 
+(define-obsolete-variable-alias 'hackernews-map
+  'hackernews-mode-map "0.4.0")
+
 (defvar hackernews-button-map
   (let ((map (make-sparse-keymap)))
     (set-keymap-parent map button-map)