comment-line(3)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

NAME

comment-line - Comment out the current line
uncomment-line - Uncomment current line

comment-to-end-of-line - Extend comment to end of line
comment-restyle - Reformat the current comment

comment-start - Start a new comment
comment-end - End the current comment

SYNOPSIS

n comment-line
n uncomment-line

comment-to-end-of-line
comment-restyle

comment-start
comment-end

DESCRIPTION

The action of the comment commands are file type specific (comments in C are /* ... to ... */ where as MicroEmacs macro file comments are ; ... to the end of line) so the commands must be configured for each file type (see the NOTES section below). The configuration is automatically performed by almost all the standard file hooks released with MicroEmacs by the file hook so these commands should be fully functional.

comment-line comments out the current region, if active and n is omitted, or the current and next n-1 lines (default when n is omitted is to comment out just the current line). The cursor is then moved to the start of the next line.

uncomment-line behaves in a similar way, except that for a file type that has a start and end comment token, like C, it can effect lines outside the current region or line count if a comment goes beyond the start or end of the defined region. Note that uncomment-line also attempts to undo the effects of re-indenting a line that has been commented out, hopefully restoring the original indentation.

comment-to-end-of-line inserts comment-pads (see NOTES) up-to the $buffer-fill-col(5) and then terminates the comment with the comment-end string. comment-restyle reformats the text within the comment, filling text lines to the $buffer-fill-col and regenerating any boxing and divide lines.

comment-start opens a new "*comment*" buffer which is configured for writing a text comment, the user can then type in the comment with all the benefits of MicroEmacs in a plain text editor. Once the comment is complete use the comment-end command to insert the comment into the source file, this comment is locally bounded to "C-c C-c". The styling of the comment is controlled by the comment-flag setting (see NOTES).

NOTES

Consider the structure of a box comment to be as follows:

<comment-start><comment-pad><comment-pad><comment-pad><comment-box-right> 
<comment-box-left> COMMENT TEXT ... COMMENT TEXT      <comment-box-right> 
<comment-box-left> COMMENT TEXT ... COMMENT TEXT      <comment-box-right> 
<comment-box-left><comment-pad><comment-pad><comment-pad><comment-end>

The comment commands are configured by the single file hook command variable .fhook-<type>.comment where <type> is the file type label. The structure of the variable is a list with the following format:

    |<comment-start>|<comment-end>|<comment-pad>|<comment-box-left>|... 
        ...<comment-box-right>|<comment-flags>|

Where | is the list divide character. The <comment-flags> are a list of character flags which are defined as follows:

b

<comment-box-right>

f

Footer line required.

F

<comment-pad>

h

Header line required.

H

<comment-pad>

j

Enable Justify mode in *comment* buffer.

r

esc o

esc q

comment-restyle(3)

EXAMPLE

The following comment is the standard C setting:

set-variable .fhook-c.comment "|/*| */|*| * | * |f|"

This can be used to create comments of the form:

/* comment-line comments out the current and next n-1 lines (default 
 * when n is omitted is to comment out just the current line). The 
 * cursor is then moved to the start of the next line. 
 * 
 * uncomment-line behaves differently depending on whether the file 
 * type terminates a comment with an end token or simply by the end 
 * of the line. 
 */

A box style comment can be generated by changing the <comment-flags> form f to bfFhH, producing: