Setting Up the Software
Using NoteTab Light with XML Documents
This document presents an introduction to setting up and using ds3.dtd, the Digital Scriptorium transcription DTD (Document Type Definition), with NoteTab Light, a freeware editing program. It explains where to obtain and how to install the necessary files. It also offers information on viewing and parsing documents that have been produced with ds3.dtd. Once you have completed the setup procedure, we suggest that you read the remainder of this document alongside the Tag Set, then proceed to How To for an introductory procedure that applies markup tags step by step. All of the documentation files are included in the ds3.exe package, available here, and are linked by a table of contents.
The Digital Scriptorium transcription DTD provides a set of XML (eXtensible Markup Language) tags for the transcription of medieval manuscripts, for use either with excerpts (e.g., transcripts of individual pages) or with full transcripts of an entire manuscript. To simplify the preparation of the encoded transcription, we also provide documentation that shows how to use the DTD with NoteTab Light. We include a simple style sheet as part of the ds3.exe package so that encoded transcriptions can be viewed and printed in a Web browser.
We hope to help individual students and scholars to produce machine-readable transcriptions of medieval manuscripts for the purposes of textual study, the preparation of concordances, or any other task that requires the preparation of a close transcription, in a format compatible with the Guidelines of the Text Encoding Initiative.
Throughout this documentation, fixed-width font denotes filenames, text to be typed in a procedure, tags, and other computer-related text where quotation marks might be confusing.
Before you begin marking up your transcription in XML using the Digital Scriptorium guidelines, complete the installation steps below to set up the the software you will need. This procedure has been verified on Windows XP, 2000 SP2, NT 4.0 SP6, and 98. It is expected also to work with Windows 95 and Me. All software titles are the property of their respective owners.
To set up the necessary data and support files, including the DTD (rules), style sheet, and special characters:
- Download the transcription software package (ds3.exe).
- Double-click ds3.exe to unzip the files automatically to the c:\ds3\ directory on your hard disk. Accept the default target directory c:\. The ds3 subdirectory will be created automatically if it does not already exist.
Note: Do not change the directories specified in this procedure unless you are prepared also to modify the package's batch files.
In addition to the DS DTD and a sample XSL style sheet, the ds3.exe package includes sample XML files created for Digital Sciptorium, a guide to the markup tags (Tag Set and Element Types), an introduction to marking up a manuscript transcription (How To), James Clark's sp parser (to analyze and help verify tag syntax), and an XSLT conversion tool (to enable visual output in a Web browser).
To set up the NoteTab software package:
- Download NoteTab Light (the freeware version, ntfree.zip) from http://www.notetab.com to an appropriate subdirectory on your computer (e.g., My Download Files or Desktop).
- Open ntfree.zip, then double-click setup.exe to install NoteTab. When its installation program asks where you would like to install the files, specify the c:\ds3\NoteTab\ directory.
- Using Windows Explorer, move the ds3.clb file from the c:\ds3\document\ directory to the c:\ds3\NoteTab\Libraries\ directory. This is the clipboard library file that contains the DS tag set you will use in NoteTab.
- Launch NoteTab. (It is not necessary to enable the commercial features.)
- From the menu, choose View > Options..., then choose the Files tab.
Set both the Open Directory and Save Directory to c:\ds3\document, then choose OK.
- Check which Web browser(s) are installed on your computer.
For consistent output from the DS package's style sheet, we recommend using Netscape Communicator 4.7 or later, Mozilla 1.0 or later, or Internet Explorer 5.5. To verify which version of an application is installed, launch it and choose Help > About from the menu.
N.B. If you use Netscape Communicator 4.7, launch it before you begin work in NoteTab; otherwise, you will need to load your HTML output manually the first time.
- In NoteTab, choose View > Options... from the menu, then choose the Internet tab. In the Main Browser field, enter the full directory path to your browser.
You should now be ready to view and edit DS files.
When you launch NoteTab, you should see three regions below the menu and button bars: a list of available tags and tools in the left-hand pane, a blank area (or the last file you opened) in the larger right-hand pane, and a row of available libraries alphabetized at the window's bottom. For general information on using NoteTab, please consult its Help menu. We recommend that you read the procedures below from top to bottom.
To view the DS documentation:
- Choose File > Open... from NoteTab's menu, then select and open the Tag Set file.
The file's content appears in the right-hand pane.
- Click the View in Browser icon (a small globe with a magnifying glass in the button bar).
A Web browser launches and displays the documentation, titled "A TEI-Based Tag Set for Manuscript Transcription."
To parse an XML document:
- Choose File > Open... from NoteTab's menu, then select and open your XML file.
- Select the ds3 library from the button row at the bottom of NoteTab's window.
The left-hand pane displays the ds3 tools and tags. Always have this library selected when you work with the Digital Scriptorium transcription DTD.
If you edit your file at this point, make sure you save before continuing to the next step.
- Double-click XML Parse in the left-hand pane.
An MS-DOS window opens briefly, then closes. A text file named error.txt opens in NoteTab and displays the first error in your document. Though the parser acts upon the open window, not the last-saved version of your file, it is always a good idea to save before parsing.
The parser locates errors hierarchically first, then in flat top-to-bottom order of occurrence. For example:
- <note> </note>
Given the preceding correct structure, if both of the underlined end-tags were missing (</note> and </p>), the parser would report the omitted </p> first. This is because it would encounter the <p> start-tag first, look for (and miss) a </p>, and report an error without reaching the <note> start-tag.
- Note the Line and Pos[ition] citations given in error.txt, then select the tab bearing your file's name to restore its content to the right-hand pane. Locate the error using the pair of numbers, line:pos, on NoteTab's status bar (bottom left corner).
- Repeat step two until error.txt displays only your file's name and path (for example, c:\ds3\document\ucb152.xml).
The parser halts processing each time it encounters an error. If there are five errors in your document, for example, one will appear the first time you run the parser, and the parser will approve your file only upon its sixth pass.
To create an HTML file from an XML document:
Note: Because Web browsers cannot display XML documents reliably at present, you must convert your XML file to HTML (via the included XSL style sheet) to view a legible version of your encoded transcription. Use this task also to view the sample XML file, ucb152.xml.
- Choose File > Open... from NoteTab's menu, then select and open your XML file.
If you edit your file at this point, make sure you save before continuing to the next step. Also, if the ds3 library is not active, select it.
- Verify that the file parses correctly by double-clicking XML Parse in the left-hand pane.
For more information about the parser routine, see To parse an XML document above.
- Select the tab labeled ucb152.xml to restore its content to the right-hand pane.
- Double-click XSLT (under XML Tools) in the left-hand pane.
In the small dialog window that opens, enter your filename without its extension, then choose OK. For example, if you want to convert ucb152.xml, enter ucb152 (no full stop).
- A larger dialog window appears with three fields. Verify your XML file's location in the first field. In the third field, accept or modify the name and location of the HTML file that this routine creates. Choose OK.
You should not need to modify the second field, which displays the location of the XSL transformation style sheet.
- Wait for the routine in the MS-DOS window to complete, then press a key when directed to do so.
After the MS-DOS window closes, NoteTab opens your new HTML file in the right-hand pane, where you can edit it if necessary.
- If you want to view the new HTML file in a Web browser, click the View in Browser icon.
If you have completed this task using ucb152.xml, you can compare the beginning of this sample transcription with the digitized image of MS UCB 152, f. 1r. Open the DS Test Database manuscript search form (http://sunsite.berkeley.edu/scriptorium/form_msimage.html) in a Web browser, enter "ucb 152" in the Shelfmark field, and choose Run. F. 1r is the topmost image on the ensuing page; click the image to view it at medium magnification.