13. Entities

The sgml widget supports both general entities and parameter entities. It provides access to the entities defined in the document prolog and allows the user to define new entities.

The entity command

entity allowed index
	Returns a boolean value indicating whether an entity reference may be inserted at index or not.
entity at index
	Returns a handle for the expanded text entity containing index
entity defined ?options? ?entityName?
	Returns information about defined entities. If entityName name is omitted a list of all defined entities is returned. If entityName is specified, then a boolean value is returned that indicates if entity has been defined or not. Additional options can be used to restrict the result to entities with specific characteristics or to change the result format.
entity display how
	Specifies how entity references should be displayed. If how is set to name, the entity name is shown. If how is set to content, the character replacement is shown instead of the entity name if one has been defined for this entity by the charmap command.
entity index handle ?end?
	Returns the index of the start or end tag of the expanded text entity identified by handle.
entity show entity ?what?
	Specifies what should be display for an entity reference if the display mode has been set to content. If what is provided, it can be an arbitrary string that is shown instead of the entity name. If what is omitted, the command returns the string that is displayed for the entity reference (or an empty string if no such mapping has been defined).
entity insert entityName index
	Inserts a reference to entity at location specified by index. Fails if the DTD does not allow data content at index
entity type name
	Returns a keyword indicating the data type of the entity name. The result is one of the values cdata, sdata, ndata, text, or pi.
entity unlock handle
	Removes the lock on an expanded text entity identified by handle.
entity local name
	Returns a boolean value indicating whether the entity name was locally (i.e. in the document) defined or not.
entity external name
	Returns a boolean value indicating whether the entity name is an external entity or not.
entity expand name ?boolean?
	Returns or sets the expansion state of the entity name.
entity text name
	Returns the entity text for the internal entity name. Fails if name is not an internal entity.
entity sysid name
	Returns the effective system identifier for the external entity name. Fails if name is not an external entity.
entity notation name
	Returns the notation for the external entity name or an empty string if name is an SGML text entity. Fails if name is not an external entity.
entity configure name option ?value option value ...?
	Query or modify the configuration options for entity name. If only the option argument is supplied, the command returns the current value of the configuration option option. If a value is supplied, the configuration option option is set to this value. In this second form, any number of option-value pairs can be specified.

The sgml widget maintains as list of defined entities, the entity list. The entity list is constructed when a new document is created or when an existing document is loaded into the sgml widget (i.e. every time when a DTD is loaded into the sgml widget as a part of the document prolog). The entity list is modified when new entities are declared or when existing entity declarations are removed.

Each element of the entity list is a pair of an entity name and the entity text associated with this name.

Entities are shown in the sgml widget either as entity names (delimited by the entity reference delimiters ERO, normally &, and REFC, normally ;) or as the entity text. To change the way how entity names are displayed, the entity display widget command can be used.

13.1 Inserting entities

Entities can be inserted into the sgml widget in two ways: The entity insert widget command can be used to create an entity at a specific index. The following command inserts the &auml entity at the beginning of the third line of the document instance in the sgml widget .s:

	.s entity insert auml 3.0
$\Rightarrow$	1

This is a somehow artificial construct, however. Normally, insertion of entities would occur at the location of the insertion cursor (denoted by the reserved index name insert). The following command would insert the &auml entity at the current insertion location:

.s entity insert auml insert

13.2 Modifying the display

Entities references can be displayed as entity names or as an arbitrary string.

The entity name is the character sequence that is used to refer to the entity in the SGML document. For example, the entity for the German sz character has the name szlig and is usually mapped to the character ß. Depending on the the current display mode for entities, this entity would be displayed either as ß or as ß.

The entity display mode can be changed with the entity display command.

entity display mode

where mode is either name or content. Independently of the current display mode, each entity reference counts as a single character.

If the entity display mode is set to content, the ????

13.2.1 XML and Entities

The XML declaration for XML documents defines the five entities amp, lt, gt, quot, and apos. These entities are available even in documents that are only well-formed (i.e. documents without a DTD).

13.3 Defining new entities

New general entities can be declared by using the entity declare command. The basic form of the command is entity declare name option ?options...? where name is the name of the entity to be declared and the options specify how the entity should be declared. The following options are available:

• -system sysid

  his option declares the entity to be an external entity with a system identifier sysid.

• -public pubid

  This option is used to declare an external entity with a public identifier pubid. The public identifier is resolved using the SGML catalog to construct a system identifier for the entity.

• -type type

  The value of this option is the data type of the entity replacement text. For internal entities, the value of this option can be one of the predefined keywords CDATA, SDATA, or PI. For external entities, it can be CDATA, SDATA, or NDATA. If this option is not specified, the entity is assumed to contain SGML text.

• -text text

  The value of this option is the replacement text of the entity. The interpretation of the entity text depends on the value of the type option. If no entity type has been provided, the entity is declared as an internal text entity. This option can not be used if an external entity is declared.

• -notation notation

  The value of this option is the notation name for an external entity. The notation name must be known to the sgml widget. This option can only be used for external entities, i.e. in the presence of the -public or -system options.

• -attribute attname attval

  This options allows the specification of data attributes for external entities and requires the presence of a -notation option. The option can be used repeatedly to specify more than one data attribute. All attributes are checked against the attributes of the notation.

At least one of the options -system, -public, or -text has to be supplied.

	.s index insert
$\Rightarrow$	3.2
	.s entity insert myEntity 3.2
$\oslash$	no such entity in current DTD "myEntity"
	.s entity declare myEntity -text "text of my entity"
	.s entity insert myEntity 3.2

The entity definition is stored in the document prolog within the document instance.

13.3.0.1 Using public or system identifiers for external entities

When external entities are defined, both public and system identifiers can be used to specify the storage location of the entity.

Simple or formal system identifiers can be used for external entities. See section  for more details on system identifiers. When a system identifier is specified, the SGML catalog is queried for a possible replacement of the system identifier (which could be specified with a SYSTEM entry in the catalog file).

A relative system identifier is resolved relative to the location of the document. For documents that have been loaded from an operating system file or by the http protocol, this location is the storage of the document. For new documents (or for documents that have been loaded from other types of storage locations such as Tcl channels or literals), the base storage location for resolving relative system identifiers is the current directory.

When a public identifier is used to specify the storage location of an external entity, the public identifier is resolved using the SGML catalog and the resulting system identifier is used when the entity is referenced.

The lookup of public and system identifiers occurs when the entity definition is processed; modifications of SYSTEM or PUBLIC entries in the SGML catalog will have no effect after the entity definition has been processed. The only exception to this rule is the validation of the document (see chapter  for details). It is advisable to reload an sgml document after SGML catalogs have been modified.

13.3.1 Removing entity definitions

The definitions of all entities that are defined in the document instance (and not in the DTD) can be removed using the entity undeclare command. The basic form of the command is
entity undeclare name

where name is the name of the entity that should be removed. This command will fail if the entity in question has not been declared in the document instance or if the document still contains references to this entity.

13.4 The character map

Entities can be inserted semi-automatically by using the charmap table. This table stores translations of single characters to entity names and is consulted whenever data is inserted into the sgml widget (unless the data is inserted while the document is loaded from a file or the character mapping mechanism has been disabled).

The charmap command

charmap enable ?boolean?
	Query or set the status of character to entity mapping. If boolean is omitted returns the current status of the character to entity mapping facility. Turns character to entity mapping on or off if boolean is supplied.
charmap list
	Returns a list of all currently defined mappings. Each list element is a list itself, consisting of a single character and the name of the entity to which the character is mapped.
charmap c ?entityName?
	Query or set the character to entity mapping for character c. Establishes character to entity mapping for c if entityName is supplied. Returns the entity mapping for character c if entityName is omitted. To cancel a character mapping, an empty string can be supplied as entityName.

Although the charmap table can be changed by the charmap widget command, it is mostly sufficient to rely on the automatic initialization of the charmap table: When internal entities are defined during the parsing of the document prolog, every entity is examined regarding its definition (the entity name) and their content (the entity text). If the following two conditions are met, the charmap table is updated automatically for the entity:

• The entity text has to be defined as data text, i.e. the entity has to be declared CDATA.
• The entity text has be exactly one character long

<!ENTITY Atilde CDATA "&#195;" -- capital A, tilde -->

Whenever an entity is defined to contain character data

The entity map can be accessed using the charmap widget command.

13.4.1 Character to Entity Mapping

Most of the time, entities are inserted to refer to special characters that are either not easily displayable, that are not represented in the underlying character set, or that would require additional processing steps (such as font selection) to be properly displayed.

As a shortcut for entering some of these entities, the sgml widget maintains an entity map for single-character entities. This map contains pairs of single characters and entity references and is consulted whenever data is inserted into the sgml widget. If a character-entity pair is found for a character that is to be inserted into the sgml widget, this character is replaced by the corresponding entity reference.

The primary purpose of this approach is to simplify editing of documents in languages that need to use characters that are usually represented by entities, e.g. accented characters.

13.4.2 Construction of the entity map

charmap list

Returns a Tcl list that contains pairs of characters and entity names.

charmap enable ?status?

Returns or sets the status of character to entity mapping. If used without the optional boolean parameter status, the command returns the current mapping status as a boolean value. If the status parameter is supplied, the mapping status is set to this value which can be any string acceptable to Tcl_GetBoolean.

charmap c ?entity?

Returns or sets the current entity map entry for the character c. If

13.5 Text entities

Text entities are support in two ways, depending on the setting of the -expandtext configuration options.

• If the expandtext option is set to true, the widgets expands a reference to a text entity and inserts the contents of the text entity into the document, delimited by text entity tags.
• if expandtext is false, any references to text entities are treated like other entity references and normal entity references are displayed by the sgml widget.

Expansion of text entities is performed when a document is loaded or when a text entity is inserted into the document. The content of expanded text entities is locked by the sgml widget to prevent modification of the entity.

13.5.1 Inserting text entities

Since the text entity content needs to be inserted (instead of a simple entity reference), certain restrictions apply to text entities that can be inserted by the entity insert command. These restrictions are described below:

• A text entity must be defined in such a way that all markup contained in the text entity is properly nested. While it is in theory possible (but not advisable) to define text entities that contain improperly balanced markup tags, such entities can not be inserted by the sgml widget.
• The text entity must not be a bracketed text entity (i.e. it should not be a defined as STARTTAG, ENDTAG, MS, or MD).
• The text entity content must not use any markup minimization other than end tag omission for empty elements.

If a text entity definition does not adhere to these restrictions, the entity insert command will refuse to insert the entity.

These restrictions do not apply when a document is loaded into the sgml widget. Text entities are always properly resolved and inserted when a document is loaded.

13.5.2 Unlocking of text entities

Expanded text entities can be unlocked and, after unlocking, modified like any other document content. In order for a text entity to be unlocked, the following conditions must be met:

• If the text entity is an external entity, it must be handled by one of the CHANNEL, TCL, OSFILE, or OSFD storage managers.
• If the text entity is an internal text entity, then it must be declared in the prolog of the document instance.

The sgml widget will refuse to unlock an text entity that violates these criteria.

If a text entity has been unlocked with the entity unlock widget command, it will be treated as a part of the document instance. When the document is saved, however, the content of the text entity is written to the original location from which it was loaded.

13.6 Parameter entities

Within the sgml widget, access to parameter entities is limited to parameter entities that might function as status keyword specifications in marked sections (see chapter  for further information).

13.7 Configuring entities

Entities can be configured with the configuration options described below. All of these options (except for -image, -padx, -pady, and -align) only take effect if a replacement text is displayed for the entity reference.

• -image image

  Specifies an image that should be shown at the place of the entity reference. The widget must have been create with the image create command. (see image(n) for details.)

• -padx pixels

  Pixels specifies the amount of extra space to leave on the top and bottom sides side of the image. It may have any of the usual forms defined for a screen distance.

• -pady pixels

  Pixels specifies the amount of extra space to leave on each side of the image. It may have any of the usual forms defined for a screen distance.

• -align where

  If the image is not as tall as the line in which it is displayed, this option determines where the image is displayed in the line. Where must have one of the values top (align the top of the image with the top of the line), center (center the image within the range of the line), bottom (align the bottom of the image with the bottom of the line's area), or baseline (align the bottom of the image with the baseline of the line).

• -background color

  Color specifies the background color to use for characters when displaying the replacement text of the entity. It may have any of the forms described in section .

• -bgstipple bitmap

  Bitmap specifies a bitmap that is used as a stipple pattern for the background. It may have any of the forms described in section . If bitmap hasn't been specified, or if it is specified as an empty string, then a solid fill will be used for the background.

• -borderwidth pixels

  Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the entity replacement test (if such a border is being drawn; the -relief option typically determines this). The value may have any of the forms acceptable as a screen distance (cf. section ).

• -fgstipple bitmap

  Bitmap specifies a bitmap that is used as a stipple pattern when drawing text and other foreground information such as underlines. If bitmap hasn't been specified, or if it is specified as an empty string, then a solid fill will be used.

• -font fontName

  FontName is the name of a font to use for drawing characters. If this option is set, it will override any values specified by the -family, -italic, -bold, and -size configuration options.

• -foreground color

  Color specifies the color to use when drawing text and other foreground information such as underlines. It may have any of the forms described in section .

• -offset pixels

  Pixels specifies an amount by which the baseline of the replacement text should be offset vertically from the baseline of the overall line, in pixels. For example, a positive offset can be used for superscripts and a negative offset can be used for subscripts. Pixels may have any of the standard forms for screen distances.

• -relief relief

  Relief specifies the 3-D relief to use for drawing backgrounds, in any of the forms described in section . This option is used in conjunction with the -borderwidth option to give a 3-D appearance to the background for characters; it is ignored unless the -background option has been set for the entity.

• -spacing4

• -spacing5

• -underline boolean

  Boolean specifies whether or not to draw an underline underneath characters. Boolean may have any of the forms described in section .

• -overstrike boolean

  Specifies whether or not to draw a horizontal rule through the middle of the characters of the entity replacement text. Boolean may have any of the forms described in section .

• -italic boolean

  Specifies whether characters are to be italicized or not. The value may have any of the forms described in section .

• -bold

  Specifies whether characters are to be printed in bold font or not. The value may have any of the forms described in section .

• -size

  Specifies the default font size of the replacement. If the size argument is a positive number, it is interpreted as a size in points. If size is a negative number, its absolute value is interpreted as a size in pixels. If a font cannot be displayed at the specified size, a nearby size will be chosen. If size is unspecified, the font size is determined by the enclosing text.

• -family

  Specifies the default font family for the entity replacement text. If the family is unspecified or unrecognized, the font size is determined by the surrounding text.

13.8 Notations

External sgml entities other than text entities need to be further described by specifying a notation for the external entity. The notation is used by SGML systems determine how the content of the external entity should be processed.

The notation command

notation attlist notation ?attribute?
	Returns information about notation attributes. Returns a list of the attributes that were defined for the notation if attribute was omitted. If attribute was specified, a description of the attribute is returned.
notation defined ?notation?
	Query defined notations. If the notation name is omitted a list of all defined notations is returned. If notation is specified, then a boolean value is returned that indicates if notation has been defined or not.

The sgml widget itself does not rely on the notation information for external entities because it deals only with references to these entities, not with the entity content itself. Therefore, support for notations is limited to accessing the list of defined notations and querying the properties of these notations.