XRefHT32

XRefHT32 provides a variety of functions to assist in the production of Web-based indexes and other kinds of Web pages. When used in conjunction with the TheW32 thesaurus management software, it will add cross-references to indexes automatically.

"XRefHT" is commonly pronounced "shreft".

List

The main XRefH32 window contains a three-column grid for a list. The first two columns are for headings and subheadings and the third column is for corresponding URLs.

An example of a list element might be
text formatting goodhtml.htm#textform

To edit the contents of a cell in the grid, either double-click on it or use the cursor keys to select it and then press Enter.

Click on the "+" button or use Ctrl-Space to insert a new item in the list. Click on the "-" button or use Ctrl-Del to delete the current item from the list.

Other list-related functions are described below under the "File" menu and the "Edit" menu.

The number of items in the list is displayed in the status bar at the bottom of the window.

The "File" menu

"New list"

This function clears the list, leaving only a single blank item.

"Open list..."

This function clears the list in the main window and then loads a list from a file that you specify. The file should be in comma-delimited form, with the URL first in each line, followed by the heading and subheading combined with a backslash ("\") between them; for example,

    "goodhtml.htm#textform","text\formatting"

Any line in which both the URL and the heading+subheading are empty will be ignored.

"Append..."

This function reads a list from a file that you specify and adds the items to the end of the list in the main window.

"Extract targets from..."

This function extracts targets (named anchors) from one or more HTML files that you specify and adds them to the end of the list.

The part of the URL following "#" in each item in the list will be the "name" value in the file. The term will consist of all text included between the "a" and "/a" tags, except that any prefix listed in a Xrestrip.txt file will be removed. If no text is included between the tags, the term will be empty. If "Title as subhead" is checked, the subheading will consist of the page's title (if any).

"Extract headings from..."

This function creates list items from "h" headings in one or more files that you specify and adds them to the end of the list.

You specify the range of heading levels for which headings will be extracted. The term will be the same as the heading, but with embedded tags omitted and any prefix listed in a Xrestrip.txt file removed; the part of the URL following the "#" will be empty. If "Title as subhead" is checked, the subheading will consist of the page's title (if any).

"Extract titles from..."

This function creates list entries from the titles of a set of HTML files that you specify and adds them to the end of the list. Any prefix listed in a Xrestrip.txt file will be omitted. Each URL will consist of the corresponding filename, preceded by a URL prefix that you specify if the list insertion option "Prompt for URL prefix" is checked.

"Extract meta keywords from..."

This function creates list entries from the keywords in the first META tag with NAME or HTTP-EQUIV equal to "keywords"; in each of a set of HTML files that you specify and adds them to the end of the list. Each URL will consist of the corresponding filename, preceded by a URL prefix that you specify if the list insertion option "Prompt for URL prefix" is checked. If "Title as subhead" is checked, the subheading will consist of the page's title (if any).

"From URL"

This submenu allows you to create index entries directly from URLs.

"Extract targets"

This function extracts targets (named anchors) from an HTML file whose URL you supply.

The URL for each entry will consist of the URL you supplied plus "#" the "name" value in the file. The heading and subheading will be the same as when extracting from a local file.

"Extract headings"

This function creates list items from "h" headings in a file whose URL you supply.

The URL for each entry will be the URL you supplied. The heading and subheading will be the same as when extracting from a local file.

"Extract title"

This function creates list entries from the title of an HTML file whose URL you supply.

The URL for each entry will be the URL you supplied. The heading and subheading will be the same as when extracting from a local file.

"Extract meta keywords"

This function creates list entries from the keywords in the first META tag with NAME or HTTP-EQUIV equal to "keywords"; in an HTML files whose URL you supply.

The URL for each entry will be the URL you supplied. The heading and subheading will be the same as when extracting from a local file.

"Extract from site"

This submenu allows you to create index entries from a whole site. Each function will prompt you for the extraction options that you wish to use.

"Home page URL..."

This function creates index entries from a whole site the URL of whose home page you specify.

(It is not really recommended that you use this function with password-protected sites, where a validation dialog will pop up for every page.)

"Home page filename..."

This function creates index entries from a whole site the pathname of whose home page you specify. If "Prompt for URL prefix" is checked, you will be prompted for the URL prefix to use. Note that, if any of the HTML files are in subdirectories, you will need to edit entries for them manually afterwards.

"Save list as..."

This function saves the list in comma-delimited form in a file that you specify.

"Save inverted list as..."

This function saves the list in comma-delimited form, with the heading+subheading first and the URL second, in a file that you specify.

"Create HTML index..."

This function sorts the list, converts it to an index, and stores the index in an HTML file (or set of files) that you specify.

Each subheading in the index will be linked to the corresponding URL from the list. If the subheading in an item is empty, either the heading will be linked to the corresponding URL (provided "Allow headings as links" is checked under "HTML index creation" in the "Options" menu) or a subheading consisting of a single character ("*") will be substituted for the empty subheading to allow the link to work.

You can choose to include automatically in the index cross-references to any headings that match terms in a thesaurus. For this option to work correctly, TheW32 should be running with the desired thesaurus open. (See "HTML index creation" in the "Options" menu.)

You can override the default template for the index by creating a file Xretempl.htm in the same folder in which the index will be saved. This file may contain any HTML code, but must contain the precise string [XRefHT32 index] to mark the place where the index code is to be inserted.

"Anchor headings..."

This function automatically makes all headings into anchors in an HTML file that you choose. You may save the results in the same file or another file.

The "Anchor headings..." function is suitable for adding anchors to a main thesaurus HTML file created by applying the "Indented..." function to an indented thesaurus file. You can then extract the anchors and apply the resulting list to each of the thesaurus HTML files in turn.

"Autoanchor..."

This function uses the headings from the list to add anchors automatically to an HTML file that you choose. You may save the results in the same file or another file. An anchor is added wherever a heading in the list occurs in the source file. For the first occurrence of a given term, the "name" value is derived from the heading. For later occurrences, unique names are generated automatically for the anchors added, and the terms are not included in the anchors.

If there is more than one occurrence of a given term in the source file, "Autoanchor" also makes links from one occurrence to the next. Each such link contains the same text, which you specify.

"Autolink"

This function uses the list to add links automatically to an HTML file that you choose. You may save the results in the same file or another file. A link is added wherever an item's heading occurs in the source file. Each link includes the same text, which you specify, but its "href" value is copied from the corresponding URL. Subheadings are ignored.

If an item's heading is empty, no links will be added for it.

"Table of contents..."

This function allows you to create a table of contents to an HTML file. When you click on the button, a "Table of contents" dialog appears.

"Convert text file"

These functions add HTML tags to existing text files according to various rules, without using the list. In each case, you specify the source file and the destination file, which may be the same.

"Indented..."

This function converts a file to use HTML "h" and unordered list codes in place of indentations.

You specify the number of heading levels, which may be from 0 to 9 (but not over 6 for standard HTML). Lines indented within this range will be tagged as headings. Lines indented beyond this range will be tagged as items in unordered lists.

Indentation in the source file may be by tabs or double spaces.

The "Indented" function is suitable for initial conversion to HTML format of plain text files created by TheW32 and its predecessors.

"Index..."

This function converts an indented index display file with URLs as locators into an HTML file. Heading and list codes will be substituted for indentations.

You specify the URL tag, which must be a single character. The portion of each line following the last URL tag character will be treated as the URL. A line without a URL tag character will be assumed to give just a heading or subheading without a locator.

You specify the number of heading levels, which may be from 0 to 9 (but not over 6 for standard HTML). Lines indented within this range will be tagged as headings. Lines indented beyond this range will be tagged as items in unordered lists.

Indentation in the source file may be by tabs or double spaces.

The "Index..." function does not recognize wrapped lines. Before producing a source file with a package such as CINDEX, you should set column width to a sufficiently high value to avoid line wrapping.

The "Index..." function does not translate double quotes, ampersands, and angular brackets into the corresponding HTML codes """, "&", "<", and ">". Avoid using these characters in the source file.

"Thesaurus..."

This function translates a thesaurus file with lines in the form

	Term1!Relation!Term2

into a single HTML file for an alphabetical thesarus display. For example, the line

	ANIMALS!NT!CATS

would be translated into

	<A NAME="ANIMALS"><H1>ANIMALS</H1></A>
	<H2>RT</H2>
	<A HREF="#CATS">CATS</A>
	<BR>

The function makes a link for Term2 only when Relation is 'USE', 'UF', 'BT', 'NT', or 'RT'.

If Relation is not 'USE', 'UF', 'BT', 'NT', or 'RT', Term2 may contain a preformatted HTML link. In this way, the thesaurus can double as a hypertext index.

The "Thesaurus..." function does not translate double quotes, ampersands, and angular brackets into the corresponding HTML codes "&quot;", "&amp;", "&lt;", and "&gt;". Avoid using these characters in the source file.

The "Thesaurus..." function does not automatically reciprocate relations.

"Replace in all..."

This function allows you to apply a simple search and replace to the text of multiple files that you select. You will be prompted first for the files to update, then for the text to be replaced, and finally for the replacement text.

The "Edit" menu

"Insert item"

This function inserts a new item in the list. If the HTML editing window is open, the URL of the new item inserted will be the URL displayed in the HTML editing window, and the term will be any text selected in the active control of the HTML editing window. Otherwise, the new item will be blank.

(To add a new, blank, item at the end of the list, go to the URL field of the last item and press the Tab key.)

"Duplicate"

This function creates a copy of the currently selected item at the end of the list and then selects the copy so that it is ready for you to modify.

"Duplicate flipped"

This function is the same as "Duplicate" except that, in the copy, the heading and subheading swap places.

"Delete item"

This function deletes the current item from the list. If the list contains only one item, a blank item is substituted.

"Delete items..."

This function deletes all items containing a character string that you specify. This is useful for removing individual pages and all pages in particular directories from the list.

"Clear list"

This function clears the list, leaving only a single blank item.

"Copy list"

This function copies the list to the clipboard in comma-delimited form.

"Extract from clipboard"

The functions in this submenu create new entries in the list by extracting from any HTML code on the clipboard.

You will be prompted for the part of the URL to precede the "#" in all URLs added to the list. If XRefHT32's HTML editing window is displaying a file, XRefHT32 will present, as the default value, the URL of that file.

"Targets"

This function extracts targets.

The part of the URL following "#" in each item added to the list will be the value specified following "name=" in the text. The term will consist of all text included between "a" and the "/a" tags, except that any prefix listed in a Xrestrip.txt file will be removed. If no text is included between the tags, the term will be empty.

"Headings"

This function extracts headings.

You will be prompted for the levels of headings to be included.

The term in each item added will be a heading. If "Title as subhead" is checked, the subheading will consist of the page's title (if any).

"Title"

This function extracts the title. Any prefix listed in a Xrestrip.txt file will be removed.

"Meta keywords"

This function extracts any keywords in a META tag with NAME="KEYWORDS".

The term in each item added will be a keyword. If "Title as subhead" is checked, the subheading will consist of the page's title (if any).

"Paste list"

This function converts the text on the clipboard into list elements and adds them to the end of list in the main window. It will attempt to interpret the clipboard text as being in comma-delimited form.

"Sort"

This function sorts the items in the list by term. Upper and lower case are interfiled and HTML tags and special character codes are ignored. If two items have the same heading, they will be subsorted by subheading; if two items have the same heading and the same subheading, they will be subsorted by URL.

"Sort by URL"

This function sorts the items in the list by URL. Upper and lower case are interfiled and HTML tags and special character codes are ignored. If two items have the same URL, they will be subsorted by heading; if two items have the same URL and the same heading, they will be subsorted by subheading.

"Find/Replace..."

This function brings up a standard dialog that allows you to find the next occurrence of a character string in the list, replace the next occurrence of a character string with another string, or replace all occurrences of a character string with another string.

"Check"

This function provides warnings of three common sources of problems in items in the list: different headings that sort identically (for example, upper and lower case forms of the same word); headings with trailing blanks; and bare headings with no subheadings or URLs. For the first type of warning to be issued correctly, make sure the list has been sorted before using the function.

"Options" menu

"HTML index creation"

The first two checkable items in this submenu determine whether XRefHT32 will look for cross-references in a currently running copy of TheW32 and whether the HTML index will be split into multiple files, one for each initial letter.

If you choose to create multiple files, you can generally discard the main file, since each of the files for specific initials contains a complete set of navigation links.

The third checkable item, "Allow headings as links" (checked by default), determines whether the first empty subheading link under a heading will be collapsed into a link directly from the heading (making a more compact display for simple indexes).

"Run in subheadings" (unchecked by default) determines whether subheadings will be run into a single paragraph with their corresponding heading, rather than appearing as individual list items.

"Subsitution linktype" allows you to select, by its mnemonic, a linktype in a in a currently running copy of TheW32 that links a term to a substitute form to be used in HTML output. This allows for sorting and cross-referencing with a limited character set on the one hand and, on the other hand, more flexibility in how headings are displayed. Variations in the substitute forms might include special characters in the Latin-1 character set such as accented letters, HTML tags such as those for italics or images, or character entity references or two-byte UTF codes for characters in non-Western European writing systems (in the latter case, you are advised to edit the template to contain the appropriate "content-type" meta tag for the character set used). A version of TheW32 dated May 9, 2006, or later is required for this feature to work.

"List insertion"

The first three checkable items in this submenu determine how much of the URL from the HTML editing window will be included when a new item is inserted with "Insert item". The "Title as subhead" item determines whether the title of the page in the HTML editing window will be included as a subheading. The "Title as subhead" item also determines whether page titles will be included as subheadings when headings or targets are extracted.

The "Prompt for URL prefix" item determines whether a prefix that you specify will be added automatically to URLs when you choose to extract titles, keywords, headings, or targets from files. This can be useful for creating an index to files that will reside in different directories on a server.

The "Strip prefixes" item allows you to load a file of prefixes that will be removed automatically from headings and subheadings, one prefix to a line. As one example, you might choose to list comman initial articles as prefixes to be stripped:

A
An
The
Include a space at the end of the prefix if you do not want it to be stripped when it forms the first part of a longer word.

"Sort keys..."

This function allows you to load a conversion table that specifies strings to be used in sorting in place of strings that actually begin headings or subheadings. Each line in the sort key file should consist of the string to be converted from, a tab, and the string to be sorted on. For example, if you want headings starting with "1066" to sort as if they started with "Ten sixty-six", you could include the line
1066→Ten sixty-six
Or, if you want headings starting with "The" to sort on the following word, you could include a line consisting of the string The plus a space and a tab.

The "Tools" menu

"Thesaurus"

This function attempts to run the thesaurus program TheW32 if it is not already running. The first time you select this function, you may be prompted for the location of the program file Thew32.exe on your computer.

If XRefHT32 finds TheW32 already running or succeeds in running it, it then focuses the TheW32 window. If TheW32 was running with a thesaurus open, XRefHT32 also places the current term in TheW32's clipboard list.

"Spell check"

This function checks the spelling of all headings and subheadings in the list.

"Standardize"

This function uses any thesaurus currently open in TheW32 to standardize the wording of all headings in the list.

"Preview in browser"

This function previews the most recently saved HTML file in your workstation's default browser.

"Window" menu

"Editing"

This function displays XRefHT32's HTML editing window.

"Web browser"

If you have SHDOCVW.DLL installed, this function displays XRefHT32's Web browser window.

"Scripting"

This function displays XRefHT32's Scripting window.

"Stay on top"

When this menu item is checked, the main XRefHT32 window stays on top of other windows, including those of other applications. This is handy if you want to use an external browser, such as Netscape Navigator, to view files that you are indexing with XRefHT32.

Creating HTML thesaurus files

Although you can still use a combination of XRefHT32 functions to create sets of linked HTML thesaurus files, you will probably find it more convenient to use a recent version of TheW32 for this purpose (note the "Create target list" and "Use target list" options).

Configuration file

Customized settings are stored in a Xrefht32.ini configuration file. This file may be edited directly if you wish. For the current version of XRefHT32, the only values stored are the command lines to be used for TheW32 and ExtPhr32. You may wish to modify the command line for TheW32 to include a parameter for the specific thesaurus to be opened, as in
[XRefHT32]
ExtPhrPathname=c:\Program Files\Timothy C. Craven\extphr32\extphr32.exe
TheWPathname=c:\Program Files\Timothy C. Craven\thew32\thew.exe "c:\My Documents\mythes.the"
.
Last updated February 28, 2011, by Tim Craven