2. Walk-through example

This chapter is meant to provide a simple example for using TkSGML. It assumes some familarity with Tcl/Tk and knowledge about how to interact with the Tcl interpreter. The basic assumption for the content of this chapter is that the Tcl interpreter is used interactively, i.e. that the commands shown in the following sections are typed into the console window of the wish application (on Windows or Macintosh Systems) or into the terminal window in which you started the wish application (under Unix/Linux).

Normally, commands like these would have been stored in a script file that is loaded upon invocation of the wish application. Please consult the Tcl/Tk documentation for more info about script files.

2.0.0.0.1 Step 1: Load TkSGML

To make use of TkSGML, the TkSGML extension must be loaded into a Tcl interpreter. If TkSGML has been installed as recommend, it is sufficient to issue the command

	package require Tksgml
$\Rightarrow$	1.2

If this step fails, you have probably not installed TkSGML in the default location. Please refer to section  for more details.

2.0.0.0.2 Step 2: Create an SGML widget

Now that TkSGML has been loaded, you can create a new sgml widget with the command sgml. The simplest form of the command takes exactly one argument, the widget path name of the new sgml widget.

	sgml .s
$\Rightarrow$	.s

This creates a new sgml widget with the widget name .s that can be used to refer to this widget in other Tcl commands. In addition, a new Tcl command .s is created for communicating with the new sgml widget.

2.0.0.0.3 Step 3: Make the widget visible

Before the sgml widget can be shown on the screen, it must be managed by a Tk geometry manager. In this example, we will use the grid geometry manager for this purpose and tell it to show the widget .s in row 0 and column 0 of its parent window.

	grid .s -row 0 -column 0
$\Rightarrow$	.s

The window of the sgml widget will now appear within the window of the wish application.

2.0.0.0.4 Step 4: Load a document into the widget

To show an sgml document in the widget you have just created, you have to tell the sgml widget to load the document. Since the widget command .s has been created for you, you can use this command to communicate with the widget. The widget command accepts additional parameters that tell the widget which operations to perform. The excate number of these parameters depend on the type of operations that should be performed. To load an existing document into thew sgml widget, you can use the load command, followed by a file name to load.

.s load $TkSGML_library/samples/welcome.sgml

The content of the sgml document will be read and shown in the sgml widget.

In this example, we have been using the Tcl variable $TkSGML_library to specify part of the file name for the document. The variable is replaced by the Tcl interpreter with the pathname of your TkSGML installation directory before the result is passed to the sgml widget. After the document has been loaded, the display of the sgml widget will look like the figure shown below.

2.0.0.0.5 Step 5: Adding scrollbars

The text now shown in the sgml widget fits easily into the available space, but nevertheless we will add scrollbars for convenience. In a first step, we will create two scrollbars as new widgets and place them at the appropriate sides of the sgml widget.

	scrollbar .vs -orient vertical
	scrollbar .hs -orient horizontal
	grid .hs -row 1 -column 0 -sticky ew
	grid .vs -row 0 -column 1 -sticky ns

Just creating the scrollbars is not enough, however. We need to tell the sgml widget about the scrollbars and we need to inform the scrollbars that they should tell the sgml widget to scroll when they are operated. These adjustments are performed by configuring the scrollbars and the sgml widget with the commands shown below:

	.vs configure -command ".s yview"
	.hs configure -command ".s xview"
	.s configure -xscrollcommand ".hs set"
	.s configure -yscrollcommand ".vs set"

After performing these steps, your application window will look like this:

We are now ready to embark on some serious work. We start by inserting a new element into the sgml document.

2.0.0.0.6 Step 5: Inserting elements

To insert an element, we need to tell the sgml widget the position where a new element should be inserted. In TkSGML, like in the Tk text widget, this kind of position is called an index. The easiest way to specify an index is the reserved name insert that refers to the location of the insertion cursor within your document.

Now place the insertion cursor just between the two tags and to denote the location where we want to insert a new element. Instead of blindly telling the sgml widget to insert an element, we ask which elements could be inserted at this location with the command

	.s element allowed insert
$\Rightarrow$	P HEAD

In the command above, the word insert refers to the location of the insertion cursor. It specifies the index where we want to insert a new element. Please refer to section  for more details about indexes.

The sgml returns a list of allowed elements that could occur at the specified index. Since the widget tells us that we could insert either P or HEAD elements here, we choose the HEAD element and create a new element at the location of the insertion cursor with the commands

	.s element insert HEAD insert
$\Rightarrow$	E8307330

The first occurrence of the word insert in the command above is a keyword for the element widget command, telling the sgml widget that an element insertion is requested. The second occurrence, following the element name HEAD, specifies the index where the element should be inserted which happens to be the location of the insertion cursor. Your application window should now appear as shown below:

2.0.0.0.7 Step 6: Inserting text

You could now start entering the content of the newly inserted element by moving the insertion cursor into the element and typing in whatever the head of the section should be.

The sgml widget will let you enter text only a locations where text is allowed to occur. You can not enter text (either by using the keyboard or a widget command) at locations where no text can occur according to the DTD of the document you are editing:

	.s insert 1.0 "some text"
$\oslash$	Data is not allowed here

The argument 1.0 is another way to refer to an index. The particular value used in this example specifies a location before the 0th character at the 1st line, i.e. immediately at the beginning of the document. Since you can not insert text before the document element, the sgml widget responded (correctly) with an error message.

2.0.0.0.8 Step 7: Saving your document

After you have altered your document, you may want to save the document to disk. You can write the contents of an sgml widget to a file with the following commands:

.s save test.sgml

The widget will overwrite any existing file with the given name. In a real application, you will probably want to check for an existing file with this name first and ask the user if (s)he really wants to overwrite that file.

2.0.0.0.9 Step 8: Creating a new document

To create a new document, you have to know what the prolog of the document will be. Normally, your document prolog will contain a doctype statement and a reference to the DTD describing this document type. Fortunately, live can be made easier if you already have a document of the same type as the new document you want to create.

To create a new document of the same type as a document that has already been loaded into the sgml widget, we can ask the widget for the prolog of the loaded document and then use this value as the prolog for a new document:

	set prolog [ .s dtd prolog ]
	.s new $prolog

The first command retrieves the prolog from the sgml widget and stores it in the Tcl variable prolog. The second command tells the sgml widget to create a new document with the value of this variable as the prolog for the new document.

When the sgml widget creates a new document, it automatically inserts the document element. It is, of course, up to the user to fill the document with the required content.