emacs make square block comments with right aligned border

Question

I need to write code comments with aligned borders on all four sides due to an externally enforced coding standard.

What's the easiest way, in Emacs, to:

1. Convert some text into a block comment in this format
2. Edit the text in a block comment and have Emacs reflow it correctly

Comment format examples:

#*****************************************************************************#
#* This is a block comment. It has right-aligned borders.                    *#
#*                                                                           *#
#* It can have separate paragraphs. Text in a long paragraph flows from one  *#
#* line to the next with one space of internal padding.                      *#
#*                                                                           *#
#* The right hand border is at char 78                                       *#
#*****************************************************************************#
sub MySub
{
  #***************************************************************************#
  #* The left hand edge of the comment is aligned with the current code      *#
  #* block, but the right hand border is still at char 78                    *#
  #***************************************************************************# 
  my $var = 3;
}

auto-fill-mode by itself doesn't preserve the right hand border.

Answer 1

The venerable and versatile library "rebox2" can do this.

To install, download https://raw.github.com/lewang/rebox2/master/rebox2.el into your site-lisp dir, and add the following to your .emacs file:

(require 'rebox2)

; The following template defines the specific style required here,
; which does not correspond to any built-in rebox2 style.
;
; "75" means that the style is registered as x75, where "x" depends
; on the current langauge mode. The "?" char is switched for the language
; specific comment char
;
; "999" is the weighting used for recognising this comment style.
; This value works for me.
(rebox-register-template
 75
 999
 '("?*************?"
   "?* box123456 *?"
   "?*************?"))

(add-hook 'perl-mode-hook (lambda ()
; The "style loop" specifies a list of box styles which rebox will cycle
; through if you refill (M-q) a box repeatedly. Having "11" in this loop
; will allow you to easily "unbox" a comment block, e.g. for "uncomment-region"
                (set (make-local-variable 'rebox-style-loop) '(75 11))
; The "min-fill-column" setting ensures that the box is not made narrower
; when the text is short
                (set (make-local-variable 'rebox-min-fill-column) 79)
                (rebox-mode 1)))

Now:

1. To convert some text into a block comment in this format, you just select the text and do M-q
2. To edit the text in a block comment, you can just edit the text directly, and emacs will reflow the box automatically. (You may need to do M-q to request a reflow if emacs doesn't automatically do it.)

Answer 2

M-x customize-variable RET comment-style RET

Then choose "box" from value-menue

Answer 3

You could use yasnippet for inserting and overwrite-mode for editing.

If you want word wrapping, you could also kill rectangle C-x r k, switch to a temp buffer C-x b, yank rectangle C-x r y. Edit there to your heart's content. Afterwards, kill rectangle from the temp buffer and paste into your source.

Here's the block begin/end snippet:

# -*- mode: snippet -*-
# name: block comment
# key: bb
# --
`(concat "#" (make-string (- 80 aya-tab-position) ?*) "#")`
$0
`(concat "#" (make-string (- 80 aya-tab-position) ?*) "#")`

Here's the block line snippet:

# -*- mode: snippet -*-
# name: block comment line
# key: bl
# --
`"#* "`$1${1:$(make-string (- 78 aya-tab-position (length text)) ? )}#

Note that I'm using here the auto-yasnippet package variable aya-tab-position. To use it in a snippet, you have to expand the snippet with aya-open-line. You can get both packages from MELPA.

Answer 4

A partial answer to (1) (but I'd love to hear a better one):

• Type the comment para as plain text
• M-x set-fill-column 76
• Place the cursor at the start of the comment para and manually typing in the opening "#* " (note space)
• With the cursor at the first letter of the comment para, run M-x set-fill-prefix
• Now use M-q to reflow the para
• This will sort the word wrapping and put the left hand border in place.
• Finally, manually add the top, bottom and right hand borders.

See http://www.gnu.org/software/emacs/manual/html_node/emacs/Fill-Prefix.html

The same approach can be used for some of (2):

• Ensure that set-fill-column and set-fill-prefix are correct (see above)
• Delete all the right hand border markers
• Reflow the para using M-q
• Finally, manually add the top, bottom and right hand borders.