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 | 8 +++---
lisp/org-docview.el | 11 ++++++--
lisp/org-entities.el | 8 ++++--
lisp/org-exp-blocks.el | 58 +++++++++++++++++++++++
+------------------------
lisp/org-exp.el | 29 ++++++++++++++----------
lisp/org-feed.el | 4 +-
lisp/org-freemind.el | 14 +++++-----
lisp/org-habit.el | 3 ++
lisp/org-html.el | 56 ++++++++++++++++++++++++
+--------------------
9 files changed, 106 insertions(+), 85 deletions(-)
diff --git a/lisp/org-docbook.el b/lisp/org-docbook.el
index bbd0bed..c136d20 100644
--- a/lisp/org-docbook.el
+++ b/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.
diff --git a/lisp/org-docview.el b/lisp/org-docview.el
index 5db6594..b3a5178 100644
--- a/lisp/org-docview.el
+++ b/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)
+
+(provide 'org-docview)
+
+;;; org-docview.el ends here
diff --git a/lisp/org-entities.el b/lisp/org-entities.el
index 59734dc..501eb1c 100644
--- a/lisp/org-entities.el
+++ b/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>&\\([^<;]+;\\)" nil t)
(replace-match (concat "<td>&" (match-string 1)) t t)))
diff --git a/lisp/org-exp-blocks.el b/lisp/org-exp-blocks.el
index 4bf5db6..bbe245c 100644
--- a/lisp/org-exp-blocks.el
+++ b/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.
diff --git a/lisp/org-exp.el b/lisp/org-exp.el
index 55b8812..ae10cc4 100644
--- a/lisp/org-exp.el
+++ b/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
@@ -2597,8 +2602,8 @@ Does include HTML export options as well as
TODO and CATEGORY stuff."
#+AUTHOR: %s
#+EMAIL: %s
#+DATE: %s
-#+DESCRIPTION:
-#+KEYWORDS:
+#+DESCRIPTION:
+#+KEYWORDS:
#+LANGUAGE: %s
#+OPTIONS: H:%d num:%s toc:%s \\n:%s @:%s ::%s |:%s ^:%s -:%s f:%s
*:%s <:%s
#+OPTIONS: TeX:%s LaTeX:%s skip:%s d:%s todo:%s pri:%s tags:%s
@@ -2607,7 +2612,7 @@ Does include HTML export options as well as
TODO and CATEGORY stuff."
#+EXPORT_EXCLUDE_TAGS: %s
#+LINK_UP: %s
#+LINK_HOME: %s
-#+XSLT:
+#+XSLT:
#+CATEGORY: %s
#+SEQ_TODO: %s
#+TYP_TODO: %s
diff --git a/lisp/org-feed.el b/lisp/org-feed.el
index 2af97e5..58c552b 100644
--- a/lisp/org-feed.el
+++ b/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.
diff --git a/lisp/org-freemind.el b/lisp/org-freemind.el
index 538b404..d066960 100644
--- a/lisp/org-freemind.el
+++ b/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 "")
diff --git a/lisp/org-habit.el b/lisp/org-habit.el
index 97c2bf7..f4b990e 100644
--- a/lisp/org-habit.el
+++ b/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))
diff --git a/lisp/org-html.el b/lisp/org-html.el
index d972c58..3889778 100644
--- a/lisp/org-html.el
+++ b/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 &, < to < and > to >
+ "convert & to &, < to < and > to >"
(let ((start 0))
(while (string-match "&" s start)
(setq s (replace-match "&" 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]*$")))
_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
address@hidden
http://lists.gnu.org/mailman/listinfo/emacs-orgmode