4

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.

Rich
  • 15,048
  • 2
  • 66
  • 119
  • Maybe try `artist-mode`? I'm not sure you can change the character it uses to draw boxes, but chances are it won't be too difficult to change, if not already possible. –  Aug 13 '13 at 14:53

4 Answers4

3

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.)
Rich
  • 15,048
  • 2
  • 66
  • 119
  • Hi @Rich, When the lines in the comment box is increasing, typing the `Space` key after words or just pure continual `Space` keys which is replaced by `rebox-space` in the rebox comment box will become very laggy. This happends to me when I'm coding in C. Do you know how to solve this problem??? I posted an issue at the Github site, but the author did't update it for years. – CodyChan Sep 25 '14 at 02:12
  • @CodyChan - no idea, sorry – Rich Sep 25 '14 at 09:29
2

M-x customize-variable RET comment-style RET

Then choose "box" from value-menue

Andreas Röhler
  • 4,804
  • 14
  • 18
  • This looks close, but has a few problems for me. The lines are all "####", not "#****#" as in the examples. There is no inner "*" border on the left and the right. The width is not correct. – Rich Aug 13 '13 at 15:27
  • @Rich AFAIU which chars are used depends from the kind of comment defined. See in newcomment.el from line 967, ;; box comment. The filling char might be hacked there. – Andreas Röhler Aug 13 '13 at 16:02
1

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.

abo-abo
  • 20,038
  • 3
  • 50
  • 71
0

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.
Rich
  • 15,048
  • 2
  • 66
  • 119