rebox.el

;;; Handling of comment boxes.
;;; Copyright (C) 1991, 92, 93, 94, 95, 96, 97 Free Software Foundation, Inc.
;;; François Pinard <pinard@iro.umontreal.ca>, April 1991.

;;; I first observed rounded corners, as in style 223 boxes, in code from
;;; Warren Tucker <wht@n4hgf.mt-park.ga.us>, a previous shar maintainer.

;;; Refilling paragraphs inside comments, stretching or shrinking the
;;; surrounding box as needed, is a pain to do "by hand".  This GNU Emacs
;;; LISP code eases my life on this and I find it fair, giving all sources
;;; for a package, to also give the means for nicely modifying comments.

;;; The function rebox-comment discovers the extent of the boxed comments
;;; near the cursor, possibly refills the text, then adjusts the comment
;;; box style.  The function rebox-region does the same, except that it
;;; takes the current region as a boxed comment.  Numeric prefixes are
;;; used to add or remove a box, change its style (language, quality or
;;; type), or to prevent refilling of its text.  A minus sign alone as
;;; prefix asks for interactive style selection.

;;; For most Emacs language editing modes, refilling does not make sense
;;; outside comments, so you may redefine the M-q command and link it to
;;; this file.  For example, I use this in my .emacs file:

;;;	(setq c-mode-hook
;;;	      '(lambda ()
;;;		 (define-key c-mode-map "\M-q" 'rebox-comment)))
;;;	(autoload 'rebox-comment "rebox" nil t)
;;;	(autoload 'rebox-region "rebox" nil t)

;;; The cursor should be within a comment before any of these commands,
;;; or else it should be between two comments, in which case the command
;;; applies to the next comment.  When the command is given without prefix,
;;; the current comment box style is recognized from the comment itself
;;; as far as possible, and preserved.	A prefix may be used to force
;;; a particular box style.  A style is made up of three attributes: a
;;; language (the hundreds digit), a quality (the tens digit) and a type
;;; (the units digit).	A zero or negative flag value changes the default
;;; box style to its absolute value.  Zero digits in default style,
;;; when not overriden in flag, asks for recognition of corresponding
;;; attributes from the current box.  `C-u' avoids refilling the text,
;;; using the default box style.  `C-u -' defines the style interactively.

;;; Box language is associated with comment delimiters.  Values are 100
;;; for none or unknown, 200 for `/*' and `*/' as in plain C, 300 for
;;; '//' as in C++, 400 for `#' as in most scripting languages, 500 for
;;; `;' as in LISP or assembler and 600 for `%' as in TeX or PostScript.

;;; Box quality differs according to language.	For unknown languages (100)
;;; or for the C language (200), values are 10 for simple, 20 or 30 for
;;; rounded, and 40 for starred.  For all others, box quality indicates
;;; the thickness in characters of the left and right sides of the box:
;;; values are 10, 20, 30 or 40 for 1, 2, 3 or 4 characters wide.  C++
;;; quality 10 is always promoted to 20.  Roughly said, simple quality
;;; boxes (10) use comment delimiters to left and right of each comment
;;; line, and also for the top or bottom line when applicable.	Rounded
;;; quality boxes (20 or 30) try to suggest rounded corners in boxes.
;;; Starred quality boxes (40) mostly use a left margin of asterisks or
;;; X'es, and use them also in box surroundings.  Experiment a little to
;;; see what happens.

;;; Box type values are 1 for fully opened boxes for which boxing is done
;;; only for the left and right but not for top or bottom, 2 for half
;;; single lined boxes for which boxing is done on all sides except top,
;;; 3 for fully single lined boxes for which boxing is done on all sides,
;;; 4 for half double lined boxes which is like type 2 but more bold,
;;; or 5 for fully double lined boxes which is like type 3 but more bold.

;;; The special style 221 or 231 is worth a note, because it is fairly
;;; common: the whole C comment stays between a single opening `/*'