16. GUI Example: Man Page Viewer

Contents:
man and perlman
Implementation
Resources

Help wanted. Telepath. You know where to apply.

- Anonymous

The primary objective of this chapter is to exercise some of the most important capabilities of Tk's text widget; a man page viewer called perlman provides an ideal test case.[1] In this chapter, you will familiarize yourself with the widget's text insertion, deletion, and retrieval capabilities; use a variety of indexing primitives; create and configure tags; and perform regular expression searching and highlighting of text. Along the way, you'll also learn to use entry widgets and construct menus dynamically.

[1] For a more ambitious workout of the text widget, you could try writing an HTML page viewer.

perlman is modeled after TkMan [5], a very nice man page viewer written by Thomas Phelps at the University of California at Berkeley, using Tcl/Tk. perlman contains only a small subset of TkMan's functionality.

Thomas has also written an experience paper entitled "Two Years with TkMan: Lessons and Innovations. Or, Everything I Needed to Know about Tcl/Tk I Learned from TkMan" [6]. It presents a good case for writing the entire utility in a scripting language and unwittingly convinces us, smug Perl programmers that we are, why Perl would have been the ideal choice. Please see the Section 16.3, "Resources" section at the end of this chapter for pointers to TkMan and this paper.

16.1 man and perlman

Unix manual pages are normally viewed by the man(1) command. When you say man perl at the command line, it searches the list of directories indicated by the environment variable MANPATH, a colon-separated list of pathnames. (If MANPATH is not specified, man(1) looks at standard locations, such as /usr/man.) Once it finds a file called perl.1, it calls tbl to format the tables and nroff to format the text, and pipes the output through a suitable pager, such as more(1) or less(1).

Figure 16.1: perlman screen

perlman, shown in Figure 16.1, is a GUI wrapper over man. To view a topic, you have to enter a string in the "Show" box and press the Return key. To highlight all pieces of text matching a given regular expression, simply enter it in the "Search" box and press Return. You can also perform exact string searches and ignore case optionally. In addition, perlman provides the following features:

Hypertext: If you double-click on any word, perlman displays the man page on that topic, if it exists. In man(1), you have to quit the current man page before looking at the other documentation. In contrast to other help systems such as those found on Microsoft Windows or HTML pages, perlman doesn't require a piece of text to be specially marked as a hypertext link. In addition, if you click on a string such as strcmp(3), perlman looks for the corresponding documentation in section three of the manual. This helps immensely with the "SEE ALSO" sections.
Section headers: Some manual pages such as csh(1), gcc(1), and perlfunc(1) are very big. perlman helps the user navigate faster through such documents by creating a special menu called "Headings." Under this menu, it shows all the section headings in that document, such as "NAME," "DESCRIPTION," and "SEE," as shown in Figure 16.1. When the user selects one of these options, the corresponding section is brought into view.
Sections: perlman shows all the sections available, in a menu called "Sections," and when you select one of them, it shows all the topics available in that section. You can then double-click on any of these topics to get help.