[Docutils-checkins] r3228 - in trunk/docutils/tools/editors/emacs: restructuredtext.el tests/tests-adjust-section.el

[<bl...@us...>]

Author: blais
Date: 2005-04-18 00:18:30 +0200 (Mon, 18 Apr 2005)
New Revision: 3228

Modified:
   trunk/docutils/tools/editors/emacs/restructuredtext.el
   trunk/docutils/tools/editors/emacs/tests/tests-adjust-section.el
Log:
Two things to the underlining function for emacs:

1. when the underlining is invoked with a negative argument
   on a line that has no decoration, we should not interpret
   that as a style switch (box vs simple). This is reserved
   for a positive prefix-arg only.  This is more consistent
   with the behaviour when there already is some decoration
   present on the current title.

2. changed the default sectioning char to a list, and the
   underlining function to suggest a new underlining char
   (i.e. one that is not already present in the file),
   choosing it from the list formed by the difference between
   the preferred sectioning chars and the chars already in
   the file, when rotating the section underlines.

   This is really useful, because in practice, you often
   start a new file, and need to underline a new section
   which doesn't have other existing underlining. By using
   the list in the rest-preferred-characters variables
   you can specify your usual preferred order for sectioning
   chars and the new suggested character is automatically
   the one you're expecting. I set the default preferred
   list to something reasonable, =, then -, then ~, then
   other stuff.  Feel free to customize for your own needs.

   Note that the order that is already present in the file
   is used above the preferred chars list.  The preferred
   list is only used to suggest new characters.

This is getting pretty cool.  I feel like this is probably
the end of feature enhancements for this function.  Very
happy with it.
 


Modified: trunk/docutils/tools/editors/emacs/restructuredtext.el
===================================================================
--- trunk/docutils/tools/editors/emacs/restructuredtext.el	2005-04-17 03:10:05 UTC (rev 3227)
+++ trunk/docutils/tools/editors/emacs/restructuredtext.el	2005-04-17 22:18:30 UTC (rev 3228)
@@ -88,6 +88,13 @@
 ;;   If the function is invoked on a section that is complete, the character
 ;;   is rotated among the existing ones.
 ;;
+;;   Note that when rotating the underlining characters, if we come to the end
+;;   of the hierarchy of characters, the variable rest-preferred-characters
+;;   is consulted to propose a new underline char, and if continued, we cycle
+;;   the underline characters all over again.  Set this variable to nil if 
+;;   you want to limit the underlining character propositions to the existing
+;;   underlines in the file.
+;;
 ;; - prefix argument is used to alternate the sectioning style.
 ;;
 ;; Examples:
@@ -211,6 +218,16 @@
 	))
     chars))
 
+(defun rest-suggest-new-char (allchars)
+  "Given the last char that has been seen, suggest a new,
+  different character, different from all that have been seen."
+  (let ((potentials (copy-sequence rest-preferred-characters)))
+    (dolist (x allchars)
+      (setq potentials (delq x potentials))
+      )
+    (car potentials)
+    ))
+
 (defun rest-update-section (underlinechar style &optional indent)
   "Unconditionally updates the overline/underline of a section
   title using the given character CHAR, with STYLE 'simple or
@@ -275,11 +292,11 @@
       (goto-char marker)
       ))
 
+(defvar rest-preferred-characters '(?= ?- ?~ ?+ ?` ?# ?@)
+  "Preferred ordering of underline characters.  This sequence is
+  consulted to offer a new underline character when we rotate the 
+  underlines at the end of the existing hierarchy of characters.")
 
-(defvar rest-default-section-char ?=
-  "Default section underlining character to use when there aren't
-  any others to be used in the file.")
-
 (defvar rest-default-under-and-over-indent 1
   "Number of characters to indent the section title when toggling
   sectioning styles.  This is used when switching from a simple 
@@ -312,10 +329,10 @@
     and underline the current line as a section title (also see
     prefix argument below).
 
-    If no pre-existing underlining character is found in the
-    file, we use the last seen underline char or
-    rest-default-section-char if this is the first title in the
-    entire file.
+    If no pre-existing underlining character is found in the on
+    the line, we use the last seen underline char or consult the
+    first element of rest-preferred-characters if this is the
+    first title in the entire file.
 
   - If the current line does have an underline or overline, and
     if
@@ -393,18 +410,20 @@
     (if (or (and current-prefix-arg
 		 (not (< (prefix-numeric-value current-prefix-arg) 0)))
 	    (eq curchar nil))
-
+	
 	;; we're switching characters or there is currently no sectioning
 	(progn
 	  (setq curchar 
 		(or curchar
 		    (rest-find-last-section-char)
 		    (car (rest-all-section-chars))
-		    rest-default-section-char))
-	  
+		    (car rest-preferred-characters)
+		    ?=))
+
 	  (rest-update-section
-	   (or curchar rest-default-section-char)
-	   (if current-prefix-arg
+	   curchar
+	   (if (and current-prefix-arg
+		    (not (< (prefix-numeric-value current-prefix-arg) 0)))
 	       (if (eq init-style 'over-and-under) 'simple 'over-and-under)
 	     init-style)
 	   rest-default-under-and-over-indent)
@@ -434,7 +453,15 @@
 			      (if (bolp) 1 0)))
 		  (allchars (rest-all-section-chars 
 			     (list (- curline 1) curline (+ curline 1))))
-		  (rotchars (append allchars (list (car allchars))))
+
+		  (rotchars 
+		   (append allchars 
+			   (filter 'identity
+				   (list 
+				    ;; suggest a new char
+				    (rest-suggest-new-char allchars)
+				    ;; rotate to first char
+				    (car allchars)))))
 		  (nextchar 
 		   (or (cadr (memq curchar 
 				   (if (< (prefix-numeric-value 
@@ -442,6 +469,7 @@
 				       (reverse rotchars) rotchars)))
 		       (car allchars)) ) )
 
+
 	    (if nextchar
 		(rest-update-section nextchar init-style curindent))
 	    )))

Modified: trunk/docutils/tools/editors/emacs/tests/tests-adjust-section.el
===================================================================
--- trunk/docutils/tools/editors/emacs/tests/tests-adjust-section.el	2005-04-17 03:10:05 UTC (rev 3227)
+++ trunk/docutils/tools/editors/emacs/tests/tests-adjust-section.el	2005-04-17 22:18:30 UTC (rev 3228)
@@ -111,6 +111,30 @@
 
 ")
 
+    (with-suggested-new-text
+"
+Some Title
+==========
+
+Subtitle
+--------
+
+Subtitle2@
+
+"
+"
+Some Title
+==========
+
+Subtitle
+--------
+
+Subtitle2
+~~~~~~~~~
+
+"
+2)
+
     (with-previous-text-rotating
 "
 Some Title
@@ -133,7 +157,7 @@
 =========
 
 "
-2)
+3)
 
   )
   
@@ -173,9 +197,3 @@
  rest-adjust-section-tests
  (lambda ()
    (call-interactively 'rest-adjust-section-title)))
-
-
-
-
-
-