comment-line(3)

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 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. If an end token is used then uncomment-line removes the current and next n comments. If the end of line is used uncomment-line removes the first comment on the current and next n-1 lines.

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


Box format required, i.e. create right edge using <comment-box-right>.

f


Footer line required.

F


Fill footer line with <comment-pad> strings.

h


Header line required.

H


Fill header line with <comment-pad> strings.

j


Enable Justify mode in *comment* buffer.

r


A restyle key binding is added to the buffer "esc o" and "esc q" buffer key bindings are added and bound to 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:

/********************************************************************* 
 * 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.                                                      * 
 *********************************************************************/ 

SEE ALSO

buffer-init(3), File Hooks.

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12