DESCRIPTION

comment has two modes of operation. In its normal mode, it reads input text, and formats it as comments for the given programming language. In its header mode (option -H, it generates a program header in a standard format.

In the formatted output, the lines are normally made up of four fields, indent, left margin, text and right margin. The indent is calculated from the -n and -i options, by multiplying them together; it consists of so many spaces. The left margin consists of the opening comment string (option -co or -c+,, but more often set indirectly by means of the -l option), plus any characters for documentation tool (option -d), right padded to the margin width (option -m). The right margin is only present if the closing comment string (option -cc or -c-, but more often set indirectly by means of the -l option) is not empty; it consists of the closing comment string, left padded to the margin width. The text field is the text from input, formatted to the remaining width of the line (width - indent - 2*margin, width as per the -w option). There are several exceptions, however, where the padding will not be added to the opening and closing comments (and if the closing comment is the empty string, the text will be extended to the right by as many characters as would be in the right margin.)

(In the following, sample output is given in C so that the left margin handling will be visible. Also, we've greatly reduced the page width. That is, we always use the options -lc -w 56)

A documentation tool string (specified by the -d option) can be automatically appended after the opening comment; it will not be inserted in automatically generated lines like the header and footer rule. When a documentation tool string has been specified, the padding in the margin will be suppressed for lines begining with one of the meta characters specified by the -M option; these lines will not be formatted, either (but will be padded and have a closing comment appended if the closing comment string is not empty). This feature may be used to visually separate certain documentation commands from the rest of the comment, e.g. with -d! -M@:

      /*!@brief                                             */
      /*!     Formatted text.  You can see how the          */
      /*!     command @brief is set out from the rest       */
      /*!     of the comment.                               */
    

Header and footer lines are created by the options -hc and -fc. In such lines, the margin is ignored: one space is inserted between the opening and closing comment string, even this space is suppressed if the adjacent character (last character of opening comment, first of closing comment) is the same as the character being used to make the line. (For example, in C, a footer created by -f- would look like:

      /* -------------------------------------------------- */
    

and a header created by -h* would be:

      /******************************************************/
    

Note that comment will not insert the documentation tool string (see below) in header and footer lines.

Any time the first line ends with the character ':', and is followed by an empty line, comment treats it as a title. If the -uc option is set, the title will be underlined with the given character. Otherwise, if the -hc option (header line) is set, and the -U option is not set, the title will be underlined with the character used to draw the header line. If either the -U is given, or neither the -h option or the -u is given, the title will be treated like any other text. Thus, for example, given the text:

      Function name:

      Some text
    

The options -h= -f- will result in (language C):

      /* ================================================= */
      /*         Function name:                            */
      /*         ==============                            */
      /*                                                   */
      /*         Some text.                                */
      /* ------------------------------------------------- */
    

This is a bit heavy, and more often, for a simple function, we will use something like -u- -f-:

      /*         Function name:                            */
      /*         --------------                            */
      /*                                                   */
      /*         Some text.                                */
      /* ------------------------------------------------- */
    

Note that comment will not insert the documentation tool strings in the title lines. Thus, the options -u- -f- -d ! will generate:

      /*         Function name:                            */
      /*         --------------                            */
      /*                                                   */
      /*!        Some text.                                */
      /* ------------------------------------------------- */
    

comment supports a very primitive mark-up language, based on the use of tab characters. (It is sufficient to make lists, but that's about all.) Basically, anytime a tab character is seen, the indentation is memorized, and used on all following lines in the paragraph. For example:

      /*      This is previous text.                        */
      /*                                                    */
      /*       -- This is an indented paragraph.  In        */
      /*          the source, the line beginning this       */
      /*          paragraph begins with a single            */
      /*          blank, and there is a single tab          */
      /*          character between the -- and the          */
      /*          rest of the text                          */
      /*                                                    */
      /*      And this is following text.                   */
    

Indentation using blank characters is ignored. There is no option to set tab stops; the indent width (option -i) is used.

In header mode, the text to be formatted is not read from input, but automatically generated, according to the following model (here, using -m 4 -H in addition to our usual options):

      /******************************************************/
      /*  File:       filename                              */
      /*  Author:     J. Kanze                              */
      /*  Date:       10/11/2005                            */
      /*      Copyright (c) 2005 James Kanze                */
      /* -------------------------------------------------- */
    

The text fields in the first three text lines can be set by the -F, -P and -D options; a single filename argument can replace the -F. There is no default for the first line; either a -F option or a filename argument must be given. For the second line, the environement variable $PROGRAMMER is used if no -P option is given; if neither is present, it is an error. For the third, the current date is used if there is no -D option. The fourth text line always starts with the indented string "Copyright (c) ". This will be followed by the text given by the -C option, if given, otherwise by the year from the data (either the -D option or the current data) and the organization, as specified by the -O option, or the environment variable $ORGANIZATION. Note that the entire line can be suppressed by passing an empty string to the -C option.

OPTIONS

The following options are supported:

-H

Selects header mode.

-fc

Draw a footer line, using character c.

-hc

Draw a header line, using character c. If neither -u nor -U are present, will also cause a title to be recognized and underlined with the character c.

-uc

Recognize a title, and underline it using the character c.

-U

Do not recognize a title. This option is only useful when the -h option has been given, to suppress the recognition of a title.

-n

Specifies the level of indentation (level = n, n must be a decimal integer). Default 0 (no indentation).

-i n

specifies the number of spaces per level of indentation (default 4). The actual indentation will be the product of this and the -n option. This value is also used for internal indentation.

-m n

Specifies the margin size, used for both left and right margins. Defaults to 8.

-w n

Specifies the total width to be used, inclusive indentation, margins and formatted text. Defaults to 78.

-E

Use "European" typesetting. By default, comment will put two spaces after any sentence ending punctuation (e.g. any character in the set {.!?}, followed by zero or more characters in the set {"')]}). If this option is given, it will only insert one. Not used when -H has been given. (Latex calls this "frenchspacing", but standard typesetting practice in both France and Germany calls for normal interword spacing after sentence ending punctuation.)

-llang

Specifies the language to be used in determining the default opening and closing comment strings. Accepted values of lang are:

lang	comment strings		language
	opening	closing
A	#		AWK
C	//		C++
P	{	}	Pascal and family (e.g. Modula)
S	;		Intel ASM-86
a	--		Ada
c	/*	*/	C
j	//		Java
l	;;		Lisp
m	#		Make
p	(*	*)	Pascal (alternative)
s	#		Shell (Unix)

Note that no space is allowed between the -l and the language specifier. The default is C++ (-C).

-co string or -c+ string

Opening comment string. The default is that specified by the -l option. (This option is rarely used, but is necessary for a language not provided for.)

-cc string or -c- string

Closing comment string. The default is that specified by the -l option. (This option is rarely used, but is necessary for a language not provided for. It may also be used if it is desired to add a closing comment indicator in languages not using one.)

-d sring

Documentation tool string. This option is used to add a string to the end of the opening comment string, for documentation tools like Doxygen (-d !) or JavaDoc (-d /). Not used when -H has been given.

-M string

Characters to be recognized as meta-characters; a line which starts with one of these characters will not have a left margin, and will not be formatted. Not used when -H has been given.

The following additional options are used in header mode (option -H given):

-F filename

Specifies the filename to be used in the header. This file is not opened or read, and need not even exist. Either this option or a single filename argument (but not both) must be given.

-P programmer

String to be used as the author's name in a header, defaults to the contents of the environment variable $PROGRAMMER. If the environment variable has not been set, this option must be given.

-D date

Specifies the date to be used, both in the header text, and as year for the copyright. Must be a string in the format "DD/MM/YYYY", where DD, MM and YYYY are decimal digits specifying the day, the month and the year respectively, and the / may be replaced by any convenient punctuation. (Note that day and month must be two digits, and year 4. Feb. 1, 2005 would thus be "01/02/2005".) Defaults to the current date.

-O organization

Specifies the organization which should own the copyright. Defaults to the contents of the environment variable $ORGANIZATION. If this variable is not set, either this option or the -C option must be given.

-C string

Specifies the string to be used after the text "    Copyright (c) " in the copyright message. If this option is not specified, the year (extracted from the date) followed by the organization (see option -O, above) will be used. If this option is not present, the organization must be present, either as an option or via the environment variable. If this option is set to the empty string (-C '' under most Unix shells), the entire copyright line will be surpressed.

OPERANDS

The following operands are supported:

file

In normal most, A pathname of an input file. If no file operands are specified, the standard input shall be used. (For header mode, see the -F option, above.)

EXIT STATUS

0	no error.
2	One of the input files could not be opened.
3	Hardware error on standard out.

BUGS

This should really be two separate programs, comment and header.

The text in header mode is far to rigid. The program really should read from a template, inserting the variable text where indicated.