Browse Source

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
Philip Rooke 11 years ago
parent
commit
07cacd881d
9 changed files with 103 additions and 82 deletions
  1. 4 4
      lisp/org-docbook.el
  2. 8 3
      lisp/org-docview.el
  3. 5 3
      lisp/org-entities.el
  4. 29 29
      lisp/org-exp-blocks.el
  5. 14 9
      lisp/org-exp.el
  6. 2 2
      lisp/org-feed.el
  7. 7 7
      lisp/org-freemind.el
  8. 3 0
      lisp/org-habit.el
  9. 31 25
      lisp/org-html.el

+ 4 - 4
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.

+ 8 - 3
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

+ 5 - 3
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]" "[diamond]" "⋄")
     ("loz" "\\diamond" t "&loz;" "[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)))

+ 29 - 29
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.

+ 14 - 9
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

+ 2 - 2
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.

+ 7 - 7
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 "")

+ 3 - 0
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))
 

+ 31 - 25
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]*$")))