Menu
▾
▴
[Docutils-checkins] r4699 - in trunk/docutils: docs/user/emacs.txt tools/editors/emacs/rst.el
|
From: <bl...@us...> - 2006-08-24 18:59:47
|
Author: blais
Date: 2006-08-24 20:59:23 +0200 (Thu, 24 Aug 2006)
New Revision: 4699
Modified:
trunk/docutils/docs/user/emacs.txt
trunk/docutils/tools/editors/emacs/rst.el
Log:
Updated rst.el with new features for enumerating and bulleting lists of items.
Modified: trunk/docutils/docs/user/emacs.txt
===================================================================
--- trunk/docutils/docs/user/emacs.txt 2006-08-23 04:06:54 UTC (rev 4698)
+++ trunk/docutils/docs/user/emacs.txt 2006-08-24 18:59:23 UTC (rev 4699)
@@ -26,7 +26,8 @@
5.2 Maintaining the Table of Contents Up-to-date
6 Navigating Between the Section Titles
7 Shifting Bullet List Levels
- 8 Enumerating Lists
+ 8 Bulleting and Enumerating Lists
+ 8.1 Straightening Existing Bullet List Hierarchies
9 Creating and Remove Line Blocks
10 Major Mode for Editing reStructuredText Documents
11 Converting Documents from Emacs
@@ -302,34 +303,103 @@
column positions are.
-Enumerating Lists
-=================
+Bulleting and Enumerating Lists
+===============================
-Sometimes it can be useful to insert enumeration markers before list
-items. You can do this easily by invoking ``rst-enumerate-region``
-with ``C-c p e``, for example, the following::
+Sometimes it can be useful to insert bullet list markers enumeration
+number before a number of lines or paragraphs. You can do this easily
+by invoking ``rst-enumerate-region`` (``C-c p e``), for example, the
+following::
Apples
+
Oranges
+
Bananas
becomes::
1. Apples
+
2. Oranges
+
3. Bananas
-.. note:: This will be improved in the future, as we will eventually
- provide a function to “straighten” bulleted lists to use
- the same bullet character, as well as to enumerate lists or
- add bullets automatically if they are not present
- (--blais).
+``rst-listify-region`` (``C-c p b``) does the same, but only adds
+bullet list markers, e.g.::
+ Apples
+
+ Oranges
+
+ Bananas
+
+becomes::
+
+ - Apples
+
+ - Oranges
+
+ - Bananas
+
+
+By default, each paragraph starting on the leftmost line in the
+highlighted region will be taken to be a single list or enumeration
+item, for example, enumerating the following::
+
+ An apple a day
+ keeps the doctor away.
+
+ But oranges
+ are tastier than apples.
+
+ If you preferred bananas
+ you may be
+ a monkey.
+
+Will result in::
+
+ 1. An apple a day
+ keeps the doctor away.
+
+ 2. But oranges
+ are tastier than apples.
+
+ 3. If you preferred bananas
+ you may be
+ a monkey.
+
+If you would like to enumerate each of the lines, use a prefix
+argument on the preceding commands, e.g.::
+
+ Apples
+ Oranges
+ Bananas
+
+becomes::
+
+ - Apples
+ - Oranges
+ - Bananas
+
+
+
+Straightening Existing Bullet List Hierarchies
+----------------------------------------------
+
+If you invoke ``rst-straighten-bullets-region`` (C-c p w), the
+existing bullets in the highlighted region will be replaced to reflect
+their respective level. This does not make a difference in the
+document structure that reStructuredText_ defines, but looks better in
+the input file, for example, if all of the top-level bullet items use
+the character ``-``, and all of the 2nd level items use ``*``, etc.
+
+
Creating and Remove Line Blocks
===============================
To create line blocks, first select the region to convert and invoke
-``rst-toggle-line-block`` with ``C-c p b``, for example, the
+``rst-toggle-line-block`` with ``C-c p B``, for example, the
following::
Apples
Modified: trunk/docutils/tools/editors/emacs/rst.el
===================================================================
--- trunk/docutils/tools/editors/emacs/rst.el 2006-08-23 04:06:54 UTC (rev 4698)
+++ trunk/docutils/tools/editors/emacs/rst.el 2006-08-24 18:59:23 UTC (rev 4699)
@@ -156,6 +156,15 @@
;; feature off. See `Local Variables in Files' in the Emacs documentation for a
;; more complete discussion.
+;;; BUGS
+
+;; David: If I try rst-toc-insert in docs/dev/rst/alternatives.txt, it skips the
+;; section 5 title, "... Or Not To Do?". Perhaps it mistakes it for a comment? A
+;; comment requires two periods and a space or newline; three periods is not a
+;; comment.
+
+;; Doing a line block creates two pipes, Wtf, should be one?
+
;;; TODO list
;; Bindings
@@ -201,7 +210,7 @@
;;; History:
-;;
+;;
;;; Code:
@@ -231,17 +240,20 @@
("i" . rst-toc-insert)
("+" . rst-toc-insert)
("u" . rst-toc-insert-update)
+ ("f" . rst-goto-section)
+ ;;([return] . rst-goto-section)
("h" . rst-display-decorations-hierarchy)
("s" . rst-straighten-decorations)
("w" . rst-straighten-bullets-region)
+ ("b" . rst-listify-region)
+ ("e" . rst-enumerate-region)
("p" . rst-backward-section)
("n" . rst-forward-section)
("m" . rst-mark-section)
("r" . rst-shift-region-right)
("l" . rst-shift-region-left)
- ("e" . rst-enumerate-region)
- ("E" . rst-enumerate-region-bullets)
- ("b" . rst-line-block-region)
+ ("v" . rst-convert-bullets-to-enumeration)
+ ("B" . rst-line-block-region)
("c" . rst-compile)
("C" . rst-compile-alt-toolset)
("x" . rst-compile-pseudo-region)
@@ -249,8 +261,6 @@
))
(define-key rst-prefix-map (car m) (cdr m)))
-
-
(defun rst-text-mode-bindings ()
"Default text mode hook for rest."
@@ -1421,13 +1431,13 @@
(goto-char pos)
(delete-char 1)
(insert (char-to-string char))))
-
+
;; Sorted list of indent . positions
(sort poslist (lambda (x y) (<= (car x) (car y))))
;; List of preferred bullets.
rst-preferred-bullets)
-
+
)))
(defun rst-rstrip (str)
@@ -1865,16 +1875,22 @@
(defvar rst-toc-buffer-name "*Table of Contents*"
"Name of the Table of Contents buffer.")
-(defun rst-toc-mode-goto-section ()
+(defun rst-goto-section (&optional kill)
"Go to the section the current line describes."
(interactive)
(let ((pos (rst-toc-mode-find-section)))
- (kill-buffer (get-buffer rst-toc-buffer-name))
+ (when kill
+ (kill-buffer (get-buffer rst-toc-buffer-name)))
(pop-to-buffer (marker-buffer pos))
(goto-char pos)
;; FIXME: make the recentering conditional on scroll.
(recenter 5)))
+(defun rst-toc-mode-goto-section ()
+ "Go to the section the current line describes and kill the toc buffer."
+ (interactive)
+ (rst-goto-section t))
+
(defun rst-toc-mode-mouse-goto (event)
"In `rst-toc' mode, go to the occurrence whose line you click on.
EVENT is the input event."
@@ -2074,7 +2090,7 @@
;; towards the left).
(let ((col (current-column)))
(when (< col leftcol)
-
+
;; Add the beginning of the line as a tabbing point.
(unless (memq col (mapcar 'car tablist))
(setq tablist (cons (cons col (point)) tablist)))
@@ -2167,7 +2183,7 @@
;; Apply the indent.
(indent-rigidly
mbeg mend
-
+
;; Find the next tab after the leftmost columnt.
(let ((tab (funcall find-next-fun tabs leftmostcol)))
@@ -2182,7 +2198,7 @@
(line-end-position))))
)
(- (caar tab) leftmostcol)) ;; Num chars.
-
+
;; Otherwise use the basic offset
(funcall offset-fun rst-shift-basic-offset)
)))
@@ -2249,37 +2265,70 @@
;;
;; FIXME: TODO we need to do the enumeration removal as well.
-(defun rst-enumerate-region (rbeg rend)
- "Insert numbered enumeration list prefixes to the currently
-selected region. With prefix argument, remove the enumeration.
-(Note: the removal part of not implemented yet.)"
+(defun rst-enumerate-region (beg end)
+ "Add enumeration to all the leftmost paragraphs in the given region.
+The region is specified between BEG and END. With prefix argument,
+do all lines instead of just paragraphs."
(interactive "r")
- (save-excursion
- (goto-char rend)
- (beginning-of-line)
+ (let ((count 0)
+ (last-insert-len nil))
+ (rst-iterate-leftmost-paragraphs
+ beg end (not current-prefix-arg)
+ (let ((ins-string (format "%d. " (incf count))))
+ (setq last-insert-len (length ins-string))
+ (insert ins-string))
+ (insert (make-string last-insert-len ?\ ))
+ )))
- (let (tight-rbeg
- tight-rend
- ;; Count the number of lines in the region
- (nlines (count-lines rbeg rend))
- ;; Find the minimum column in all the lines in the region
- (lcol (rst-find-leftmost-column rbeg rend))
- (curnum 1))
+(defun rst-listify-region (beg end)
+ "Add bullets to all the leftmost paragraphs in the given region.
+The region is specified between BEG and END. With prefix argument,
+do all lines instead of just paragraphs."
+ (interactive "r")
+ (rst-iterate-leftmost-paragraphs
+ beg end (not current-prefix-arg)
+ (insert "- ")
+ (insert " ")
+ ))
- (let ((curindex 1))
- (operate-on-rectangle 'rst-enumerate-insert-enum rbeg rend t)))
- ))
+(defmacro rst-iterate-leftmost-paragraphs
+ (beg end first-only body-consequent body-alternative)
+ "Call FUN at the beginning of each line, with an argument that
+specifies whether we are at the first line of a paragraph that
+starts at the leftmost column of the given region BEG and END.
+Set FIRST-ONLY to true if you want to callback on the first line
+of each paragraph only."
+ `(save-excursion
+ (let ((leftcol (rst-find-leftmost-column beg end))
+ (endm (set-marker (make-marker) end))
+ ,(when first-only '(in-par nil))
+ )
-(defun rst-enumerate-insert-enum (startpos begextra endextra)
- (back-to-indentation)
- (if (= (current-column) lcol)
- (progn
- (insert (int-to-string curnum))
- (insert ". ")
- (incf curnum))
- (indent-line-to (+ lcol 3))))
+ (do* (;; Iterate lines
+ (l (progn (goto-char beg) (back-to-indentation))
+ (progn (forward-line 1) (back-to-indentation)))
+ (previous nil valid)
+ (curcol (current-column)
+ (current-column))
+
+ (valid (and (= curcol leftcol)
+ (not (looking-at "[ \t]*$")))
+ (and (= curcol leftcol)
+ (not (looking-at "[ \t]*$"))))
+ )
+ ((>= (point-marker) endm))
+
+ (if (if ,first-only
+ (and valid (not previous))
+ valid)
+ ,body-consequent
+ ,body-alternative)
+
+ ))))
+
+
;; FIXME: there are some problems left with the following function
;; implementation:
;;
@@ -2288,7 +2337,7 @@
;;
;; I suppose it does 90% of the job for now.
-(defun rst-enumerate-region-bullets (beg end)
+(defun rst-convert-bullets-to-enumeration (beg end)
"Convert all the bulleted items and enumerated items in the
region to enumerated lists, renumbering as necessary."
(interactive "r")
@@ -2312,6 +2361,7 @@
))
+
;;------------------------------------------------------------------------------
(defun rst-line-block-region (rbeg rend &optional pfxarg)
@@ -2328,7 +2378,7 @@
;; FIXME todo: we need to provide the option of adding the line block chars for
;; empty lines as well. Sometimes this has to be decided by the user, but in
;; certain cases it could be detected automatically, e.g.
-;;
+;;
;; Foo
;;
;; Bar
@@ -3224,7 +3274,7 @@
"Convert the document to a PDF file and launch a preview program."
(interactive)
(let* ((tmp-filename "/tmp/out.pdf")
- (command (format "rst2pdf.py %s %s && %s %s"
+ (command (format "rst2pdf.py %s %s && %s %s"
buffer-file-name tmp-filename
rst-pdf-program tmp-filename)))
(start-process-shell-command "rst-pdf-preview" nil command)
|