Mercurial > emacs

--- a/lisp/ChangeLog	Mon Nov 24 15:45:54 2008 +0000
+++ b/lisp/ChangeLog	Mon Nov 24 16:30:14 2008 +0000
@@ -1,3 +1,24 @@
+2008-11-24  Juanma Barranquero  <lekktu@gmail.com>
+
+	* textmodes/artist.el (artist-charlist-to-string): Simplify.
+	(artist-mode-name, artist-mt, artist-vaporize-fuzziness)
+	(artist-prev-next-op-alist, artist-mode-line-show-curr-operation)
+	(artist-replace-string, artist-draw-rect, artist-draw-line)
+	(artist-undraw-line, artist-draw-sline, artist-undraw-rect)
+	(artist-rect-corners-squarify, artist-undraw-square, artist-fill-square)
+	(artist-pen, artist-pen-line, artist-text-insert-common)
+	(artist-text-overwrite, artist-spray-get-interval)
+	(artist-spray-clear-circle, artist-erase-char)
+	(artist-ellipse-generate-quadrant, artist-copy-square, artist-paste)
+	(artist-flood-fill, artist-key-draw-continously, artist-key-draw-poly)
+	(artist-key-draw-1point, artist-key-draw-2points)
+	(artist-mouse-draw-continously): Fix typos in docstrings.
+	(artist-aspect-ratio, artist-mode, artist-go-get-symbol-shift)
+	(artist-go-get-symbol-shift-sub, artist-previous-line, artist-next-line)
+	(artist-backward-char, artist-forward-char): Doc fixes.
+	(artist-vaporize-line, artist-spray-chars, artist-spray-new-char):
+	Reflow docstrings.
+
 2008-11-24  Stefan Monnier  <monnier@iro.umontreal.ca>

 	* international/quail.el (quail-vunion): New function.
--- a/lisp/textmodes/artist.el	Mon Nov 24 15:45:54 2008 +0000
+++ b/lisp/textmodes/artist.el	Mon Nov 24 16:30:14 2008 +0000
@@ -263,7 +263,7 @@

 (defcustom artist-aspect-ratio 1
   "Defines the character height-to-width aspect ratio.
-This is used when drawing squares and circles.  If the height of the"
+This is used when drawing squares and circles."
   :group 'artist
   :type 'number)

@@ -343,8 +343,8 @@
                       \\/ /
             A----*----/\\/----------B
                      / /\\
- (in fact, only the left part (between the A and the leftmost ``/''
- crossing the line) will be vaporized)"
+ (in fact, only the left part [between the A and the leftmost ``/''
+ crossing the line] will be vaporized)."
   :group 'artist
   :type 'integer)

@@ -399,17 +399,15 @@
   ;; package shows lists of characters as a lists of integers,
   ;; which is confusing
   "*Characters (``color'') to use when spraying.
-They should be ordered
-from the ``lightest'' to the ``heaviest'' since spraying replaces a
-light character with the next heavier one.")
+They should be ordered from the ``lightest'' to the ``heaviest''
+since spraying replaces a light character with the next heavier one.")


 (defvar artist-spray-new-char ?.
   "*Initial character to use when spraying.
-This character is used if spraying upon a character that is
-not in `artist-spray-chars'.  The character defined by this variable
-should be in `artist-spray-chars', or spraying will behave
-strangely.")
+This character is used if spraying upon a character that is not in
+`artist-spray-chars'.  The character defined by this variable should
+be in `artist-spray-chars', or spraying will behave strangely.")


 ;; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -423,7 +421,7 @@
 (make-variable-buffer-local 'artist-mode)

 (defvar artist-mode-name " Artist"
-  "Name of artist mode beginning with a space (appears in the mode-line).")
+  "Name of Artist mode beginning with a space (appears in the mode-line).")

 (defvar artist-curr-go 'pen-char
   "Current selected graphics operation.")
@@ -477,7 +475,7 @@
 * OP is an atom: the KEY-SYMBOL in the `artist-mt' structure
 * PREV-OP and NEXT-OP are strings: the KEYWORD in the `artist-mt' structure

-This variable is initialized by the artist-make-prev-next-op-alist function.")
+This variable is initialized by the `artist-make-prev-next-op-alist' function.")

 (eval-when-compile
   ;; Make rect available at compile-time
@@ -803,7 +801,7 @@

   "Master Table for `artist-mode'.
 This table is primarily a table over the different graphics operations
-available in artist mode, but it also holds layout information for the
+available in Artist mode, but it also holds layout information for the
 popup menu.

 The master table is a list of table elements.  The elements of this table
@@ -935,7 +933,7 @@

   ENDPOINT-1 and ENDPOINT-2 are endpoints which are created with
   `artist-make-endpoint'
-  SHAPE is an opaque structure, created by the DRAW-FN and intented
+  SHAPE is an opaque structure, created by the DRAW-FN and intended
   to be used only by the UNDRAW-FN.

 If DRAW-HOW is `artist-do-poly':
@@ -950,7 +948,7 @@

   ENDPOINT-1 and ENDPOINT-2 are endpoints which are created with
   `artist-make-endpoint'.
-  SHAPE is an opaque structure, created by the DRAW-FN and intented
+  SHAPE is an opaque structure, created by the DRAW-FN and intended
   to be used only by the UNDRAW-FN.
   POINT-LIST is a list of vectors [X Y].")

@@ -1156,11 +1154,12 @@

 ;;;###autoload
 (defun artist-mode (&optional state)
-  "Toggle artist mode. With arg, turn artist mode on if arg is positive.
-Artist lets you draw lines, squares, rectangles and poly-lines, ellipses
-and circles with your mouse and/or keyboard.
-
-How to quit artist mode
+  "Toggle Artist mode.
+With argument STATE, turn Artist mode on if STATE is positive.
+Artist lets you draw lines, squares, rectangles and poly-lines,
+ellipses and circles with your mouse and/or keyboard.
+
+How to quit Artist mode

  Type \\[artist-mode-off] to quit artist-mode.

@@ -1215,10 +1214,10 @@
 		* Straight lines can only go horizontally, vertically
 		  or diagonally.

-		* Poly-lines are drawn while holding mouse-1 down. When you
-		  release the button, the point is set. If you want a segment
+		* Poly-lines are drawn while holding mouse-1 down.  When you
+		  release the button, the point is set.  If you want a segment
 		  to be straight, hold down shift before pressing the
-		  mouse-1 button. Click mouse-2 or mouse-3 to stop drawing
+		  mouse-1 button.  Click mouse-2 or mouse-3 to stop drawing
 		  poly-lines.

 		* See thru for text means that text already in the buffer
@@ -1226,7 +1225,7 @@
 		  overwrite means the opposite.

 		* Vaporizing connected lines only vaporizes lines whose
-		  _endpoints_ are connected. See also the variable
+		  _endpoints_ are connected.  See also the variable
 		  `artist-vaporize-fuzziness'.

 		* Cut copies, then clears the rectangle/square.
@@ -1259,7 +1258,7 @@
  Trimming	Toggles trimming of line-endings (that is: when the shape
 		is drawn, extraneous white-space at end of lines is removed)

- Borders        Toggles the drawing of line borders around filled shapes.
+ Borders        Toggles the drawing of line borders around filled shapes


 Drawing with keys
@@ -1441,7 +1440,7 @@
   (sit-for 0))

 (defun artist-mode-line-show-curr-operation (is-drawing)
-  "Show current operation in  mode-line.  If IS-DRAWING, show that."
+  "Show current operation in mode-line.  If IS-DRAWING, show that."
   (let ((mtext (concat artist-mode-name "/"
 		       (artist-go-get-mode-line-from-symbol artist-curr-go)
 		       (if is-drawing "/*" ""))))
@@ -1684,13 +1683,13 @@
 (defun artist-go-get-symbol-shift (symbol is-shifted)
   "Search for (shifted or unshifted) graphics operation SYMBOL.
 If IS-SHIFTED is non-nil, return the shifted symbol,
-otherwise the shifted symbol."
+otherwise the unshifted symbol."
   (artist-go-get-symbol-shift-sub artist-mt symbol is-shifted))

 (defun artist-go-get-symbol-shift-sub (table symbol is-shifted)
   "Search TABLE for (shifted or unshifted) graphics SYMBOL.
 If IS-SHIFTED is non-nil, return the shifted symbol,
-otherwise the shifted symbol."
+otherwise the unshifted symbol."
   (catch 'found
     (mapc
      (lambda (element)
@@ -2010,7 +2009,7 @@

 (defsubst artist-replace-string (string &optional see-thru)
   "Replace contents at point with STRING.
-With optional argument SEE-THRU, set to non-nil, text in the buffer
+With optional argument SEE-THRU set to non-nil, text in the buffer
 ``shines thru'' blanks in the STRING."
   (let ((char-list (append string nil))	; convert the string to a list
 	(overwrite-mode 'overwrite-mode-textual)
@@ -2321,6 +2320,7 @@
 ;; Some inline funtions for creating, setting and reading
 ;; members of a coordinate
 ;;
+
 (defsubst artist-new-coord (x y &optional new-char)
   "Create a new coordinate at X,Y for use in a line.
 Optional argument NEW-CHAR can be used for setting the new-char component
@@ -2533,7 +2533,7 @@
 ;;

 (defun artist-draw-line (x1 y1 x2 y2)
-  "Draws a line from X1, Y1 to X2, Y2.
+  "Draw a line from X1, Y1 to X2, Y2.

 Output is a line, which is a list (END-POINT-1 END-POINT-2 SHAPE-INFO).

@@ -2558,7 +2558,7 @@
 	 (artist-eight-point x1 y1 x2 y2))))))))

 (defun artist-undraw-line (line)
-  "Undraws LINE."
+  "Undraw LINE."
   (mapcar
    (lambda (coord)
      (artist-move-to-xy (artist-coord-get-x coord)
@@ -2572,7 +2572,7 @@
 ;;

 (defun artist-draw-sline (x1 y1 x2 y2)
-  "Draw a strait line from X1, Y1 to X2, Y2.
+  "Draw a straight line from X1, Y1 to X2, Y2.
 Straight lines are vertical, horizontal or diagonal lines.
 They are faster to draw and most often they are what you need
 when drawing a simple image.
@@ -2630,7 +2630,7 @@
 ;;

 (defun artist-draw-rect (x1 y1 x2 y2)
-  "Draws a rectangle with corners at X1, Y1 and X2, Y2.
+  "Draw a rectangle with corners at X1, Y1 and X2, Y2.

 Output is a rectangle, which is a list on the form
 \(END-POINT-1 END-POINT-2 SHAPE-INFO).
@@ -2650,7 +2650,7 @@
 			       (list line1 line2 line3 line4))))

 (defun artist-undraw-rect (rectangle)
-  "Undraws RECTANGLE."
+  "Undraw RECTANGLE."
   (if rectangle
       (let ((shape-info (artist-2point-get-shapeinfo rectangle)))
 	(artist-undraw-sline (elt shape-info 3))
@@ -2661,8 +2661,8 @@

 (defun artist-rect-corners-squarify (x1 y1 x2 y2)
   "Compute square corners from rectangle corners at X1, Y1 and X2, Y2.
-The square's first corner will be X1, Y1. The position of the second corner
-depends on which of X2 and Y2 is most far away from X1, Y1."
+The square's first corner will be X1, Y1.  The position of the second
+corner depends on which of X2 and Y2 is most far away from X1, Y1."
   (let* ((delta-x      (- x2 x1))
 	 (delta-y      (- y2 y1))
 	 (delta-x-sign (if (< delta-x 0) -1 1))
@@ -2716,7 +2716,7 @@
 			       (list line1 line2 line3 line4))))

 (defun artist-undraw-square (square)
-  "Undraws SQUARE."
+  "Undraw SQUARE."
   (if square
       (let ((shape-info (artist-2point-get-shapeinfo square)))
 	(artist-undraw-sline (elt shape-info 3))
@@ -2741,7 +2741,7 @@
 	(setq y (1+ y))))))

 (defun artist-fill-square (square x1 y1 x2 y2)
-  "Fills a SQUARE from X1,Y1 to X2,Y2."
+  "Fill a SQUARE from X1,Y1 to X2,Y2."
   (let* ((square-corners (artist-rect-corners-squarify x1 y1 x2 y2))
 	 (new-x1 (elt square-corners 0))
 	 (new-y1 (elt square-corners 1))
@@ -2763,7 +2763,7 @@
 ;;

 (defun artist-pen (x1 y1)
-  "Draws a character at X1, Y1.
+  "Draw a character at X1, Y1.
 The character is replaced with the character in `artist-fill-char'."
   (artist-move-to-xy x1 y1)
   (artist-replace-char (if artist-line-char-set
@@ -2774,7 +2774,7 @@


 (defun artist-pen-line (x1 y1)
-  "Draws a line from last pen position to X1, Y1.
+  "Draw a line from last pen position to X1, Y1.
 The character is replaced with the character in `artist-fill-char'.
 This will store all points in `artist-key-poly-point-list' in reversed
 order (I assume it is faster to cons to the beginning of the list than
@@ -2891,7 +2891,7 @@

 (defun artist-text-insert-common (x y text see-thru)
   "At position X, Y, insert text TEXT.
-If SEE-THRU is non-nil, then blanks in TEXT does not replace text
+If SEE-THRU is non-nil, then blanks in TEXT do not replace text
 in the buffer."
   (let* ((string-list (artist-string-split text "\n"))
 	 (i 0)
@@ -2930,7 +2930,7 @@
 `artist-text-renderer-function', which must return a list of strings,
 to be inserted in the buffer.

-Blanks in the rendered text overwrites any text in the buffer."
+Blanks in the rendered text overwrite any text in the buffer."
   (let* ((input-text (read-string "Type text to render: "))
 	 (rendered-text (artist-funcall artist-text-renderer-function input-text)))
     (artist-text-insert-overwrite x y rendered-text)))
@@ -2940,7 +2940,7 @@
 ;;

 (defun artist-spray-get-interval ()
-  "Retrieves the interval for repeated spray."
+  "Retrieve the interval for repeated spray."
   artist-spray-interval)

 (defun artist-spray-random-points (n radius)
@@ -2978,7 +2978,7 @@
       (setq spray-points (cdr spray-points)))))

 (defun artist-spray-clear-circle (circle x1 y1 x2 y2)
-  "Clears circle CIRCLE at X1, Y1 through X2, Y2."
+  "Clear circle CIRCLE at X1, Y1 through X2, Y2."
   (artist-undraw-circle circle))

 (defun artist-spray-set-radius (circle x1 y1 x2 y2)
@@ -2994,7 +2994,7 @@
 ;;

 (defun artist-erase-char (x1 y1)
-  "Erases a character at X1, Y1.
+  "Erase a character at X1, Y1.
 The character is replaced with the character in `artist-erase-char'."
   (artist-move-to-xy x1 y1)
   (artist-replace-char artist-erase-char))
@@ -3160,8 +3160,8 @@
 (defun artist-vaporize-line (x1 y1)
   "Vaporize (erase) the straight line through X1, Y1.
 Do this by replacing the characters that forms the line with
-`artist-erase-char'.  Output is a list of endpoints for lines
-through X1, Y1. An endpoint is a cons pair, (ENDPOINT-X . ENDPOINT-Y)."
+`artist-erase-char'.  Output is a list of endpoints for lines through
+X1, Y1.  An endpoint is a cons pair, (ENDPOINT-X . ENDPOINT-Y)."
   (let ((endpoints (artist-vap-find-endpoints x1 y1)))
     (mapc
      (lambda (endpoints)
@@ -3234,7 +3234,7 @@
 (defun artist-ellipse-generate-quadrant (x-radius y-radius)
   "Create a point-list for first quadrant.
 Points go from (X-RADIUS, 0) to (0, Y-RADIUS).
-Quadrant is generated around origo."
+Quadrant is generated around origin."
   (let* ((rx2 (* x-radius x-radius))
 	 (ry2 (* y-radius y-radius))
 	 (2rx2 (* 2 rx2))
@@ -3655,7 +3655,7 @@
   (artist-copy-generic x1 y1 x2 y2))

 (defun artist-copy-square (square x1 y1 x2 y2)
-  "Copies a SQUARE drawn from X1, Y1 to X2, Y2 (but made square)."
+  "Copy a SQUARE drawn from X1, Y1 to X2, Y2 (but made square)."
   (artist-undraw-square square)
   (let* ((square-corners (artist-rect-corners-squarify x1 y1 x2 y2))
 	 (new-x1 (elt square-corners 0))
@@ -3665,7 +3665,7 @@
     (artist-copy-generic new-x1 new-y1 new-x2 new-y2)))

 (defun artist-paste (x y)
-  "Pastes the contents of the copy-buffer at X,Y."
+  "Paste the contents of the copy-buffer at X,Y."
   (let ((copy-buf (if artist-interface-with-rect
 		      killed-rectangle
 		    artist-copy-buffer)))
@@ -3721,7 +3721,7 @@
         (>= y last-line)))))

 (defun artist-flood-fill (x1 y1)
-  "Flood-fill starting at X1, Y1. Fill with the char in `artist-fill-char'."
+  "Flood-fill starting at X1, Y1.  Fill with the char in `artist-fill-char'."
   (let ((stack nil)
 	(input-queue nil)
 	;; We are flood-filling the area that has this character.
@@ -3946,25 +3946,25 @@
 ;; user has released the button, so the timer will always be cancelled
 ;; at that point.
 (defun artist-key-draw-continously (x y)
-  "Draws current continous shape at X,Y."
+  "Draw current continous shape at X,Y."
   (let ((draw-fn   (artist-go-get-draw-fn-from-symbol artist-curr-go)))
     (setq artist-key-shape (artist-funcall draw-fn x y))))

 (defun artist-key-draw-poly (x y)
-  "Draws current poly-point shape with nth point at X,Y."
+  "Draw current poly-point shape with nth point at X,Y."
   (let ((draw-fn   (artist-go-get-draw-fn-from-symbol artist-curr-go))
 	(x1        (artist-endpoint-get-x artist-key-endpoint1))
 	(y1        (artist-endpoint-get-y artist-key-endpoint1)))
     (setq artist-key-shape (artist-funcall draw-fn x1 y1 x y))))

 (defun artist-key-draw-1point (x y)
-  "Draws current 1-point shape at X,Y."
+  "Draw current 1-point shape at X,Y."
   (let ((draw-fn   (artist-go-get-draw-fn-from-symbol artist-curr-go)))
     (setq artist-key-shape (artist-funcall draw-fn x y))))


 (defun artist-key-draw-2points (x y)
-  "Draws current 2-point shape at X,Y."
+  "Draw current 2-point shape at X,Y."
   (let ((draw-fn   (artist-go-get-draw-fn-from-symbol artist-curr-go))
 	(x1        (artist-endpoint-get-x artist-key-endpoint1))
 	(y1        (artist-endpoint-get-y artist-key-endpoint1)))
@@ -4382,7 +4382,7 @@
 ;;

 (defun artist-previous-line (&optional n)
-  "Move cursor up optional N lines (default is 1), updating current shape.
+  "Move cursor up N lines (default is 1), updating current shape.
 If N is negative, move cursor down."
   (interactive "p")
   (let ((col (artist-current-column)))
@@ -4393,7 +4393,7 @@


 (defun artist-next-line (&optional n)
-  "Move cursor down optional N lines (default is 1), updating current shape.
+  "Move cursor down N lines (default is 1), updating current shape.
 If N is negative, move cursor up."
   (interactive "p")
   (let ((col (artist-current-column)))
@@ -4403,7 +4403,7 @@
     (artist-key-do-continously-common)))

 (defun artist-backward-char (&optional n)
-  "Move cursor backward optional N chars (default is 1), updating curr shape.
+  "Move cursor backward N chars (default is 1), updating current shape.
 If N is negative, move forward."
   (interactive "p")
   (if (> n 0)
@@ -4411,7 +4411,7 @@
     (artist-forward-char n)))

 (defun artist-forward-char (&optional n)
-  "Move cursor forward optional N chars (default is 1), updating curr shape.
+  "Move cursor forward N chars (default is 1), updating current shape.
 If N is negative, move backward."
   (interactive "p")
   (let* ((step-x   (if (>= n 0) 1 -1))
@@ -4464,11 +4464,7 @@

 (defun artist-charlist-to-string (char-list)
   "Convert a list of characters, CHAR-LIST, to a string."
-  (let ((result ""))
-    (while (not (null char-list))
-      (setq result (concat result (char-to-string (car char-list))))
-      (setq char-list (cdr char-list)))
-    result))
+  (concat char-list))

 (defun artist-string-to-charlist (str)
   "Convert a string, STR, to list of characters."
@@ -4908,7 +4904,7 @@


 (defun artist-mouse-draw-continously (ev)
-  "Generic function for shapes that requires 1 point as input.
+  "Generic function for shapes that require 1 point as input.
 Operation is done continously while the mouse button is hold down.
 The event, EV, is the mouse event."
   (let* ((unshifted    (artist-go-get-symbol-shift artist-curr-go nil))