Improved documentation

diff --git a/visible-mark.el b/visible-mark.el
index 557e9c44d1ffc61e4061446c913206f9083cf8df..a21e9bd6d9b24799f5188a496b5c73328e99bfb4 100644 (file)
--- a/visible-mark.el
+++ b/visible-mark.el
@@ -20,30 +20,29 @@
 
 ;;; Commentary:
 
-;; Minor mode to display custom overlay faces on mark location(s).
-;; Can display marks from the mark ring in the normal backward direction
-;; in the forward direction.
+;; Emacs minor mode to highlight mark(s).
+;;
+;; Allows setting the number of marks to display, and the faces to display them.
 ;;
 ;; Example installation:
 ;;
 ;; 1. Put this file in Emacs's load-path
 ;;
-;; 2. add to init file
+;; 2. add custom faces to init file
 ;; (require 'visible-mark)
+;; (global-visible-mark-mode 1) ;; or add (visible-mark-mode) to specific hooks
+;;
+;; 3. Add customizations. The defaults are very minimal. They could also be set
+;; via customize.
 ;; 
-;; ;; example of customizations.
-;; ;; This could be set via M-x customize-group visible-mark
+;; (defface visible-mark-active ;; put this before (require 'visible-mark)
+;;   '((((type tty) (class mono)))
+;;     (t (:background "magenta"))) "")
 ;; (setq visible-mark-max 2)
-;; (defface my-visible-mark-face-2
-;;   `((t (:background "orange" :foreground "black")))
-;;   "Face for the mark."
-;;   :group 'visible-mark)
-;; (setq visible-mark-faces `(visible-mark-face1 my-visible-mark-face-2))
+;; (setq visible-mark-faces `(visible-mark-face1 my-visible-mark-face2))
 ;; 
-;; (global-visible-mark-mode +1)
-;;
 ;;
-;; Additional useful functions like unpoping the mark are listed
+;; Additional useful functions like unpoping the mark are at
 ;; http://www.emacswiki.org/emacs/MarkCommands
 ;; and http://www.emacswiki.org/emacs/VisibleMark
 
@@ -90,43 +89,21 @@
     (((class color) (background light))
      (:background "grey80"))
     (t (:background "gray")))
-  "Face for the active mark."
-  :group 'visible-mark)
-
-(defface visible-mark-face1
-  '((((type tty) (class mono)))
-    (t (:background "light salmon")))
-  "Example face which can be customized and added to subsequent face lists."
-  :group 'visible-mark)
-  
-(defface visible-mark-face2
-  '((((type tty) (class mono)))
-    (t (:background "light goldenrod")))
-  "Example face which can be customized and added to subsequent face lists."
-  :group 'visible-mark)
-
-(defface visible-mark-forward-face1
-  '((((type tty) (class mono)))
-    (t (:background "pale green")))
-  "Example face which can be customized and added to subsequent face lists."
+  "Face for the active mark. To redefine this in your init file,
+do it before loading/requiring visible-mark."
   :group 'visible-mark)
 
-(defface visible-mark-forward-face2
-  nil
-  "Placeholder face for customization and addition to subsequent face lists."
-  :group 'visible-mark)
-
-
-(defvar visible-mark-overlays nil
-  "The overlays used in this buffer.")
-(make-variable-buffer-local 'visible-mark-overlays)
-
 (defcustom visible-mark-inhibit-trailing-overlay t
   "If non-nil, inhibit the extension of an overlay at the end of a line
 to the window margin."
   :group 'visible-mark
   :type 'boolean)
 
+(defcustom global-visible-mark-mode-exclude-alist nil
+  "A list of buffer names to be excluded."
+  :group 'visible-mark
+  :type '(repeat regexp))
+
 
 (defcustom visible-mark-max 1
   "The number of marks in the backward direction to be visible."
@@ -150,10 +127,40 @@ the last defined face will be reused."
   :group 'visible-mark
   :type '(repeat face))
 
-(defcustom global-visible-mark-mode-exclude-alist nil
-  "A list of buffer names to be excluded."
-  :group 'visible-mark
-  :type '(repeat regexp))
+
+;;; example faces
+
+(defface visible-mark-face1
+  '((((type tty) (class mono)))
+    (t (:background "light salmon")))
+  "Example face which can be customized and added to subsequent face lists."
+  :group 'visible-mark)
+  
+(defface visible-mark-face2
+  '((((type tty) (class mono)))
+    (t (:background "light goldenrod")))
+  "Example face which can be customized and added to subsequent face lists."
+  :group 'visible-mark)
+
+(defface visible-mark-forward-face1
+  '((((type tty) (class mono)))
+    (t (:background "pale green")))
+  "Example face which can be customized and added to subsequent face lists."
+  :group 'visible-mark)
+
+(defface visible-mark-forward-face2
+  nil
+  "Placeholder face for customization and addition to subsequent face lists."
+  :group 'visible-mark)
+
+
+
+
+(defvar visible-mark-overlays nil
+  "The overlays used for mark faces. Used internally by visible-mark-mode.")
+(make-variable-buffer-local 'visible-mark-overlays)
+
+
 
 (defun visible-mark-initialize-overlays ()
   (mapc