14. Marked Sections

Marked section (i.e. sections of a document that have been marked for a special purpose) are enclosed in marked section tags. The special treatment of a marked section is reflected by the marked section status that is displayed in the start and end tag of the marked section.

When a marked section is created, zero or more status keywords can be supplied that specify what kind of special treatment the marked section should receive. The following status keywords are recognized by the sgml widget:

• ignore

  The contents of the marked should be ignored.

• include

  The contents of the marked section should be included in the document.

• cdata

  The marked section contains character data in which no SGML elements, entity references, or markup declarations are recognized.

• rcdata

  The marked section contains replaceable character data in which no SGML elements and markup declarations are recognized. Entity references, however, are recognized and resolved by SGML applications.

• temp

  The marked section is flagged as temporary.

Although more than one status keyword can be present in the specification of the marked section, the effective status of the marked section is determined by the priority of the supplied status keyword. In the list above, status keywords with higher priority are listed before status keywords with lower priority.

If no status keywords have been specified for a marked section, the effective status defaults to include.

Marked sections in the sgml widget are identified my marked section handles. Like other handles, marked section handles are Tcl tokens that serve the single purpose of uniquely identifying a marked section in the document. Marked sections that occur in the document prolog can not be accessed by marked section handles.

Marked sections are manipulated by the markedsection widget command. For convenience, the markedsection command can be abbreviated by ms.

Marked section commands

ms allowed index
	Returns a boolean value indicating whether inserting a marked section at index is allowed or not.
ms at index
	Returns a handle for the marked section enclosing index or an empty string if index is not within a marked section.
ms delete handle
	Deletes the marked section identified by handle.
ms insert index ?spec?
	Creates a new marked section at index
ms index handle ?end?
	Returns an index for the marked section denoted by handle. If end has been specified, the index refers to the end tag of the marked section; it refers to the start tag if end has been omitted.
ms specification handle
	Returns the list of status keyword specifications for the marked section denoted by handle. The result is a proper Tcl list where each element is either a status keyword or the name of a parameter entity (starting with %).
ms status handle
	Returns the effective status of the marked section denoted by handle. The result is one of the status keywords CDATA, RCDATA, IGNORE, INCLUDE, or TEMP.

14.1 Inserting marked sections

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

pathname ms allowed index

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

Marked sections are inserted into the document by the ms insert command that has the general form

pathname ms insert index ?keyword...?

The command creates a new marked section at the location specified by index and returns a handle for the new marked section. The status keywords arguments are optional; omitting the status keyword arguments results in an effective status of include.

	.s ms insert 3.5 CDATA IGNORE
$\Rightarrow$	M8641e80

Any suitable parameter entities that have been defined in the DTD or the document prolog can be provided as status keywords. If a status keyword argument is not recognized as a valid marked section status keyword, the sgml widget looks in the list of known parameter entities for a parameter entity with that name.

	.s ms insert 3.5 draft
$\Rightarrow$	M8641e80

In the example above, the status keyword parameter draft is not recognized as a marked section keyword; the sgml widget examines the list of defined parameter entities to determine if it is the name of a parameter entity. If a parameter entity with the given name is found, the keyword parameter is accepted and the definition of the parameter entity is used to compute the marked section status.

If more than one status keyword arguments have been supplied, the effective status of the marked section is determined from the definition of the parameter entities in conjunction with all other marked section status keywords according to the priority scheme outlined above. If an undefined parameter entity name has been supplied as a status keyword argument, the sgml widget signals an error.

	.s ms insert 3.5 release
$\oslash$	Invalid status keyword or parameter entity "release"

In the unlikely case that a parameter entity has been defined with the same name as a marked section status keyword, the parameter entity name can be prefixed with the %-character to distinguish it from the status keyword.

14.2 Indices for marked sections

To retrieve a handle for a marked section enclosing an index, the widget command ms at can be used. The ms at command hast the following general form:

pathname ms at index

The command returns a handle for the marked section containing index or an empty string if index is not inside any marked section. For nested marked sections, the ms at command returns a handle for the innermost marked section.

	.s ms at insert
$\Rightarrow$	M8641e80

The index of a marked section can be retrieved using the ms index command. This command has the following general form:

pathname ms index handle ?end?

The required argument handle is a handle for a marked section that has been returned by the ms insert or ms at widget commands. Without the optional argument end, the ms index command returns the index of the start tag of the marked section. The returned index specifies the position immediately to the left of the marked section start tag; therefore it is outside of the marked section denoted by handle. To adjust the index to a location immediately behind the start tag, it should be advanced by 1 character.

If the optional argument end has been supplied, the ms index command returns the index of the end tag of the marked section. Again, the index specifies the position immediately to the left of the tag; therefore it is inside of the marked section denoted by handle.

The following example procedure utilizes the ms index command to return the text of a marked section:

The if-statement in line  checks if tags are currently shown in the widget and adjusts the start index by one character if yes. Since invisible tags do not have any index width, the index is not adjusted if tags are turned off to avoid loosing the first character of the marked section text.

14.3 Deleting marked sections

Marked sections are deleted using the ms delete delete widget command. The command requires one argument: a handle for the marked section to delete.

The general form of the command is

pathname ms delete handle

where handle must have been obtained from a ms insert or ms at widget command. The following example procedure shows how to delete the marked section at the position of the insertion cursor:

The ms delete widget command deletes the marked section and all its contents. After the deletion of the marked section, the handle to the marked section becomes invalid and must not be used any more.

14.4 Marked section status

The sgml widget provides two widget commands that deal with the status of a marked section: The ms status and the command ms specification command.

The ms status command requires a single argument which must be a marked section handle that has been provided by the sgml widget. The general form of the command is

pathname ms status handle

The command returns the effective status of the marked section as one of the keywords described above.

	.s ms status M8641e80
$\Rightarrow$	IGNORE

Like the ms status command, the ms specification command requires a marked section handle as an argument:

pathname ms specification handle

The ms specification command returns the list of status keywords that have been specified for the marked section identified by handle. The result is a Tcl list where each element of the list is a status keyword or the name of a parameter entity.

	.s ms specification M8641e80
$\Rightarrow$	{CDATA IGNORE}

If parameter entities have been used for specifying the status of the marked section, their name is prefixed with the %-character when returned by the ms specification command.

	.s ms specification M8641e80
$\Rightarrow$	{RCDATA %draft}