From mboxrd@z Thu Jan 1 00:00:00 1970 From: Phil Rooke Subject: [PATCH] Correct some docstrings [part 4] Date: Fri, 16 Jul 2010 17:23:01 +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=40671 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OZngp-0001WV-4Q for emacs-orgmode@gnu.org; Fri, 16 Jul 2010 12:23:09 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OZngm-0006F4-C3 for emacs-orgmode@gnu.org; Fri, 16 Jul 2010 12:23:06 -0400 Received: from mail-ew0-f41.google.com ([209.85.215.41]:39366) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OZngl-0006En-Ts for emacs-orgmode@gnu.org; Fri, 16 Jul 2010 12:23:04 -0400 Received: by ewy28 with SMTP id 28so865572ewy.0 for ; Fri, 16 Jul 2010 09:23:03 -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 Same rationale as previous patches in this series. Phil --=20 lisp/org-mac-message.el | 10 ++++---- lisp/org-macs.el | 4 +- lisp/org-mks.el | 12 +++++++-- lisp/org-mobile.el | 12 +++++---- lisp/org-mouse.el | 15 ++++++----- lisp/org-plot.el | 4 +- lisp/org-protocol.el | 60 ++++++++++++++++++++++++-------------------= --- lisp/org-publish.el | 33 +++++++++++-------------- lisp/org-remember.el | 51 ++++++++++++++++++++++------------------ 9 files changed, 107 insertions(+), 94 deletions(-) diff --git a/lisp/org-mac-message.el b/lisp/org-mac-message.el index 1fca14d..bb108ce 100644 --- a/lisp/org-mac-message.el +++ b/lisp/org-mac-message.el @@ -39,7 +39,7 @@ ;; messages selected in Mail.app. =20 ;; (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. =20 @@ -53,7 +53,7 @@ :group 'org-link) =20 (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) =20 @@ -81,7 +81,7 @@ This will use the command `open' with the message URL." "open" (concat "message://<" (substring message-id 2) ">"))) =20 (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"))) =20 (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, an= d also returned." =20 (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"))) diff --git a/lisp/org-macs.el b/lisp/org-macs.el index 2043045..4c2fecd 100644 --- a/lisp/org-macs.el +++ b/lisp/org-macs.el @@ -92,7 +92,7 @@ Also, do not record undo information." =20 (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))) =20 outline-regexp diff --git a/lisp/org-mks.el b/lisp/org-mks.el index 4a49a2b..88b01c2 100644 --- a/lisp/org-mks.el +++ b/lisp/org-mks.el @@ -23,6 +23,12 @@ ;; along with GNU Emacs. If not, see . ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;= ;;; =20 + +;;; Commentary: +;;=20 + +;;; 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. =20 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 selecte= d. When you press a prefix key, the commands (and maybe further prefixes) under this key will be shown and offered for selection. =20 @@ -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=20 + (setq table (mapcar (lambda (x) (if (and (> (length (car x)) 1) (equal (substring (car x) 0 1) pressed)) diff --git a/lisp/org-mobile.el b/lisp/org-mobile.el index ce82688..0f508fd 100644 --- a/lisp/org-mobile.el +++ b/lisp/org-mobile.el @@ -33,6 +33,8 @@ =20 (require 'org) (require 'org-agenda) +;;; Code: + (eval-when-compile (require 'cl)) =20 (defgroup org-mobile nil @@ -66,7 +68,7 @@ org-agenda-text-search-extra-files :type 'directory) =20 (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." =20 (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 acces= s." :group 'org-mobile :type 'directory) @@ -88,7 +90,7 @@ You might want to put this file into a directory where on= ly 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")))) =20 (defun org-mobile-create-index-file () "Write the index file in the WebDAV directory." diff --git a/lisp/org-mouse.el b/lisp/org-mouse.el index a56c55f..eea51ec 100644 --- a/lisp/org-mouse.el +++ b/lisp/org-mouse.el @@ -137,6 +137,8 @@ ;; ;; Versions 0.01 -- 0.07: (I don't remember) =20 +;;; Code: + (eval-when-compile (require 'cl)) (require 'org) =20 @@ -225,7 +227,7 @@ this function is called. Otherwise, the current major = mode menu is used." (mouse-save-then-kill event))) =20 (defun org-mouse-line-position () - "Returns `:beginning' or `:middle' or `:end', depending on the point pos= ition. + "Return `:beginning' or `:middle' or `:end', depending on the point posi= tion. =20 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 KEYWOR= DS. 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 KEYWOR= DS. 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)))))) =20 (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,7 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:" (org-next-item))))) =20 (defun org-mouse-bolp () - "Returns true if there only spaces, tabs, and '*', between the beginnin= g of line and the point" + "Return true if there only spaces, tabs, and '*', between the beginning= of line and the point." (save-excursion (skip-chars-backward " \t*") (bolp))) =20 @@ -1145,4 +1146,4 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:" =20 ;; arch-tag: ff1ae557-3529-41a3-95c6-baaebdcc280f =20 -;;; org-mouse.el ends-here +;;; org-mouse.el ends here diff --git a/lisp/org-plot.el b/lisp/org-plot.el index 8282d30..8183207 100644 --- a/lisp/org-plot.el +++ b/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'.") =20 (defvar org-plot-timestamp-fmt nil) =20 @@ -272,7 +272,7 @@ manner suitable for prepending to a user-specified scri= pt." ;; 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) diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index cdfbf10..e97c32e 100644 --- a/lisp/org-protocol.el +++ b/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 file= names -;; for `org-protocol-the-protocol' and sub-procols defined in +;; This is done by advising `server-visit-files' to scan the list of filen= ames +;; 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 presen= t) and -;; pushes the browsers URL to the `kill-ring' for yanking. This handle= r is +;; pushes the browsers URL to the `kill-ring' for yanking. This handl= er 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 t= ext +;; 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 inserte= d 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\". @@ -156,17 +156,18 @@ See `org-protocol-protocol-alist' for a description o= f 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' ho= ld the -sub-protocols that trigger the required action. You will have to define ju= st one -protocol handler OS-wide (MS-Windows) or per application (Linux). That pro= tocol +sub-protocols that trigger the required action. You will have to define j= ust one +protocol handler OS-wide (MS-Windows) or per application (Linux). That pr= otocol handler should call emacsclient.") =20 =20 ;;; User variables: =20 (defcustom org-protocol-reverse-list-of-files t - "* The filenames passed on the commandline are passed to the emacs-serve= r 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 tra= iling colon and slashes. If you define a protocol \"my-protocol\", `org-protocol-check-f= ilename-for-protocol' will search filenames for \"org-protocol:/my-protocol:/\" and trigger your action for every match. `org-protocol' is defi= ned in - `org-protocol-the-protocol'. Double and tripple slashes are com= pressed + `org-protocol-the-protocol'. Double and triple slashes are comp= ressed to one by emacsclient. =20 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 =20 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 com= mand + `C-g' to avoid dangling emacsclients. Note, that all other comm= and line arguments but the this one will be discarded, greedy handl= ers still receive the whole list of arguments though. =20 @@ -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)) =20 @@ -267,7 +268,7 @@ Here is an example: ;;; Helper functions: =20 (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." =20 =20 (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 = `=C3=BC'." =20 =20 (defun org-protocol-unhex-compound (hex) - "Unhexify unicode hex-chars. E.g. `%C3%B6' is the german Umlaut `=C3=BC'= ." + "Unhexify unicode hex-chars. E.g. `%C3%B6' is the German Umlaut `=C3=BC'= ." (let* ((bytes (remove "" (split-string hex "%"))) (ret "") (eat 0) @@ -415,9 +417,9 @@ This function transforms it into a flat list." ;;; Standard protocol handlers: =20 (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'. =20 The location for a browser's bookmark has to look like this: =20 @@ -588,7 +590,7 @@ This is, how the matching is done: =20 protocol and sub-protocol are regexp-quoted. =20 -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 t= he 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) diff --git a/lisp/org-publish.el b/lisp/org-publish.el index a50cf56..5475386 100644 --- a/lisp/org-publish.el +++ b/lisp/org-publish.el @@ -193,7 +193,7 @@ The following properties control the creation of a conc= ept index. :type 'alist) =20 (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)))) =20 (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 u= sing + "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 us= ing 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, becau= se we do not know under what file name the file will be stored - the publishi= ng @@ -286,7 +286,7 @@ If there is no timestamp, create one." (org-publish-cache-set key stamp))) =20 (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." =20 ;; 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 all the timestamps and titles for files in publishing p= rojects. +Blocks could hash sha1 values here.") =20 =20 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -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 eventually alph= abetically." (let ((retval t)) (when (or sitemap-alphabetically sitemap-sort-folders) ;; First we sort alphabetically: @@ -456,7 +455,7 @@ matching filenames." org-publish-temp-files)) =20 (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) =20 @@ -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)))) =20 (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)))) =20 (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." =20 (unless project-name (error "%s%s" "Cannot initialize `org-publish-cache' without projects = name" @@ -976,9 +974,8 @@ Return `t', if the file needs publishing" (< pstamp ctime))))) =20 (defun org-publish-cache-set-file-property (filename property value &optio= nal 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. + "Set the VALUE for a PROPERTY of file FILENAME in publishing cache to VA= LUE. +Use cache file of PROJECT-NAME. If the entry does not exist, it will be c= reated. Return VALUE." ;; Evtl. load the requested cache file: (if project-name (org-publish-initialize-cache project-name)) @@ -992,7 +989,7 @@ Return VALUE." =20 (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)) =20 (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")) diff --git a/lisp/org-remember.el b/lisp/org-remember.el index d9d52cb..8d76e78 100644 --- a/lisp/org-remember.el +++ b/lisp/org-remember.el @@ -54,14 +54,15 @@ :group 'org) =20 (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-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. =20 -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) =20 @@ -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: =20 - %^{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\ + \\ + (skipping the \\[org-remember-finalize] that normally trigge= rs storing) %& jump to target location immediately after storing note - - %? After completing the template, position cursor here. + %? after completing the template, position cursor here. =20 Apart from these general escapes, you can access information specific to t= he link type that is created. For example, calling `remember' in emails or g= nus @@ -215,7 +215,7 @@ The remember buffer is still current when this hook run= s." :type 'hook) =20 (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 war= ning. =20 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. =20 -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. =20 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'. - +\\ 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. =20 -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. =20 -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. =20 -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). =20 Before storing the note, the function ensures that the text has an org-mode-style headline, i.e. a first line that starts with