Function: rst-insert-list

rst-insert-list is an interactive and byte-compiled function defined in rst.el.gz.

Signature

(rst-insert-list &optional PREFER-ROMAN)

Documentation

Insert a list item at the current point.

The command can insert a new list or a continuing list. When it is called at a non-list line, it will promote to insert new list. When it is called at a list line, it will insert a list with the same list style.

1. When inserting a new list:

User is asked to select the item style first, for example (a), i), +. Use TAB for completion and choices.

 (a) If user selects bullets or #, it's just added.
 (b) If user selects enumerations, a further prompt is given. User needs to
     input a starting item, for example e for A) style.

The position of the new list is arranged according to whether or not the current line and the previous line are blank lines.

2. When continuing a list, one thing needs to be noticed:

List style alphabetical list, such as a., and roman numerical list, such as i., have some overlapping items, for example v. The function can deal with the problem elegantly in most situations. But when those overlapped list are preceded by a blank line, it is hard to determine which type to use automatically. The function uses alphabetical list by default. If you want roman numerical list, just use a prefix to set PREFER-ROMAN.

Probably introduced at or before Emacs version 24.3.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/textmodes/rst.el.gz
;; FIXME: At least the continuation may be folded into
;;        'newline-and-indent'. However, this may not be wanted by everyone so
;;        it should be possible to switch this off.
(defun rst-insert-list (&optional prefer-roman)
  ;; testcover: ok.
  "Insert a list item at the current point.

The command can insert a new list or a continuing list.  When it is called at a
non-list line, it will promote to insert new list.  When it is called at a list
line, it will insert a list with the same list style.

1. When inserting a new list:

User is asked to select the item style first, for example (a), i), +.  Use TAB
for completion and choices.

 (a) If user selects bullets or #, it's just added.
 (b) If user selects enumerations, a further prompt is given.  User needs to
     input a starting item, for example `e' for `A)' style.

The position of the new list is arranged according to whether or not the
current line and the previous line are blank lines.

2. When continuing a list, one thing needs to be noticed:

List style alphabetical list, such as `a.', and roman numerical list, such as
`i.', have some overlapping items, for example `v.' The function can deal with
the problem elegantly in most situations.  But when those overlapped list are
preceded by a blank line, it is hard to determine which type to use
automatically.  The function uses alphabetical list by default.  If you want
roman numerical list, just use a prefix to set PREFER-ROMAN."
  (interactive "P")
  (save-match-data
    (1value
     (rst-forward-line-strict 0))
    ;; FIXME: Finds only tags in single line items. Multi-line items should be
    ;;        considered as well.
    ;; Using `rst-forward-line-looking-at' is more complicated so don't do it.
    (if (looking-at (rst-re 'itmany-beg-1))
	(rst-insert-list-continue
	 (buffer-substring-no-properties
	  (match-beginning 0) (match-beginning 1))
	 (match-string 1)
	 (buffer-substring-no-properties (match-end 1) (match-end 0))
	 prefer-roman)
      (rst-insert-list-new-item))))