The HTML Viewer

The help viewer windows provide access to the help system topics, and can display general HTML and image files.

There are three colored buttons in the menu bar of the viewer. The left-facing arrow button (back) will return to the previous topic shown in the window. The right-facing arrow button (forward) will advance to the next topic, if the back button has been used. The Stop button will stop HTTP transfers in progress.

There are four drop-down menus in the menu bar: File, which contains basic commands for loading and printing, Options, which contains commands for setting display attributes, Bookmarks, which allows saving frequently used references, and Help which provides documentation.

The File menu contains the following command buttons.

Open
The Open button in the File menu pops up a dialog into which a new keyword, URL, or file name can be entered.

Open File
The Open File button brings up the File Selection panel. The Ok button (green octagon) on the File Selection panel will load the selected file into the viewer (the file should be a viewable file). The file can also be dragged into the viewer from the File Selection panel.

Save
The Save button in the File menu allows the text of the current window to be saved in a file. This functionality is also provided by the Print button. The saved text is pure ASCII.

Print
The Print button brings up a pop-up which allows the user to send the help text to a printer, or to a file. The format of the text is set by the drop-down menu, with the current setting indicated on the menu button. The choices are PostScript in four fonts (Times, Helvetica, New Century Schoolbook, and Lucida Bright), HTML, or plain text. If the To File button is active, output goes to that file, otherwise the command string is executed to send output to a printer. If the characters ``%s'' appear in the command string, they are replaced with the temporary print file name, otherwise the temporary file name is appended to the string, separated by a space character.

Reload
The Reload button in the File menu will re-read the input file and redisplay the contents. This can be useful when writing new help text or HTML files, as it will show changes made to the input file. However, if you edit a ``.hlp'' file, the internally cached offsets for the topics below the editing point will be wrong, and will not display correctly. When developing a help text topic, placing it in a separate file will avoid this problem. One can also use the !helpreset command to update the file offset table. If the displayed object is a web page, the page will be redisplayed from the disk cache if it is enabled, rather than being downloaded again.

Old Charset
The help viewer uses the UTF-8 character set, which is the current standard international character set. However, older input sources may assume another character set, such as ISO-8859, that will display some characters incorrectly. If the user observes that some characters are missing or wrong in the display, setting this mode might help.

Make FIFO
This controls an obscure but unique feature. When the button is pressed, a named pipe, or FIFO, is created in the user's home directory. The name is ``mozyfifo'', or if this name is in use, an integer suffix is added to make the name unique. This is a special type of file, that has the property in this case that text written to this ``file'' will be parsed and displayed on the viewer screen.

The feature was developed for use in the stand-alone mozy program, for use as a HTML viewer for the mutt mail client. If an HTML MIME attachment is ``saved'' to the FIFO file, it will be displayed in the viewer.

The FIFO will be destroyed if this toggle button is pressed a second time, or when the help window exist normally. If the program crashes, the FIFO may be left behind and require manual removal.

Quit
The Quit button in the File menu removes the help window. This will exit help mode (where clicking on a command button brings up help) if there are no other help windows visible. Pressing the Help button in the Help Menu a second time or pressing the Esc key also exits help mode, though the help windows remain visible.

The Options menu presents a number of configuration and visual attribute choices to the user. These are described below.

Save Config
The Save Config button in the Options will save a configuration file in the user's home directory, named ``.mozyrc''. This file is read whenever a new help window appears, and sets various parameters, defaults, etc. This provides persistence of the options selected in the Options menu. Without an existing .mozyrc file, changes are discarded. If the file exists, it will be updated whenever a help window is dismissed.

Set Proxy
This button will create or manipulate a .wrproxy file in the user's home directory, which will provide a transport proxy url for internet access. The proxy will apply in all XicTools programs when connecting to the internet.

The $HOME/.wrproxy file contains a single line giving the internet url of the proxy server. The proxy server will be used to relay internet transactions such as checking for program updates, obtaining data or input files via http or ftp transport, and general internet access.

One can create a .wrproxy file by hand with a text editor. The general form is

http://username:password@ proxy.mydomain.com:port

The format must be http, https is not supported at present. The username and password if needed are specified as shown, using the colon `:' and at-sign `@' as separators. The address can be a numeric ip quad, or a standard internet address. The port number is appended following a colon. No white space is allowed within the text.

When the menu button is pressed, a pop-up appears that solicits the proxy address. Here, the address is the complete token, as described above, but possibly without the port. The port number can be passed as a trailing number separated by white space, if it is not already given (separated by a colon). If no port number is given, the system will assume use of port number 80.

If the entry area is empty, any existing .wrproxy file will be moved to ``.wrproxy.bak'' in the user's home directory, effectively disabling use of a proxy. The behavior will be identical if the address consists of a hyphen `-'. An existing .wrproxy.bak file will be overwritten. If the hyphen is followed by some non-space characters, the .wrproxy file will be moved to a new file where the given characters serve as a suffix following a period. For example, if -ZZ is given, the new file would be ``.wrproxy.ZZ'' in the user's home directory. An existing file of that name will be overwritten.

If the argument consists of only a plus sign `+', if a file named ``.wrproxy.bak'' exists in the user's home directory, it will be moved to .wrproxy. An existing .wrproxy will be overwritten. If the `+' is followed by some non-space characters, the command will look for a file where the characters are used as a suffix, as above, and if found the file will be moved to .wrproxy.

Only the .wrproxy file will provide a proxy url, the other files are ignored. The renamed files provide convenient storage, for quickly switching between proxys, or no proxy.

Otherwise, if an address is given, the first argument must start with ``http:'' or an error will result.

Search Database
The Search Database button in the Options menu brings up a dialog which solicits a regular expression to use as a search key into the help database. The regular expression syntax follows POSIX 1003.2 extended format (roughly that used by the Unix egrep command). The search is case-insensitive. When the search is complete, a new display appears, with the database entries which contained a match listed in the ``References'' field. The library functions which implement the regular expression evaluation differ slightly between systems. Further information can be found in the Unix manual pages for ``regex''.

Find Text
The Find Text command enables searching for text in the window. A dialog window appears, into which a regular expression is entered. Text matching the regular expression, if any, is selected and scrolled into view, on pressing one of the blue up/down arrow buttons. The down arrow searches from the text shown at the top of the window to the end of the document, and will highlight the first match found, and bring it into view if necessary. The up button will search the text starting with that shown at the bottom of the window to the start of the document, in reverse order. Similarly, it will highlight and possibly scroll to the first match found. The buttons can be pressed repeatedly to visit all matches.

Default Colors
The Default Colors button in the Options menu brings up the Default Colors panel, from which the default colors used in the display may be set. The entries provide defaults which are used when the document being displayed does not provide alternative values (in a <body> tag). The defaults apply in general to help text.

The color entries can take a color name, as listed in the listing brought up with the Colors button, or a numerical RGB entry in any common format. The entries are the following:

Background color
Set the default background color used.

Background image
If set to a path to an image file in any standard image format, the image is used to tile the background.

Text color
The default color to use for text.

Link color
The default color to use for un-visited links.

Visited link color
The default color to use for visited links.

Activated link color
The default color to use for a link over which the user presses a mouse button.

Select color
The color to use as the background of selected text. This color can not be set from the document.

Imagemap border color
The color to use for the border drawn around imagemaps. This color can not be set from the document.

The Colors button brings up a panel which lists available named colors. Clicking on a name in this panel selects it, and enters the name into the system clipboard. The ``paste'' operation can then be used to enter the color name into an entry area. This may vary between systems, typically clicking on an entry area with the middle mouse button will paste text from the clipboard.

Pressing the Apply button will apply the new colors to the viewer window. Pressing Dismiss or otherwise retiring the panel without pressing Apply will discard changes. Changes made will not be persistent unless the Save Config button has been used to create a .mozyrc file, as mentioned above.

Set Font
The Set Font button in the Options menu will bring up a font selection pop-up. One can choose a typeface from among those listed in the left panel. The base size can be selected in the right panel. There are two separate font families used by the viewer: the normal, proportional-spaced font, and a fixed-pitch font for preformatted and ``typewriter'' text. Pressing Apply will set the currently selected font. The display will be redrawn using the new font.

In Xic, there are commands to set the font families:

!helpfixed [family-size]
!helpfont [family-size]

The format of the family-size argument depends upon the version of the GTK toolkit employed.

Cache group
A disk cache of downloaded pages and images is maintained. The cache is located in the user's home directory under a subdirectory named ``.wr_cache''. The cache files are named ``wr_cacheN''" where N is an integer. A file named ``directory'' in this directory contains a human-readable listing of the cache files and the original URLs. The listing consists of a line with internal data, followed by data for the cache files. Each such line has three columns. The first column indicates the file number N. The second column is 0 if the wr_cacheN file exists and is complete, 1 otherwise. The third column is the source URL for the file. The number of files saved is limited, defaulting to 64. The cache only pertains to files obtained through HTTP transfer. This directory may also contain a file named ``cookies'' which contains a list of cookies received from web sites.

A page will not be downloaded if it exists in the cache, unless the modification time of the page is newer than the modification time of the cache file.

The Don't Cache button in the Options menu will disable caching of downloaded pages and images.

The Clear Cache button in the Options menu will clear the internal references to the cache. The files, however, are not cleared.

The Reload Cache button in the Options menu will clear and reload the internal cache references from the files that presently exist in the cache directory.

The Show Cache button in the Options menu brings up a listing of the URLs in the internal cache. Clicking on one of the URLs in the listing will load that page or image into the viewer. This is particularly useful on a system that is not continuously on-line. One can access the pages while on-line, then read them later, from cache, without being on-line.

No Cookies
Support is provided for Netscape-style cookies. Cookies are small fragments if information stored by the browser and transmitted to or received from the web site. The No Cookies button in the Options menu will disable sending and receiving cookies. With cookies, it is possible to view certain web sites that require registration (for example). It is also possible to view some commerce sites that require cookies. There is no encryption, so it is not a good idea to send sensitive information such as credit card numbers.

Images group
Image support is provided for gif, jpeg, png, tiff, xbm, and xpm. Animated gifs are supported as well. Images found on the local file system are always displayed immediately (unless debugging options are set in the startup file). The treatment of images that must be downloaded is set by this button group in the Options menu. One and only one of these choices is active. If No Images is chosen, images that aren't local will not be displayed at all. If Sync Images is chosen, images are downloaded as they are encountered. All downloading will be complete before the page is displayed. If Delayed Images is chosen, images are downloaded after the page is displayed. The display will be updated as the images are received. If Progressive Images is chosen, images are downloaded after the page is displayed, and images are displayed in sections as downloading progresses.

Anchor group
There are choices as to how anchors (the clickable references) are displayed. If the Anchor Plain button in the Options menu is selected, anchors will be displayed with standard blue text. If Anchor Buttons is selected, a button metaphor will be used to display the anchors. If Anchor Underline is selected, the anchor will consist of underlined blue text. The underlining style can be changed in the ``mozyrc'' startup file. One and only one of these three choices is active. In addition, if Anchor Highlight is selected, the anchors are highlighted when the pointer passes over them.

Bad HTML Warnings
If the Bad HTML Warnings button in the Options menu is active, messages about incorrect HTML format are emitted to standard output.

Freeze Animations
If the Freeze Animations button in the Options menu is active, active animations are frozen at the current frame. New animations will stop after the first frame is shown. This is for users who find animations distracting.

Log Transactions
If the Log Transactions button in the Options menu is active, the header text emitted and received during HTTP transactions is printed on the terminal screen. This is for debugging and hacking.

The Bookmarks menu contains entries to add and delete entries, plus a list of entries. The entries, previously added by the user, are help keywords, file names, or URLs that can be accessed by selecting the entry. Thus, frequently accessed pages can be saved for convenient access. Pressing the Add button will add the page currently displayed in the viewer to the list. The next time the Bookmarks menu is displayed, the topic should appear in the menu. To remove a topic, the Delete button is pressed. Then, the menu is brought up again, and the item to delete is selected. This will remove the item from the menu. Selecting any of the other items in the menu will display the item in the viewer. The bookmark entries are saved in a file named ``bookmarks'' which is located in the same directory containing the cache files.