Browse Source

Improve docstrings

* lisp/ob-core.el (org-confirm-babel-evaluate):
(org-babel-no-eval-on-ctrl-c-ctrl-c):
(org-babel-hash-at-point):
* lisp/org-agenda.el (org-agenda-custom-commands):
(org-stuck-projects):
(org-agenda):
(org-timeline):
(org-todo-list):
(org-agenda-filter-by-tag):
(org-agenda-log-mode):
(org-agenda-refile):
(org-agenda-show-and-scroll-up):
(org-agenda-tree-to-indirect-buffer):
(org-agenda-show-the-flagging-note):
(org-agenda-to-appt):
* lisp/org-capture.el (org-capture-mode):
(org-capture-use-agenda-date):
(org-capture):
* lisp/org-clock.el (org-clock-in):
(org-clock-display):
* lisp/org-colview.el (org-columns--display-here):
(org-columns):
* lisp/org-footnote.el (org-footnote-section):
* lisp/org-gnus.el (org-gnus-prefer-web-links):
* lisp/org-lint.el (org-lint):
* lisp/org-list.el (org-plain-list-ordered-item-terminator):
(org-list-allow-alphabetical):
(org-list-automatic-rules):
(org-list-use-circular-motion):
* lisp/org-protocol.el (org-protocol-store-link):
(org-protocol-create-for-org):
* lisp/org-src.el (org-src-preserve-indentation):
(org-edit-src-content-indentation):
(org-src-mode-hook):
(org-src-mode):
(org-edit-table.el):
(org-edit-export-block):
(org-edit-src-code):
(org-edit-fixed-width-region):
* lisp/org-table.el (org-table-automatic-realign):
(org-table-copy-increment):
(org-table-formula-evaluate-inline):
(org-table-allow-automatic-line-recalculation):
(org-table-edit-field):
(orgtbl-ascii-plot):
* lisp/org-timer.el (org-timer):
* lisp/org.el (org-deadline-string):
(org-comment-string):
(org-ellipsis):
(org-show-context-detail):
(org-indirect-buffer-display):
(org-cycle-global-at-bob):
(org-insert-heading-respect-content):
(org-enable-table-editor):
(org-context-in-file-links):
(org-display-internal-link-with-indirect-buffer):
(org-file-apps):
(org-refile-targets):
(org-todo-keywords):
(org-use-fast-todo-selection):
(org-treat-insert-todo-heading-as-state-change):
(org-time-clocksum-use-fractional):
(org-time-clocksum-use-effort-durations):
(org-agenda-files):
(org-cycle-hide-archived-subtrees):
(org-cycle):
(org-global-cycle):
(org-tree-to-indirect-buffer):
(org-insert-heading):
(org-store-link):
(org-insert-link):
(org-mark-ring-push):
(org-refile):
(org-todo):
(org-show-todo-tree):
(org-reveal):
(org-check-deadlines):
(org-switchb):
(org-cdlatex-mode):
(org-toggle-latex-fragment):
(org-ctrl-c-ctrl-c):
(org-toggle-heading):
(org-indent-line):
(org-yank):
(org-speedbar-set-agenda-restriction):
* lisp/ox-html.el (org-html-htmlize-output-type):
* lisp/ox-icalendar.el (org-icalendar-combined-agenda-file):
* lisp/ox-publish.el (org-publish-project-alist):
* lisp/ox.el (org-export-in-background):
(org-export-stack-mode):
(org-export--stack-source-at-point):
(org-export-dispatch): Improve quotes and formatting in docstrings.
Nicolas Goaziou 3 years ago
parent
commit
0cf58cc208
18 changed files with 380 additions and 282 deletions
  1. 4 4
      lisp/ob-core.el
  2. 46 27
      lisp/org-agenda.el
  3. 19 14
      lisp/org-capture.el
  4. 25 15
      lisp/org-clock.el
  5. 2 2
      lisp/org-colview.el
  6. 1 1
      lisp/org-footnote.el
  7. 2 2
      lisp/org-gnus.el
  8. 4 4
      lisp/org-lint.el
  9. 20 11
      lisp/org-list.el
  10. 3 3
      lisp/org-protocol.el
  11. 28 20
      lisp/org-src.el
  12. 17 12
      lisp/org-table.el
  13. 11 8
      lisp/org-timer.el
  14. 181 145
      lisp/org.el
  15. 1 1
      lisp/ox-html.el
  16. 1 1
      lisp/ox-icalendar.el
  17. 4 3
      lisp/ox-publish.el
  18. 11 9
      lisp/ox.el

+ 4 - 4
lisp/ob-core.el

@@ -117,11 +117,11 @@ execution or nil if no prompt is required.
 
 Warning: Disabling confirmation may result in accidental
 evaluation of potentially harmful code.  It may be advisable
-remove code block execution from \\[org-ctrl-c-ctrl-c] \
+remove code block execution from `\\[org-ctrl-c-ctrl-c]' \
 as further protection
 against accidental code block evaluation.  The
 `org-babel-no-eval-on-ctrl-c-ctrl-c' variable can be used to
-remove code block execution from the \\[org-ctrl-c-ctrl-c] keybinding."
+remove code block execution from the `\\[org-ctrl-c-ctrl-c]' keybinding."
   :group 'org-babel
   :version "24.1"
   :type '(choice boolean function))
@@ -130,7 +130,7 @@ remove code block execution from the \\[org-ctrl-c-ctrl-c] keybinding."
 
 (defcustom org-babel-no-eval-on-ctrl-c-ctrl-c nil
   "\\<org-mode-map>\
-Remove code block evaluation from the \\[org-ctrl-c-ctrl-c] key binding."
+Remove code block evaluation from the `\\[org-ctrl-c-ctrl-c]' key binding."
   :group 'org-babel
   :version "24.1"
   :type 'boolean)
@@ -1323,7 +1323,7 @@ the `org-mode-hook'."
   "Return the value of the hash at POINT.
 \\<org-mode-map>\
 The hash is also added as the last element of the kill ring.
-This can be called with \\[org-ctrl-c-ctrl-c]."
+This can be called with `\\[org-ctrl-c-ctrl-c]'."
   (interactive)
   (let ((hash (car (delq nil (mapcar
 			      (lambda (ol) (overlay-get ol 'babel-hash))

+ 46 - 27
lisp/org-agenda.el

@@ -440,8 +440,9 @@ This will be spliced into the custom type of
 (defcustom org-agenda-custom-commands
   '(("n" "Agenda and all TODOs" ((agenda "") (alltodo ""))))
   "Custom commands for the agenda.
+\\<org-mode-map>
 These commands will be offered on the splash screen displayed by the
-agenda dispatcher \\[org-agenda].  Each entry is a list like this:
+agenda dispatcher `\\[org-agenda]'.  Each entry is a list like this:
 
    (key desc type match settings files)
 
@@ -606,14 +607,17 @@ subtree to see if any of the subtasks have project status.
 See also the variable `org-tags-match-list-sublevels' which applies
 to projects matched by this search as well.
 
-After defining this variable, you may use \\[org-agenda-list-stuck-projects]
-or `C-c a #' to produce the list."
+After defining this variable, you may use `\\[org-agenda-list-stuck-projects]'
+\(bound to `C-c a #') to produce the list."
   :group 'org-agenda-custom-commands
   :type '(list
 	  (string :tag "Tags/TODO match to identify a project")
-	  (repeat :tag "Projects are *not* stuck if they have an entry with TODO keyword any of" (string))
-	  (repeat :tag "Projects are *not* stuck if they have an entry with TAG being any of" (string))
-	  (regexp :tag "Projects are *not* stuck if this regexp matches inside the subtree")))
+	  (repeat :tag "Projects are *not* stuck if they have an entry with \
+TODO keyword any of" (string))
+	  (repeat :tag "Projects are *not* stuck if they have an entry with \
+TAG being any of" (string))
+	  (regexp :tag "Projects are *not* stuck if this regexp matches inside \
+the subtree")))
 
 (defgroup org-agenda-skip nil
   "Options concerning skipping parts of agenda files."
@@ -2697,7 +2701,7 @@ searches can be pre-defined in this way.
 
 If the current buffer is in Org mode and visiting a file, you can also
 first press `<' once to indicate that the agenda should be temporarily
-\(until the next use of \\[org-agenda]) restricted to the current file.
+\(until the next use of `\\[org-agenda]') restricted to the current file.
 Pressing `<' twice means to restrict to the current subtree or region
 \(if active)."
   (interactive "P")
@@ -4017,12 +4021,16 @@ This check for agenda markers in all agenda buffers currently active."
 (defvar org-agenda-show-log-scoped) ;; dynamically scope in `org-timeline' or `org-agenda-list'
 
 (defun org-timeline (&optional dotodo)
-  "Show a time-sorted view of the entries in the current org file.
-Only entries with a time stamp of today or later will be listed.  With
-\\[universal-argument] prefix, all unfinished TODO items will also be shown,
+  "Show a time-sorted view of the entries in the current Org file.
+
+Only entries with a time stamp of today or later will be listed.
+
+With `\\[universal-argument]' prefix, all unfinished TODO items will also be \
+shown,
 under the current date.
-If the buffer contains an active region, only check the region for
-dates."
+
+If the buffer contains an active region, only check the region
+for dates."
   (interactive "P")
   (let* ((dopast t)
 	 (org-agenda-show-log-scoped org-agenda-show-log)
@@ -4718,7 +4726,7 @@ Press `\\[org-agenda-manipulate-query-add]', \
 (defun org-todo-list (&optional arg)
   "Show all (not done) TODO entries from all agenda file in a single list.
 The prefix arg can be used to select a specific TODO keyword and limit
-the list to these.  When using \\[universal-argument], you will be prompted
+the list to these.  When using `\\[universal-argument]', you will be prompted
 for a keyword.  A numeric prefix directly selects the Nth keyword in
 `org-todo-keywords-1'."
   (interactive "P")
@@ -7471,9 +7479,9 @@ With two prefix arguments, remove the effort filters."
 
 The tag is selected with its fast selection letter, as configured.
 
-With a single \\[universal-argument] prefix ARG, exclude the agenda search.
+With a `\\[universal-argument]' prefix, exclude the agenda search.
 
-With a double \\[universal-argument] prefix ARG, filter the literal tag, \
+With a `\\[universal-argument] \\[universal-argument]' prefix, filter the literal tag, \
 i.e. don't
 filter on all its group members.
 
@@ -8161,9 +8169,11 @@ so that the date SD will be in that range."
 
 (defun org-agenda-log-mode (&optional special)
   "Toggle log mode in an agenda buffer.
+
 With argument SPECIAL, show all possible log items, not only the ones
 configured in `org-agenda-log-mode-items'.
-With a double \\[universal-argument] prefix arg, show *only* \
+
+With a `\\[universal-argument] \\[universal-argument]' prefix, show *only* \
 log items, nothing else."
   (interactive "P")
   (org-agenda-check-type t 'agenda 'timeline)
@@ -8178,8 +8188,7 @@ log items, nothing else."
   (setq org-agenda-start-with-log-mode org-agenda-show-log)
   (org-agenda-set-mode-name)
   (org-agenda-redo)
-  (message "Log mode is %s"
-	   (if org-agenda-show-log "on" "off")))
+  (message "Log mode is %s" (if org-agenda-show-log "on" "off")))
 
 (defun org-agenda-archives-mode (&optional with-files)
   "Toggle inclusion of items in trees marked with :ARCHIVE:.
@@ -8503,11 +8512,16 @@ If this information is not given, the function uses the tree at point."
 (defun org-agenda-refile (&optional goto rfloc no-update)
   "Refile the item at point.
 
-When GOTO is 0 or \\='(64) or a triple \\[universal-argument] prefix argument,
-clear the refile cache.
-When GOTO is \\='(16) or a double \\[universal-argument] prefix argument,
-go to the location of the last refiled item.
+When called with `\\[universal-argument] \\[universal-argument]', \
+go to the location of the last
+refiled item.
+
+When called with `\\[universal-argument] \\[universal-argument] \
+\\[universal-argument]' prefix or when GOTO is 0, clear
+the refile cache.
+
 RFLOC can be a refile location obtained in a different way.
+
 When NO-UPDATE is non-nil, don't redo the agenda buffer."
   (interactive "P")
   (cond
@@ -8624,8 +8638,10 @@ if it was hidden in the outline."
 (defvar org-agenda-show-window nil)
 (defun org-agenda-show-and-scroll-up (&optional arg)
   "Display the Org file which contains the item at point.
+
 When called repeatedly, scroll the window that is displaying the buffer.
-With a \\[universal-argument] prefix, use `org-show-entry' instead of \
+
+With a `\\[universal-argument]' prefix, use `org-show-entry' instead of \
 `outline-show-subtree'
 to display the item, so that drawers and logbooks stay folded."
   (interactive "P")
@@ -8753,8 +8769,10 @@ This calls the command `org-tree-to-indirect-buffer' from the original buffer.
 
 With a numerical prefix ARG, go up to this level and then take that tree.
 With a negative numeric ARG, go up by this number of levels.
-With a \\[universal-argument] prefix, make a separate frame for this tree (i.e. don't
-use the dedicated frame)."
+
+With a `\\[universal-argument]' prefix, make a separate frame for this tree, \
+i.e. don't use
+the dedicated frame."
   (interactive "P")
   (if current-prefix-arg
       (org-agenda-do-tree-to-indirect-buffer arg)
@@ -10035,7 +10053,7 @@ tag and (if present) the flagging note."
       (goto-char (point-min))
       (select-window win)
       (message "%s" (substitute-command-keys "Flagging note pushed to \
-kill ring.  Press \\[org-agenda-show-the-flagging-note] again to remove \
+kill ring.  Press `\\[org-agenda-show-the-flagging-note]' again to remove \
 tag and note")))))
 
 (defun org-agenda-remove-flag (marker)
@@ -10059,7 +10077,8 @@ tag and note")))))
 ;;;###autoload
 (defun org-agenda-to-appt (&optional refresh filter &rest args)
   "Activate appointments found in `org-agenda-files'.
-With a \\[universal-argument] prefix, refresh the list of
+
+With a `\\[universal-argument]' prefix, refresh the list of \
 appointments.
 
 If FILTER is t, interactively prompt the user for a regular

+ 19 - 14
lisp/org-capture.el

@@ -463,8 +463,9 @@ Turning on this mode runs the normal hook `org-capture-mode-hook'."
   (setq-local
    header-line-format
    (substitute-command-keys
-    "\\<org-capture-mode-map>Capture buffer.  Finish \\[org-capture-finalize], \
-refile \\[org-capture-refile], abort \\[org-capture-kill].")))
+    "\\<org-capture-mode-map>Capture buffer.  Finish \
+`\\[org-capture-finalize]', refile `\\[org-capture-refile]', \
+abort `\\[org-capture-kill]'.")))
 (define-key org-capture-mode-map "\C-c\C-c" 'org-capture-finalize)
 (define-key org-capture-mode-map "\C-c\C-k" 'org-capture-kill)
 (define-key org-capture-mode-map "\C-c\C-w" 'org-capture-refile)
@@ -533,7 +534,8 @@ to avoid duplicates.)"
 
 (defcustom org-capture-use-agenda-date nil
   "Non-nil means use the date at point when capturing from agendas.
-When nil, you can still capture using the date at point with \\[org-agenda-capture]."
+When nil, you can still capture using the date at point with
+`\\[org-agenda-capture]'."
   :group 'org-capture
   :version "24.3"
   :type 'boolean)
@@ -542,17 +544,20 @@ When nil, you can still capture using the date at point with \\[org-agenda-captu
 (defun org-capture (&optional goto keys)
   "Capture something.
 \\<org-capture-mode-map>
-This will let you select a template from `org-capture-templates', and then
-file the newly captured information.  The text is immediately inserted
-at the target location, and an indirect buffer is shown where you can
-edit it.  Pressing \\[org-capture-finalize] brings you back to the previous state
-of Emacs, so that you can continue your work.
-
-When called interactively with a \\[universal-argument] prefix argument GOTO, don't capture
-anything, just go to the file/headline where the selected template
-stores its notes.  With a double prefix argument \
-\\[universal-argument] \\[universal-argument], go to the last note
-stored.
+This will let you select a template from `org-capture-templates', and
+then file the newly captured information.  The text is immediately
+inserted at the target location, and an indirect buffer is shown where
+you can edit it.  Pressing `\\[org-capture-finalize]' brings you back to the \
+previous
+state of Emacs, so that you can continue your work.
+
+When called interactively with a `\\[universal-argument]' prefix argument \
+GOTO, don't
+capture anything, just go to the file/headline where the selected
+template stores its notes.
+
+With a `\\[universal-argument] \\[universal-argument]' prefix argument, go to \
+the last note stored.
 
 When called with a `C-0' (zero) prefix, insert a template at point.
 

+ 25 - 15
lisp/org-clock.el

@@ -1170,15 +1170,22 @@ so long."
 ;;;###autoload
 (defun org-clock-in (&optional select start-time)
   "Start the clock on the current item.
+
 If necessary, clock-out of the currently active clock.
-With a prefix argument SELECT (\\[universal-argument]), offer a list of recently clocked
-tasks to clock into.  When SELECT is \\[universal-argument] \\[universal-argument], clock into the current task
-and mark it as the default task, a special task that will always be offered
-in the clocking selection, associated with the letter `d'.
-When SELECT is \\[universal-argument] \\[universal-argument] \\[universal-argument], \
-clock in by using the last clock-out
-time as the start time \(see `org-clock-continuously' to
-make this the default behavior.)"
+
+With a `\\[universal-argument]' prefix argument SELECT, offer a list of \
+recently clocked
+tasks to clock into.
+
+When SELECT is `\\[universal-argument] \ \\[universal-argument]', \
+clock into the current task and mark it as
+the default task, a special task that will always be offered in the
+clocking selection, associated with the letter `d'.
+
+When SELECT is `\\[universal-argument] \\[universal-argument] \
+\\[universal-argument]', clock in by using the last clock-out
+time as the start time.  See `org-clock-continuously' to make this
+the default behavior."
   (interactive "P")
   (setq org-clock-notification-was-shown nil)
   (org-refresh-properties
@@ -1876,15 +1883,18 @@ PROPNAME lets you set a custom text property instead of :org-clock-minutes."
   "Show subtree times in the entire buffer.
 
 By default, show the total time for the range defined in
-`org-clock-display-default-range'.  With \\[universal-argument] \
+`org-clock-display-default-range'.  With `\\[universal-argument]' \
 prefix, show
-the total time for today instead.  With \\[universal-argument] \
-\\[universal-argument] prefix, use
-a custom range, entered at the prompt.  With \\[universal-argument] \
-\\[universal-argument] \\[universal-argument]
-prefix, display the total time in the echo area.
+the total time for today instead.
+
+With `\\[universal-argument] \\[universal-argument]' prefix, \
+use a custom range, entered at prompt.
+
+With `\\[universal-argument] \ \\[universal-argument] \
+\\[universal-argument]' prefix, display the total time in the
+echo area.
 
-Use \\[org-clock-remove-overlays] to remove the subtree times."
+Use `\\[org-clock-remove-overlays]' to remove the subtree times."
   (interactive "P")
   (org-clock-remove-overlays)
   (let* ((todayp (equal arg '(4)))

+ 2 - 2
lisp/org-colview.el

@@ -394,7 +394,7 @@ DATELINE is non-nil when the face used should be
 	  (line-beginning-position 2)
 	  'read-only
 	  (substitute-command-keys
-	   "Type \\<org-columns-map>\\[org-columns-edit-value] \
+	   "Type \\<org-columns-map>`\\[org-columns-edit-value]' \
 to edit property")))))))
 
 (defun org-columns-add-ellipses (string width)
@@ -774,7 +774,7 @@ Also sets `org-columns-top-level-marker' to the new position."
 Column view applies to the whole buffer if point is before the
 first headline.  Otherwise, it applies to the first ancestor
 setting \"COLUMNS\" property.  If there is none, it defaults to
-the current headline.  With a \\[universal-argument] prefix \
+the current headline.  With a `\\[universal-argument]' prefix \
 argument, turn on column
 view for the whole buffer unconditionally.
 

+ 1 - 1
lisp/org-footnote.el

@@ -108,7 +108,7 @@ this heading will be ignored.
 If you don't use the customize interface to change this variable,
 you will need to run the following command after the change:
 
-  \\[universal-argument] \\[org-element-cache-reset]"
+  `\\[universal-argument] \\[org-element-cache-reset]'"
   :group 'org-footnote
   :initialize 'custom-initialize-default
   :set (lambda (var val)

+ 2 - 2
lisp/org-gnus.el

@@ -48,8 +48,8 @@
 
 (defcustom org-gnus-prefer-web-links nil
   "If non-nil, `org-store-link' creates web links to Google groups or Gmane.
-When nil, Gnus will be used for such links.
-Using a prefix arg to the command \\[org-store-link] (`org-store-link')
+\\<org-mode-map>When nil, Gnus will be used for such links.
+Using a prefix argument to the command `\\[org-store-link]' (`org-store-link')
 negates this setting for the duration of the command."
   :group 'org-link-store
   :type 'boolean)

+ 4 - 4
lisp/org-lint.el

@@ -1162,10 +1162,10 @@ Checker will also be ignored in all subsequent reports."
 (defun org-lint (&optional arg)
   "Check current Org buffer for syntax mistakes.
 
-By default, run all checkers.  With a single prefix ARG \
-\\[universal-argument],
-select one category of checkers only.  With a double prefix
-\\[universal-argument] \\[universal-argument], select one precise \
+By default, run all checkers.  With a `\\[universal-argument]' prefix ARG, \
+select one
+category of checkers only.  With a `\\[universal-argument] \
+\\[universal-argument]' prefix, run one precise
 checker by its name.
 
 ARG can also be a list of checker names, as symbols, to run."

+ 20 - 11
lisp/org-list.el

@@ -241,7 +241,7 @@ This variable needs to be set before org.el is loaded.  If you
 need to make a change while Emacs is running, use the customize
 interface or run the following code after updating it:
 
-  \\[org-element-update-syntax]"
+  `\\[org-element-update-syntax]'"
   :group 'org-plain-lists
   :type '(choice (const :tag "dot like in \"2.\"" ?.)
 		 (const :tag "paren like in \"2)\"" ?\))
@@ -260,7 +260,7 @@ This variable needs to be set before org.el is loaded.  If you
 need to make a change while Emacs is running, use the customize
 interface or run the following code after updating it:
 
-  \\[org-element-update-syntax]"
+  `\\[org-element-update-syntax]'"
   :group 'org-plain-lists
   :version "24.1"
   :type 'boolean
@@ -282,12 +282,19 @@ spaces instead of one after the bullet in each item of the list."
 (defcustom org-list-automatic-rules '((checkbox . t)
 				      (indent . t))
   "Non-nil means apply set of rules when acting on lists.
+\\<org-mode-map>
 By default, automatic actions are taken when using
- \\[org-meta-return], \\[org-metaright], \\[org-metaleft],
- \\[org-shiftmetaright], \\[org-shiftmetaleft],
- \\[org-ctrl-c-minus], \\[org-toggle-checkbox] or
- \\[org-insert-todo-heading].  You can disable individually these
- rules by setting them to nil.  Valid rules are:
+  `\\[org-meta-return]',
+  `\\[org-metaright]',
+  `\\[org-metaleft]',
+  `\\[org-shiftmetaright]',
+  `\\[org-shiftmetaleft]',
+  `\\[org-ctrl-c-minus]',
+  `\\[org-toggle-checkbox]',
+  `\\[org-insert-todo-heading]'.
+
+You can disable individually these rules by setting them to nil.
+Valid rules are:
 
 checkbox  when non-nil, checkbox statistics is updated each time
           you either insert a new checkbox or toggle a checkbox.
@@ -307,13 +314,15 @@ indent    when non-nil, indenting or outdenting list top-item
 
 (defcustom org-list-use-circular-motion nil
   "Non-nil means commands implying motion in lists should be cyclic.
-
+\\<org-mode-map>
 In that case, the item following the last item is the first one,
 and the item preceding the first item is the last one.
 
-This affects the behavior of \\[org-move-item-up],
- \\[org-move-item-down], \\[org-next-item] and
- \\[org-previous-item]."
+This affects the behavior of
+  `\\[org-move-item-up]',
+  `\\[org-move-item-down]',
+  `\\[org-next-item]',
+  `\\[org-previous-item]'."
   :group 'org-plain-lists
   :version "24.1"
   :type 'boolean)

+ 3 - 3
lisp/org-protocol.el

@@ -435,8 +435,8 @@ form URL/TITLE can also be used."
       (push (list uri title) org-stored-links))
     (kill-new uri)
     (message "`%s' to insert new org-link, `%s' to insert `%s'"
-             (substitute-command-keys"\\[org-insert-link]")
-             (substitute-command-keys"\\[yank]")
+             (substitute-command-keys "`\\[org-insert-link]'")
+             (substitute-command-keys "`\\[yank]'")
              uri))
   nil)
 
@@ -655,7 +655,7 @@ delegates most of the work to `org-protocol-create'."
   (let ((all (or (org-publish-get-project-from-filename buffer-file-name))))
     (if all (org-protocol-create (cdr all))
       (message "Not in an org-project.  Did you mean `%s'?"
-               (substitute-command-keys"\\[org-protocol-create]")))))
+               (substitute-command-keys "`\\[org-protocol-create]'")))))
 
 (defun org-protocol-create (&optional project-plist)
   "Create a new org-protocol project interactively.

+ 28 - 20
lisp/org-src.el

@@ -107,11 +107,12 @@ These are the regions where each line starts with a colon."
 
 (defcustom org-src-preserve-indentation nil
   "If non-nil preserve leading whitespace characters on export.
+\\<org-mode-map>
 If non-nil leading whitespace characters in source code blocks
 are preserved on export, and when switching between the org
 buffer and the language mode edit buffer.
 
-When this variable is nil, after editing with \\[org-edit-src-code],
+When this variable is nil, after editing with `\\[org-edit-src-code]',
 the minimum (across-lines) number of leading whitespace characters
 are removed from all lines, and the code block is uniformly indented
 according to the value of `org-edit-src-content-indentation'."
@@ -120,10 +121,12 @@ according to the value of `org-edit-src-content-indentation'."
 
 (defcustom org-edit-src-content-indentation 2
   "Indentation for the content of a source code block.
+
 This should be the number of spaces added to the indentation of the #+begin
 line in order to compute the indentation of the block content after
-editing it with \\[org-edit-src-code].  Has no effect if
-`org-src-preserve-indentation' is non-nil."
+editing it with `\\[org-edit-src-code]'.
+
+It has no effect if `org-src-preserve-indentation' is non-nil."
   :group 'org-edit-structure
   :type 'integer)
 
@@ -168,7 +171,7 @@ other-frame       Use `switch-to-buffer-other-frame' to display edit buffer.
   "Hook run after Org switched a source code snippet to its Emacs mode.
 \\<org-mode-map>
 This hook will run:
-- when editing a source code snippet with \\[org-edit-special]
+- when editing a source code snippet with `\\[org-edit-special]'
 - when formatting a source code snippet for export with htmlize.
 
 You may want to use this hook for example to turn off `outline-minor-mode'
@@ -595,7 +598,7 @@ with \",*\", \",#+\", \",,*\" and \",,#+\"."
   "Minor mode for language major mode buffers generated by Org.
 \\<org-mode-map>
 This minor mode is turned on in two situations:
-  - when editing a source code snippet with \\[org-edit-special]
+  - when editing a source code snippet with `\\[org-edit-special]'
   - when formatting a source code snippet for export with htmlize.
 
 \\{org-src-mode-map}
@@ -607,10 +610,10 @@ See also `org-src-mode-hook'."
      header-line-format
      (substitute-command-keys
       (if org-src--allow-write-back
-	  "Edit, then exit with \\[org-edit-src-exit] or abort with \
-\\[org-edit-src-abort]"
-	"Exit with \\[org-edit-src-exit] or abort with \
-\\[org-edit-src-abort]"))))
+	  "Edit, then exit with `\\[org-edit-src-exit]' or abort with \
+`\\[org-edit-src-abort]'"
+	"Exit with `\\[org-edit-src-exit]' or abort with \
+`\\[org-edit-src-abort]'"))))
   ;; Possibly activate various auto-save features (for the edit buffer
   ;; or the source buffer).
   (when org-edit-src-turn-on-auto-save
@@ -827,11 +830,12 @@ A coderef format regexp can only match at the end of a line."
 
 (defun org-edit-table.el ()
   "Edit \"table.el\" table at point.
-
+\\<org-src-mode-map>
 A new buffer is created and the table is copied into it.  Then
 the table is recognized with `table-recognize'.  When done
-editing, exit with \\[org-edit-src-exit].  The edited text will
-then replace the area in the Org mode buffer.
+editing, exit with `\\[org-edit-src-exit]'.  The edited text will \
+then replace
+the area in the Org mode buffer.
 
 Throw an error when not at such a table."
   (interactive)
@@ -850,12 +854,14 @@ Throw an error when not at such a table."
 
 (defun org-edit-export-block ()
   "Edit export block at point.
-
+\\<org-src-mode-map>
 A new buffer is created and the block is copied into it, and the
 buffer is switched into an appropriate major mode.  See also
-`org-src-lang-modes'.  When done, exit with
-\\[org-edit-src-exit].  The edited text will then replace the
-area in the Org mode buffer.
+`org-src-lang-modes'.
+
+When done, exit with `\\[org-edit-src-exit]'.  The edited text \
+will then replace
+the area in the Org mode buffer.
 
 Throw an error when not at an export block."
   (interactive)
@@ -877,7 +883,7 @@ Throw an error when not at an export block."
   "Edit the source or example block at point.
 \\<org-src-mode-map>
 The code is copied to a separate buffer and the appropriate mode
-is turned on.  When done, exit with \\[org-edit-src-exit].  This \
+is turned on.  When done, exit with `\\[org-edit-src-exit]'.  This \
 will remove the
 original code in the Org buffer, and replace it with the edited
 version.  See `org-src-window-setup' to configure the display of
@@ -967,14 +973,16 @@ name of the sub-editing buffer."
 
 (defun org-edit-fixed-width-region ()
   "Edit the fixed-width ASCII drawing at point.
-
+\\<org-src-mode-map>
 This must be a region where each line starts with a colon
 followed by a space or a newline character.
 
 A new buffer is created and the fixed-width region is copied into
 it, and the buffer is switched into the major mode defined in
-`org-edit-fixed-width-region-mode', which see.  When done, exit
-with \\[org-edit-src-exit].  The edited text will then replace
+`org-edit-fixed-width-region-mode', which see.
+
+When done, exit with `\\[org-edit-src-exit]'.  The edited text \
+will then replace
 the area in the Org mode buffer."
   (interactive)
   (let ((element (org-element-at-point)))

+ 17 - 12
lisp/org-table.el

@@ -199,7 +199,7 @@ alignment to the right border applies."
 
 (defcustom org-table-automatic-realign t
   "Non-nil means automatically re-align table when pressing TAB or RETURN.
-When nil, aligning is only done with \\[org-table-align], or after column
+When nil, aligning is only done with `\\[org-table-align]', or after column
 removal/insertion."
   :group 'org-table-editing
   :type 'boolean)
@@ -262,7 +262,8 @@ t       accept as input and present for editing"
 	  (const :tag "Convert user input, don't offer during editing" from)))
 
 (defcustom org-table-copy-increment t
-  "Non-nil means increment when copying current field with \\[org-table-copy-down]."
+  "Non-nil means increment when copying current field with \
+`\\[org-table-copy-down]'."
   :group 'org-table-calculation
   :version "25.2"
   :package-version '(Org . "8.3")
@@ -316,7 +317,7 @@ which should be evaluated as described in the manual and in the documentation
 string of the command `org-table-eval-formula'.  This feature requires the
 Emacs calc package.
 When this variable is nil, formula calculation is only available through
-the command \\[org-table-eval-formula]."
+the command `\\[org-table-eval-formula]'."
   :group 'org-table-calculation
   :type 'boolean)
 
@@ -349,7 +350,7 @@ Constants can also be defined on a per-file basis using a line like
 (defcustom org-table-allow-automatic-line-recalculation t
   "Non-nil means lines marked with |#| or |*| will be recomputed automatically.
 \\<org-mode-map>\
-Automatically means when TAB or RET or \\[org-ctrl-c-ctrl-c] \
+Automatically means when `TAB' or `RET' or `\\[org-ctrl-c-ctrl-c]' \
 are pressed in the line."
   :group 'org-table-calculation
   :type 'boolean)
@@ -1989,9 +1990,10 @@ blank, and the content is appended to the field above."
 ;;;###autoload
 (defun org-table-edit-field (arg)
   "Edit table field in a different window.
-This is mainly useful for fields that contain hidden parts.
-When called with a \\[universal-argument] prefix, just make the full field visible so that
-it can be edited in place."
+This is mainly useful for fields that contain hidden parts.  When called
+with a `\\[universal-argument]' prefix, just make the full field \
+visible so that it can be
+edited in place."
   (interactive "P")
   (cond
    ((equal arg '(16))
@@ -5295,12 +5297,15 @@ of regular ascii characters."
 
 ;;;###autoload
 (defun orgtbl-ascii-plot (&optional ask)
-  "Draw an ascii bar plot in a column.
-With cursor in a column containing numerical values, this
-function will draw a plot in a new column.
+  "Draw an ASCII bar plot in a column.
+
+With cursor in a column containing numerical values, this function
+will draw a plot in a new column.
+
 ASK, if given, is a numeric prefix to override the default 12
-characters width of the plot.  ASK may also be the
-\\[universal-argument] prefix, which will prompt for the width."
+characters width of the plot.  ASK may also be the `\\[universal-argument]' \
+prefix,
+which will prompt for the width."
   (interactive "P")
   (let ((col (org-table-current-column))
 	(min  1e999)		 ; 1e999 will be converted to infinity

+ 11 - 8
lisp/org-timer.el

@@ -204,22 +204,25 @@ With prefix arg STOP, stop it entirely."
   (message "Timer stopped"))
 
 ;;;###autoload
-(defun org-timer (&optional restart no-insert-p)
+(defun org-timer (&optional restart no-insert)
   "Insert a H:MM:SS string from the timer into the buffer.
-The first time this command is used, the timer is started.  When used with
-a \\[universal-argument] prefix, force restarting the timer.
-When used with a double prefix argument \\[universal-argument], change all the timer string
-in the region by a fixed amount.  This can be used to recalibrate a timer
-that was not started at the correct moment.
+The first time this command is used, the timer is started.
 
-If NO-INSERT-P is non-nil, return the string instead of inserting
+When used with a `\\[universal-argument]' prefix, force restarting the timer.
+
+When used with a `\\[universal-argument] \\[universal-argument]' \
+prefix, change all the timer strings
+in the region by a fixed amount.  This can be used to re-calibrate
+a timer that was not started at the correct moment.
+
+If NO-INSERT is non-nil, return the string instead of inserting
 it in the buffer."
   (interactive "P")
   (if (equal restart '(16))
       (org-timer-start restart)
     (when (or (equal restart '(4)) (not org-timer-start-time))
       (org-timer-start))
-    (if no-insert-p
+    (if no-insert
 	(org-timer-value-string)
       (insert (org-timer-value-string)))))
 

+ 181 - 145
lisp/org.el

@@ -372,15 +372,17 @@ FULL is given."
 
 (defvar org-deadline-string "DEADLINE:"
   "String to mark deadline entries.
-A deadline is this string, followed by a time stamp.  Should be a word,
-terminated by a colon.  You can insert a schedule keyword and
-a timestamp with \\[org-deadline].")
+\\<org-mode-map>
+A deadline is this string, followed by a time stamp.  It must be
+a word, terminated by a colon.  You can insert a schedule keyword
+and a timestamp with `\\[org-deadline]'.")
 
 (defvar org-scheduled-string "SCHEDULED:"
   "String to mark scheduled TODO entries.
-A schedule is this string, followed by a time stamp.  Should be a word,
-terminated by a colon.  You can insert a schedule keyword and
-a timestamp with \\[org-schedule].")
+\\<org-mode-map>
+A schedule is this string, followed by a time stamp.  It must be
+a word, terminated by a colon.  You can insert a schedule keyword
+and a timestamp with `\\[org-schedule]'.")
 
 (defconst org-ds-keyword-length
   (+ 2
@@ -521,8 +523,9 @@ not contribute to the agenda listings.")
 
 (defconst org-comment-string "COMMENT"
   "Entries starting with this keyword will never be exported.
+\\<org-mode-map>
 An entry can be toggled between COMMENT and normal with
-\\[org-toggle-comment].")
+`\\[org-toggle-comment]'.")
 
 
 ;;;; LaTeX Environments and Fragments
@@ -1115,7 +1118,7 @@ When nil, just use the standard three dots.
 When a string, use that string instead.
 
 The change affects only Org mode (which will then use its own display table).
-Changing this requires executing \\[org-mode] in a buffer to become
+Changing this requires executing `\\[org-mode]' in a buffer to become
 effective."
   :group 'org-startup
   :type '(choice (const :tag "Default" nil)
@@ -1160,8 +1163,8 @@ around point.  How much is shown depends on the initial action,
 or context.  Valid contexts are
 
   agenda         when exposing an entry from the agenda
-  org-goto       when using the command `org-goto' (\\[org-goto])
-  occur-tree     when using the command `org-occur' (\\[org-sparse-tree] /)
+  org-goto       when using the command `org-goto' (`\\[org-goto]')
+  occur-tree     when using the command `org-occur' (`\\[org-sparse-tree] /')
   tags-tree      when constructing a sparse tree based on tags matches
   link-search    when exposing search matches associated with a link
   mark-goto      when exposing the jump goal of a mark
@@ -1196,7 +1199,7 @@ As special cases, a nil or t value means show all contexts in
 
 Some views can make displayed information very compact, but also
 make it harder to edit the location of the match.  In such
-a case, use the command `org-reveal' (\\[org-reveal]) to show
+a case, use the command `org-reveal' (`\\[org-reveal]') to show
 more context."
   :group 'org-reveal-location
   :version "25.2"
@@ -1226,8 +1229,10 @@ more context."
 
 (defcustom org-indirect-buffer-display 'other-window
   "How should indirect tree buffers be displayed?
+
 This applies to indirect buffers created with the commands
-\\[org-tree-to-indirect-buffer] and \\[org-agenda-tree-to-indirect-buffer].
+`org-tree-to-indirect-buffer' and `org-agenda-tree-to-indirect-buffer'.
+
 Valid values are:
 current-window   Display in the current window
 other-window     Just display in another window.
@@ -1333,12 +1338,17 @@ This can also be set in on a per-file basis with
 
 (defcustom org-cycle-global-at-bob nil
   "Cycle globally if cursor is at beginning of buffer and not at a headline.
-This makes it possible to do global cycling without having to use S-TAB or
-\\[universal-argument] TAB.  For this special case to work, the first line
-of the buffer must not be a headline -- it may be empty or some other text.
+
+This makes it possible to do global cycling without having to use `S-TAB'
+or `\\[universal-argument] TAB'.  For this special case to work, the first \
+line of the buffer
+must not be a headline -- it may be empty or some other text.
+
 When used in this way, `org-cycle-hook' is disabled temporarily to make
-sure the cursor stays at the beginning of the buffer.  When this option is
-nil, don't do anything special at the beginning of the buffer."
+sure the cursor stays at the beginning of the buffer.
+
+When this option is nil, don't do anything special at the beginning of
+the buffer."
   :group 'org-cycle
   :type 'boolean)
 
@@ -1600,9 +1610,11 @@ default   the value to be used for all contexts not explicitly
 
 (defcustom org-insert-heading-respect-content nil
   "Non-nil means insert new headings after the current subtree.
+\\<org-mode-map>
 When nil, the new heading is created directly after the current line.
-The commands \\[org-insert-heading-respect-content] and \\[org-insert-todo-heading-respect-content] turn
-this variable on for the duration of the command."
+The commands `\\[org-insert-heading-respect-content]' and \
+`\\[org-insert-todo-heading-respect-content]' turn this variable on
+for the duration of the command."
   :group 'org-structure
   :type 'boolean)
 
@@ -1723,7 +1735,7 @@ Optimization requires replacing the functions `self-insert-command',
 `delete-char', and `backward-delete-char' in Org buffers, with a
 slight (in fact: unnoticeable) speed impact for normal typing.  Org is very
 good at guessing when a re-align will be necessary, but you can always
-force one with \\[org-ctrl-c-ctrl-c].
+force one with `\\[org-ctrl-c-ctrl-c]'.
 
 If you would like to use the optimized version in Org mode, but the
 un-optimized version in OrgTbl-mode, see the variable `orgtbl-optimized'.
@@ -1984,27 +1996,31 @@ It should match if the message is from the user him/herself."
 
 (defcustom org-context-in-file-links t
   "Non-nil means file links from `org-store-link' contain context.
-A search string will be added to the file name with :: as separator and
-used to find the context when the link is activated by the command
+\\<org-mode-map>
+A search string will be added to the file name with :: as separator
+and used to find the context when the link is activated by the command
 `org-open-at-point'.  When this option is t, the entire active region
 will be placed in the search string of the file link.  If set to a
 positive integer, only the first n lines of context will be stored.
 
-Using a prefix arg to the command \\[org-store-link] (`org-store-link')
+Using a prefix arg to the command `org-store-link' (`\\[universal-argument] \
+\\[org-store-link]')
 negates this setting for the duration of the command."
   :group 'org-link-store
   :type '(choice boolean integer))
 
 (defcustom org-keep-stored-link-after-insertion nil
   "Non-nil means keep link in list for entire session.
-
+\\<org-mode-map>
 The command `org-store-link' adds a link pointing to the current
 location to an internal list.  These links accumulate during a session.
 The command `org-insert-link' can be used to insert links into any
-Org file (offering completion for all stored links).  When this option
-is nil, every link which has been inserted once using \\[org-insert-link]
-will be removed from the list, to make completing the unused links
-more efficient."
+Org file (offering completion for all stored links).
+
+When this option is nil, every link which has been inserted once using
+`\\[org-insert-link]' will be removed from the list, to make completing the \
+unused
+links more efficient."
   :group 'org-link-store
   :type 'boolean)
 
@@ -2136,7 +2152,7 @@ another window."
   "Non-nil means use indirect buffer to display infile links.
 Activating internal links (from one location in a file to another location
 in the same file) normally just jumps to the location.  When the link is
-activated with a \\[universal-argument] prefix (or with mouse-3), the link \
+activated with a `\\[universal-argument]' prefix (or with mouse-3), the link \
 is displayed in
 another window.  When this option is set, the other window actually displays
 an indirect buffer clone of the current buffer, to avoid any visibility
@@ -2300,8 +2316,9 @@ Possible values for the file identifier are:
                \(\"html\" . default) to the list as well.
  `system'      The system command to open files, like `open' on Windows
                and Mac OS X, and mailcap under GNU/Linux.  This is the command
-               that will be selected if you call \\[org-open-at-point] with a double
-               \\[universal-argument] \\[universal-argument] prefix.
+               that will be selected if you call `org-open-at-point' with a
+               double prefix argument (`\\[universal-argument] \
+\\[universal-argument] \\[org-open-at-point]').
  t             Default for files not matched by any of the other options.
 
 Possible values for the command are:
@@ -2440,7 +2457,7 @@ will temporarily be changed to `time'."
 	  (const :tag "Record timestamp with note." note)))
 
 (defcustom org-refile-targets nil
-  "Targets for refiling entries with \\[org-refile].
+  "Targets for refiling entries with `\\[org-refile]'.
 This is a list of cons cells.  Each cell contains:
 - a specification of the files to be considered, either a list of files,
   or a symbol whose function or variable value will be used to retrieve
@@ -2602,7 +2619,7 @@ for inclusion into the global TODO list Org produces.  If one of the
 signify that no further action is necessary.  If \"|\" is not found,
 the last keyword is treated as the only DONE state of the sequence.
 
-The command \\[org-todo] cycles an entry through these states, and one
+The command `\\[org-todo]' cycles an entry through these states, and one
 additional state where no keyword is present.  For details about this
 cycling, see the manual.
 
@@ -2690,7 +2707,7 @@ more information."
 
 (defcustom org-use-fast-todo-selection t
   "\\<org-mode-map>\
-Non-nil means use the fast todo selection scheme with \\[org-todo].
+Non-nil means use the fast todo selection scheme with `\\[org-todo]'.
 This variable describes if and under what circumstances the cycling
 mechanism for TODO keywords will be replaced by a single-key, direct
 selection scheme.
@@ -2819,7 +2836,7 @@ to change is while Emacs is running is through the customize interface."
 
 (defcustom org-treat-insert-todo-heading-as-state-change nil
   "Non-nil means inserting a TODO heading is treated as state change.
-So when the command \\[org-insert-todo-heading] is used, state change
+So when the command `\\[org-insert-todo-heading]' is used, state change
 logging will apply if appropriate.  When nil, the new TODO item will
 be inserted directly, and no logging will take place."
   :group 'org-todo
@@ -3301,7 +3318,7 @@ in minutes (even for durations longer than an hour)."
 			     (const t)))))
 
 (defcustom org-time-clocksum-use-fractional nil
-  "When non-nil, \\[org-clock-display] uses fractional times.
+  "When non-nil, `\\[org-clock-display]' uses fractional times.
 See `org-time-clocksum-format' for more on time clock formats."
   :group 'org-time
   :group 'org-clock
@@ -3309,7 +3326,7 @@ See `org-time-clocksum-format' for more on time clock formats."
   :type 'boolean)
 
 (defcustom org-time-clocksum-use-effort-durations nil
-  "When non-nil, \\[org-clock-display] uses effort durations.
+  "When non-nil, `\\[org-clock-display]' uses effort durations.
 E.g. by default, one day is considered to be a 8 hours effort,
 so a task that has been clocked for 16 hours will be displayed
 as during 2 days in the clock display or in the clocktable.
@@ -3885,17 +3902,18 @@ is used instead.")
 
 (defcustom org-agenda-files nil
   "The files to be used for agenda display.
-Entries may be added to this list with \\[org-agenda-file-to-front] and removed with
-\\[org-remove-file].  You can also use customize to edit the list.
 
-If an entry is a directory, all files in that directory that are matched by
-`org-agenda-file-regexp' will be part of the file list.
+If an entry is a directory, all files in that directory that are matched
+by `org-agenda-file-regexp' will be part of the file list.
 
 If the value of the variable is not a list but a single file name, then
-the list of agenda files is actually stored and maintained in that file, one
-agenda file per line.  In this file paths can be given relative to
+the list of agenda files is actually stored and maintained in that file,
+one agenda file per line.  In this file paths can be given relative to
 `org-directory'.  Tilde expansion and environment variable substitution
-are also made."
+are also made.
+
+Entries may be added to this list with `\\[org-agenda-file-to-front]'
+and removed with `\\[org-remove-file]'."
   :group 'org-agenda
   :type '(choice
 	  (repeat :tag "List of files and directories" file)
@@ -4834,7 +4852,8 @@ Otherwise, these types are allowed:
 	(goto-char beg)
 	(when (looking-at-p (concat ".*:" org-archive-tag ":"))
 	  (message "%s" (substitute-command-keys
-			 "Subtree is archived and stays closed.  Use \\[org-force-cycle-archived] to cycle it anyway.")))))))
+			 "Subtree is archived and stays closed.  Use \
+`\\[org-force-cycle-archived]' to cycle it anyway.")))))))
 
 (defun org-force-cycle-archived ()
   "Cycle subtree even if it is archived."
@@ -6819,51 +6838,56 @@ and subscripts."
 (defun org-cycle (&optional arg)
   "TAB-action and visibility cycling for Org mode.
 
-This is the command invoked in Org mode by the TAB key.  Its main purpose
-is outline visibility cycling, but it also invokes other actions
+This is the command invoked in Org mode by the `TAB' key.  Its main
+purpose is outline visibility cycling, but it also invokes other actions
 in special contexts.
 
-- When this function is called with a prefix argument, rotate the entire
-  buffer through 3 states (global cycling)
+When this function is called with a `\\[universal-argument]' prefix, rotate \
+the entire
+buffer through 3 states (global cycling)
   1. OVERVIEW: Show only top-level headlines.
   2. CONTENTS: Show all headlines of all levels, but no body text.
   3. SHOW ALL: Show everything.
-  With a double \\[universal-argument] prefix argument, \
+
+With a `\\[universal-argument] \\[universal-argument]' prefix argument, \
 switch to the startup visibility,
-  determined by the variable `org-startup-folded', and by any VISIBILITY
-  properties in the buffer.
-  With a triple \\[universal-argument] prefix argument, \
-show the entire buffer, including any drawers.
+determined by the variable `org-startup-folded', and by any VISIBILITY
+properties in the buffer.
+
+With a `\\[universal-argument] \\[universal-argument] \
+\\[universal-argument]' prefix argument, show the entire buffer, including
+any drawers.
 
-- When inside a table, re-align the table and move to the next field.
+When inside a table, re-align the table and move to the next field.
 
-- When point is at the beginning of a headline, rotate the subtree started
-  by this line through 3 different states (local cycling)
+When point is at the beginning of a headline, rotate the subtree started
+by this line through 3 different states (local cycling)
   1. FOLDED:   Only the main headline is shown.
   2. CHILDREN: The main headline and the direct children are shown.
                From this state, you can move to one of the children
                and zoom in further.
   3. SUBTREE:  Show the entire subtree, including body text.
-  If there is no subtree, switch directly from CHILDREN to FOLDED.
-
-- When point is at the beginning of an empty headline and the variable
-  `org-cycle-level-after-item/entry-creation' is set, cycle the level
-  of the headline by demoting and promoting it to likely levels.  This
-  speeds up creation document structure by pressing TAB once or several
-  times right after creating a new headline.
-
-- When there is a numeric prefix, go up to a heading with level ARG, do
-  a `show-subtree' and return to the previous cursor position.  If ARG
-  is negative, go up that many levels.
-
-- When point is not at the beginning of a headline, execute the global
-  binding for TAB, which is re-indenting the line.  See the option
-  `org-cycle-emulate-tab' for details.
-
-- Special case: if point is at the beginning of the buffer and there is
-  no headline in line 1, this function will act as if called with prefix arg
-  (\\[universal-argument] TAB, same as S-TAB) also when called without prefix arg.
-  But only if also the variable `org-cycle-global-at-bob' is t."
+If there is no subtree, switch directly from CHILDREN to FOLDED.
+
+When point is at the beginning of an empty headline and the variable
+`org-cycle-level-after-item/entry-creation' is set, cycle the level
+of the headline by demoting and promoting it to likely levels.  This
+speeds up creation document structure by pressing `TAB' once or several
+times right after creating a new headline.
+
+When there is a numeric prefix, go up to a heading with level ARG, do
+a `show-subtree' and return to the previous cursor position.  If ARG
+is negative, go up that many levels.
+
+When point is not at the beginning of a headline, execute the global
+binding for `TAB', which is re-indenting the line.  See the option
+`org-cycle-emulate-tab' for details.
+
+As a special case, if point is at the beginning of the buffer and there is
+no headline in line 1, this function will act as if called with prefix arg
+\(`\\[universal-argument] TAB', same as `S-TAB') also when called without \
+prefix arg, but only
+if the variable `org-cycle-global-at-bob' is t."
   (interactive "P")
   (org-load-modules-maybe)
   (unless (or (run-hook-with-args-until-success 'org-tab-first-hook)
@@ -6914,7 +6938,7 @@ show the entire buffer, including any drawers.
        ((org-at-table-p 'any)
 	(if (org-at-table.el-p)
 	    (message "%s" (substitute-command-keys "\\<org-mode-map>\
-Use \\[org-edit-special] to edit table.el tables"))
+Use `\\[org-edit-special]' to edit table.el tables"))
 	  (if arg (org-table-edit-field t)
 	    (org-table-justify-field-maybe)
 	    (call-interactively 'org-table-next-field))))
@@ -7125,7 +7149,7 @@ Use \\[org-edit-special] to edit table.el tables"))
 ;;;###autoload
 (defun org-global-cycle (&optional arg)
   "Cycle the global visibility.  For details see `org-cycle'.
-With \\[universal-argument] prefix arg, switch to startup visibility.
+With `\\[universal-argument]' prefix ARG, switch to startup visibility.
 With a numeric prefix, show all headlines up to that level."
   (interactive "P")
   (let ((org-cycle-include-plain-lists
@@ -7755,17 +7779,18 @@ or nil."
 
 (defun org-tree-to-indirect-buffer (&optional arg)
   "Create indirect buffer and narrow it to current subtree.
+
 With a numerical prefix ARG, go up to this level and then take that tree.
 If ARG is negative, go up that many levels.
 
 If `org-indirect-buffer-display' is not `new-frame', the command removes the
 indirect buffer previously made with this command, to avoid proliferation of
 indirect buffers.  However, when you call the command with a \
-\\[universal-argument] prefix, or
-when `org-indirect-buffer-display' is `new-frame', the last buffer
-is kept so that you can work with several indirect buffers at the same time.
-If `org-indirect-buffer-display' is `dedicated-frame', the \
-\\[universal-argument] prefix also
+`\\[universal-argument]' prefix, or
+when `org-indirect-buffer-display' is `new-frame', the last buffer is kept
+so that you can work with several indirect buffers at the same time.  If
+`org-indirect-buffer-display' is `dedicated-frame', the \
+`\\[universal-argument]' prefix also
 requests that a new frame be made for the new buffer, so that the dedicated
 frame is not changed."
   (interactive "P")
@@ -7874,13 +7899,13 @@ headline/item with the text in the current line after point (see
 a special case, on a headline, splitting can only happen on the
 title itself.  E.g., this excludes breaking stars or tags.
 
-With a \\[universal-argument] prefix, set \
+With a `\\[universal-argument]' prefix, set \
 `org-insert-heading-respect-content' to
 a non-nil value for the duration of the command.  This forces the
 insertion of a heading after the current subtree, independently
 on the location of point.
 
-With a \\[universal-argument] \\[universal-argument] prefix, \
+With a `\\[universal-argument] \\[universal-argument]' prefix, \
 insert the heading at the end of the tree
 above the current heading.  For example, if point is within a
 2nd-level heading, then it will insert a 2nd-level heading at
@@ -9838,18 +9863,21 @@ and then used in capture templates."
 
 ;;;###autoload
 (defun org-store-link (arg)
-  "\\<org-mode-map>Store an org-link to the current location.
+  "Store an org-link to the current location.
+\\<org-mode-map>
 This link is added to `org-stored-links' and can later be inserted
-into an Org buffer with \\[org-insert-link].
+into an Org buffer with `org-insert-link' (`\\[org-insert-link]').
 
-For some link types, a prefix ARG is interpreted.
+For some link types, a `\\[universal-argument]' prefix ARG is interpreted.
 For links to Usenet articles, ARG negates `org-gnus-prefer-web-links'.
 For file links, ARG negates `org-context-in-file-links'.
 
-A double prefix ARG force skipping storing functions that are not
-part of Org's core.
+A `\\[universal-argument] \\[universal-argument]' prefix ARG forces \
+skipping storing functions that are not
+part of Org core.
 
-A triple prefix ARG force storing a link for each line in the
+A `\\[universal-argument] \\[universal-argument] \\[universal-argument]' \
+prefix ARG forces storing a link for each line in the
 active region."
   (interactive "P")
   (org-load-modules-maybe)
@@ -10344,43 +10372,44 @@ prepend or to append."
 (defun org-insert-link (&optional complete-file link-location default-description)
   "Insert a link.  At the prompt, enter the link.
 
-Completion can be used to insert any of the link protocol prefixes like
-http or ftp in use.
+Completion can be used to insert any of the link protocol prefixes in use.
 
 The history can be used to select a link previously stored with
 `org-store-link'.  When the empty string is entered (i.e. if you just
-press RET at the prompt), the link defaults to the most recently
-stored link.  As SPC triggers completion in the minibuffer, you need to
-use M-SPC or C-q SPC to force the insertion of a space character.
+press `RET' at the prompt), the link defaults to the most recently
+stored link.  As `SPC' triggers completion in the minibuffer, you need to
+use `M-SPC' or `C-q SPC' to force the insertion of a space character.
 
 You will also be prompted for a description, and if one is given, it will
 be displayed in the buffer instead of the link.
 
-If there is already a link at point, this command will allow you to edit link
-and description parts.
+If there is already a link at point, this command will allow you to edit
+link and description parts.
 
-With a \\[universal-argument] prefix, prompts for a file to link to.  The file name can
-be selected using completion.  The path to the file will be relative to the
+With a `\\[universal-argument]' prefix, prompts for a file to link to.  The \
+file name can be
+selected using completion.  The path to the file will be relative to the
 current directory if the file is in the current directory or a subdirectory.
 Otherwise, the link will be the absolute path as completed in the minibuffer
 \(i.e. normally ~/path/to/file).  You can configure this behavior using the
 option `org-link-file-path-type'.
 
-With two \\[universal-argument] prefixes, enforce an absolute path even if the file is in
+With a `\\[universal-argument] \\[universal-argument]' prefix, enforce an \
+absolute path even if the file is in
 the current directory or below.
 
-With three \\[universal-argument] prefixes, negate the meaning of
-`org-keep-stored-link-after-insertion'.
+A `\\[universal-argument] \\[universal-argument] \\[universal-argument]' \
+prefix negates `org-keep-stored-link-after-insertion'.
 
 If `org-make-link-description-function' is non-nil, this function will be
 called with the link target, and the result will be the default
 link description.
 
-If the LINK-LOCATION parameter is non-nil, this value will be
-used as the link location instead of reading one interactively.
+If the LINK-LOCATION parameter is non-nil, this value will be used as
+the link location instead of reading one interactively.
 
-If the DEFAULT-DESCRIPTION parameter is non-nil, this value will
-be used as the default description."
+If the DEFAULT-DESCRIPTION parameter is non-nil, this value will be used
+as the default description."
   (interactive "P")
   (let* ((wcf (current-window-configuration))
 	 (origbuf (current-buffer))
@@ -11302,7 +11331,8 @@ to read."
 	       (or buffer (current-buffer)))
   (message "%s"
 	   (substitute-command-keys
-	    "Position saved to mark ring, go back with \\[org-mark-ring-goto].")))
+	    "Position saved to mark ring, go back with \
+`\\[org-mark-ring-goto]'.")))
 
 (defun org-mark-ring-goto (&optional n)
   "Jump to the previous position in the mark ring.
@@ -11880,6 +11910,7 @@ the *old* location.")
 
 (defun org-refile (&optional arg default-buffer rfloc msg)
   "Move the entry or entries at point to another heading.
+
 The list of target headings is compiled using the information in
 `org-refile-targets', which see.
 
@@ -11891,10 +11922,12 @@ If there is an active region, all entries in that region will be
 refiled.  However, the region must fulfill the requirement that
 the first heading sets the top-level of the moved text.
 
-With prefix arg ARG, the command will only visit the target
-location and not actually move anything.
+With a `\\[universal-argument]' ARG, the command will only visit the target \
+location
+and not actually move anything.
 
-With a double prefix arg \\[universal-argument] \\[universal-argument], go to the location where the last
+With a prefix `\\[universal-argument] \\[universal-argument]', go to the \
+location where the last
 refiling operation has put the subtree.
 
 With a numeric prefix argument of `2', refile to the running clock.
@@ -11913,7 +11946,7 @@ See also `org-refile-use-outline-path'.
 
 If you are using target caching (see `org-refile-use-cache'), you
 have to clear the target cache in order to find new targets.
-This can be done with a 0 prefix (`C-0 C-c C-w') or a triple
+This can be done with a `0' prefix (`C-0 C-c C-w') or a triple
 prefix argument (`C-u C-u C-u C-c C-w')."
   (interactive "P")
   (if (member arg '(0 (64)))
@@ -12513,34 +12546,37 @@ nil or a string to be used for the todo mark." )
 (defvar org-state) ;; dynamically scoped into this function
 (defun org-todo (&optional arg)
   "Change the TODO state of an item.
+
 The state of an item is given by a keyword at the start of the heading,
 like
      *** TODO Write paper
      *** DONE Call mom
 
 The different keywords are specified in the variable `org-todo-keywords'.
-By default the available states are \"TODO\" and \"DONE\".
-So for this example: when the item starts with TODO, it is changed to DONE.
+By default the available states are \"TODO\" and \"DONE\".  So, for this
+example: when the item starts with TODO, it is changed to DONE.
 When it starts with DONE, the DONE is removed.  And when neither TODO nor
 DONE are present, add TODO at the beginning of the heading.
 
-With \\[universal-argument] prefix arg, use completion to determine the new \
+With `\\[universal-argument]' prefix ARG, use completion to determine the new \
 state.
-With numeric prefix arg, switch to that state.
-With a double \\[universal-argument] prefix, switch to the next set of TODO \
+With numeric prefix ARG, switch to that state.
+With a `\\[universal-argument] \\[universal-argument]' prefix, switch to the \
+next set of TODO \
 keywords (nextset).
-With a triple \\[universal-argument] prefix, circumvent any state blocking.
+With a `\\[universal-argument] \\[universal-argument] \\[universal-argument]' \
+prefix, circumvent any state blocking.
 With a numeric prefix arg of 0, inhibit note taking for the change.
 With a numeric prefix arg of -1, cancel repeater to allow marking as DONE.
 
 When called through ELisp, arg is also interpreted in the following way:
-`none'             -> empty state
-\"\"(empty string)  -> switch to empty state
-`done'             -> switch to DONE
-`nextset'          -> switch to the next set of keywords
-`previousset'      -> switch to the previous set of keywords
-\"WAITING\"         -> switch to the specified keyword, but only if it
-                     really is a member of `org-todo-keywords'."
+`none'        -> empty state
+\"\"            -> switch to empty state
+`done'        -> switch to DONE
+`nextset'     -> switch to the next set of keywords
+`previousset' -> switch to the previous set of keywords
+\"WAITING\"     -> switch to the specified keyword, but only if it
+                 really is a member of `org-todo-keywords'."
   (interactive "P")
   (if (and (org-region-active-p) org-loop-over-headlines-in-active-region)
       (let ((cl (if (eq org-loop-over-headlines-in-active-region 'start-level)
@@ -13338,7 +13374,7 @@ enough to shift date past today.  Continue? "
   "Make a compact tree which shows all headlines marked with TODO.
 The tree will show the lines where the regexp matches, and all higher
 headlines above the match.
-With a \\[universal-argument] prefix, prompt for a regexp to match.
+With a `\\[universal-argument]' prefix, prompt for a regexp to match.
 With a numeric prefix N, construct a sparse tree for the Nth element
 of `org-todo-keywords-1'."
   (interactive "P")
@@ -14086,9 +14122,8 @@ With optional argument SIBLINGS, on each level of the hierarchy all
 siblings are shown.  This repairs the tree structure to what it would
 look like when opened with hierarchical calls to `org-cycle'.
 
-With double optional argument \\[universal-argument] \\[universal-argument], \
-go to the parent and show the
-entire tree."
+With a \\[universal-argument] \\[universal-argument] prefix, \
+go to the parent and show the entire tree."
   (interactive "P")
   (run-hooks 'org-reveal-start-hook)
   (cond ((equal siblings '(4)) (org-show-set-visibility 'canonical))
@@ -17517,8 +17552,9 @@ This is used by `org-read-date' in a temporary keymap for the calendar buffer."
   "Check if there are any deadlines due or past due.
 A deadline is considered due if it happens within `org-deadline-warning-days'
 days from today's date.  If the deadline appears in an entry marked DONE,
-it is not shown.  The prefix arg NDAYS can be used to test that many
-days.  If the prefix is a raw \\[universal-argument] prefix, all deadlines are shown."
+it is not shown.  A numeric prefix argument NDAYS can be used to test that
+many days.  If the prefix is a raw `\\[universal-argument]', all deadlines \
+are shown."
   (interactive "P")
   (let* ((org-warn-days
 	  (cond
@@ -18517,9 +18553,9 @@ changes from another.  I believe the procedure must be like this:
 (defun org-switchb (&optional arg)
   "Switch between Org buffers.
 
-With \\[universal-argument] prefix, restrict available buffers to files.
+With `\\[universal-argument]' prefix, restrict available buffers to files.
 
-With \\[universal-argument] \\[universal-argument] \
+With `\\[universal-argument] \\[universal-argument]' \
 prefix, restrict available buffers to agenda files."
   (interactive "P")
   (let ((blist (org-buffer-list
@@ -18874,9 +18910,9 @@ in Org mode.
     (defadvice texmathp (around org-math-always-on activate)
       "Always return t in Org buffers.
 This is because we want to insert math symbols without dollars even outside
-the LaTeX math segments.  If Orgmode thinks that point is actually inside
-an embedded LaTeX fragment, let texmathp do its job.
-\\[org-cdlatex-mode-map]"
+the LaTeX math segments.  If Org mode thinks that point is actually inside
+an embedded LaTeX fragment, let `texmathp' do its job.
+`\\[org-cdlatex-mode-map]'"
       (interactive)
       (let (p)
 	(cond
@@ -19084,8 +19120,8 @@ current section.
 
 With prefix ARG, preview or clear image for all fragments in the
 current subtree or in the whole buffer when used before the first
-headline.  With a double prefix ARG \\[universal-argument] \
-\\[universal-argument] preview or clear images
+headline.  With a prefix ARG `\\[universal-argument] \
+\\[universal-argument]' preview or clear images
 for all fragments in the buffer."
   (interactive "P")
   (when (display-graphic-p)
@@ -21203,7 +21239,7 @@ This command does many different things, depending on context:
 	   ;; cell, maybe recalculate line but always align table.
 	   (if (eq (org-element-property :type context) 'table.el)
 	       (message "%s" (substitute-command-keys "\\<org-mode-map>\
-Use \\[org-edit-special] to edit table.el tables"))
+Use `\\[org-edit-special]' to edit table.el tables"))
 	     (let ((org-enable-table-editor t))
 	       (if (or (eq type 'table)
 		       ;; Check if point is at a TBLFM line.
@@ -21398,7 +21434,7 @@ Calls `org-table-insert-hline', `org-toggle-item', or
   "Convert headings to normal text, or items or text to headings.
 If there is no active region, only convert the current line.
 
-With a \\[universal-argument] prefix, convert the whole list at
+With a `\\[universal-argument]' prefix, convert the whole list at
 point into heading.
 
 In a region:
@@ -22873,8 +22909,8 @@ Indentation is done according to the following rules:
   - Otherwise, indent like the first non-blank line above.
 
 The function doesn't indent an item as it could break the whole
-list structure.  Instead, use \\<org-mode-map>\\[org-shiftmetaleft] or \
-\\[org-shiftmetaright].
+list structure.  Instead, use \\<org-mode-map>`\\[org-shiftmetaleft]' or \
+`\\[org-shiftmetaright]'.
 
 Also align node properties according to `org-property-format'."
   (interactive)
@@ -23923,7 +23959,7 @@ on the value of the following variables.
     becomes the smaller one of the two *visible* surrounding headings.
 
 Any prefix to this command will cause `yank' to be called directly with
-no special treatment.  In particular, a simple \\[universal-argument] prefix \
+no special treatment.  In particular, a simple `\\[universal-argument]' prefix \
 will just
 plainly yank the text as it is.
 
@@ -24905,7 +24941,7 @@ If there is no description, use the link target."
 
 (defun org-speedbar-set-agenda-restriction ()
   "Restrict future agenda commands to the location at point in speedbar.
-To get rid of the restriction, use \\[org-agenda-remove-restriction-lock]."
+To get rid of the restriction, use `\\[org-agenda-remove-restriction-lock]'."
   (interactive)
   (require 'org-agenda)
   (let (p m tp np dir txt)

+ 1 - 1
lisp/ox-html.el

@@ -895,7 +895,7 @@ a style file to define the look of these classes.
 To get a start for your css file, start Emacs session and make sure that
 all the faces you are interested in are defined, for example by loading files
 in all modes you want.  Then, use the command
-\\[org-html-htmlize-generate-css] to extract class definitions."
+`\\[org-html-htmlize-generate-css]' to extract class definitions."
   :group 'org-export-html
   :type '(choice (const css) (const inline-css) (const nil)))
 

+ 1 - 1
lisp/ox-icalendar.el

@@ -46,7 +46,7 @@
 
 (defcustom org-icalendar-combined-agenda-file "~/org.ics"
   "The file name for the iCalendar file covering all agenda files.
-This file is created with the command \\[org-icalendar-combine-agenda-files].
+This file is created with the command `\\[org-icalendar-combine-agenda-files]'.
 The file name should be absolute.  It will be overwritten without warning."
   :group 'org-export-icalendar
   :type 'file)

+ 4 - 3
lisp/ox-publish.el

@@ -67,9 +67,10 @@ produced.")
 
 (defcustom org-publish-project-alist nil
   "Association list to control publishing behavior.
-Each element of the alist is a publishing project.  The CAR of
+\\<org-mode-map>
+Each element of the alist is a publishing project.  The car of
 each element is a string, uniquely identifying the project.  The
-CDR of each element is in one of the following forms:
+cdr of each element is in one of the following forms:
 
 1. A well-formed property list with an even number of elements,
    alternating keys and values, specifying parameters for the
@@ -86,7 +87,7 @@ When the CDR of an element of org-publish-project-alist is in
 this second form, the elements of the list after `:components'
 are taken to be components of the project, which group together
 files requiring different publishing options.  When you publish
-such a project with \\[org-publish], the components all publish.
+such a project with `\\[org-publish]', the components all publish.
 
 When a property is given a value in `org-publish-project-alist',
 its setting overrides the value of the corresponding user

+ 11 - 9
lisp/ox.el

@@ -922,7 +922,7 @@ these cases."
 (defcustom org-export-in-background nil
   "Non-nil means export and publishing commands will run in background.
 Results from an asynchronous export are never displayed
-automatically.  But you can retrieve them with \\[org-export-stack]."
+automatically.  But you can retrieve them with `\\[org-export-stack]'."
   :group 'org-export-general
   :version "24.4"
   :package-version '(Org . "8.0")
@@ -6168,13 +6168,13 @@ within Emacs."
 (define-derived-mode org-export-stack-mode tabulated-list-mode "Org-Stack"
   "Mode for displaying asynchronous export stack.
 
-Type \\[org-export-stack] to visualize the asynchronous export
+Type `\\[org-export-stack]' to visualize the asynchronous export
 stack.
 
 In an Org Export Stack buffer, use \
-\\<org-export-stack-mode-map>\\[org-export-stack-view] to view export output
-on current line, \\[org-export-stack-remove] to remove it from the stack and \
-\\[org-export-stack-clear] to clear
+\\<org-export-stack-mode-map>`\\[org-export-stack-view]' to view export output
+on current line, `\\[org-export-stack-remove]' to remove it from the stack and \
+`\\[org-export-stack-clear]' to clear
 stack completely.
 
 Removing entries in a stack buffer does not affect files
@@ -6242,7 +6242,7 @@ appropriate for `tabulated-list-print'."
 	  ;; SOURCE is not consistent with current line.  The stack
 	  ;; view is outdated.
 	  (error (substitute-command-keys
-		  "Source unavailable; type \\[org-export-stack-refresh] \
+		  "Source unavailable; type `\\[org-export-stack-refresh]' \
 to refresh buffer")))))))
 
 
@@ -6269,10 +6269,12 @@ SPC and DEL (resp. C-n and C-p) keys.
 Set variable `org-export-dispatch-use-expert-ui' to switch to one
 flavor or the other.
 
-When ARG is \\[universal-argument], repeat the last export action, with the same set
-of options used back then, on the current buffer.
+When ARG is `\\[universal-argument]', repeat the last export action, with the\
+ same
+set of options used back then, on the current buffer.
 
-When ARG is \\[universal-argument] \\[universal-argument], display the asynchronous export stack."
+When ARG is `\\[universal-argument] \\[universal-argument]', display the \
+asynchronous export stack."
   (interactive "P")
   (let* ((input
 	  (cond ((equal arg '(16)) '(stack))