1. Introduction

1.1 About TkSGML

This document describes the sgml widget, an extension to the Tk toolkit. Tk is a system for providing a graphical user interface to programs written in the Tool Command Language (Tcl). The internals of Tcl and Tk are not discussed in this document; readers who are not familiar with Tcl and Tk should refer to the documentation available for Tcl/Tk, such as [#!welch97!#] or the manual pages and help files that come with Tcl/Tk. This manual requires a working knowlege about Tcl/Tk and at least a basic familiarity with the concepts of SGML and XML.

While Tcl provides the mere basics of the programming language, Tk adds a set of predefined user interface elements than can be combined to create powerful graphical user interfaces (GUIs). These user interface elements correspond to what is called widgets in the OSF-Motif library or controls in the Windows operating system.

The sgml widget extends the Tk toolkit by providing a facility to view and edit SGML and XML documents. Unlike some other SGML/XML editing tools, the sgml widget works with virtually any DTD and is not restricted to a limited set of built-in document types.

Figure: TkSGML System

The sgml widget adds a new widget to the set of Tk widgets that is compatible with the existing widgets and follows the Tk programming philosophy. Like any other widget, multiple instances of the sgml widget can be created and manipulated with widget-specific commands.

Great care has been taken to make the sgml widget backward compatible with the Tk text widget. Programmers who know how to use the Tk text widget should be able to use the sgml widget with minimal effort.

The sgml widget allows the user to view, edit, and create SGML documents. Additionally, it provides some features that can be used to write SGML-aware programs that operate on the document instance stored in the sgml widget.

The sgml widget contains a full-featured SGML parser that is used to parse the document type definition and the document when it is loaded into the widget. The parser is based on the freely available SP system, but has been enhanced in several ways to fit the needs of the sgml widget.

When the document is edited, the sgml widget tries to enforce the conformance of the document to the DTD. Although it is possible to create documents that do not adhere to the DTD, this is viewed as a temporary state of the document instance during the editing process that should be corrected as soon as possible.

By extending the Tk functionality with the sgml widget, it is possible to create integrated environments for SGML processing tasks. The main advantage of using Tcl together with Tk and the sgml widget is the ability to provide sophisticated, yet widely unrestricted possibilities for creating graphical user interfaces for SGML-integrated applications and editing systems. The extensibility of the Tcl language makes it easy to add interfaces to different software systems such as text formatters, database systems, or typesetting systems. By using Tcl as an integration language, it is possible to present the user with a homogenous environment for all related tasks and create a graphical interface that fits the users needs.

1.2 How is this manual organised

The manual is divided into three main parts.

Part 

deals with basic aspects of the TkSGML system, such as creating a wiget instance or loading TkSGML into a running Tk application.

Part 

describes the widget commands that are used to manipulate the contents of an sgml widget.

Part 

conatins additional information about the system environment in which TkSGML is used.

1.2.1 Notational conventions

Throughout the manual, Courier will be used for anything that might be typed to a computer. Tcl commands occur in Courier and their results appear in a slanted variety of the same font. The symbol $\Rightarrow$ indicates that this is a normal return value.

	.s dtd name
$\Rightarrow$	HTML

We've taken the liberty to omit the return values where they are of no significance for what is being explained in the various chapters. If an error occurs, the error message will be printed in the same font as results, but the $\oslash$ symbol will preceed the error message.

	.s element insert chapt
$\oslash$	wrong # args: should be "element insert element index"

When the syntax of Tcl commands is described, Courier is used for the command name and for keywords that must be typed exactly as shown. Formal argument names are printed in the same slanted variety of Courier as Tcl results. Optional arguments (or groups of optional arguments) are enclosed in question marks. For example, the sytax of the element index command is as follows:

element index handle ?end?

This means that the words element index must be entered verbatim to invoke the command and that the parameter handle must be substituted by an element handle. The keyword end may be omitted, but must be typed exactly as shown if it is supplied.

Impotant aspects and common pitfalls are marked with a attention sign to draw the readers attention to this information.

Important information like this should not be ignored.