From mboxrd@z Thu Jan 1 00:00:00 1970 From: Philip Rooke Subject: [PATCH] Correct some docstrings [part 2] Date: Thu, 15 Jul 2010 18:54:53 +0100 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from [140.186.70.92] (port=41084 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OZSeH-0004Jy-37 for emacs-orgmode@gnu.org; Thu, 15 Jul 2010 13:55:11 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OZSeA-0002ka-1v for emacs-orgmode@gnu.org; Thu, 15 Jul 2010 13:55:04 -0400 Received: from mail-ew0-f41.google.com ([209.85.215.41]:55756) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OZSe9-0002kQ-Hn for emacs-orgmode@gnu.org; Thu, 15 Jul 2010 13:54:58 -0400 Received: by ewy28 with SMTP id 28so376072ewy.0 for ; Thu, 15 Jul 2010 10:54:56 -0700 (PDT) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org 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 --=20 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 . =20 -;; 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) =20 (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 time= s." ("=3D" "" "") ("~" "" "") ("+" "" "")) - "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 @@ ))) =20 (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)))) =20 (defun org-docview-complete-link () - "Use the existing file name completion for file: links to get the file n= ame, - 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"))) =20 =20 (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: =20 +;;; Code: + (require 'org-macs) =20 (declare-function org-table-align "org-table" ()) @@ -459,7 +461,7 @@ loaded, add these packages to `org-export-latex-package= s-alist'." ("Diamond" "\\diamond" t "⋄" "[diamond]" "[diamond]" "=E2=8B= =84") ("loz" "\\diamond" t "◊" "[lozenge]" "[lozenge]" "=E2=97=8A") ) - "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'.") =20 (defsubst org-entity-get (name) @@ -521,7 +523,7 @@ Kind can be any of `latex', `html', `ascii', `latin1', = or `utf8'." (org-table-align))) =20 (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=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D\n\n") @@ -555,7 +557,7 @@ Kind can be any of `latex', `html', `ascii', `latin1', = or `utf8'." =20 =20 (defun replace-amp () - "Postprocess HTML file to unescape the ampersant." + "Postprocess HTML file to unescape the ampersand." (interactive) (while (re-search-forward "&\\([^<;]+;\\)" nil t) (replace-match (concat "&" (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'. =20 +;;; 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 argume= ts..." :set 'org-export-blocks-set) =20 (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. =20 (ditaa org-export-blocks-format-ditaa nil)" (unless (member block-spec org-export-blocks) @@ -122,29 +124,28 @@ blocks is as follows... =20 (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) =20 (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 expor= ted." :group 'org-export-general :type 'list) =20 (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) =20 (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")) =20 (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")) =20 (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 ali= st. +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.") =20 (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: =20 +;;; Code: + (require 'org) (require 'org-macs) (require 'org-agenda) (require 'org-exp-blocks) (require 'ob-exp) (require 'org-src) + (eval-when-compile (require 'cl)) =20 @@ -96,9 +99,10 @@ This works by starting up a separate Emacs process visit= ing 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. - +\\ 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]. =20 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= '. =20 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-argum= ent], \ +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.") =20 (defun org-export-preprocess-string (string &rest parameters) "Cleanup STRING so that that the true exported has a more consistent sou= rce. @@ -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)))))) =20 (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 l= ist 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-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:=20 -#+KEYWORDS:=20 +#+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:=20 +#+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." =20 ;;;###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;." )) =20 (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;." =20 ;;(org-freemind-convert-links-to-org "= link-text") (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 "\n")) =20 (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 @@ =20 ;; This file contains the habit tracking code for Org-mode =20 +;;; Code: + (require 'org) (require 'org-agenda) + (eval-when-compile (require 'cl)) =20 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: =20 +;;; Code: + (require 'org-exp) + (eval-when-compile (require 'cl)) =20 (declare-function org-id-find-id-file "org-id" (id)) @@ -57,7 +60,7 @@ by the footnotes themselves." :type 'string) =20 (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) =20 @@ -81,7 +84,7 @@ and corresponding declarations." (string :tag "Declaration"))))) =20 (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." } /*]]>*///--> " -"Basic javascript that is needed by HTML files produced by Org-mode.") +"Basic JavaScript that is needed by HTML files produced by Org-mode.") =20 (defconst org-export-html-style-default " tags." (put 'org-export-html-style-extra 'safe-local-variable 'stringp) =20 (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) =20 (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 pref= ix. 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) =20 @@ -235,10 +238,11 @@ CSS classes, then this prefic can be very useful." | HOME " - "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) =20 @@ -340,7 +344,7 @@ When nil, also column one will use data tags." :type 'boolean) =20 (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." =20 =20 (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) =20 @@ -426,7 +431,7 @@ This may also be a function, building and inserting the= postamble.") ;;; HTML export =20 (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." =20 ;;;###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=3D$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'." ) =20 (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'" =20 @@ -565,10 +571,10 @@ See variable `org-export-html-link-org-files-as-html'" =20 ;;; 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))) =20 (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) =20 (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]*$")))