Doc, comment, etc updates for increased use of locate-user-emacs-file

This should have been a prerequisite for making these changes in the
first place.

* doc/emacs/calendar.texi (Time Intervals):
* doc/misc/idlwave.texi (Lesson III---User Catalog, Online Help)
(Starting the Shell, Catalogs, User Catalog):
* doc/misc/remember.texi (Quick Start):
* doc/misc/viper.texi:
* doc/misc/vip.texi (Customization, Customizing Constants)
(Customizing Key Bindings): Update for files being in ~/.emacs.d/.

* lisp/ido.el (ido-save-directory-list-file):
* lisp/saveplace.el (save-place-file):
* lisp/calendar/timeclock.el (timeclock-file):
* lisp/net/quickurl.el (quickurl-url-file):
* lisp/obsolete/otodo-mode.el (todo-file-do, todo-file-done, todo-file-top):
* lisp/progmodes/idlwave.el (idlwave-config-directory):
* lisp/textmodes/remember.el (remember-data-file):
Bump :version.

* lisp/shadowfile.el (shadow-info-file, shadow-todo-file): Doc fix.
* lisp/strokes.el (strokes-file): Doc fix.  Bump :version.
(strokes-help): Doc fix.
* lisp/emulation/viper-init.el (viper-vi-style-in-minibuffer): Doc fix.
* lisp/emulation/viper.el (viper): Doc fix for custom group.
(top-level): Remove oh-so-no-longer-relevant text about vip.
* lisp/obsolete/otodo-mode.el (todo-prefix): Doc fix.

* etc/NEWS: Related edits.

16 files changed, 88 insertions, 59 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index fcbff5b8ee5..a84cc146c65 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,22 @@
+2014-01-27  Glenn Morris  <rgm@gnu.org>
+
+        * shadowfile.el (shadow-info-file, shadow-todo-file): Doc fix.
+        * strokes.el (strokes-file): Doc fix.  Bump :version.
+        (strokes-help): Doc fix.
+        * emulation/viper-init.el (viper-vi-style-in-minibuffer): Doc fix.
+        * emulation/viper.el (viper): Doc fix for custom group.
+        (top-level): Remove oh-so-no-longer-relevant text about vip.
+        * obsolete/otodo-mode.el (todo-prefix): Doc fix.
+
+        * ido.el (ido-save-directory-list-file):
+        * saveplace.el (save-place-file):
+        * calendar/timeclock.el (timeclock-file):
+        * net/quickurl.el (quickurl-url-file):
+        * obsolete/otodo-mode.el (todo-file-do, todo-file-done, todo-file-top):
+        * progmodes/idlwave.el (idlwave-config-directory):
+        * textmodes/remember.el (remember-data-file):
+        Bump :version.
+
 2014-01-26  Glenn Morris  <rgm@gnu.org>
 
         * progmodes/opascal.el (opascal-tab-always-indents, opascal-tab):
diff --git a/lisp/calendar/timeclock.el b/lisp/calendar/timeclock.el
index 016fa2f8738..2b4db9a7820 100644
--- a/lisp/calendar/timeclock.el
+++ b/lisp/calendar/timeclock.el
@@ -64,7 +64,7 @@
 ;;
 ;;   (add-hook 'kill-emacs-query-functions 'timeclock-query-out)
 
-;; NOTE: If you change your .timelog file without using timeclock's
+;; NOTE: If you change your timelog file without using timeclock's
 ;; functions, or if you change the value of any of timeclock's
 ;; customizable variables, you should run the command
 ;; `timeclock-reread-log'.  This will recompute any discrepancies in
@@ -83,6 +83,7 @@
 
 (defcustom timeclock-file (locate-user-emacs-file "timelog" ".timelog")
   "The file used to store timeclock data in."
+  :version "24.4"                       ; added locate-user-emacs-file
   :type 'file
   :group 'timeclock)
 
diff --git a/lisp/emulation/viper-ex.el b/lisp/emulation/viper-ex.el
index a4a5f349ffe..65192c245e0 100644
--- a/lisp/emulation/viper-ex.el
+++ b/lisp/emulation/viper-ex.el
@@ -1887,7 +1887,8 @@ Please contact your system administrator. "
                             (if (featurep 'xemacs) "X" "")
                             ))))))
 
-;; Ex source command.  Loads the file specified as argument or `~/.viper'
+;; Ex source command.
+;; Loads the file specified as argument or viper-custom-file-name.
 (defun ex-source ()
   (viper-get-ex-file)
   (if (string= ex-file "")
diff --git a/lisp/emulation/viper-init.el b/lisp/emulation/viper-init.el
index 27e7c30375b..9914fdcd2f4 100644
--- a/lisp/emulation/viper-init.el
+++ b/lisp/emulation/viper-init.el
@@ -922,7 +922,7 @@ value refers to the number of characters affected."
 
 (defcustom viper-vi-style-in-minibuffer t
   "If t, use vi-style editing in minibuffer.
-Should be set in `~/.viper' file."
+Should be set in `viper-custom-file-name'."
   :type 'boolean
   :group 'viper)
 
diff --git a/lisp/emulation/viper-keym.el b/lisp/emulation/viper-keym.el
index 10afe229a63..96c5c2bb650 100644
--- a/lisp/emulation/viper-keym.el
+++ b/lisp/emulation/viper-keym.el
@@ -147,8 +147,8 @@ viper-insert-basic-map.  Not recommended, except for novice users.")
 (defvar viper-empty-keymap (make-sparse-keymap))
 
 ;; This was the main Vi mode in old versions of VIP which may have been
-;; extensively used by VIP users.  We declare it as a global var
-;; and, after .viper is loaded, we add this keymap to viper-vi-basic-map.
+;; extensively used by VIP users.  We declare it as a global var and, after
+;; viper-custom-file-name is loaded, we add this keymapto viper-vi-basic-map.
 (defvar viper-mode-map (make-sparse-keymap))
 
 ;; Some important keys used in viper
diff --git a/lisp/emulation/viper-macs.el b/lisp/emulation/viper-macs.el
index a937309c63d..0c4e7ddac6f 100644
--- a/lisp/emulation/viper-macs.el
+++ b/lisp/emulation/viper-macs.el
@@ -322,7 +322,8 @@ a key is a symbol, e.g., `a', `\\1', `f2', etc., or a list, e.g.,
 ;; More general definitions are inherited by more specific scopes:
 ;; global->major mode->buffer. More specific definitions override more general
 (defun viper-record-kbd-macro (macro-name state macro-body &optional scope)
-  "Record a Vi macro.  Can be used in `.viper' file to define permanent macros.
+  "Record a Vi macro.
+Can be used in `viper-custom-file-name' to define permanent macros.
 MACRO-NAME is a string of characters or a vector of keys.  STATE is
 either `vi-state' or `insert-state'.  It specifies the Viper state in which to
 define the macro.  MACRO-BODY is a string that represents the keyboard macro.
@@ -351,8 +352,8 @@ If SCOPE is nil, the user is asked to specify the scope."
         (error "Can't map an empty macro name"))
 
     ;; Macro-name is usually a vector.  However, command history or macros
-    ;; recorded in ~/.viper may be recorded as strings.  So, convert to
-    ;; vectors.
+    ;; recorded in viper-custom-file-name may be recorded as strings.
+    ;; So, convert to vectors.
     (setq macro-name (viper-fixup-macro macro-name))
     (if (viper-char-array-p macro-name)
         (setq macro-name (viper-char-array-to-macro macro-name)))
@@ -422,7 +423,7 @@ If SCOPE is nil, the user is asked to specify the scope."
                        ;; if we don't let vector macro-body through %S,
                        ;; the symbols `\.' `\[' etc will be converted into
                        ;; characters, causing invalid read  error on recorded
-                       ;; macros in .viper.
+                       ;; macros in viper-custom-file-name.
                        ;; I am not sure is macro-body can still be a string at
                        ;; this point, but I am preserving this option anyway.
                        (if (vectorp macro-body)
@@ -483,11 +484,11 @@ If SCOPE is nil, the user is asked to specify the scope."
 ;; in effect
 (defun viper-unrecord-kbd-macro (macro-name state)
   "Delete macro MACRO-NAME from Viper STATE.
-MACRO-NAME must be a vector of viper-style keys.  This command is used by Viper
-internally, but the user can also use it in ~/.viper to delete pre-defined
-macros supplied with Viper.  The best way to avoid mistakes in macro names to
-be passed to this function is to use viper-describe-kbd-macros and copy the
-name from there."
+MACRO-NAME must be a vector of viper-style keys.  This command is used
+by Viper internally, but you can also use it in `viper-custom-file-name'
+to delete pre-defined macros supplied with Viper.  The best way to avoid
+mistakes in macro names to be passed to this function is to use
+`viper-describe-kbd-macros' and copy the name from there."
   (let* (state-name keymap
          (macro-alist-var
           (cond ((eq state 'vi-state)
@@ -507,7 +508,8 @@ name from there."
          macro-pair macro-entry)
 
     ;; Macro-name is usually a vector.  However, command history or macros
-    ;; recorded in ~/.viper may appear as strings.  So, convert to vectors.
+    ;; recorded in viper-custom-file-name may appear as strings.
+    ;; So, convert to vectors.
     (setq macro-name (viper-fixup-macro macro-name))
     (if (viper-char-array-p macro-name)
         (setq macro-name (viper-char-array-to-macro macro-name)))
diff --git a/lisp/emulation/viper.el b/lisp/emulation/viper.el
index 690cd881c6c..650b8acbb81 100644
--- a/lisp/emulation/viper.el
+++ b/lisp/emulation/viper.el
@@ -153,9 +153,9 @@
 ;;
 ;;  The last viper-vi-basic-minor-mode contains most of the usual Vi bindings
 ;;  in its edit mode.  This mode provides access to all Emacs facilities.
-;;  Novice users, however, may want to set their viper-expert-level to 1
-;;  in their .viper file.  This will enable viper-vi-diehard-minor-mode.  This
-;;  minor mode's bindings make Viper simulate the usual Vi very closely.
+;;  Novice users, however, may want to set their viper-expert-level to 1 in
+;;  their viper-custom-file-name.  This will enable viper-vi-diehard-minor-mode.
+;;  This minor mode's bindings make Viper simulate the usual Vi very closely.
 ;;  For instance,  C-c will not have its standard Emacs binding
 ;;  and so many of the goodies of Emacs are not available.
 ;;
@@ -165,12 +165,12 @@
 ;;
 ;;  Viper gurus should have at least
 ;;      (setq viper-expert-level 4)
-;;  in their ~/.viper files.  This will unsuppress all Emacs keys that are not
-;;  essential for VI-style editing.
+;;  in their viper-custom-file-name.  This will unsuppress all Emacs keys
+;;  that are not essential for VI-style editing.
 ;;  Pick-and-choose users may want to put
 ;;      (setq viper-expert-level 5)
-;;  in ~/.viper.  Viper will then leave it up to the user to set the variables
-;;  viper-want-*  See viper-set-expert-level for details.
+;;  in viper-custom-file-name.  Viper will then leave it up to the user to
+;;  set the variables viper-want-*  See viper-set-expert-level for details.
 ;;
 ;;  The very first minor mode, viper-vi-intercept-minor-mode, is of no
 ;;  concern for the user.  It is needed to bind Viper's vital keys, such as
@@ -319,8 +319,7 @@ If set by the user, this must be done _before_ Viper is loaded in `~/.emacs'.")
 
 (defgroup viper nil
   "Vi emulation within Emacs.
-NOTE: Viper customization should be saved in `viper-custom-file-name', which
-defaults to `~/.viper'."
+NOTE: Viper customization should be saved in `viper-custom-file-name'."
   :prefix "viper-"
   :group 'emulations)
 
@@ -1222,11 +1221,7 @@ If you wish to Viperize AND make this your way of life, please put
         (require 'viper)
 
 in your init file (preferably, close to the top).
-These two lines must come in the order given.
-
-** Viper users:
-        **** The startup file name has been changed from .vip to .viper
-        **** All vip-* style names have been converted to viper-* style."))
+These two lines must come in the order given."))
          (if (y-or-n-p "Viperize? ")
              (setq viper-mode t)
            (setq viper-mode nil))
@@ -1268,8 +1263,8 @@ These two lines must come in the order given.
 
 
 ;; Set some useful macros, advices
-;; These must be BEFORE ~/.viper is loaded,
-;; so the user can unrecord them in ~/.viper.
+;; These must be BEFORE viper-custom-file-name is loaded,
+;; so the user can unrecord them in viper-custom-file-name.
 (if viper-mode
     (progn
       ;; set advices and some variables that give emacs Vi look.
@@ -1289,7 +1284,7 @@ These two lines must come in the order given.
       ;; Make %%% toggle parsing comments for matching parentheses
       (viper-set-parsing-style-toggling-macro nil)
 
-      ;; ~/.viper is loaded if exists
+      ;; viper-custom-file-name is loaded if exists
       (viper-load-custom-file)
 
       ;; should be after loading custom file to avoid the pesky msg that
@@ -1300,7 +1295,7 @@ These two lines must come in the order given.
 
 
 
-;; Applying Viper customization -- runs after (load .viper)
+;; Applying Viper customization -- runs after (load viper-custom-file-name)
 
 ;; Save user settings or Viper defaults for vars controlled by
 ;; viper-expert-level
@@ -1350,7 +1345,7 @@ These two lines must come in the order given.
 
 
 ;; Intercept maps could go in viper-keym.el
-;; We keep them here in case someone redefines them in ~/.viper
+;; We keep them here in case someone redefines them in viper-custom-file-name
 
 (define-key viper-vi-intercept-map viper-ESC-key 'viper-intercept-ESC-key)
 (define-key viper-insert-intercept-map viper-ESC-key 'viper-intercept-ESC-key)
diff --git a/lisp/ido.el b/lisp/ido.el
index f0a4dd36a98..265a9a9f1c1 100644
--- a/lisp/ido.el
+++ b/lisp/ido.el
@@ -956,6 +956,7 @@ ido is running.  Copied from `icomplete-minibuffer-setup-hook'."
 Variables stored are: `ido-last-directory-list', `ido-work-directory-list',
 `ido-work-file-list', and `ido-dir-file-cache'.
 Must be set before enabling ido mode."
+  :version "24.4"                       ; added locate-user-emacs-file
   :type 'string
   :group 'ido)
 
diff --git a/lisp/net/quickurl.el b/lisp/net/quickurl.el
index c2e4a734214..fdb117ea690 100644
--- a/lisp/net/quickurl.el
+++ b/lisp/net/quickurl.el
@@ -97,6 +97,7 @@
 (defcustom quickurl-url-file
   (locate-user-emacs-file "quickurls" ".quickurls")
   "File that contains the URL list."
+  :version "24.4"                       ; added locate-user-emacs-file
   :type  'file
   :group 'quickurl)
 
diff --git a/lisp/obsolete/otodo-mode.el b/lisp/obsolete/otodo-mode.el
index 53220f06481..d551d167a91 100644
--- a/lisp/obsolete/otodo-mode.el
+++ b/lisp/obsolete/otodo-mode.el
@@ -272,7 +272,7 @@
 
 This is useful in conjunction with `calendar' and `diary' if you use
 
-#include \"~/.todo-do\"
+#include \"~/.emacs.d/todo-do\"
 
 in your diary file to include your todo list file as part of your
 diary.  With the default value \"*/*\" the diary displays each entry
@@ -284,10 +284,12 @@ the diary file somewhat."
   :group 'todo)
 (defcustom todo-file-do    (locate-user-emacs-file "todo-do" ".todo-do")
   "TODO mode list file."
+  :version "24.4"                       ; added locate-user-emacs-file
   :type 'file
   :group 'todo)
 (defcustom todo-file-done  (locate-user-emacs-file "todo-done" ".todo-done")
   "TODO mode archive file."
+  :version "24.4"                       ; added locate-user-emacs-file
   :type 'file
   :group 'todo)
 (defcustom todo-mode-hook  nil
@@ -321,6 +323,7 @@ window."
 
 Not in TODO format, but diary compatible.
 Automatically generated when `todo-save-top-priorities' is non-nil."
+  :version "24.4"                       ; added locate-user-emacs-file
   :type 'string
   :group 'todo)
 
@@ -916,7 +919,7 @@ If INCLUDE-SEP is non-nil, return point after the separator."
                     ["Quit"                 todo-quit t]
                     ))
 
-;; As calendar reads .todo-do before todo-mode is loaded.
+;; As calendar reads todo-file-do before todo-mode is loaded.
 ;;;###autoload
 (define-derived-mode todo-mode nil "TODO"
   "Major mode for editing TODO lists."
diff --git a/lisp/progmodes/idlwave.el b/lisp/progmodes/idlwave.el
index 3dcc183345a..8d4320669a1 100644
--- a/lisp/progmodes/idlwave.el
+++ b/lisp/progmodes/idlwave.el
@@ -449,6 +449,7 @@ value of `!DIR'.  See also `idlwave-library-path'."
 (defcustom idlwave-config-directory
   (locate-user-emacs-file "idlwave" ".idlwave")
   "Directory for configuration files and user-library catalog."
+  :version "24.4"                       ; added locate-user-emacs-file
   :group 'idlwave-routine-info
   :type 'file)
 
diff --git a/lisp/saveplace.el b/lisp/saveplace.el
index 064a70a1041..91da103ba9e 100644
--- a/lisp/saveplace.el
+++ b/lisp/saveplace.el
@@ -70,6 +70,7 @@ following code in your init file:
 
 (defcustom save-place-file (locate-user-emacs-file "places" ".emacs-places")
   "Name of the file that records `save-place-alist' value."
+  :version "24.4"                       ; added locate-user-emacs-file
   :type 'file
   :group 'save-place)
 
diff --git a/lisp/shadowfile.el b/lisp/shadowfile.el
index d409d5672f5..2bf200d07dd 100644
--- a/lisp/shadowfile.el
+++ b/lisp/shadowfile.el
@@ -34,21 +34,22 @@
 ;;  documentation for these functions for information on how and when to use
 ;;  them).  After doing this once, everything should be automatic.
 
-;;  The lists of clusters and shadows are saved in a file called .shadows,
-;;  so that they can be remembered from one Emacs session to another, even
-;;  (as much as possible) if the Emacs session terminates abnormally.  The
-;;  files needing to be copied are stored in .shadow_todo; if a file cannot
-;;  be copied for any reason, it will stay on the list to be tried again
-;;  next time.  The .shadows file should itself have shadows on all your
-;;  accounts so that the information in it is consistent everywhere, but
-;;  .shadow_todo is local information and should have no shadows.
+;;  The lists of clusters and shadows are saved in a ~/.emacs.d/shadows
+;;  (`shadow-info-file') file, so that they can be remembered from one
+;;  Emacs session to another, even (as much as possible) if the Emacs
+;;  session terminates abnormally.  The files needing to be copied are
+;;  stored in `shadow-todo-file'; if a file cannot be copied for any
+;;  reason, it will stay on the list to be tried again next time.  The
+;;  `shadow-info-file' file should itself have shadows on all your accounts
+;;  so that the information in it is consistent everywhere, but
+;;  `shadow-todo-file' is local information and should have no shadows.
 
 ;;  If you do not want to copy a particular file, you can answer "no" and
 ;;  be asked again next time you hit C-x 4 s or exit Emacs.  If you do not
 ;;  want to be asked again, use shadow-cancel, and you will not be asked
 ;;  until you change the file and save it again.  If you do not want to
-;;  shadow that file ever again, you can edit it out of the .shadows
-;;  buffer.  Anytime you edit the .shadows buffer, you must type M-x
+;;  shadow that file ever again, you can edit it out of the shadows
+;;  buffer.  Anytime you edit the shadows buffer, you must type M-x
 ;;  shadow-read-files to load in the new information, or your changes will
 ;;  be overwritten!
 
@@ -106,10 +107,13 @@ files that have been changed and need to be copied to other systems."
   :type 'boolean
   :group 'shadow)
 
+;; FIXME in a sense, this changed in 24.4 (addition of locate-user-emacs-file),
+;; but due to the weird way this variable is initialized to nil, it didn't
+;; literally change.  Same for shadow-todo-file.
 (defcustom shadow-info-file nil
   "File to keep shadow information in.
 The `shadow-info-file' should be shadowed to all your accounts to
-ensure consistency.  Default: ~/.shadows"
+ensure consistency.  Default: ~/.emacs.d/shadows"
   :type '(choice (const nil) file)
   :group 'shadow)
 
@@ -119,7 +123,7 @@ This means that if a remote system is down, or for any reason you cannot or
 decide not to copy your shadow files at the end of one Emacs session, it will
 remember and ask you again in your next Emacs session.
 This file must NOT be shadowed to any other system, it is host-specific.
-Default: ~/.shadow_todo"
+Default: ~/.emacs.d/shadow_todo"
   :type '(choice (const nil) file)
   :group 'shadow)
 
diff --git a/lisp/strokes.el b/lisp/strokes.el
index 890c3d0726c..35136e5da65 100644
--- a/lisp/strokes.el
+++ b/lisp/strokes.el
@@ -118,8 +118,7 @@
 
 ;; > M-x strokes-prompt-user-save-strokes
 
-;; and it will save your strokes in ~/.strokes, or you may wish to change
-;; this by setting the variable `strokes-file'.
+;; and it will save your strokes in your `strokes-file'.
 
 ;; Note that internally, all of the routines that are part of this
 ;; package are able to deal with complex strokes, as they are a superset
@@ -261,7 +260,8 @@ WARNING: Changing the value of this variable will gravely affect the
   :group 'strokes)
 
 (defcustom strokes-file (locate-user-emacs-file "strokes" ".strokes")
-  "File containing saved strokes for Strokes mode (default is ~/.strokes)."
+  "File containing saved strokes for Strokes mode."
+  :version "24.4"                       ; added locate-user-emacs-file
   :type 'file
   :group 'strokes)
 
@@ -991,11 +991,10 @@ down, then use a prefix argument:
 
 > C-u M-x strokes-list-strokes
 
-Your strokes are stored as you enter them.  They get saved in a file
-called ~/.strokes, along with other strokes configuration variables.
-You can change this location by setting the variable `strokes-file'.
-You will be prompted to save them when you exit Emacs, or you can save
-them with
+Your strokes are stored as you enter them.  They get saved into the
+file specified by the `strokes-file' variable, along with other strokes
+configuration variables.  You will be prompted to save them when
+you exit Emacs, or you can save them with
 
 > M-x strokes-prompt-user-save-strokes
 
diff --git a/lisp/textmodes/remember.el b/lisp/textmodes/remember.el
index ceecbd9ba37..3f5227f908b 100644
--- a/lisp/textmodes/remember.el
+++ b/lisp/textmodes/remember.el
@@ -118,7 +118,7 @@
 ;;
 ;; * Using "remember"
 ;;
-;; As a rough beginning, what I do is to keep my .notes file in
+;; As a rough beginning, what I do is to keep my `remember-data-file' in
 ;; outline-mode format, with a final entry called "* Raw data".  Then,
 ;; at intervals, I can move the data that gets appended there into
 ;; other places.  But certainly this should evolve into an intuitive
@@ -386,6 +386,7 @@ Subject: %s\n\n"
   "The file in which to store unprocessed data.
 When set via customize, visited file of the notes buffer (if it
 exists) might be changed."
+  :version "24.4"                       ; added locate-user-emacs-file
   :type 'file
   :set (lambda (symbol value)
          (let ((buf (find-buffer-visiting (default-value symbol))))
diff --git a/lisp/type-break.el b/lisp/type-break.el
index 3e09a7a6c06..f954e5d1c26 100644
--- a/lisp/type-break.el
+++ b/lisp/type-break.el
@@ -1,7 +1,6 @@
 ;;; type-break.el --- encourage rests from typing at appropriate intervals  -*- lexical-binding: t -*-
 
-;; Copyright (C) 1994-1995, 1997, 2000-2014 Free Software Foundation,
-;; Inc.
+;; Copyright (C) 1994-1995, 1997, 2000-2014 Free Software Foundation, Inc.
 
 ;; Author: Noah Friedman
 ;; Maintainer: Noah Friedman <friedman@splode.com>
@@ -208,6 +207,7 @@ key is pressed."
   (locate-user-emacs-file "type-break" ".type-break")
   "Name of file used to save state across sessions.
 If this is nil, no data will be saved across sessions."
+  :version "24.4"                       ; added locate-user
   :type 'file)
 
 (defvar type-break-post-command-hook '(type-break-check)