Improve documentation a little

.gitignore

@@ -1,4 +1,5 @@
 # Generated files
+README.html
 *.elc
 *-pkg.el
 *.tar

CONTRIBUTING.md

@@ -34,12 +34,3 @@ Write meaningful docstrings for all functions and vars.
 - Document all functions and variables as directed by `checkdoc`.
 - Consider using [Flycheck](https://github.com/flycheck/flycheck) to automate
   `checkdoc` while you're editing.
-
-### Common Lisp functions
-
-Use `cl-lib` instead of `cl`. The `cl` library pollutes the global namespace and
-its usage is therefore discouraged.
-
-- Use `cl-lib`, which adds prefixes to all cl function names
-- Use [noflet](https://github.com/nicferrier/emacs-noflet) instead of `flet`
-  when you need to dynamically rebind functions.

README.org

@@ -14,8 +14,8 @@
 
 Redefine ~M-<~ and ~M->~ (or any key bound to ~beginning-of-buffer~ or
 ~end-of-buffer~) for some modes so that point moves to meaningful
-locations. The real beginning and end of buffers are still accessible
-by pressing the same key again.
+locations. The real beginning and end of buffers (i.e., ~point-min~
+and ~point-max~) are still accessible by pressing the same key again.
 
 In particular, these modes are supported:
 
@@ -36,8 +36,7 @@ In particular, these modes are supported:
 | *elfeed-mode*         | first feed              | last feed                  |
 | *prodigy-mode*        | first service           | last service               |
 
-
-Adding new modes is a matter of a few lines of code.
+Finally, beginend does what you expect when your buffer is narrowed.
 
 ** Installing
 
@@ -53,16 +52,17 @@ configuration file:
 #+END_SRC
 
 You can also decide to only activate beginend for some of its
-supported modes. Activate the dedicated beginend mode then (e.g.,
-~beginend-dired-mode~).
+supported major modes (e.g., through ~beginend-dired-mode~).
 
 ** Using
 
 At this point, newly opened supported buffers will get improved
 versions of ~M-<~ and ~M->~ (or any key bound to ~beginning-of-buffer~
 or ~end-of-buffer~).
 
-The following shows some screencasts.
+The following shows some screencasts. In each screencast, the cursor
+is moved to the meaningful beginning and end and to the real beginning
+and end.
 
 *** Dired mode
 [[file:media/beginend-dired-mode.gif]]
@@ -79,6 +79,25 @@ The following shows some screencasts.
 
 Yes, please do! See [[file:CONTRIBUTING.md][CONTRIBUTING]] for guidelines.
 
+Adding new modes is a matter of a few lines of code. For example,
+these five lines (already included) define the behavior of beginend in
+~org-agenda-mode~:
+
+#+BEGIN_SRC emacs-lisp
+(beginend-define-mode org-agenda-mode
+  (progn
+    (org-agenda-next-item 1))
+  (progn
+    (org-agenda-previous-item 1)))
+#+END_SRC
+
+The first ~progn~ is responsible for moving point to the meaningful
+beginning of buffer. Before being executed, point is at the real
+beginning of the buffer (i.e., ~point-min~). The expression
+~(org-agenda-next-item 1)~ thus moves to the first agenda item.
+Similarly, the second ~progn~ is responsible for moving point to the
+meaningful end of buffer starting from real end (i.e., ~point-max~).
+
 ** License
 
 See [[file:COPYING][COPYING]]. Copyright (c) 2017 [[mailto:damien@cassou.me][Damien Cassou]] and [[mailto:matus.goljer@gmail.com][Matus Goljer]].

beginend.el

@@ -26,14 +26,20 @@
 
 ;;; Commentary:
 
-;; Redefine M-< and M-> for some modes
+;; Redefine M-< and M-> for some modes.  For example,
 ;;
-;; - in dired mode, M-< (respectively M->) go to first (respectively last) file
-;;   line
+;; - in dired mode, M-< (respectively M->) goes to first (respectively last)
+;;   file line
 ;;
 ;; - in message mode,
-;;    - M-< go to first line of message body (after headings)
-;;    - M-> go to last line before message signature
+;;    - M-< goes to first line of message body (after headings)
+;;    - M-> goes to last line before message signature
+;;
+;; - in prog-mode,
+;;    - M-< goes to the first line after comments
+;;    - M-> goes to the last line before comments
+;;
+;; Many more modes are supported.
 ;;
 ;;; Code: