Correct some docstrings [part 4]

Same rationale as previous patches in this series.

Phil

lisp/org-mac-message.el

@@ -39,7 +39,7 @@
 ;; messages selected in Mail.app.
 
 ;; (org-mac-message-insert-flagged) searches within an org-mode buffer
-;; for a specific heading, creating it if it doesn't exist. Any
+;; for a specific heading, creating it if it doesn't exist.  Any
 ;; message:// links within the first level of the heading are deleted
 ;; and replaced with links to flagged messages.
 
@@ -53,7 +53,7 @@
   :group 'org-link)
 
 (defcustom org-mac-mail-account "customize"
-  "The Mail.app account in which to search for flagged messages"
+  "The Mail.app account in which to search for flagged messages."
   :group 'org-mac-flagged-mail
   :type 'string)
 
@@ -81,7 +81,7 @@ This will use the command `open' with the message URL."
 		 "open" (concat "message://<" (substring message-id 2) ">")))
 
 (defun as-get-selected-mail ()
-  "AppleScript to create links to selected messages in Mail.app"
+  "AppleScript to create links to selected messages in Mail.app."
   (do-applescript
    (concat
     "tell application \"Mail\"\n"
@@ -97,7 +97,7 @@ This will use the command `open' with the message URL."
     "end tell")))
 
 (defun as-get-flagged-mail ()
-  "AppleScript to create links to flagged messages in Mail.app"
+  "AppleScript to create links to flagged messages in Mail.app."
   (do-applescript
    (concat
     ;; Is Growl installed?
@@ -179,7 +179,7 @@ The Org-syntax text will be pushed to the kill ring, and also returned."
 
 (defun org-mac-message-insert-selected ()
   "Insert a link to the messages currently selected in Mail.app.
-This will use applescript to get the message-id and the subject of the
+This will use AppleScript to get the message-id and the subject of the
 active mail in Mail.app and make a link out of it."
   (interactive)
   (insert (org-mac-message-get-links "s")))

lisp/org-macs.el

@@ -92,7 +92,7 @@ Also, do not record undo information."
 
 (defmacro org-maybe-intangible (props)
   "Add '(intangible t) to PROPS if Emacs version is earlier than Emacs 22.
-In emacs 21, invisible text is not avoided by the command loop, so the
+In Emacs 21, invisible text is not avoided by the command loop, so the
 intangible property is needed to make sure point skips this text.
 In Emacs 22, this is not necessary.  The intangible text property has
 led to problems with flyspell.  These problems are fixed in flyspell.el,
@@ -292,7 +292,7 @@ This is in contrast to merely setting it to 0."
 (defvar org-inlinetask-min-level) ; defined in org-inlinetask.el
 (defun org-get-limited-outline-regexp ()
   "Return outline-regexp with limited number of levels.
-The number of levels is controlled by "
+The number of levels is controlled by `org-inlinetask-min-level'"
   (if (or (not (org-mode-p)) (not (featurep 'org-inlinetask)))
 
       outline-regexp

lisp/org-mks.el

@@ -23,6 +23,12 @@
 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
+
+;;; Commentary:
+;; 
+
+;;; Code:
+
 (require 'org)
 (eval-when-compile
   (require 'cl))
@@ -41,8 +47,8 @@ There should be two types of entries.
    short description string of the item.
 
 The command will then make a temporary buffer listing all entries
-that can be selected with a single key, and all the sinke key
-prefixes.  When you press the key for a single-letter enty, it is selected.
+that can be selected with a single key, and all the single key
+prefixes.  When you press the key for a single-letter entry, it is selected.
 When you press a prefix key, the commands (and maybe further prefixes)
 under this key will be shown and offered for selection.
 
@@ -113,7 +119,7 @@ only the bare key is returned."
 	    (throw 'exit (setq rtn (rassoc (cdr (assoc pressed table))
 					   orig-table))))
 	  (setq current (concat current pressed))
-	  (setq table (mapcar 
+	  (setq table (mapcar
 		       (lambda (x)
 			 (if (and (> (length (car x)) 1)
 				  (equal (substring (car x) 0 1) pressed))

lisp/org-mobile.el

@@ -33,6 +33,8 @@
 
 (require 'org)
 (require 'org-agenda)
+;;; Code:
+
 (eval-when-compile (require 'cl))
 
 (defgroup org-mobile nil
@@ -66,7 +68,7 @@ org-agenda-text-search-extra-files
   :type 'directory)
 
 (defcustom org-mobile-use-encryption nil
-  "Non-nil means keep only encrypted files on the webdav server.
+  "Non-nil means keep only encrypted files on the WebDAV server.
 Encryption uses AES-256, with a password given in
 `org-mobile-encryption-password'.
 When nil, plain files are kept on the server.
@@ -78,7 +80,7 @@ support it - at the time of this writing it did not yet."
 
 (defcustom org-mobile-encryption-tempfile "~/orgtmpcrypt"
   "File that is being used as a temporary file for encryption.
-This must be local file on your local machine (not on the webdav server).
+This must be local file on your local machine (not on the WebDAV server).
 You might want to put this file into a directory where only you have access."
   :group 'org-mobile
   :type 'directory)
@@ -88,7 +90,7 @@ You might want to put this file into a directory where only you have access."
 This is a single password which is used for AES-256 encryption.  The same
 password must also be set in the MobileOrg application.  All Org files,
 including mobileorg.org will be encrypted using this password.
-Note that, whe Org runs the encryption commands, the password could
+Note that, when Org runs the encryption commands, the password could
 be visible on your system with the `ps' command.  So this method is only
 intended to keep the files secure on the server, not on your own machine."
   :group 'org-mobile
@@ -358,10 +360,10 @@ agenda view showing the flagged items."
       (error
        "To use encryption, you must set `org-mobile-encryption-password'"))
     (unless (file-writable-p org-mobile-encryption-tempfile)
-      (error "Cannot write to entryption tempfile %s"
+      (error "Cannot write to encryption tempfile %s"
 	     org-mobile-encryption-tempfile))
     (unless (executable-find "openssl")
-      (error "openssl is needed to encrypt files."))))
+      (error "openssl is needed to encrypt files"))))
 
 (defun org-mobile-create-index-file ()
   "Write the index file in the WebDAV directory."

lisp/org-mouse.el

@@ -137,6 +137,8 @@
 ;;
 ;; Versions 0.01 -- 0.07: (I don't remember)
 
+;;; Code:
+
 (eval-when-compile (require 'cl))
 (require 'org)
 
@@ -225,7 +227,7 @@ this function is called.  Otherwise, the current major mode menu is used."
     (mouse-save-then-kill event)))
 
 (defun org-mouse-line-position ()
-  "Returns `:beginning' or `:middle' or `:end', depending on the point position.
+  "Return `:beginning' or `:middle' or `:end', depending on the point position.
 
 If the point is at the end of the line, return `:end'.
 If the point is separated from the beginning of the line only by white
@@ -290,7 +292,7 @@ ITEMFORMAT governs formatting of the elements of KEYWORDS.  If it
 is a function, it is invoked with the keyword as the only
 argument.  If it is a string, it is interpreted as the format
 string to (format ITEMFORMAT keyword).  If it is neither a string
-nor a function, elements of KEYWORDS are used directly. "
+nor a function, elements of KEYWORDS are used directly."
   (mapcar
    `(lambda (keyword)
      (vector (cond
@@ -342,8 +344,7 @@ ITEMFORMAT governs formatting of the elements of KEYWORDS.  If it
 is a function, it is invoked with the keyword as the only
 argument.  If it is a string, it is interpreted as the format
 string to (format ITEMFORMAT keyword).  If it is neither a string
-nor a function, elements of KEYWORDS are used directly.
-"
+nor a function, elements of KEYWORDS are used directly."
   (setq group (or group 0))
   (let ((replace (org-mouse-match-closure
 		  (if nosurround 'replace-match
@@ -432,7 +433,7 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
       (lambda (kwd) (equal state kwd))))))
 
 (defun org-mouse-tag-menu ()		;todo
-  "Create the tags menu"
+  "Create the tags menu."
   (append
    (let ((tags (org-get-tags)))
      (org-mouse-keyword-menu
@@ -585,7 +586,8 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
 	(org-next-item)))))
 
 (defun org-mouse-bolp ()
-  "Returns true if there only spaces, tabs, and '*',  between the beginning of line and the point"
+  "Return true if there only spaces, tabs, and '*' before point.
+This means, between the beginning of line and the point."
   (save-excursion
     (skip-chars-backward " \t*") (bolp)))
 
@@ -1145,4 +1147,4 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
 
 ;; arch-tag: ff1ae557-3529-41a3-95c6-baaebdcc280f
 
-;;; org-mouse.el ends-here
+;;; org-mouse.el ends here

lisp/org-plot.el

@@ -44,7 +44,7 @@
   '((:plot-type . 2d)
     (:with . lines)
     (:ind . 0))
-  "Default options to gnuplot used by `org-plot/gnuplot'")
+  "Default options to gnuplot used by `org-plot/gnuplot'.")
 
 (defvar org-plot-timestamp-fmt nil)
 
@@ -272,7 +272,7 @@ manner suitable for prepending to a user-specified script."
 ;; facade functions
 ;;;###autoload
 (defun org-plot/gnuplot (&optional params)
-  "Plot table using gnuplot. Gnuplot options can be specified with PARAMS.
+  "Plot table using gnuplot.  Gnuplot options can be specified with PARAMS.
 If not given options will be taken from the +PLOT
 line directly before or after the table."
   (interactive)

lisp/org-protocol.el

@@ -31,8 +31,8 @@
 ;;
 ;; Intercept calls from emacsclient to trigger custom actions.
 ;;
-;; This is done by advising `server-visit-files' to scann the list of filenames
-;; for `org-protocol-the-protocol' and sub-procols defined in
+;; This is done by advising `server-visit-files' to scan the list of filenames
+;; for `org-protocol-the-protocol' and sub-protocols defined in
 ;; `org-protocol-protocol-alist' and `org-protocol-protocol-alist-default'.
 ;;
 ;; Any application that supports calling external programs with an URL
@@ -58,7 +58,7 @@
 ;;       (setq org-protocol-protocol-alist
 ;;             '(("my-protocol"
 ;;                :protocol "my-protocol"
-;;                :function my-protocol-handler-fuction)))
+;;                :function my-protocol-handler-function)))
 ;;
 ;;       A "sub-protocol" will be found in URLs like this:
 ;;
@@ -84,13 +84,13 @@
 ;;     URLs to local filenames defined in `org-protocol-project-alist'.
 ;;
 ;;   * `org-protocol-store-link' stores an Org-link (if Org-mode is present) and
-;;     pushes the browsers URL to the `kill-ring' for yanking. This handler is
+;;     pushes the browsers URL to the `kill-ring' for yanking.  This handler is
 ;;     triggered through the sub-protocol \"store-link\".
 ;;
 ;;   * Call `org-protocol-capture' by using the sub-protocol \"capture\".  If
-;;     Org-mode is loaded, emacs will pop-up a capture buffer and fill the
-;;     template with the data provided. I.e. the browser's URL is inserted as an
-;;     Org-link of which the page title will be the description part. If text
+;;     Org-mode is loaded, Emacs will pop-up a capture buffer and fill the
+;;     template with the data provided.  I.e. the browser's URL is inserted as an
+;;     Org-link of which the page title will be the description part.  If text
 ;;     was select in the browser, that text will be the body of the entry.
 ;;
 ;;   * Call `org-protocol-remember' by using the sub-protocol \"remember\".
@@ -155,18 +155,19 @@ See `org-protocol-protocol-alist' for a description of this variable.")
 
 (defconst org-protocol-the-protocol "org-protocol"
   "This is the protocol to detect if org-protocol.el is loaded.
-`org-protocol-protocol-alist-default' and `org-protocol-protocol-alist' hold the
-sub-protocols that trigger the required action. You will have to define just one
-protocol handler OS-wide (MS-Windows) or per application (Linux). That protocol
-handler should call emacsclient.")
+`org-protocol-protocol-alist-default' and `org-protocol-protocol-alist' hold
+the sub-protocols that trigger the required action.  You will have to define
+just one protocol handler OS-wide (MS-Windows) or per application (Linux).
+That protocol handler should call emacsclient.")
 
 
 ;;; User variables:
 
 (defcustom org-protocol-reverse-list-of-files t
-  "* The filenames passed on the commandline are passed to the emacs-server in
-reversed order. Set to `t' (default) to re-reverse the list, i.e. use the
-sequence on the command line. If nil, the sequence of the filenames is
+  "* Non-nil means re-reverse the list of filenames passed on the command line.
+The filenames passed on the command line are passed to the emacs-server in
+reverse order.  Set to t (default) to re-reverse the list, i.e. use the
+sequence on the command line.  If nil, the sequence of the filenames is
 unchanged."
   :group 'org-protocol
   :type 'boolean)
@@ -229,7 +230,7 @@ protocol - protocol to detect in a filename without trailing colon and slashes.
            If you define a protocol \"my-protocol\", `org-protocol-check-filename-for-protocol'
            will search filenames for \"org-protocol:/my-protocol:/\"
            and trigger your action for every match. `org-protocol' is defined in
-           `org-protocol-the-protocol'. Double and tripple slashes are compressed
+           `org-protocol-the-protocol'. Double and triple slashes are compressed
            to one by emacsclient.
 
 function - function that handles requests with protocol and takes exactly one
@@ -243,7 +244,7 @@ function - function that handles requests with protocol and takes exactly one
 
 kill-client - If t, kill the client immediately, once the sub-protocol is
            detected. This is necessary for actions that can be interrupted by
-           `C-g' to avoid dangeling emacsclients. Note, that all other command
+           `C-g' to avoid dangling emacsclients. Note, that all other command
            line arguments but the this one will be discarded, greedy handlers
            still receive the whole list of arguments though.
 
@@ -252,10 +253,10 @@ Here is an example:
   (setq org-protocol-protocol-alist
       '((\"my-protocol\"
          :protocol \"my-protocol\"
-         :function my-protocol-handler-fuction)
+         :function my-protocol-handler-function)
         (\"your-protocol\"
          :protocol \"your-protocol\"
-         :function your-protocol-handler-fuction)))"
+         :function your-protocol-handler-function)))"
   :group 'org-protocol
   :type '(alist))
 
@@ -267,7 +268,7 @@ Here is an example:
 ;;; Helper functions:
 
 (defun org-protocol-sanitize-uri (uri)
-  "emacsclient compresses double and tripple slashes.
+  "emacsclient compresses double and triple slashes.
 Slashes are sanitized to double slashes here."
   (when (string-match "^\\([a-z]+\\):/" uri)
     (let* ((splitparts (split-string uri "/+")))
@@ -276,12 +277,13 @@ Slashes are sanitized to double slashes here."
 
 
 (defun org-protocol-split-data(data &optional unhexify separator)
-  "Split, what a org-protocol handler function gets as only argument.
-data is that one argument. Data is splitted at each occurrence of separator
- (regexp). If no separator is specified or separator is nil, assume \"/+\".
-The results of that splitting are return as a list. If unhexify is non-nil,
-hex-decode each split part. If unhexify is a function, use that function to
-decode each split part."
+  "Split, what an org-protocol handler function gets as only argument.
+DATA is that one argument. DATA is split at each occurrence of
+SEPARATOR (regexp). If no SEPARATOR is specified or SEPARATOR is
+nil, assume \"/+\".  The results of that splitting are returned
+as a list. If UNHEXIFY is non-nil, hex-decode each split part. If
+UNHEXIFY is a function, use that function to decode each split
+part."
   (let* ((sep (or separator "/+"))
          (split-parts (split-string data sep)))
     (if unhexify
@@ -319,7 +321,7 @@ encodeURIComponent. E.g. `%C3%B6' is the german Umlaut `ü'."
 
 
 (defun org-protocol-unhex-compound (hex)
-  "Unhexify unicode hex-chars. E.g. `%C3%B6' is the german Umlaut `ü'."
+  "Unhexify unicode hex-chars. E.g. `%C3%B6' is the German Umlaut `ü'."
   (let* ((bytes (remove "" (split-string hex "%")))
 	 (ret "")
 	 (eat 0)
@@ -415,9 +417,9 @@ This function transforms it into a flat list."
 ;;; Standard protocol handlers:
 
 (defun org-protocol-store-link (fname)
-  "Process an org-protocol://store-link:// style url
-and store a browser URL as an org link. Also pushes the links URL to the
-`kill-ring'.
+  "Process an org-protocol://store-link:// style url.
+Additionally store a browser URL as an org link. Also pushes the
+link's URL to the `kill-ring'.
 
 The location for a browser's bookmark has to look like this:
 
@@ -588,7 +590,7 @@ This is, how the matching is done:
 
 protocol and sub-protocol are regexp-quoted.
 
-If a matching protcol is found, the protcol is stripped from fname and the
+If a matching protocol is found, the protocol is stripped from fname and the
 result is passed to the protocols function as the only parameter. If the
 function returns nil, the filename is removed from the list of filenames
 passed from emacsclient to the server.
@@ -641,7 +643,7 @@ as filename."
 (defun org-protocol-create-for-org ()
   "Create a org-protocol project for the current file's Org-mode project.
 This works, if the file visited is part of a publishing project in
-`org-publish-project-alist'. This functions calls `org-protocol-create' to do
+`org-publish-project-alist'.  This function calls `org-protocol-create' to do
 most of the work."
   (interactive)
   (require 'org-publish)

lisp/org-publish.el

@@ -193,7 +193,7 @@ The following properties control the creation of a concept index.
   :type 'alist)
 
 (defcustom org-publish-use-timestamps-flag t
-  "When non-nil, use timestamp checking to publish only changed files.
+  "Non-nil means use timestamp checking to publish only changed files.
 When nil, do no timestamp checking and always publish all files."
   :group 'org-publish
   :type 'boolean)
@@ -260,8 +260,8 @@ You can overwrite this default per project in your
   (concat "X" (if (fboundp 'sha1) (sha1 filename) (md5 filename))))
 
 (defun org-publish-needed-p (filename &optional pub-dir pub-func true-pub-dir)
-  "Return `t' if FILENAME should be published in PUB-DIR using PUB-FUNC.
-TRUE-PUB-DIR is where the file will truely end up.  Currently we are not using
+  "Return t if FILENAME should be published in PUB-DIR using PUB-FUNC.
+TRUE-PUB-DIR is where the file will truly end up.  Currently we are not using
 this - maybe it can eventually be used to check if the file is present at
 the target location, and how old it is.  Right ow we cannot do this, because
 we do not know under what file name the file will be stored - the publishing
@@ -286,7 +286,7 @@ If there is no timestamp, create one."
     (org-publish-cache-set key stamp)))
 
 (defun org-publish-remove-all-timestamps ()
-  "Remove all files in the timstamp directory."
+  "Remove all files in the timestamp directory."
   (let ((dir org-publish-timestamp-directory)
 	files)
     (when (and (file-exists-p dir)
@@ -305,8 +305,8 @@ If there is no timestamp, create one."
 
 ;; Here, so you find the variable right before it's used the first time:
 (defvar org-publish-cache nil
-  "This will cache all the timestamps and titles for
-files in publishing projects. Blocks could hash sha1 values here.")
+  "This will cache timestamps and titles for files in publishing projects.
+Blocks could hash sha1 values here.")
 
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -354,8 +354,7 @@ This splices all the components into the list."
 (defvar sitemap-ignore-case)
 (defvar sitemap-requested)
 (defun org-publish-compare-directory-files (a b)
-  "Predicate for `sort', that sorts folders-first/last and
-eventually alphabetically."
+  "Predicate for `sort', that sorts folders-first/last and alphabetically."
   (let ((retval t))
     (when (or sitemap-alphabetically sitemap-sort-folders)
       ;; First we sort alphabetically:
@@ -456,7 +455,7 @@ matching filenames."
     org-publish-temp-files))
 
 (defun org-publish-get-project-from-filename (filename &optional up)
-  "Return the project FILENAME belongs."
+  "Return the project that FILENAME belongs to."
   (let* ((filename (expand-file-name filename))
 	 project-name)
 
@@ -577,7 +576,7 @@ See `org-publish-org-to' to the list of arguments."
 (defun org-publish-file (filename &optional project no-cache)
   "Publish file FILENAME from PROJECT.
 If NO-CACHE is not nil, do not initialize org-publish-cache and
-write it to disk. This is needed, since this function is used to
+write it to disk.  This is needed, since this function is used to
 publish single files, when entire projects are published.
 See `org-publish-projects'."
   (let* ((project
@@ -716,7 +715,7 @@ Default for SITEMAP-FILENAME is 'sitemap.org'."
     (or visiting (kill-buffer sitemap-buffer))))
 
 (defun org-publish-find-title (file)
-  "Find the title of file in project."
+  "Find the title of FILE in project."
   (or
    (org-publish-cache-get-file-property file :title nil t)
    (let* ((visiting (find-buffer-visiting file))
@@ -923,8 +922,7 @@ If FREE-CACHE, empty the cache."
     (when free-cache (org-publish-reset-cache))))
 
 (defun org-publish-initialize-cache (project-name)
-  "Initialize the projects cache if not intialized yet
-and return it."
+  "Initialize the projects cache if not initialized yet and return it."
 
   (unless project-name
     (error "%s%s" "Cannot initialize `org-publish-cache' without projects name"
@@ -976,10 +974,9 @@ Return `t', if the file needs publishing"
 	(< pstamp ctime)))))
 
 (defun org-publish-cache-set-file-property (filename property value &optional project-name)
-  "Set the VALUE for a PORPERTY of file FILENAME in publishing cache
-to VALUE. Use cache file of PROJECT-NAME.
-If the entry does not exist, it will be created.
-Return VALUE."
+  "Set the VALUE for a PROPERTY of file FILENAME in publishing cache to VALUE.
+Use cache file of PROJECT-NAME.  If the entry does not exist, it will be
+created.  Return VALUE."
   ;; Evtl. load the requested cache file:
   (if project-name (org-publish-initialize-cache project-name))
   (let ((pl (org-publish-cache-get filename)))
@@ -992,7 +989,7 @@ Return VALUE."
 
 (defun org-publish-cache-get-file-property
   (filename property &optional default no-create project-name)
-  "Return the value for a PORPERTY of file FILENAME in publishing cache.
+  "Return the value for a PROPERTY of file FILENAME in publishing cache.
 Use cache file of PROJECT-NAME. Return the value of that PROPERTY or
 DEFAULT, if the value does not yet exist.
 If the entry will be created, unless NO-CREATE is not nil."
@@ -1019,7 +1016,7 @@ exist."
   (gethash key org-publish-cache))
 
 (defun org-publish-cache-set (key value)
-  "Store KEY VLAUE pair in `org-publish-cache'.
+  "Store KEY VALUE pair in `org-publish-cache'.
 Returns value on success, else nil."
   (unless org-publish-cache
     (error "%s" "`org-publish-cache-set' called, but no cache present"))

lisp/org-remember.el

@@ -54,14 +54,15 @@
   :group 'org)
 
 (defcustom org-remember-store-without-prompt t
-  "Non-nil means `C-c C-c' stores remember note without further prompts.
+  "Non-nil means \\<org-remember-mode-map>\\[org-remember-finalize] \
+stores the remember note without further prompts.
 It then uses the file and headline specified by the template or (if the
 template does not specify them) by the variables `org-default-notes-file'
 and `org-remember-default-headline'.  To force prompting anyway, use
-`C-u C-c C-c' to file the note.
+\\[universal-argument] \\[org-remember-finalize] to file the note.
 
-When this variable is nil, `C-c C-c' gives you the prompts, and
-`C-u C-c C-c' triggers the fasttrack."
+When this variable is nil, \\[org-remember-finalize] gives you the prompts, and
+\\[universal-argument] \\[org-remember-finalize] triggers the fasttrack."
   :group 'org-remember
   :type 'boolean)
 
@@ -121,15 +122,14 @@ The template specifies the structure of the remember buffer.  It should have
 a first line starting with a star, to act as the org-mode headline.
 Furthermore, the following %-escapes will be replaced with content:
 
-  %^{PROMPT}  Prompt the user for a string and replace this sequence with it.
+  %^{PROMPT}  prompt the user for a string and replace this sequence with it.
               A default value and a completion table can be specified like this:
               %^{prompt|default|completion2|completion3|...}
               The arrow keys access a prompt-specific history.
   %a          annotation, normally the link created with `org-store-link'
   %A          like %a, but prompt for the description part
-  %i          Initial content, copied from the active region.  If %i is
+  %i          initial content, copied from the active region.  If %i is
               indented, the entire inserted text will be indented as well.
-
   %t          time stamp, date only
   %T          time stamp with date and time
   %u, %U      like the above, but inactive time stamps
@@ -148,11 +148,11 @@ Furthermore, the following %-escapes will be replaced with content:
   %^{PROP}p   Prompt the user for a value for property PROP
   %[PATHNAME] insert the contents of the file given by PATHNAME
   %(SEXP)     evaluate elisp `(SEXP)' and replace with the result
-  %!          store this note immediately after completing the template
-              (skipping the `C-c C-c' that normally triggers storing)
+  %!          store this note immediately after completing the template\
+              \\<org-remember-mode-map>
+              (skipping the \\[org-remember-finalize] that normally triggers storing)
   %&          jump to target location immediately after storing note
-
-  %?          After completing the template, position cursor here.
+  %?          after completing the template, position cursor here.
 
 Apart from these general escapes, you can access information specific to the
 link type that is created.  For example, calling `remember' in emails or gnus
@@ -215,7 +215,7 @@ The remember buffer is still current when this hook runs."
   :type 'hook)
 
 (defvar org-remember-mode-map (make-sparse-keymap)
-  "Keymap for org-remember-mode, a minor mode.
+  "Keymap for `org-remember-mode', a minor mode.
 Use this map to set additional keybindings for when Org-mode is used
 for a Remember buffer.")
 (defvar org-remember-mode-hook nil
@@ -233,7 +233,7 @@ for a Remember buffer.")
 This only applies if the clock is running in the remember buffer.  If the
 clock is not stopped, it continues to run in the storage location.
 Instead of nil or t, this may also be the symbol `query' to prompt the
-user each time a remember buffer with a running clock is filed away.  "
+user each time a remember buffer with a running clock is filed away."
   :group 'org-remember
   :type '(choice
 	  (const :tag "Never" nil)
@@ -269,7 +269,7 @@ Set this to nil if you find that you don't need the warning.
 
 If you cancel remember calls frequently and know when they
 contain useful information (because you know that you made an
-error or emacs crashed, for example) nil is more useful.  In the
+error or Emacs crashed, for example) nil is more useful.  In the
 opposite case, the default, t, is more useful."
   :group 'org-remember
   :type 'boolean)
@@ -725,9 +725,11 @@ from that hook."
 If there is an active region, make sure remember uses it as initial content
 of the remember buffer.
 
-When called interactively with a `C-u' prefix argument GOTO, don't remember
+When called interactively with a \\[universal-argument] \
+prefix argument GOTO, don't remember
 anything, just go to the file/headline where the selected template usually
-stores its notes.  With a double prefix arg `C-u C-u', go to the last
+stores its notes.  With a double prefix argument \
+\\[universal-argument] \\[universal-argument], go to the last
 note stored by remember.
 
 Lisp programs can set ORG-FORCE-REMEMBER-TEMPLATE-CHAR to a character
@@ -799,21 +801,24 @@ The user is queried for the template."
 When the template has specified a file and a headline, the entry is filed
 there, or in the location defined by `org-default-notes-file' and
 `org-remember-default-headline'.
-
+\\<org-remember-mode-map>
 If no defaults have been defined, or if the current prefix argument
-is 1 (so you must use `C-1 C-c C-c' to exit remember), an interactive
+is 1 (using C-1 \\[org-remember-finalize] to exit remember), an interactive
 process is used to select the target location.
 
-When the prefix is 0 (i.e. when remember is exited with `C-0 C-c C-c'),
+When the prefix is 0 (i.e. when remember is exited with \
+C-0 \\[org-remember-finalize]),
 the entry is filed to the same location as the previous note.
 
-When the prefix is 2 (i.e. when remember is exited with `C-2 C-c C-c'),
+When the prefix is 2 (i.e. when remember is exited with \
+C-2 \\[org-remember-finalize]),
 the entry is filed as a subentry of the entry where the clock is
 currently running.
 
-When `C-u' has been used as prefix argument, the note is stored and emacs
-moves point to the new location of the note, so that editing can be
-continued there (similar to inserting \"%&\" into the template).
+When \\[universal-argument] has been used as prefix argument, the
+note is stored and Emacs moves point to the new location of the
+note, so that editing can be continued there (similar to
+inserting \"%&\" into the template).
 
 Before storing the note, the function ensures that the text has an
 org-mode-style headline, i.e. a first line that starts with