Correct some docstrings [part 2]

This is a second patch in a series that makes some straightforward
corrections to a number of docstrings.  Each change is normally to:

- correct a typo, or
- fix up hyperlinks to function or variable names, or
- ensure slightly better conformance with the documentation guidelines
  and tips given in the Elisp manual

No attempt is made to provide missing docstrings or document arguments.

Cheers,

Phil

lisp/org-docbook.el

@@ -26,7 +26,7 @@
 ;; You should have received a copy of the GNU General Public License
 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 
-;; Commentary:
+;;; Commentary:
 ;;
 ;; This library implements a DocBook exporter for org-mode.  The basic
 ;; idea and design is very similar to what `org-export-as-html' has.
@@ -142,8 +142,8 @@ people work on the same document."
   :type 'string)
 
 (defcustom org-export-docbook-footnote-id-prefix "fn-"
-  "The prefix of footnote IDs used during exporting.  Like
-`org-export-docbook-section-id-prefix', this variable can help
+  "The prefix of footnote IDs used during exporting.
+Like `org-export-docbook-section-id-prefix', this variable can help
 avoid same set of footnote IDs being used multiple times."
   :group 'org-export-docbook
   :type 'string)
@@ -155,7 +155,7 @@ avoid same set of footnote IDs being used multiple times."
     ("=" "<code>" "</code>")
     ("~" "<literal>" "</literal>")
     ("+" "<emphasis role=\"strikethrough\">" "</emphasis>"))
-  "Alist of DocBook expressions to convert emphasis fontifiers.
+  "A list of DocBook expressions to convert emphasis fontifiers.
 Each element of the list is a list of three elements.
 The first element is the character used as a marker for fontification.
 The second element is a formatting string to wrap fontified text with.

lisp/org-docview.el

@@ -62,7 +62,7 @@
       )))
 
 (defun org-docview-store-link ()
-  "Store a link to a docview buffer"
+  "Store a link to a docview buffer."
   (when (eq major-mode 'doc-view-mode)
     ;; This buffer is in doc-view-mode
     (let* ((path buffer-file-name)
@@ -75,11 +75,16 @@
        :description path))))
 
 (defun org-docview-complete-link ()
-  "Use the existing file name completion for file: links to get the file name,
-   then ask the user for the page number and append it."
+  "Use the existing file name completion for file.
+Links to get the file name, then ask the user for the page number
+and append it."
   (concat (replace-regexp-in-string "^file:" "docview:" (org-file-complete-link))
 	  "::"
 	  (read-from-minibuffer "Page:" "1")))
 
 
 (provide 'org-docview)
+
+;; arch-tag: dd147a78-cce1-481b-b40a-15869417debe
+
+;;; org-docview.el ends here

lisp/org-entities.el

@@ -26,6 +26,8 @@
 ;;
 ;;; Commentary:
 
+;;; Code:
+
 (require 'org-macs)
 
 (declare-function org-table-align "org-table" ())
@@ -459,7 +461,7 @@ loaded, add these packages to `org-export-latex-packages-alist'."
     ("Diamond" "\\diamond" t "⋄" "[diamond]" "[diamond]" "⋄")
     ("loz" "\\diamond" t "◊" "[lozenge]" "[lozenge]" "◊")
     )
-  "Default entities used in Org-mode to preduce special characters.
+  "Default entities used in Org-mode to produce special characters.
 For details see `org-entities-user'.")
 
 (defsubst org-entity-get (name)
@@ -521,7 +523,7 @@ Kind can be any of `latex', `html', `ascii', `latin1', or `utf8'."
     (org-table-align)))
 
 (defun org-entities-help ()
-  "Create a Help buffer with all available entities"
+  "Create a Help buffer with all available entities."
   (interactive)
   (with-output-to-temp-buffer "*Org Entity Help*"
     (princ "Org-mode entities\n=================\n\n")
@@ -555,7 +557,7 @@ Kind can be any of `latex', `html', `ascii', `latin1', or `utf8'."
 
 
 (defun replace-amp ()
-  "Postprocess HTML file to unescape the ampersant."
+  "Postprocess HTML file to unescape the ampersand."
   (interactive)
   (while (re-search-forward "<td>&amp;\\([^<;]+;\\)" nil t)
     (replace-match (concat "<td>&" (match-string 1)) t t)))

lisp/org-exp-blocks.el

@@ -68,6 +68,8 @@
 ;; `org-export-blocks-add-block' to add your block type to
 ;; `org-export-blocks'.
 
+;;; Code:
+
 (eval-when-compile
   (require 'cl))
 (require 'org)
@@ -93,10 +95,10 @@
   '((comment org-export-blocks-format-comment t)
     (ditaa org-export-blocks-format-ditaa nil)
     (dot org-export-blocks-format-dot nil))
-  "Use this a-list to associate block types with block exporting
-functions.  The type of a block is determined by the text
-immediately following the '#+BEGIN_' portion of the block header.
-Each block export function should accept three argumets..."
+  "Use this alist to associate block types with block exporting functions.
+The type of a block is determined by the text immediately
+following the '#+BEGIN_' portion of the block header.  Each block
+export function should accept three arguments."
   :group 'org-export-general
   :type '(repeat
 	  (list
@@ -106,14 +108,14 @@ Each block export function should accept three argumets..."
   :set 'org-export-blocks-set)
 
 (defun org-export-blocks-add-block (block-spec)
-  "Add a new block type to `org-export-blocks'.  BLOCK-SPEC
-should be a three element list the first element of which should
-indicate the name of the block, the second element should be the
-formatting function called by `org-export-blocks-preprocess' and
-the third element a flag indicating whether these types of blocks
-should be fontified in org-mode buffers (see
-`org-protecting-blocks').  For example the BLOCK-SPEC for ditaa
-blocks is as follows...
+  "Add a new block type to `org-export-blocks'.
+BLOCK-SPEC should be a three element list the first element of
+which should indicate the name of the block, the second element
+should be the formatting function called by
+`org-export-blocks-preprocess' and the third element a flag
+indicating whether these types of blocks should be fontified in
+org-mode buffers (see `org-protecting-blocks').  For example the
+BLOCK-SPEC for ditaa blocks is as follows.
 
   (ditaa org-export-blocks-format-ditaa nil)"
   (unless (member block-spec org-export-blocks)
@@ -122,29 +124,28 @@ blocks is as follows...
 
 (defcustom org-export-interblocks
   '()
-  "Use this a-list to associate block types with block exporting
-functions.  The type of a block is determined by the text
-immediately following the '#+BEGIN_' portion of the block header.
-Each block export function should accept three argumets..."
+  "Use this a-list to associate block types with block exporting functions.
+The type of a block is determined by the text immediately
+following the '#+BEGIN_' portion of the block header.  Each block
+export function should accept three arguments."
   :group 'org-export-general
   :type 'alist)
 
 (defcustom org-export-blocks-witheld
   '(hidden)
-  "List of block types (see `org-export-blocks') which should not
-be exported."
+  "List of block types (see `org-export-blocks') which should not be exported."
   :group 'org-export-general
   :type 'list)
 
 (defcustom org-export-blocks-postblock-hook nil
-  "Run after blocks have been processed with
-`org-export-blocks-preprocess'."
+  "Run after blocks have been processed with `org-export-blocks-preprocess'."
   :group 'org-export-general
   :type 'hook)
 
 (defun org-export-blocks-html-quote (body &optional open close)
-  "Protext BODY from org html export.  The optional OPEN and
-CLOSE tags will be inserted around BODY."
+  "Protect BODY from org html export.
+The optional OPEN and CLOSE tags will be inserted around BODY."
+
   (concat
    "\n#+BEGIN_HTML\n"
    (or open "")
@@ -153,8 +154,8 @@ CLOSE tags will be inserted around BODY."
    "#+END_HTML\n"))
 
 (defun org-export-blocks-latex-quote (body &optional open close)
-  "Protext BODY from org latex export.  The optional OPEN and
-CLOSE tags will be inserted around BODY."
+  "Protect BODY from org latex export.
+The optional OPEN and CLOSE tags will be inserted around BODY."
   (concat
    "\n#+BEGIN_LaTeX\n"
    (or open "")
@@ -163,10 +164,9 @@ CLOSE tags will be inserted around BODY."
    "#+END_LaTeX\n"))
 
 (defun org-export-blocks-preprocess ()
-  "Export all blocks according to the `org-export-blocks' block
-exportation alist.  Does not export block types specified in
-specified in BLOCKS which default to the value of
-`org-export-blocks-witheld'."
+  "Export all blocks according to the `org-export-blocks' block export alist.
+Does not export block types specified in specified in BLOCKS
+which defaults to the value of `org-export-blocks-witheld'."
   (interactive)
   (save-window-excursion
     (let ((case-fold-search t)
@@ -217,7 +217,7 @@ specified in BLOCKS which default to the value of
 			       (expand-file-name
 				"../contrib"
 				(file-name-directory (or load-file-name buffer-file-name)))))))
-  "Path to the ditaa jar executable")
+  "Path to the ditaa jar executable.")
 
 (defun org-export-blocks-format-ditaa (body &rest headers)
   "Pass block BODY to the ditaa utility creating an image.

lisp/org-exp.el

@@ -26,12 +26,15 @@
 ;;
 ;;; Commentary:
 
+;;; Code:
+
 (require 'org)
 (require 'org-macs)
 (require 'org-agenda)
 (require 'org-exp-blocks)
 (require 'ob-exp)
 (require 'org-src)
+
 (eval-when-compile
   (require 'cl))
 
@@ -96,9 +99,10 @@ This works by starting up a separate Emacs process visiting the same file
 and doing the export from there.
 Not all export commands are affected by this - only the ones which
 actually write to a file, and that do not depend on the buffer state.
-
+\\<org-mode-map>
 If this option is nil, you can still get background export by calling
-`org-export' with a double prefix arg: `C-u C-u C-c C-e'.
+`org-export' with a double prefix arg: \
+\\[universal-argument] \\[universal-argument] \\[org-export].
 
 If this option is t, the double prefix can be used to exceptionally
 force an export command into the current process."
@@ -843,7 +847,8 @@ in the background.  This will be done only for commands that write
 to a file.  For details see the docstring of `org-export-run-in-background'.
 
 The prefix argument ARG will be passed to the exporter.  However, if
-ARG is a double universal prefix `C-u C-u', that means to inverse the
+ARG is a double universal prefix \\[universal-argument] \\[universal-argument], \
+that means to inverse the
 value of `org-export-run-in-background'."
   (interactive "P")
   (let* ((bg (org-xor (equal arg '(16)) org-export-run-in-background))
@@ -977,7 +982,7 @@ value of `org-export-run-in-background'."
 (defvar org-export-id-target-alist nil
   "Alist of section id's with preferred aliases.")
 (defvar org-export-code-refs nil
-  "Alist of code references and line numbers")
+  "Alist of code references and line numbers.")
 
 (defun org-export-preprocess-string (string &rest parameters)
   "Cleanup STRING so that that the true exported has a more consistent source.
@@ -1183,7 +1188,7 @@ on this string to produce the exported version."
 (defun org-export-define-heading-targets (target-alist)
   "Find all headings and define the targets for them.
 The new targets are added to TARGET-ALIST, which is also returned.
-Also find all ID and CUSTOM_ID propertiess and store them."
+Also find all ID and CUSTOM_ID properties and store them."
   (goto-char (point-min))
   (org-init-section-numbers)
   (let ((re (concat "^" org-outline-regexp
@@ -2051,7 +2056,7 @@ TYPE must be a string, any of:
 	     (delq nil
 		   (mapcar (lambda (el) (when (member el all) el)) now))))
 	(when intersection
-	  (error "recursive #+INCLUDE: %S" intersection))))))
+	  (error "Recursive #+INCLUDE: %S" intersection))))))
 
 (defun org-get-file-contents (file &optional prefix prefix1 markup)
   "Get the contents of FILE and return them as a string.
@@ -2111,7 +2116,7 @@ in the list) and remove property and value from the list in LISTVAR."
 	    nil t)
       (if (match-end 1)
 	  (if (not (match-string 4))
-	      (error "source block missing language specification: %s"
+	      (error "Source block missing language specification: %s"
 		     (let* ((body (match-string 6))
 			    (nothing (message "body:%s" body))
 			    (preview (or (and (string-match
@@ -2406,8 +2411,8 @@ INDENT was the original indentation of the block."
 (defun org-export-visible (type arg)
   "Create a copy of the visible part of the current buffer, and export it.
 The copy is created in a temporary buffer and removed after use.
-TYPE is the final key (as a string) that also select the export command in
-the `C-c C-e' export dispatcher.
+TYPE is the final key (as a string) that also selects the export command in
+the \\<org-mode-map>\\[org-export] export dispatcher.
 As a special case, if the you type SPC at the prompt, the temporary
 org-mode file will not be removed but presented to you so that you can
 continue to use it.  The prefix arg ARG is passed through to the exporting

lisp/org-feed.el

@@ -83,8 +83,8 @@
 ;;
 ;;       #+DRAWERS: PROPERTIES LOGBOOK FEEDSTATUS
 ;;
-;;  Acknowledgements
-;;  ----------------
+;;  Acknowledgments
+;;  ---------------
 ;;
 ;;  org-feed.el is based on ideas by Brad Bozarth who implemented a
 ;;  similar mechanism using shell and awk scripts.

lisp/org-freemind.el

@@ -196,7 +196,7 @@ NOT READY YET."
 
 ;;;###autoload
 (defun org-freemind-show (mm-file)
-  "Show file MM-FILE in Freemind."
+  "Show file MM-FILE in FreeMind."
   (interactive
    (list
     (save-match-data
@@ -276,7 +276,7 @@ will also unescape &#nn;."
     ))
 
 (defun org-freemind-convert-links-from-org (org-str)
-  "Convert org links in ORG-STR to freemind links and return the result."
+  "Convert org links in ORG-STR to FreeMind links and return the result."
   (let ((fm-str (replace-regexp-in-string
                  (rx (not (any "[\""))
                      (submatch
@@ -297,7 +297,7 @@ will also unescape &#nn;."
 
 ;;(org-freemind-convert-links-to-org "<a href=\"http://www.somewhere/\">link-text</a>")
 (defun org-freemind-convert-links-to-org (fm-str)
-  "Convert freemind links in FM-STR to org links and return the result."
+  "Convert FreeMind links in FM-STR to org links and return the result."
   (let ((org-str (replace-regexp-in-string
                   (rx "<a"
                       space
@@ -344,10 +344,10 @@ will also unescape &#nn;."
           "</p>\n"))
 
 (defun org-freemind-org-text-to-freemind-subnode/note (node-name start end drawers-regexp)
-  "Convert text part of org node to freemind subnode or note.
-Convert the text part of the org node named NODE-NAME. The text
-is in the current buffer between START and END. Drawers matching
-DRAWERS-REGEXP are converted to freemind notes."
+  "Convert text part of org node to FreeMind subnode or note.
+Convert the text part of the org node named NODE-NAME.  The text
+is in the current buffer between START and END.  Drawers matching
+DRAWERS-REGEXP are converted to FreeMind notes."
   ;; fix-me: doc
   (let ((text (buffer-substring-no-properties start end))
         (node-res "")

lisp/org-habit.el

@@ -27,8 +27,11 @@
 
 ;; This file contains the habit tracking code for Org-mode
 
+;;; Code:
+
 (require 'org)
 (require 'org-agenda)
+
 (eval-when-compile
   (require 'cl))
 

lisp/org-html.el

@@ -26,7 +26,10 @@
 ;;
 ;;; Commentary:
 
+;;; Code:
+
 (require 'org-exp)
+
 (eval-when-compile (require 'cl))
 
 (declare-function org-id-find-id-file "org-id" (id))
@@ -57,7 +60,7 @@ by the footnotes themselves."
   :type 'string)
 
 (defcustom org-export-html-coding-system nil
-  "Coding system for HTML export, defaults to buffer-file-coding-system."
+  "Coding system for HTML export, defaults to `buffer-file-coding-system'."
   :group 'org-export-html
   :type 'coding-system)
 
@@ -81,7 +84,7 @@ and corresponding declarations."
 			(string :tag "Declaration")))))
 
 (defcustom org-export-html-style-include-scripts t
-  "Non-nil means include the javascript snippets in exported HTML files.
+  "Non-nil means include the JavaScript snippets in exported HTML files.
 The actual script is defined in `org-export-html-scripts' and should
 not be modified."
   :group 'org-export-html
@@ -110,7 +113,7 @@ not be modified."
  }
 /*]]>*///-->
 </script>"
-"Basic javascript that is needed by HTML files produced by Org-mode.")
+"Basic JavaScript that is needed by HTML files produced by Org-mode.")
 
 (defconst org-export-html-style-default
 "<style type=\"text/css\">
@@ -207,20 +210,20 @@ settings with <style>...</style> tags."
 (put 'org-export-html-style-extra 'safe-local-variable 'stringp)
 
 (defcustom org-export-html-tag-class-prefix ""
-  "Prefix to clas names for TODO keywords.
+  "Prefix to class names for TODO keywords.
 Each tag gets a class given by the tag itself, with this prefix.
 The default prefix is empty because it is nice to just use the keyword
 as a class name.  But if you get into conflicts with other, existing
-CSS classes, then this prefic can be very useful."
+CSS classes, then this prefix can be very useful."
   :group 'org-export-html
   :type 'string)
 
 (defcustom org-export-html-todo-kwd-class-prefix ""
-  "Prefix to clas names for TODO keywords.
+  "Prefix to class names for TODO keywords.
 Each TODO keyword gets a class given by the keyword itself, with this prefix.
 The default prefix is empty because it is nice to just use the keyword
 as a class name.  But if you get into conflicts with other, existing
-CSS classes, then this prefic can be very useful."
+CSS classes, then this prefix can be very useful."
   :group 'org-export-html
   :type 'string)
 
@@ -235,10 +238,11 @@ CSS classes, then this prefic can be very useful."
  |
  <a accesskey=\"H\" href=\"%s\"> HOME </a>
 </div>"
-  "Snippet used to insert the HOME and UP links.  This is a format,
-the first %s will receive the UP link, the second the HOME link.
-If both `org-export-html-link-up' and `org-export-html-link-home' are
-empty, the entire snippet will be ignored."
+  "Snippet used to insert the HOME and UP links.
+This is a format string, the first %s will receive the UP link,
+the second the HOME link.  If both `org-export-html-link-up' and
+`org-export-html-link-home' are empty, the entire snippet will be
+ignored."
   :group 'org-export-html
   :type 'string)
 
@@ -340,7 +344,7 @@ When nil, also column one will use data tags."
   :type 'boolean)
 
 (defcustom org-export-html-validation-link nil
-  "Non-nil means add validationlink to postamble of HTML exported files."
+  "Non-nil means add validation link to postamble of HTML exported files."
   :group 'org-export-html
   :type '(choice
 	  (const :tag "Nothing" nil)
@@ -349,9 +353,10 @@ When nil, also column one will use data tags."
 
 
 (defcustom org-export-html-with-timestamp nil
-  "If non-nil, write `org-export-html-html-helper-timestamp'
-into the exported HTML text.  Otherwise, the buffer will just be saved
-to a file."
+  "If non-nil, write timestamp into the exported HTML text.
+If non-nil Write `org-export-html-html-helper-timestamp' into the
+exported HTML text.  Otherwise, the buffer will just be saved to
+a file."
   :group 'org-export-html
   :type 'boolean)
 
@@ -426,7 +431,7 @@ This may also be a function, building and inserting the postamble.")
 ;;; HTML export
 
 (defun org-export-html-preprocess (parameters)
-  ;; Convert LaTeX fragments to images
+  "Convert LaTeX fragments to images."
   (when (and org-current-export-file
 	     (plist-get parameters :LaTeX-fragments))
     (org-format-latex
@@ -460,7 +465,8 @@ headlines.  The default is 3.  Lower levels will become bulleted lists."
 
 ;;;###autoload
 (defun org-export-as-html-batch ()
-  "Call `org-export-as-html', may be used in batch processing as
+  "Call the function `org-export-as-html'.
+This function can be used in batch processing as:
 emacs   --batch
         --load=$HOME/lib/emacs/org.el
         --eval \"(setq org-export-headline-levels 2)\"
@@ -540,12 +546,12 @@ in a window.  A non-interactive call will only return the buffer."
    nil
    "Function to convert link URLs to exportable URLs.
 Takes two arguments, TYPE and PATH.
-Returns exportable url as (TYPE PATH), or `nil' to signal that it
+Returns exportable url as (TYPE PATH), or nil to signal that it
 didn't handle this case.
 Intended to be locally bound around a call to `org-export-as-html'." )
 
 (defun org-html-cvt-org-as-html (opt-plist type path)
-   "Convert and org filename to an equivalent html filename.
+   "Convert an org filename to an equivalent html filename.
 If TYPE is not file, just return `nil'.
 See variable `org-export-html-link-org-files-as-html'"
 
@@ -565,10 +571,10 @@ See variable `org-export-html-link-org-files-as-html'"
 
 ;;; org-html-should-inline-p
 (defun org-html-should-inline-p (filename descp)
-   "Return non-nil if link FILENAME should be inlined, according to
-current settings.
-DESCP is the boolean of whether there was a link description.
-See variables `org-export-html-inline-images' and
+   "Return non-nil if link FILENAME should be inlined.
+The decision to inline the FILENAME link is based on the current
+settings.  DESCP is the boolean of whether there was a link
+description.  See variables `org-export-html-inline-images' and
 `org-export-html-inline-image-extensions'."
    (declare (special
 	     org-export-html-inline-images
@@ -2018,7 +2024,7 @@ that uses these same face definitions."
   (goto-char (point-min)))
 
 (defun org-html-protect (s)
-  ;; convert & to &amp;, < to &lt; and > to &gt;
+  "convert & to &amp;, < to &lt; and > to &gt;"
   (let ((start 0))
     (while (string-match "&" s start)
       (setq s (replace-match "&amp;" t t s)
@@ -2033,7 +2039,7 @@ that uses these same face definitions."
   s)
 
 (defun org-html-expand (string)
-  "Prepare STRING for HTML export.  Applies all active conversions.
+  "Prepare STRING for HTML export.  Apply all active conversions.
 If there are links in the string, don't modify these."
   (let* ((re (concat org-bracket-link-regexp "\\|"
 		     (org-re "[ \t]+\\(:[[:alnum:]_@:]+:\\)[ \t]*$")))