TACTWeb: Configuration

So far we have described how TACTweb should be set up, and we've tested it with the demonstration TDB we have provided. Now we will discuss how you can use TACTweb with your TDBs, and will also tell you how to modify the query form to suit your own purposes.

Setting up TACTweb to work with your texts

Creating a TACT database

TACTweb works with textual databases (TDBs) that are created by other parts of the TACT system (version 2.x). If you are already using TACT tools such as UseBase or Collgen from version 2.0 or 2.1 on your text, you already have the necessary TDB database. If you do not have a TDB database for your text, then you will need to create a TDB for it. This can be done using the standard TACT 2.x system tools MAKEBASE or MERGEBASE. The TACT software that contains these tools is available from ftp.epas.utoronto.ca. Alternatively, texts marked up with an SGML derived language can used as the basis for a TDB by processing them with sgml2tdb -- a part of the TACT system that was recently added.

Although TDBs can be put in any directory on your computer, there are some advantages to putting all the TDBs you want TACTweb to access in one subdirectory. We'll discuss this further when we talk about the steps involved in configuring TACTweb for your use. When TACTweb.ZIP is uncompressed, it will create a subdirectory within C:\WebSite\cgi-dos called tactweb. You will find the demonstration TDB midsumme.tdb there already, and you can also place your own TDBs there if you wish.

How TACTweb accesses your TDBs

There are two files which you must create to make TACTweb access your own TDB:

• A .BAT file must be created that can be automatically invoked by WebSite. This batch file will set up the environment for TACTweb, will start TACTweb running, and will point it at your TDB. The file \WebSite\cgi-dos\dotactq.bat provides this function for the demonstration database, and should be used as a model.
• An HTML form document must be created that contains information relevant to your TDB, and also specifes that the batch file (mentioned above) is to be run when the form is submitted. The file \WebSite\htdocs\TACTweb\tactweb.htm does this for the demonstration database, and can act as a model.

Pointing TACTweb to your own TACT TDB files

As was mentioned above, the first step is to create a new batch file in the directory C:\WebSite\cgi-dos. Suppose your database is called hamlet.tdb and is in the directory c:\tact\texts\hamlet.tdb. A batch file that will invoke TACTweb with your TDB could be called hamlet.bat, and must be stored with other batch files in c:\WebSite\cgi-dos if WebSite is to use it. Here is what it should look like:

c:
cd \website\cgi-dos
set tactpath=c:\website\cgi-dos
tactweb c:\tact\texts\hamlet.tdb >%output_file%
 

This batch file will be invoked automatically by the WebSite server when a user requests a query to be processed against the hamlet.tdb file.

• Its first two lines make sure that the current directory in which TACTweb runs is on the "C" drive, and is \website\cgi-dos.
• The third line of the file sets the environment variable that tactweb will use to find its auxillary files. As shown, it should be set to the same directory as the one containing TACTweb itself.
• The final line invokes the TACTweb program. Note the first parameter given to TACTweb (shown in bold in the example) is the name of the TDB it is supposed to use. This is the only item in the model shown above that you must change.

Controlling the secondary displays

If you have used TACTweb you will already be aware that TACTweb output contains links in the KWIC and Variable Context displays to a secondary display (also generated by TACTweb) that contains a block of text from the TDB surrounding the selected position in the text. You can set the tactpage environment variable in your batch file to specify the amount of text you want TACTweb to generate for these secondary displays.

Suppose in your Hamlet text you have provided tags that mark the page boundaries from a standard edition. The name of this unit is "rivpage". If you wish to make TACTweb use this page boundary as the boundary between the chunks of text it displays in the secondary displays, you can set the tactpage environment variable in your batch file, as shown below:

c:
cd \website\cgi-dos
set tactpath=c:\website\cgi-dos
set tactpage=rivpage/Page
tactweb c:\tact\texts\hamlet.tdb >%output_file%
 

In this example, the value assigned to tactpage has two parts separated by a slash.

• The first part must be present, and contains the name of the tagged material as used in the TDB that should act as the boundary marker for the secondary displays. In the example here the name is "rivpage".
• The second part (and its separating slash) is optional. If present, it specifies the text to be used in the HTML generated for the display itself to identify the boundary marker. Here, since the division marks off pages in a standard edition, it is natural to use the word "Page". The TACTweb user will see the each textual unit in the secondary display labelled as a "Page".

  If the second part is omitted, TACTweb will use the name in the first part in the HTML text it generates.

In other words, this setting specifies that the secondary textual displays are to contain text between "rivpage" tags, and that within the display itself this unit of text is called a "Page".

If no value for "tactpage" is given, TACTweb will generate a secondary display consisting of the line of text containing the selected position, plus 40 lines of text on each side.

• If you wish TACTweb to generate no text-based secondary displays, set "tactpage" to "-":

  set tactpage=-
   

• If you want TACTweb to generate a secondary display consisting of a different number of lines from your text, set tactpage as follows:

  set tactpage=line/20
   

  Where, the word before the slash (line) is the name of the "line" TACT Ref ID unit that represents the lines of text in the TDB, and the value after the slash is the number of lines to be displayed in total. A number can only be coded for the second part when the first part refers to the "line" TACT Ref ID.

Creating an HTML form for your own TACT TDB files

Having now created the batch file that will launch TACTweb and point it to your TDB, it is now necesary to create a form that can be filled in and will generate a request to your server to launch the batch file.

In order to understand how to modify the HTML query form, you will need to first understand how the HTML forms language works. There are many documents on the Web that describes the elements of the HTML form language. Here is a pointer to one set of them.

You have probably already seen how your browser displays the Query form we have provided as a sample.

To create a form that will cause TACTweb to access your own TDB, the easiest method is to copy the example form in c:\WebSite\htdocs\tactweb\tactweb.htm (calling the copy, say, c:\WebSite\htdocs\tactweb\hamlet.htm for the hamlet text), and edit the copy.

We will store the form on the same machine that provides access to TACTweb, and we will store it in the subdirectory under the "htdocs" directory (which contains documents that WebSite will serve), in a subdirectory called "tactweb". However, this is not necessary -- unlike the batch file which must reside in the directory "Website\cgi-dos", the form that invokes it may result in any directory that can contain documents on the WebSite machine, or, indeed even on a different Web Server altogether.

In any event, two changes from the sample form must be made:

• The Hamlet form must point at the hamlet.bat batch file that, in turn, now points to your hamlet.tdb, and,
• The lists of TACT Ref IDs that appear in the form must be updated to identify the Ref IDs that actually appear in the hamlet.tdb file.

Here is the HTML coding for the form in hamlet.htm that could be used to query the hamlet.tdb database::

<FORM METHOD="POST" ACTION="/cgi-bin/hamlet.bat">
<p><INPUT TYPE="submit" VALUE="Submit Query"> <INPUT TYPE="reset" VALUE="Reset Form">
<H2>Your Query:</H2>
 
<INPUT NAME="query" INPUT SIZE=70><P>
 
<b>Query Context:</b>
<SELECT NAME="qcontext_unit">
<OPTION> Lines
<OPTION VALUE=rivpage> Riverside Edition Page
<OPTION VALUE=ActScene> Scene
<OPTION> Speaker
<OPTION SELECTED>Words
</SELECT> 
 
Before: <INPUT NAME="qcontext_before" VALUE="5" INPUT SIZE=5 MAXLENGTH=5>
After: <INPUT NAME="qcontext_after" VALUE="5" INPUT SIZE=5 MAXLENGTH=5>
 
<h2>Display</h2>
<SELECT NAME="display_type">
<OPTION VALUE="KWIC" SELECTED>KWIC
<OPTION VALUE="VAR"> Variable Context Display
<OPTION VALUE="DIST"> Distribution
<OPTION VALUE="WORD"> Word List
</SELECT> 
 
<p><b>Variable Context Display Context:</b>
<SELECT NAME="dcontext_unit">
<OPTION SELECTED>Lines
<OPTION VALUE=rivpage>Riverside Edition Page
<OPTION VALUE=ActScene>Scene
<OPTION>Speaker
<OPTION>Words
</SELECT> 
 
Before: <INPUT NAME="dcontext_before" VALUE="3" INPUT SIZE=5 MAXLENGTH=5>
After: <INPUT NAME="dcontext_after" VALUE="3" INPUT SIZE=5 MAXLENGTH=5>
 
<p><b>Reference Template:</b>
<INPUT NAME="ref_template" INPUT SIZE=40>
</FORM>
 

If you have reviewed the format of HTML Forms, much of this will already be familiar to you. However, we'll give a brief overview here:

• The form begins with the "FORM" tag. For TACTweb requests this tag must contain two attributes. The "METHOD" attribute must be "POST", and the "ACTION" attribute must give a URL that specifies the batch file that your server is to run. We have just created a batch file hamlet.bat that will invoke TACTweb and point it at our hamlet.tdb database. This is how we specify that when this form is submitted, that hamlet.bat is the batch file WebSite is supposed to run.
• Within the "FORM" element will be fixed text and various special tags that act as buttons, fields to be filled in, and selection objects of various kinds. We will not discuss the "fixed text", although it is marked up using other parts of the HTML language -- an example is the line "<H2>Your Query:</H2>" which your WWW client will display as a 2nd level heading within the form material.
• Our example form shows two buttons "Submit Query" and "Reset Form". At least the "Submit Query" button must be present in any HTML form that invokes a CGI process on the WebSite server. The "submit" button must be coded coded using an INPUT element containing the attribute "TYPE" set to "submit": "<INPUT TYPE="submit" VALUE="Submit Query">" . The "VALUE" attribute is option within the INPUT element, and, if coded, will tell your WWW client what text to use to label the button it will display.
• Immediately following the "Submit Query" and "Reset Form" buttons is the place where the form user specifies his/her query in the TACT query language. In the terminology of the HTML forms language, a place where a user can type information that gets sent to the server software is called a "field". The HTML code that specifies this particular field is: "<INPUT NAME="query" INPUT SIZE=70>". It is very important that the "INPUT" element contain the "NAME" attribute since each form can contain many fields so that many different types of information can be collected from a single form. It is the name coded with the NAME attribute that will identify what type of information the field will contain. In effect, TACTweb is going to look for a name of "query" to find out what the query is. The INPUT SIZE attribute specifies that the field must be large enough to support the entry of 70 characters of data.
• The next HTML form element, the SELECT element, shows a different type of form entity: one that generates a selection list. In HTML forms, the list user is presented with several options from which s/he can choose one. Thus, the SELECT element needs to contain several OPTION elements, each of which contains the text for one of the choices that will be presented to the forms user. Here, the user can select one of the items. Again, the opening SELECT tag contains the all-important "NAME" attribute. The name "qcontext_unit" is the name TACTweb looks for to find out what unit it should use to control the size of the context for collocation operators in the Query.

  Although a field with the name "qcontext_unit" could have been used to collect this information from the user, only one of a fixed list of values (the names of the TACT RefIDs available in the TDB database) can be in fact usefully coded. By using the selection list the form user is restricted to choosing from names which the TDB actually has. The selected item will be sent to TACTweb as the value for "qcontext_unit".

  The "select" element contains one or more "option" elements. The example file shows several formats in which the option element can appear.

  • <OPTION>Speaker: This is the simplest format. The text "Speaker" both specifies the text to actually be displayed in the form to the form user, and also specifies the name to be passed to TACTweb. Here the name "speaker" is the actual name used in the TDB for the speaker textual unit, and is also a good name to be displayed to the form user.
  • <OPTION VALUE=rivpage> Riverside Edition Page: Here, the TACT id is "rivpage", but displaying the name "rivpage" to the form user would not be very helpful. Thus, the value to be passed to TACTweb is given as a "value" attribute to the option element, and the text contained in the element (Riverside Edition Page) is the text that should be shown to the form user.
  • <OPTION SELECTED>Lines: Here, the attribute "Selected" is coded for the "option" element. By coding the selected option one indicates that this particular value should be used as the starting setting for the selection element when the form is first displayed.
• The display selection list (further down in the given form, with name "display_type") uses the select element again to allow the form user to specify the type of TACTweb display they wish to see. The text TACTweb wishes to see to specify the display type is brief and perhaps cryptic for a form user, so the OPTION attribute is coded to provide both a short form for TACTweb, and a fuller description for the form user. With "<OPTION VALUE="VAR"> Variable Context Display" , for example, the form user will see "Variable Context Display" as one of the possible options to choose in this list. If this option is chosen, however, TACTweb will be passed the value of "VAR".

Having seen this introduction to the HTML form coding for TACTweb, you can probably read the rest of the form and understand it. The most important thing to understand here is that the NAME attribute is critical. It is the way by which specific values are identified to TACTweb for its use.

Using TACTweb to access more than one TDB

There are two ways to make TACTweb support access more than one TDB.

• One mechanism simply repeats the process described above for each TDB file you want to serve -- creating one CGI-DOS batch file and HTML form for each TDB. We need not describe it further here.
• The other mechanism uses a feature of the TACTweb.exe program that allows you to point TACTweb not at a single TDB, but instead at a directory containing several TDBs. In this approach, part of the information returned by means of the HTML form will specify which TDB from the set in the directory you want to use.

  In this model your users could use the same HTML form to access all your TDBs, but they will be able to select which TDB to use as an option in the form itself.

In the second method, since the same form is used to gain access to all TDBs, it will be necessary that all TDBs contain the same Reference information, since the names of the Reference Information are coded in the single form that is going to access all of them. Although some of your options are more restricted with this method, your users may find that the second procedure (which allows them to select among your TDBs) by choosing something on the form, is more flexible for them and easier to use.

The procedure to follow is:

 
• First, create a batch file similar to dotactq.bat, but instead of specifying explicitly a particular TDB, use the "-d" option. This option tells TACTweb that it should allow access to a number of TDBs all from a single directory, and names the directory the TDBs are in, e.g.

  tactweb -d c:\tact\tdbs  >%output_file%"

  In this example, TACTweb will allow access for any TDB found in directory c:\tact\tdbs.

• Now that the "-d" option is coded, it will be the responsibility of the HTML form to provide the name of the TDB file to use within that directory. A value for tdb_file must be generated in the form and passed to TACTweb, and this item must contain the name of the TDB (found in the specified directory) that TACTweb is to use.

If for example, the directory contained a set of 3 TDB's for three different Shakespeare plays, a SELECT element might be coded in a form to allow the user to select between them. The value assigned to "tdb_file" from this process would tell TACTweb which database to use. The suggested HTML for the SELECT element might be:

<p>Select play here: <SELECT NAME="tdb_file">
<OPTION SELECTED VALUE="midsumme.tdb">A Midsummer's Night's Dream
<OPTION VALUE="rjf.tdb">Romeo and Juliet
<OPTION VALUE="hamlet.tdb">Hamlet
</SELECT>
 

The TACTweb Result "Wrapper"

When TACTweb processes a query it generates a sequence of HTML containing the result. Surrounding this result is a small amount of HTML, that "wraps" the main result data. By generating a "wrapper file" for TACTweb, and specifying in the batch file that you want TACTweb to use your wrapper file you can control the HTML that will be wrapped around the results of a TACTweb display. In this way, you can, for example, wrap the results with some text that identifies your project, or your institution.

If you project was called the "Public Shakespeare Project", and you were mounting a set of plays as TACT databases, you might, for example, use something like the following as a "wrapper file" for, say the "midsumme.tdb":

<HTML>
<HEAD>
<TITLE>Public Shakespeare Project, Search Results</TITLE>
</HEAD>
<BODY>
<H1>Public Shakespeare Project</H1>
<H2>Search Results: A Midsummer Night's Dream</H2>
$$$$
<ADDRESS>
The Public Shakespeare Project<BR>
Copyright (c) 1997
</ADDRESS>
</BODY>
</HTML>
 

The line containing "$$$$" is the spot in the file TACTweb will look for to tell it where to insert its results.

Once you have created a wrapper file, you must tell TACTweb to use it. Suppose your wrapper file was called "midsumme.wap". Add the "-w" switch to the line in your CGI batch file that invokes TACTweb, and follow it with the wrapper file name, e.g.:

tactweb texts\midsumme.tdb -w midsumme.wap >%output_file%
 

What Else Is There?

We have now described the work involved in setting up TACTweb to provide access to your own TDBs. In the next page of the installation section we will describe how to create new forms, and use options on them to control the TACTweb search engine.

Web design Alex Stevens, content Geoffrey Rockwell or John Bradley. March 7, 1997