15. Comments

Comments in the document instance are represented by a pair of comment tags which enclose no further data and where the start tag contains the text of the comment. Comments in the document can be manipulated by using comment handles which refer to the individual comments.

Comment commands

comment allowed index
	Returns a boolean value indicating whether inserting a comment at index is allowed or not.
comment at index
	Returns a handle for the comment enclosing index or an empty string if index is not within a pair of comment tags.
comment delete handle
	Deletes the comment identified by handle.
comment insert index
	Creates a new comment at index.
comment index handle ?end?
	Returns an index for the comment denoted by handle. If end has been specified, the index refers to the end tag of the comment; it refers to the start tag if end has been omitted.
comment text handle ?text?
	Returns or sets the comment text for the comment identified by handle.

15.1 Inserting comments

To determine whether a comment may be inserted at a given index in the sgml widget, the command comment allowed can be used. The command that has the general form

pathname comment allowed index

and returns a boolean value indicating whether a comment may be inserted at index or not.

Insertion of comments is performed by the comment insert widget command that has the general form

pathname comment insert index

The command creates a new comment at the location specified by index and returns a handle for the new comment.

	.s comment insert 3.5
$\Rightarrow$	C642103e

15.2 Getting a comment handle

To get a handle for the comment enclosing an index, the comment at widget command can be used.

pathname comment at index

The command returns a handle for the comment enclosing index or an empty string if index is not within a comment.

15.3 Modifying comments

Since the text of a comment is not displayed like document data, all modifications to a comment must use the comment text widget command. The command has the general form

pathname comment text handle ?newText?

When the optional argument newText is not specified, the command returns the current text of the comment identified by handle. To substitute the current comment text by a new comment text, the new text must be supplied as the last (optional) argument to the comment text widget command.

15.4 Deleting comments

Comments can be deleted by passing a handle for the comment to the comment delete widget command.

pathname comment delete handle

The comment delete command destroys the comment identified by the argument handle and invalidates the comment handle. After the comment has been deleted, the comment handle should not be used any more.