diff --git a/lisp/org-list.el b/lisp/org-list.el index b0bdc9c7d..c121c064d 100644 --- a/lisp/org-list.el +++ b/lisp/org-list.el @@ -29,9 +29,9 @@ ;; This file contains the code dealing with plain lists in Org-mode. -;; The fundamental idea behind lists work is to use structures. A -;; structure is a snapshot of the list, in the shape of data tree (see -;; `org-list-struct'). +;; The fundamental idea behind lists work is to use structures. +;; A structure is a snapshot of the list, in the shape of data tree +;; (see `org-list-struct'). ;; Once the list structure is stored, it is possible to make changes ;; directly on it or get useful information about the list, with the @@ -39,8 +39,8 @@ ;; `org-list-prevs-alist', and using accessors or methods. ;; Structure is eventually applied to the buffer with -;; `org-list-write-struct'. This function repairs (bullets, -;; indentation, checkboxes) the structure before applying it. It +;; `org-list-write-struct'. This function repairs (bullets, +;; indentation, checkboxes) the structure before applying it. It ;; should be called near the end of any function working on ;; structures. @@ -48,8 +48,8 @@ ;; template: ;; 1. Verify point is in a list and grab item beginning (with the same -;; function `org-in-item-p'). If the function requires the cursor -;; to be at item's bullet, `org-at-item-p' is more selective. If +;; function `org-in-item-p'). If the function requires the cursor +;; to be at item's bullet, `org-at-item-p' is more selective. If ;; the cursor is amidst the buffer, it is possible to find the ;; closest item with `org-list-search-backward', or ;; `org-list-search-forward', applied to `org-item-beginning-re'. @@ -63,13 +63,13 @@ ;; 4. Proceed with the modifications, using methods and accessors. ;; 5. Verify and apply structure to buffer, using -;; `org-list-write-struct'. Possibly use +;; `org-list-write-struct'. Possibly use ;; `org-update-checkbox-count-maybe' if checkboxes might have been ;; modified. ;; Computing a list structure can be a costly operation on huge lists -;; (a few thousand lines long). Thus, code should follow the rule : -;; "collect once, use many". As a corollary, it is usally a bad idea +;; (a few thousand lines long). Thus, code should follow the rule : +;; "collect once, use many". As a corollary, it is usally a bad idea ;; to use directly an interactive function inside the code, as those, ;; being independant entities, read the whole list structure another ;; time. @@ -214,18 +214,18 @@ the safe choice." (defcustom org-alphabetical-lists nil "Non-nil means single character alphabetical bullets are allowed. -Both uppercase and lowercase are handled. Lists with more than 26 -items will fallback to standard numbering. Alphabetical counters -like \"[@c]\" will be recognized." +Both uppercase and lowercase are handled. Lists with more than +26 items will fallback to standard numbering. Alphabetical +counters like \"[@c]\" will be recognized." :group 'org-plain-lists :type 'boolean) (defcustom org-list-two-spaces-after-bullet-regexp nil "A regular expression matching bullets that should have 2 spaces after them. -When nil, no bullet will have two spaces after them. -When a string, it will be used as a regular expression. When the +When nil, no bullet will have two spaces after them. When +a string, it will be used as a regular expression. When the bullet type of a list is changed, the new bullet type will be -matched against this regexp. If it matches, there will be two +matched against this regexp. If it matches, there will be two spaces instead of one after the bullet in each item of the list." :group 'org-plain-lists :type '(choice @@ -245,7 +245,7 @@ an item, but not starting one, is less or equally indented than the first item of the list. When set to `both', each of the preceding methods is applied to -determine lists endings. This is the default method." +determine lists endings. This is the default method." :group 'org-plain-lists :type '(choice (const :tag "With a regexp defining ending" regexp) @@ -255,7 +255,7 @@ determine lists endings. This is the default method." (defcustom org-empty-line-terminates-plain-lists nil "Non-nil means an empty line ends all plain list levels. This variable only makes sense if `org-list-ending-method' is set -to `regexp' or `both'. This is then equivalent to set +to `regexp' or `both'. This is then equivalent to set `org-list-end-regexp' to \"^[ \\t]*$\"." :group 'org-plain-lists :type 'boolean) @@ -277,7 +277,7 @@ By default, automatic actions are taken when using \\[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: + rules by setting them to nil. Valid rules are: bullet when non-nil, cycling bullet do not allow lists at column 0 to have * as a bullet and descriptions lists @@ -356,7 +356,7 @@ Names must be in lower case.") (defvar org-list-export-context '(block inlinetask) "Context types where lists will be interpreted during export. -Valid types are `drawer', `inlinetask' and `block'. More +Valid types are `drawer', `inlinetask' and `block'. More specifically, type `block' is determined by the variable `org-list-forbidden-blocks'.") @@ -444,9 +444,9 @@ This checks `org-list-ending-method'." ((eq (nth 2 context) 'invalid) nil) ((looking-at item-re) (point)) (t - ;; Detect if cursor in amidst `org-list-end-re'. First, count + ;; Detect if cursor in amidst `org-list-end-re'. First, count ;; number HL of hard lines it takes, then call `org-in-regexp' - ;; to compute its boundaries END-BOUNDS. When point is + ;; to compute its boundaries END-BOUNDS. When point is ;; in-between, move cursor before regexp beginning. (let ((hl 0) (i -1) end-bounds) (when (and (not (eq org-list-ending-method 'indent)) @@ -542,7 +542,7 @@ Contexts `block' and `invalid' refer to `org-list-forbidden-blocks'." (org-with-limited-levels (beginning-of-line) (let ((case-fold-search t) (pos (point)) beg end context-type - ;; Get positions of surrounding headings. This is the + ;; Get positions of surrounding headings. This is the ;; default context. (lim-up (or (save-excursion (and (ignore-errors (org-back-to-heading t)) (point))) @@ -550,8 +550,8 @@ Contexts `block' and `invalid' refer to `org-list-forbidden-blocks'." (lim-down (or (save-excursion (outline-next-heading)) (point-max)))) ;; Is point inside a drawer? (let ((end-re "^[ \t]*:END:") - ;; Can't use org-drawers-regexp as this function - ;; might be called in buffers not in Org mode + ;; Can't use org-drawers-regexp as this function might + ;; be called in buffers not in Org mode. (beg-re (concat "^[ \t]*:\\(" (mapconcat 'regexp-quote org-drawers "\\|") "\\):[ \t]*$"))) @@ -663,7 +663,7 @@ Assume point is at an item." (skip-chars-backward " \r\t\n") (min (1+ (point-at-eol)) lim-down))))) ;; 1. Read list from starting item to its beginning, and save - ;; top item position and indentation in BEG-CELL. Also store + ;; top item position and indentation in BEG-CELL. Also store ;; ending position of items in END-LST. (save-excursion (catch 'exit @@ -682,24 +682,24 @@ Assume point is at an item." (memq (assq (car beg-cell) itm-lst) itm-lst) (setq beg-cell (cons (point) ind)) (cons (funcall assoc-at-point ind) itm-lst))))) - ;; At a verbatim block, go before its beginning. Move + ;; At a verbatim block, go before its beginning. Move ;; from eol to ensure `previous-single-property-change' ;; will return a value. ((get-text-property (point) 'org-example) (goto-char (previous-single-property-change (point-at-eol) 'org-example nil lim-up)) (forward-line -1)) - ;; Looking at a list ending regexp. Dismiss useless - ;; data recorded above BEG-CELL. Jump to part 2. + ;; Looking at a list ending regexp. Dismiss useless + ;; data recorded above BEG-CELL. Jump to part 2. ((and (not (eq org-list-ending-method 'indent)) (looking-at org-list-end-re)) (throw 'exit (setq itm-lst (memq (assq (car beg-cell) itm-lst) itm-lst)))) - ;; Point is at an item. Add data to ITM-LST. It may - ;; also end a previous item: save it in END-LST. If ind - ;; is less or equal than BEG-CELL and there is no end - ;; at this ind or lesser, this item becomes the new + ;; Point is at an item. Add data to ITM-LST. It may + ;; also end a previous item: save it in END-LST. If + ;; ind is less or equal than BEG-CELL and there is no + ;; end at this ind or lesser, this item becomes the new ;; BEG-CELL. ((looking-at item-re) (push (funcall assoc-at-point ind) itm-lst) @@ -720,13 +720,13 @@ Assume point is at an item." (forward-line -1)) ((looking-at "^[ \t]*$") (forward-line -1)) - ;; From there, point is not at an item. Unless ending + ;; From there, point is not at an item. Unless ending ;; method is `regexp', interpret line's indentation: ;; - text at column 0 is necessarily out of any list. - ;; Dismiss data recorded above BEG-CELL. Jump to + ;; Dismiss data recorded above BEG-CELL. Jump to ;; part 2. ;; - any other case may be an ending position for an - ;; hypothetical item above. Store it and proceed. + ;; hypothetical item above. Store it and proceed. ((eq org-list-ending-method 'regexp) (forward-line -1)) ((zerop ind) (throw 'exit @@ -738,7 +738,7 @@ Assume point is at an item." (forward-line -1))))))) ;; 2. Read list from starting point to its end, that is until we ;; get out of context, or that a non-item line is less or - ;; equally indented than BEG-CELL's cdr. Also, store ending + ;; equally indented than BEG-CELL's cdr. Also, store ending ;; position of items in END-LST-2. (catch 'exit (while t @@ -747,24 +747,24 @@ Assume point is at an item." (cond ((>= (point) lim-down) ;; At downward limit: this is de facto the end of the - ;; list. Save point as an ending position, and jump to + ;; list. Save point as an ending position, and jump to ;; part 3. (throw 'exit (push (cons 0 (funcall end-before-blank)) end-lst-2))) - ;; At a verbatim block, move to its end. Point is at bol + ;; At a verbatim block, move to its end. Point is at bol ;; and 'org-example property is set by whole lines: ;; `next-single-property-change' always return a value. ((get-text-property (point) 'org-example) (goto-char (next-single-property-change (point) 'org-example nil lim-down))) - ;; Looking at a list ending regexp. Save point as an + ;; Looking at a list ending regexp. Save point as an ;; ending position and jump to part 3. ((and (not (eq org-list-ending-method 'indent)) (looking-at org-list-end-re)) (throw 'exit (push (cons 0 (point)) end-lst-2))) ((looking-at item-re) - ;; Point is at an item. Add data to ITM-LST-2. It may also - ;; end a previous item, so save it in END-LST-2. + ;; Point is at an item. Add data to ITM-LST-2. It may + ;; also end a previous item, so save it in END-LST-2. (push (funcall assoc-at-point ind) itm-lst-2) (push (cons ind (point)) end-lst-2) (forward-line 1)) @@ -773,7 +773,7 @@ Assume point is at an item." (org-inlinetask-goto-end)) ((looking-at "^[ \t]*$") (forward-line 1)) - ;; Ind is lesser or equal than BEG-CELL's. The list is + ;; Ind is lesser or equal than BEG-CELL's. The list is ;; over: store point as an ending position and jump to ;; part 3. ((and (not (eq org-list-ending-method 'regexp)) @@ -781,7 +781,7 @@ Assume point is at an item." (throw 'exit (push (cons 0 (funcall end-before-blank)) end-lst-2))) ;; Else, if ind is lesser or equal than previous item's, - ;; this is an ending position: store it. In any case, + ;; this is an ending position: store it. In any case, ;; skip block or drawer at point, and move to next line. (t (when (and (not (eq org-list-ending-method 'regexp)) @@ -824,10 +824,10 @@ This function modifies STRUCT." (lambda (elt) (let ((pos (car elt)) (ind (nth 1 elt))) - ;; Remove end candidates behind current item + ;; Remove end candidates behind current item. (while (or (<= (cdar endings) pos)) (pop endings)) - ;; Add end position to item assoc + ;; Add end position to item assoc. (let ((old-end (nthcdr 6 elt)) (new-end (assoc-default ind endings '<=))) (if old-end @@ -927,8 +927,8 @@ Point returned is at end of line." (defun org-list-get-parent (item struct parents) "Return parent of ITEM or nil. -STRUCT is the list structure. PARENTS is the alist of parents, as -returned by `org-list-parents-alist'." +STRUCT is the list structure. PARENTS is the alist of parents, +as returned by `org-list-parents-alist'." (let ((parents (or parents (org-list-parents-alist struct)))) (cdr (assq item parents)))) @@ -946,13 +946,13 @@ Value returned is the position of the first child of ITEM." (defun org-list-get-next-item (item struct prevs) "Return next item in same sub-list as ITEM, or nil. -STRUCT is the list structure. PREVS is the alist of previous +STRUCT is the list structure. PREVS is the alist of previous items, as returned by `org-list-prevs-alist'." (car (rassq item prevs))) (defun org-list-get-prev-item (item struct prevs) "Return previous item in same sub-list as ITEM, or nil. -STRUCT is the list structure. PREVS is the alist of previous +STRUCT is the list structure. PREVS is the alist of previous items, as returned by `org-list-prevs-alist'." (cdr (assq item prevs))) @@ -971,7 +971,7 @@ STRUCT is the list structure." (defun org-list-get-all-items (item struct prevs) "List all items in the same sub-list as ITEM. -STRUCT is the list structure. PREVS is the alist of previous +STRUCT is the list structure. PREVS is the alist of previous items, as returned by `org-list-prevs-alist'." (let ((prev-item item) (next-item item) @@ -1005,7 +1005,7 @@ STRUCT is the list structure." (defun org-list-get-list-begin (item struct prevs) "Return point at beginning of sub-list ITEM belongs. -STRUCT is the list structure. PREVS is the alist of previous +STRUCT is the list structure. PREVS is the alist of previous items, as returned by `org-list-prevs-alist'." (let ((first-item item) prev-item) (while (setq prev-item (org-list-get-prev-item first-item struct prevs)) @@ -1016,7 +1016,7 @@ items, as returned by `org-list-prevs-alist'." (defun org-list-get-last-item (item struct prevs) "Return point at last item of sub-list ITEM belongs. -STRUCT is the list structure. PREVS is the alist of previous +STRUCT is the list structure. PREVS is the alist of previous items, as returned by `org-list-prevs-alist'." (let ((last-item item) next-item) (while (setq next-item (org-list-get-next-item last-item struct prevs)) @@ -1025,17 +1025,17 @@ items, as returned by `org-list-prevs-alist'." (defun org-list-get-list-end (item struct prevs) "Return point at end of sub-list ITEM belongs. -STRUCT is the list structure. PREVS is the alist of previous +STRUCT is the list structure. PREVS is the alist of previous items, as returned by `org-list-prevs-alist'." (org-list-get-item-end (org-list-get-last-item item struct prevs) struct)) (defun org-list-get-list-type (item struct prevs) "Return the type of the list containing ITEM, as a symbol. -STRUCT is the list structure. PREVS is the alist of previous +STRUCT is the list structure. PREVS is the alist of previous items, as returned by `org-list-prevs-alist'. -Possible types are `descriptive', `ordered' and `unordered'. The +Possible types are `descriptive', `ordered' and `unordered'. The type is determined by the first item of the list." (let ((first (org-list-get-list-begin item struct prevs))) (cond @@ -1057,7 +1057,7 @@ in `re-search-forward'." (unless (funcall search re bound noerr) (throw 'exit (and (goto-char (if (memq noerr '(t nil)) origin bound)) nil))) - ;; 2. Match in valid context: return point. Else, continue + ;; 2. Match in valid context: return point. Else, continue ;; searching. (when (org-list-in-valid-context-p) (throw 'exit (point))))))) @@ -1096,10 +1096,10 @@ It determines the number of whitespaces to append by looking at POS is the position of point where `org-list-insert-item' was called. -STRUCT is the list structure. PREVS is the alist of previous +STRUCT is the list structure. PREVS is the alist of previous items, as returned by `org-list-prevs-alist'. -Assume point is at item's beginning. If the item is alone, apply +Assume point is at item's beginning. If the item is alone, apply some heuristics to guess the result." (save-excursion (let ((item (point)) @@ -1113,7 +1113,7 @@ some heuristics to guess the result." (not insert-blank-p)) 0) ;; When `org-blank-before-new-entry' says so, it is 1. ((eq insert-blank-p t) 1) - ;; plain-list-item is 'auto. Count blank lines separating + ;; `plain-list-item' is 'auto. Count blank lines separating ;; neighbours items in list. (t (let ((next-p (org-list-get-next-item item struct prevs))) (cond @@ -1123,14 +1123,14 @@ some heuristics to guess the result." ;; Is there a previous item? ((org-list-get-prev-item item struct prevs) (org-back-over-empty-lines)) - ;; User inserted blank lines, trust him + ;; User inserted blank lines, trust him. ((and (> pos (org-list-get-item-end-before-blank item struct)) (> (save-excursion (goto-char pos) (skip-chars-backward " \t") (setq usr-blank (org-back-over-empty-lines))) 0)) usr-blank) - ;; Are there blank lines inside the item ? + ;; Are there blank lines inside the item? ((save-excursion (org-list-search-forward "^[ \t]*$" (org-list-get-item-end-before-blank item struct) t)) @@ -1143,11 +1143,11 @@ some heuristics to guess the result." If POS is before first character after bullet of the item, the new item will be created before the current one. -STRUCT is the list structure. PREVS is the the alist of previous +STRUCT is the list structure. PREVS is the the alist of previous items, as returned by `org-list-prevs-alist'. Insert a checkbox if CHECKBOX is non-nil, and string AFTER-BULLET -after the bullet. Cursor will be after this text once the +after the bullet. Cursor will be after this text once the function ends. This function modifies STRUCT." @@ -1164,11 +1164,11 @@ This function modifies STRUCT." (split-line-p (org-get-alist-option org-M-RET-may-split-line 'item)) (blank-nb (org-list-separating-blank-lines-number pos struct prevs)) - ;; 2. Build the new item to be created. Concatenate same + ;; 2. Build the new item to be created. Concatenate same ;; bullet as item, checkbox, text AFTER-BULLET if ;; provided, and text cut from point to end of item - ;; (TEXT-CUT) to form item's BODY. TEXT-CUT depends on - ;; BEFOREP and SPLIT-LINE-P. The difference of size + ;; (TEXT-CUT) to form item's BODY. TEXT-CUT depends on + ;; BEFOREP and SPLIT-LINE-P. The difference of size ;; between what was cut and what was inserted in buffer ;; is stored in SIZE-OFFSET. (ind (org-list-get-ind item struct)) @@ -1193,7 +1193,7 @@ This function modifies STRUCT." (item-sep (make-string (1+ blank-nb) ?\n)) (item-size (+ ind-size (length body) (length item-sep))) (size-offset (- item-size (length text-cut)))) - ;; 4. Insert effectively item into buffer + ;; 4. Insert effectively item into buffer. (goto-char item) (org-indent-to-column ind) (insert body item-sep) @@ -1208,13 +1208,13 @@ This function modifies STRUCT." ((< p item) (when (> end item) (setcar (nthcdr 6 e) (+ end size-offset)))) ;; Trivial cases where current item isn't split in - ;; two. Just shift every item after new one by + ;; two. Just shift every item after new one by ;; ITEM-SIZE. ((or beforep (not split-line-p)) (setcar e (+ p item-size)) (setcar (nthcdr 6 e) (+ end item-size))) ;; Item is split in two: elements before POS are just - ;; shifted by ITEM-SIZE. In the case item would end + ;; shifted by ITEM-SIZE. In the case item would end ;; after split POS, ending is only shifted by ;; SIZE-OFFSET. ((< p pos) @@ -1222,8 +1222,8 @@ This function modifies STRUCT." (if (< end pos) (setcar (nthcdr 6 e) (+ end item-size)) (setcar (nthcdr 6 e) (+ end size-offset)))) - ;; Elements after POS are moved into new item. Length - ;; of ITEM-SEP has to be removed as ITEM-SEP + ;; Elements after POS are moved into new item. + ;; Length of ITEM-SEP has to be removed as ITEM-SEP ;; doesn't appear in buffer yet. ((< p item-end) (setcar e (+ p size-offset (- item pos (length item-sep)))) @@ -1240,7 +1240,7 @@ This function modifies STRUCT." (push (list item ind bullet nil box nil (+ item item-size)) struct) (setq struct (sort struct (lambda (e1 e2) (< (car e1) (car e2))))) ;; 6. If not BEFOREP, new item must appear after ITEM, so - ;; exchange ITEM with the next item in list. Position cursor + ;; exchange ITEM with the next item in list. Position cursor ;; after bullet, counter, checkbox, and label. (if beforep (goto-char item) @@ -1251,8 +1251,8 @@ This function modifies STRUCT." (defun org-list-exchange-items (beg-A beg-B struct) "Swap item starting at BEG-A with item starting at BEG-B in STRUCT. -Blank lines at the end of items are left in place. Return the new -structure after the changes. +Blank lines at the end of items are left in place. Return the +new structure after the changes. Assume BEG-A is lesser than BEG-B and that BEG-A and BEG-B belong to the same sub-list. @@ -1274,12 +1274,12 @@ This function modifies STRUCT." (goto-char beg-A) (delete-region beg-A end-B-no-blank) (insert (concat body-B between-A-no-blank-and-B body-A)) - ;; 2. Now modify struct. No need to re-read the list, the - ;; transformation is just a shift of positions. Some special + ;; 2. Now modify struct. No need to re-read the list, the + ;; transformation is just a shift of positions. Some special ;; attention is required for items ending at END-A and END-B - ;; as empty spaces are not moved there. In others words, item - ;; BEG-A will end with whitespaces that were at the end of - ;; BEG-B and the same applies to BEG-B. + ;; as empty spaces are not moved there. In others words, + ;; item BEG-A will end with whitespaces that were at the end + ;; of BEG-B and the same applies to BEG-B. (mapc (lambda (e) (let ((pos (car e))) (cond @@ -1307,7 +1307,7 @@ This function modifies STRUCT." (defun org-list-struct-outdent (start end struct parents) "Outdent items between positions START and END. -STRUCT is the list structure. PARENTS is the alist of items' +STRUCT is the list structure. PARENTS is the alist of items' parents, as returned by `org-list-parents-alist'. START is included, END excluded." @@ -1316,20 +1316,20 @@ START is included, END excluded." (let* ((item (car cell)) (parent (cdr cell))) (cond - ;; Item not yet in zone: keep association + ;; Item not yet in zone: keep association. ((< item start) cell) - ;; Item out of zone: follow associations in acc + ;; Item out of zone: follow associations in ACC. ((>= item end) (let ((convert (and parent (assq parent acc)))) (if convert (cons item (cdr convert)) cell))) ;; Item has no parent: error ((not parent) (error "Cannot outdent top-level items")) - ;; Parent is outdented: keep association + ;; Parent is outdented: keep association. ((>= parent start) (push (cons parent item) acc) cell) (t - ;; Parent isn't outdented: reparent to grand-parent + ;; Parent isn't outdented: reparent to grand-parent. (let ((grand-parent (org-list-get-parent parent struct parents))) (push (cons parent item) acc) @@ -1339,9 +1339,10 @@ START is included, END excluded." (defun org-list-struct-indent (start end struct parents prevs) "Indent items between positions START and END. -STRUCT is the list structure. PARENTS is the alist of parents and -PREVS is the alist of previous items, returned by, respectively, -`org-list-parents-alist' and `org-list-prevs-alist'. +STRUCT is the list structure. PARENTS is the alist of parents +and PREVS is the alist of previous items, returned by, +respectively, `org-list-parents-alist' and +`org-list-prevs-alist'. START is included and END excluded. @@ -1360,26 +1361,27 @@ bullets between START and END." (let* ((item (car cell)) (parent (cdr cell))) (cond - ;; Item not yet in zone: keep association + ;; Item not yet in zone: keep association. ((< item start) cell) ((>= item end) - ;; Item out of zone: follow associations in acc + ;; Item out of zone: follow associations in ACC. (let ((convert (assq parent acc))) (if convert (cons item (cdr convert)) cell))) (t ;; Item is in zone... (let ((prev (org-list-get-prev-item item struct prevs))) - ;; Check if bullet needs to be changed + ;; Check if bullet needs to be changed. (funcall change-bullet-maybe item) (cond ;; First item indented but not parent: error ((and (not prev) (< parent start)) (error "Cannot indent the first item of a list")) - ;; First item and parent indented: keep same parent + ;; First item and parent indented: keep same + ;; parent. ((not prev) (funcall set-assoc cell)) - ;; Previous item not indented: reparent to it + ;; Previous item not indented: reparent to it. ((< prev start) (funcall set-assoc (cons item prev))) - ;; Previous item indented: reparent like it + ;; Previous item indented: reparent like it. (t (funcall set-assoc (cons item (cdr (assq prev acc))))))))))))) @@ -1515,13 +1517,13 @@ This function modifies STRUCT." (lambda (item) (let ((parent (org-list-get-parent item struct parents))) (if parent - ;; Indent like parent + length of parent's bullet + ;; Indent like parent + length of parent's bullet. (org-list-set-ind item struct (+ (or bullet-size (length (org-list-get-bullet parent struct))) (org-list-get-ind parent struct))) - ;; If no parent, indent like top-point + ;; If no parent, indent like top-point. (org-list-set-ind item struct top-ind)))))) (mapc new-ind (mapcar 'car (cdr struct))))) @@ -1533,8 +1535,8 @@ previous items, as returned by, respectively, `org-list-parents-alist' and `org-list-prevs-alist'. If ORDERED is non-nil, a checkbox can only be checked when every -checkbox before it is checked too. If there was an attempt to -break this rule, the function will return the blocking item. In +checkbox before it is checked too. If there was an attempt to +break this rule, the function will return the blocking item. In all others cases, the return value will be nil. This function modifies STRUCT." @@ -1553,10 +1555,10 @@ This function modifies STRUCT." ((member "[-]" box-list) "[-]") ((member "[X]" box-list) "[X]") ((member "[ ]" box-list) "[ ]") - ;; parent has no boxed child: leave box as-is + ;; Parent has no boxed child: leave box as-is. (t (org-list-get-checkbox item struct)))))))) parent-list) - ;; 1. List all parents with a checkbox + ;; 1. List all parents with a checkbox. (mapc (lambda (e) (let* ((parent (org-list-get-parent e struct parents)) @@ -1564,34 +1566,34 @@ This function modifies STRUCT." (when (and parent-box-p (not (memq parent parent-list))) (push parent parent-list)))) all-items) - ;; 2. Sort those parents by decreasing indentation + ;; 2. Sort those parents by decreasing indentation. (setq parent-list (sort parent-list (lambda (e1 e2) (> (org-list-get-ind e1 struct) (org-list-get-ind e2 struct))))) ;; 3. For each parent, get all children's checkboxes to determine - ;; and set its checkbox accordingly + ;; and set its checkbox accordingly. (mapc set-parent-box parent-list) - ;; 4. If ORDERED is set, see if we need to uncheck some boxes + ;; 4. If ORDERED is set, see if we need to uncheck some boxes. (when ordered (let* ((box-list (mapcar (lambda (e) (org-list-get-checkbox e struct)) all-items)) (after-unchecked (member "[ ]" box-list))) - ;; there are boxes checked after an unchecked one: fix that + ;; There are boxes checked after an unchecked one: fix that. (when (member "[X]" after-unchecked) (let ((index (- (length struct) (length after-unchecked)))) (mapc (lambda (e) (org-list-set-checkbox e struct "[ ]")) (nthcdr index all-items)) - ;; Verify once again the structure, without ORDERED + ;; Verify once again the structure, without ORDERED. (org-list-struct-fix-box struct parents prevs nil) - ;; return blocking item + ;; Return blocking item. (nth index all-items))))))) (defun org-list-struct-apply-struct (struct old-struct) "Apply set-difference between STRUCT and OLD-STRUCT to the buffer. OLD-STRUCT is the structure before any modifications, and STRUCT -the structure to be applied. The function will only modify parts +the structure to be applied. The function will only modify parts of the list which have changed. Initial position of cursor is restored after the changes." @@ -1612,10 +1614,10 @@ Initial position of cursor is restored after the changes." (and (= (point) beg) (not (looking-at item-re)))) (cond - ;; Skip inline tasks + ;; Skip inline tasks. ((and inlinetask-re (looking-at inlinetask-re)) (org-inlinetask-goto-beginning)) - ;; Shift only non-empty lines + ;; Shift only non-empty lines. ((org-looking-at-p "^[ \t]*\\S-") (let ((i (org-get-indentation))) (org-indent-line-to (+ i delta))))) @@ -1636,7 +1638,7 @@ Initial position of cursor is restored after the changes." ;; a. Replace bullet (unless (equal old-bul new-bul) (replace-match new-bul nil nil nil 1)) - ;; b. Replace checkbox + ;; b. Replace checkbox. (cond ((and new-box box-rule-p (save-match-data (org-at-item-description-p))) @@ -1650,15 +1652,15 @@ Initial position of cursor is restored after the changes." (replace-match "")) (t (goto-char (or (match-end 2) (match-end 1))) (insert (concat new-box " ")))) - ;; c. Indent item to appropriate column + ;; c. Indent item to appropriate column. (unless (= new-ind old-ind) (delete-region (goto-char (point-at-bol)) (progn (skip-chars-forward " \t") (point))) (indent-to new-ind))))))) - ;; 1. First get list of items and position endings. We maintain + ;; 1. First get list of items and position endings. We maintain ;; two alists: ITM-SHIFT, determining indentation shift needed ;; at item, and END-POS, a pseudo-alist where key is ending - ;; position and value point + ;; position and value point. (let (end-list acc-end itm-shift all-ends sliced-struct) (mapc (lambda (e) (let* ((pos (car e)) @@ -1671,16 +1673,17 @@ Initial position of cursor is restored after the changes." (end-pos (org-list-get-item-end pos old-struct))) (push (cons pos ind-shift) itm-shift) (unless (assq end-pos old-struct) - ;; To determine real ind of an ending position that is - ;; not at an item, we have to find the item it belongs - ;; to: it is the last item (ITEM-UP), whose ending is - ;; further than the position we're interested in. + ;; To determine real ind of an ending position that + ;; is not at an item, we have to find the item it + ;; belongs to: it is the last item (ITEM-UP), whose + ;; ending is further than the position we're + ;; interested in. (let ((item-up (assoc-default end-pos acc-end '>))) (push (cons end-pos item-up) end-list))) (push (cons end-pos pos) acc-end))) old-struct) ;; 2. Slice the items into parts that should be shifted by the - ;; same amount of indentation. The slices are returned in + ;; same amount of indentation. The slices are returned in ;; reverse order so changes modifying buffer do not change ;; positions they refer to. (setq all-ends (sort (append (mapcar 'car itm-shift) @@ -1694,7 +1697,7 @@ Initial position of cursor is restored after the changes." (cdr (assq (cdr (assq up end-list)) itm-shift))))) (push (list down up ind) sliced-struct))) ;; 3. Shift each slice in buffer, provided delta isn't 0, from - ;; end to beginning. Take a special action when beginning is + ;; end to beginning. Take a special action when beginning is ;; at item bullet. (mapc (lambda (e) (unless (zerop (nth 2 e)) (apply shift-body-ind e)) @@ -1703,13 +1706,13 @@ Initial position of cursor is restored after the changes." (unless (or (not cell) (equal cell (assq beg old-struct))) (funcall modify-item beg)))) sliced-struct)) - ;; 4. Go back to initial position + ;; 4. Go back to initial position. (goto-char pos))) (defun org-list-write-struct (struct parents) "Correct bullets, checkboxes and indentation in list at point. -STRUCT is the list structure. PARENTS is the alist of parents, as -returned by `org-list-parents-alist'." +STRUCT is the list structure. PARENTS is the alist of parents, +as returned by `org-list-parents-alist'." ;; Order of functions matters here: checkboxes and endings need ;; correct indentation to be set, and indentation needs correct ;; bullets. @@ -1733,7 +1736,7 @@ returned by `org-list-parents-alist'." ;; further than the position we're interested in. (let ((item-up (assoc-default end-pos acc-end '>))) (push (cons - ;; Else part is for the bottom point + ;; Else part is for the bottom point. (if item-up (+ (org-list-get-ind item-up struct) 2) 0) end-pos) end-list))) @@ -1742,14 +1745,14 @@ returned by `org-list-parents-alist'." struct) (setq end-list (sort end-list (lambda (e1 e2) (< (cdr e1) (cdr e2))))) (org-list-struct-assoc-end struct end-list)) - ;; 3. Get bullets right + ;; 3. Get bullets right. (let ((prevs (org-list-prevs-alist struct))) (org-list-struct-fix-bul struct prevs) - ;; 4. Now get real indentation + ;; 4. Now get real indentation. (org-list-struct-fix-ind struct parents) - ;; 5. Eventually fix checkboxes + ;; 5. Eventually fix checkboxes. (org-list-struct-fix-box struct parents prevs)) - ;; 6. Apply structure modifications to buffer + ;; 6. Apply structure modifications to buffer. (org-list-struct-apply-struct struct old-struct))) @@ -1766,7 +1769,7 @@ FUNCTION is applied on items in reverse order. As an example, \(org-apply-on-list \(lambda \(result\) \(1+ result\)\) 0\) will return the number of items in the current list. -Sublists of the list are skipped. Cursor is always at the +Sublists of the list are skipped. Cursor is always at the beginning of the item." (let* ((struct (org-list-struct)) (prevs (org-list-prevs-alist struct)) @@ -2003,8 +2006,8 @@ This cycle the entire list level through the sequence: `-' -> `+' -> `*' -> `1.' -> `1)' -If WHICH is a valid string, use that as the new bullet. If WHICH -is an integer, 0 means `-', 1 means `+' etc. If WHICH is +If WHICH is a valid string, use that as the new bullet. If WHICH +is an integer, 0 means `-', 1 means `+' etc. If WHICH is `previous', cycle backwards." (interactive "P") (unless (org-at-item-p) (error "Not at an item")) @@ -2026,13 +2029,13 @@ is an integer, 0 means `-', 1 means `+' etc. If WHICH is ((string-match "\\." bullet) "1.") ((string-match ")" bullet) "1)") (t (org-trim bullet)))) - ;; Compute list of possible bullets, depending on context + ;; Compute list of possible bullets, depending on context. (bullet-list (append '("-" "+" ) - ;; *-bullets are not allowed at column 0 + ;; *-bullets are not allowed at column 0. (unless (and bullet-rule-p (looking-at "\\S-")) '("*")) - ;; Description items cannot be numbered + ;; Description items cannot be numbered. (unless (or (eq org-plain-list-ordered-item-terminator ?\)) (and bullet-rule-p (org-at-item-description-p))) '("1.")) @@ -2091,7 +2094,7 @@ in subtree, ignoring drawers." " *[[<]\\([^]>]+\\)[]>]")) (orderedp (org-entry-get nil "ORDERED")) (bounds - ;; In a region, start at first item in region + ;; In a region, start at first item in region. (cond ((org-region-active-p) (let ((limit (region-end))) @@ -2102,7 +2105,7 @@ in subtree, ignoring drawers." (setq lim-down (copy-marker limit)))) ((org-on-heading-p) ;; On an heading, start at first item after drawers and - ;; time-stamps (scheduled, etc.) + ;; time-stamps (scheduled, etc.). (let ((limit (save-excursion (outline-next-heading) (point)))) (forward-line 1) (while (or (looking-at drawer-re) (looking-at keyword-re)) @@ -2113,14 +2116,14 @@ in subtree, ignoring drawers." (setq lim-up (point-at-bol)) (error "No item in subtree")) (setq lim-down (copy-marker limit)))) - ;; Just one item: set singlep flag + ;; Just one item: set SINGLEP flag. ((org-at-item-p) (setq singlep t) (setq lim-up (point-at-bol) lim-down (point-at-eol))) (t (error "Not at an item or heading, and no active region")))) ;; Determine the checkbox going to be applied to all items - ;; within bounds + ;; within bounds. (ref-checkbox (progn (goto-char lim-up) @@ -2132,9 +2135,11 @@ in subtree, ignoring drawers." ((equal "[X]" cbox) "[ ]") (t "[X]")))))) ;; When an item is found within bounds, grab the full list at - ;; point structure, then: 1. set checkbox of all its items - ;; within bounds to ref-checkbox; 2. fix checkboxes of the whole - ;; list; 3. move point after the list. + ;; point structure, then: + ;; 1. set check-box of all its items within bounds to + ;; REF-CHECKBOX; + ;; 2. fix check-boxes of the whole list; 3. move point after the + ;; list. (goto-char lim-up) (while (and (< (point) lim-down) (org-list-search-forward (org-item-beginning-re) @@ -2149,8 +2154,8 @@ in subtree, ignoring drawers." (mapcar 'car struct)))) (mapc (lambda (e) (org-list-set-checkbox e struct - ;; if there is no box at item, leave as-is - ;; unless function was called with C-u prefix + ;; If there is no box at item, leave as-is + ;; unless function was called with C-u prefix. (let ((cur-box (org-list-get-checkbox e struct))) (if (or cur-box (equal toggle-presence '(4))) ref-checkbox @@ -2158,8 +2163,8 @@ in subtree, ignoring drawers." items-to-toggle) (setq block-item (org-list-struct-fix-box struct parents prevs orderedp)) - ;; Report some problems due to ORDERED status of subtree. If - ;; only one box was being checked, throw an error, else, + ;; Report some problems due to ORDERED status of subtree. + ;; If only one box was being checked, throw an error, else, ;; only signal problems. (cond ((and singlep block-item (> lim-up block-item)) @@ -2213,10 +2218,10 @@ With optional prefix argument ALL, do this for the whole buffer." (count-boxes (function ;; Return number of checked boxes and boxes of all types - ;; in all structures in STRUCTS. If RECURSIVEP is non-nil, - ;; also count boxes in sub-lists. If ITEM is nil, count - ;; across the whole structure, else count only across - ;; subtree whose ancestor is ITEM. + ;; in all structures in STRUCTS. If RECURSIVEP is + ;; non-nil, also count boxes in sub-lists. If ITEM is + ;; nil, count across the whole structure, else count only + ;; across subtree whose ancestor is ITEM. (lambda (item structs recursivep) (let ((c-on 0) (c-all 0)) (mapc @@ -2241,7 +2246,7 @@ With optional prefix argument ALL, do this for the whole buffer." (backup-end 1) cookies-list structs-bak box-num) (goto-char (car bounds)) - ;; 1. Build an alist for each cookie found within BOUNDS. The + ;; 1. Build an alist for each cookie found within BOUNDS. The ;; key will be position at beginning of cookie and values ;; ending position, format of cookie, and a cell whose car is ;; number of checked boxes to report, and cdr total number of @@ -2263,14 +2268,14 @@ With optional prefix argument ALL, do this for the whole buffer." (or (org-entry-get nil "COOKIE_DATA") "")))) (throw 'skip nil)) ;; Cookie is at an heading, but all lists before next - ;; heading already have been read. Use data collected - ;; in STRUCTS-BAK. This should only happen when heading - ;; has more than one cookie on it. + ;; heading already have been read. Use data collected + ;; in STRUCTS-BAK. This should only happen when + ;; heading has more than one cookie on it. ((and (org-on-heading-p) (<= (save-excursion (outline-next-heading) (point)) backup-end)) (funcall count-boxes nil structs-bak recursivep)) - ;; Cookie is at a fresh heading. Grab structure of + ;; Cookie is at a fresh heading. Grab structure of ;; every list containing a checkbox between point and ;; next headline, and save them in STRUCTS-BAK. ((org-on-heading-p) @@ -2297,7 +2302,7 @@ With optional prefix argument ALL, do this for the whole buffer." (setq backup-end (org-list-get-bottom-point struct) structs-bak (list struct))) (funcall count-boxes (point-at-bol) structs-bak recursivep)) - ;; Else, cookie found is at a wrong place. Skip it. + ;; Else, cookie found is at a wrong place. Skip it. (t (throw 'skip nil)))) cookies-list)))) ;; 2. Apply alist to buffer, in reverse order so positions stay @@ -2368,7 +2373,7 @@ Return t if successful." (error "First item of list cannot move without its subtree") t)))) - ;; Determine begin and end points of zone to indent. If moving + ;; Determine begin and end points of zone to indent. If moving ;; more than one item, save them for subsequent moves. (unless (and (memq last-command '(org-shiftmetaright org-shiftmetaleft)) (memq this-command '(org-shiftmetaright org-shiftmetaleft))) @@ -2385,7 +2390,7 @@ Return t if successful." (let* ((beg (marker-position org-last-indent-begin-marker)) (end (marker-position org-last-indent-end-marker))) (cond - ;; Special case: moving top-item with indent rule + ;; Special case: moving top-item with indent rule. (specialp (let* ((level-skip (org-level-increment)) (offset (if (< arg 0) (- level-skip) level-skip)) @@ -2393,13 +2398,13 @@ Return t if successful." (old-struct (copy-tree struct))) (if (< (+ top-ind offset) 0) (error "Cannot outdent beyond margin") - ;; Change bullet if necessary + ;; Change bullet if necessary. (when (and (= (+ top-ind offset) 0) (string-match "*" (org-list-get-bullet beg struct))) (org-list-set-bullet beg struct (org-list-bullet-string "-"))) - ;; Shift every item by OFFSET and fix bullets. Then + ;; Shift every item by OFFSET and fix bullets. Then ;; apply changes to buffer. (mapc (lambda (e) (let ((ind (org-list-get-ind (car e) struct))) @@ -2409,12 +2414,12 @@ Return t if successful." (org-list-struct-apply-struct struct old-struct)))) ;; Forbidden move: ((and (< arg 0) - ;; If only one item is moved, it mustn't have a child + ;; If only one item is moved, it mustn't have a child. (or (and no-subtree (not regionp) (org-list-has-child-p beg struct)) ;; If a subtree or region is moved, the last item - ;; of the subtree mustn't have a child + ;; of the subtree mustn't have a child. (let ((last-item (caar (reverse (org-remove-if @@ -2483,8 +2488,8 @@ If a region is active, all items inside will be moved." (defvar org-tab-ind-state) (defun org-cycle-item-indentation () "Cycle levels of indentation of an empty item. -The first run indents the item, if applicable. Subsequents runs -outdent it at meaningful levels in the list. When done, item is +The first run indents the item, if applicable. Subsequents runs +outdent it at meaningful levels in the list. When done, item is put back at its original position with its original bullet. Return t at each successful move." @@ -2504,9 +2509,9 @@ Return t at each successful move." (skip-chars-backward " \r\t\n") (point))))) (setq this-command 'org-cycle-item-indentation) - ;; When in the middle of the cycle, try to outdent first. If it - ;; fails, and point is still at initial position, indent. Else, - ;; go back to original position. + ;; When in the middle of the cycle, try to outdent first. If + ;; it fails, and point is still at initial position, indent. + ;; Else, go back to original position. (if (eq last-command 'org-cycle-item-indentation) (cond ((ignore-errors (org-list-indent-item-generic -1 t struct))) @@ -2518,7 +2523,7 @@ Return t at each successful move." ;; Break cycle (setq this-command 'identity))) ;; If a cycle is starting, remember indentation and bullet, - ;; then try to indent. If it fails, try to outdent. + ;; then try to indent. If it fails, try to outdent. (setq org-tab-ind-state (cons ind bullet)) (cond ((ignore-errors (org-list-indent-item-generic 1 t struct))) @@ -2529,12 +2534,12 @@ Return t at each successful move." (defun org-sort-list (&optional with-case sorting-type getkey-func compare-func) "Sort list items. The cursor may be at any item of the list that should be sorted. -Sublists are not sorted. Checkboxes, if any, are ignored. +Sublists are not sorted. Checkboxes, if any, are ignored. -Sorting can be alphabetically, numerically, by date/time as given by -a time stamp, by a property or by priority. +Sorting can be alphabetically, numerically, by date/time as given +by a time stamp, by a property or by priority. -Comparing entries ignores case by default. However, with an +Comparing entries ignores case by default. However, with an optional argument WITH-CASE, the sorting considers case as well. The command prompts for the sorting type unless it has been given @@ -2549,11 +2554,11 @@ t By date/time, either the first active time stamp in the entry, if Capital letters will reverse the sort order. -If the SORTING-TYPE is ?f or ?F, then GETKEY-FUNC specifies a -function to be called with point at the beginning of the record. -It must return either a string or a number that should serve as -the sorting key for that record. It will then use COMPARE-FUNC to -compare entries." +If the SORTING-TYPE is ?f or ?F, then GETKEY-FUNC specifies +a function to be called with point at the beginning of the +record. It must return either a string or a number that should +serve as the sorting key for that record. It will then use +COMPARE-FUNC to compare entries." (interactive "P") (let* ((case-func (if with-case 'identity 'downcase)) (struct (org-list-struct)) @@ -2708,7 +2713,7 @@ Point is left at list end." (childp (org-list-has-child-p e struct)) (end (org-list-get-item-end e struct))) ;; If item has a child, store text between bullet and - ;; next child, then recursively parse all sublists. At + ;; next child, then recursively parse all sublists. At ;; the end of each sublist, check for the presence of ;; text belonging to the original item. (if childp @@ -2767,8 +2772,8 @@ Point is left at list end." (defun org-list-send-list (&optional maybe) "Send a transformed version of this list to the receiver position. -With argument MAYBE, fail quietly if no transformation is defined for -this list." +With argument MAYBE, fail quietly if no transformation is defined +for this list." (interactive) (catch 'exit (unless (org-at-item-p) (error "Not at a list item")) @@ -2817,7 +2822,7 @@ this list." (defun org-list-to-generic (list params) "Convert a LIST parsed through `org-list-parse-list' to other formats. -Valid parameters PARAMS are +Valid parameters PARAMS are: :ustart String to start an unordered list :uend String to end an unordered list @@ -2846,8 +2851,8 @@ Valid parameters PARAMS are :cbon String to insert for a checked check-box :cbtrans String to insert for a check-box in transitional state -Alternatively, each parameter can also be a form returning a -string. These sexp can use keywords `counter' and `depth', +Alternatively, each parameter can also be a form returning +a string. These sexp can use keywords `counter' and `depth', reprensenting respectively counter associated to the current item, and depth of the current sub-list, starting at 0. Obviously, `counter' is only available for parameters applying to @@ -2877,9 +2882,9 @@ items." export-sublist ; for byte-compiler (export-item (function - ;; Export an item ITEM of type TYPE, at DEPTH. First string - ;; in item is treated in a special way as it can bring - ;; extra information that needs to be processed. + ;; Export an item ITEM of type TYPE, at DEPTH. First + ;; string in item is treated in a special way as it can + ;; bring extra information that needs to be processed. (lambda (item type depth) (let* ((counter (pop item)) (fmt (concat @@ -2925,7 +2930,7 @@ items." item (or (eval csep) ""))))))) (export-sublist (function - ;; Export sublist SUB at DEPTH + ;; Export sublist SUB at DEPTH. (lambda (sub depth) (let* ((type (car sub)) (items (cdr sub))