implemented in Tcl/Tk 8.4
TkMan icon drawn by Rei Shinozuka
many other icons taken from the AIcons collection
Compatible with Sun Solaris, SunOS, Hewlett-Packard HP-UX, OSF/1 aka Digital UNIX, DEC Ultrix, AT&T System V, SGI IRIX, Linux, SCO, IBM AIX, FreeBSD, NetBSD, BSDI — each of which, believe you-me, is in some way different from all the others
TkMan is maintained at http://tkman.sourceforge.net.
Before reporting a bug, first check the home site to make sure
you're using the latest version of TkMan. If you want to change
how a feature works, first check the Preferences dialog.
If you send me bug reports and/or suggestions for new features, include your
MANPATH, the versions of TkMan, Tcl/Tk, X Windows, and UNIX, your
machine and X window manager names, the edited Makefile, a copy of
your ~/.tkman file, and the first few lines of the
tkman executable. I'd also be interested in learning
where you obtained TkMan. Finally, I cannot provide support for
versions that have been processed into .rpm or .deb or packages
other than the one served by the main site.
Feedback without all this information will likely be ignored.
Send feedback to phelps (at) ACM.org
Also check out the Multivalent Browser.
"I encourage you to use TkMan for reading man pages. ... TkMan provides an extremely pleasant GUI for browsing man pages. I cannot describe all the nice features of TkMan in this small space. Instead I will merely say that I now actually look forward to reading man pages as long as I can do it with TkMan."
-- Don Libes, Exploring Expect, page 21
TkMan offers many major advantages over
Furthermore, one may highlight, as if with a yellow marker, arbitrary passages of text in man pages and Texinfo and subsequently jump directly to these passages by selecting an identifying excerpt from a pulldown menu. (Highlights are robust across changes to page content and movement of the file.) Pages are optionally given an outlining user interface whereby the text of a section can be collapsed or expanded underneath its header, independently of other sections. Within otherwise collapsed sections, a variety of Notemarks™ can appear. Notemarks are excerpts from the text showing highlighted text, command-line options, search results, or an excerpt of each paragraph in that section, shown in context with section headers and other Notemarks. Functioning as a note, a Notemark may itself communicate sufficient information; functioning as a bookmark, it can be clicked on to automatically expand the corresponding section and scroll to that point. Notemarks densely display numerous immediately available hooks into long texts to expedite identification of a desired passage.
The Texinfo browser takes a very different approach than any other GNU info brower, and thereby is able to provide a number of advantages not possible in an info-only browser. (1) TkMan's browser works from the Texinfo source, as opposed to a compiled form that has been formatted for character terminal displays, and therefore can and does provide much better looking text, in multiple fonts (proportionally-spaced for body text, typewriter for computer text, bold and italics, blue hyperlinks for crossreferences, and even a cedilla and a lowered 'e' in TeX). (2) An outlining interface that continuously gives overview and context to navigation within the document, as opposed to the system of nodes with only immediate neighbors known (next, previous, parent), which, at least for me, very quickly leads to being "lost in info-space". All this costs disk space of only 2% over the original Texinfo source files, which themselves may be compressed.
Other features include:
retkman that can be used to restart TkMan after changes to the MANPATH in a shell, as from a "package" managerIn the text that follows, click means a quick mouse button click (down and up in less than a quarter of a second), and press means press and hold down the mouse button. Some widgets in the interface function as buttons when given a click, menus if pressed. If you want to access the menu, you do not need to wait for the menu itself to appear before dragging down the menu; go ahead and drag down with the mouse, and the interface will catch up to the mouse movement when the menu appears. You still post menus, by waiting until the menu appears and then releasing the button with the cursor over the menubutton.
There are several ways to specify the manual page you desire. You
can type its name into the entry box at the top of the screen and
press Return or click the man button. The name may be just the name of
the command or may end with .n or (n),
where n specifies in which section to look. Type in a partial name
of three or more letters and type Escape to invoke page name completion.
If there was exactly one match, the letters typed in so far will be replaced by the
name of the page and its section number; otherwise it will be the longest common prefix of all
possible matches.
Man pages are matched using regular expressions, so you can use . to match
any single character, * to match any (zero or more) of the
previous regular expression, [ .. ] to match any
single character in the enclosed class; see
Whenever you have a man page name in the text display box, whether from apropos, a volume listing or a reference within another man page, you can click on it to hypertext-jump to it. In point of fact, man pages do not explicitly code man page references, but words that are especially likely to be references are distinguished, though any word may be clicked on to treat it as a man page reference. Pressing shift while clicking opens up a new viewer box to display the page.
Usually TkMan searches the colon-separated list of directories in your MANPATH
environment variable for the man page, but you may instead provide a
path name for the man page by beginning it with
`~', `/', `.' or `..';
this is the way to access a man page which isn't installed in a
MANPATH man directory. File name completion is invoked with Escape.
Further, other MANPATH order) is
shown and a pulldown menu appears which contains a list of the other
matches. Return from reading help or a volume listing to the last man
page seen with C-m when the focus is in the main text display
area.
apropos information is available by typing the name and hitting Shift-Return or pressing on the man button and dragging down to apropos. The output of apropos is piped through sort and uniq to remove duplicates. To pass the matches through additional filters, simply give the pipe as in a shell, e.g., `search | grep ^g' (each space character is significant) returns all the search-related commands which begin with the letter g. TkMan relies on the native system to supply apropos information and on some but not all systems (HP-UX but not GNU, for instance), apropos information for all pages in a given section is available by giving the section number in parentheses, e.g., (1) as the apropos search string.
If it's installed, you will see
in the man menu an entry for full text searching with glimpse.
Fuzzy full text is a full text search that finds the "best match"
in the absence of an exact match (it uses glimpse's -B option).
Glimpse was written by Udi Manber, Sun Wu, and Burra Gopal of
the University of Arizona's Department of Computer Science.
Glimpse requires only small index files ("typically 2-5% the size of the
original text" but larger percentages for smaller amounts of text).
In their performance measurements, "a search for Schwarzkopf allowing two
misspelling errors in 5600 files occupying 77MB took 7 seconds on a
SUN IPC". For example, one may search for the string WWW anywhere in any manual page
by typing in WWW in the entry line at the top of the
screen and clicking on the glimpse button
or typing Meta-Return.
Escape and C-g can interrupt a search after the
current directory is done.
To employ glimpse's command line options, simply
place them before the search pattern in the entry box, or add them to
the default options by editing the man(glimpse) variable in
your ~/.tkman startup file (see Customizing TkMan, below).
For instance, to search for perl as a full word only and not as
part of another word (as in "properly"), case insensitively,
glimpse for -wi perl.
Glimpse supports an AND operation denoted by the symbol
`;' and an OR operation denoted by the symbol
`,'.
For example, to search for
"insert" and "text" in Programmer Subroutines (volume 3), glimpse for
-F \.3 insert;text.
Refer to the
The Paths submenu under the man menu (press and hold down mouse button
on man and drag down, then across)
gives you complete control over which directory hierarchies of
your MANPATH are searched for man pages and apropos information.
If you plan more than a couple of operations with this menu, consider tearing it off
by releasing the mouse on the dashed line at the top of the menu.
If you use
a "modules" system to manage software--binaries and their accompanying documentation--that
as a side effect changes the MANPATH,
you can update TkMan by typing retkman (see below) in any shell.
You can call up a listing of all man pages in a volume through the Volumes pulldown menu and then select one to view by clicking on its name. New `pseudo-volumes' can be added, and arbitrary directories may be added to or deleted from a volume listing using tkmandesc commands, described below. In a volume listing, typing a letter jumps to the line in the listing starting with that letter; capital and lower case letters are distinct. Other special collections are placed in Volumes. Texinfo and Request for Comments display such lists. Recently added/changed presents a list of man pages whose time (specifically, ctime) is within the last couple weeks. The title of the Volume menu reflects the current menu, and that volume listing may be quickly recalled by clicking that title button or by typing C-d.
The last few man pages you looked at can be accessed directly through the History pulldown menu, which is the circular arrow to the right of the name typein box. The list is sorted top to bottom in order of increasing time since that page was last visited. The Shortcuts menu, the x/+/- to the right of History, lists your personal favorites and is used just like History, with the additional options of adding the current man page (by clicking +) or removing it (-) from the list.
(Man pages specified as above are processed through an nroff filter. TkMan can also read raw text from a file or from a command pipeline, which can then be read, searched and highlighted same as a man page. To read from a file, make the first character in the name a <, as in <~/foo.txt. To open a pipe, make the first character a | (vertical bar), as in `|gzcat foo.txt.gz' or `|cat ../foo.txt | grep bar' (that's no space after the first |, a space before and after any subsequent ones). After reading a file in this way, the current working directory is set to its directory. Commands are not processed by a shell, but the metacharacters ., .., ~ and $ (for environment variables), are expanded nonetheless. Typing is eased further by file name completion, bound to Escape. Lone files (i.e., not part of a pipe) are automatically uncompressed--no need to read compressed files through a zcat pipe. )
The elided text feature of Tk's text widget enables outlining. Page
section and subsection content can be collapsed and expanded by
clicking on the corresponding header. Opening a section by clicking on its title moves its
section title to the top of the screen save for five lines: to the top
in order to immediately show the initial text of the section, and save for five lines
in order to maintain some orienting context. Clicking button 3
anywhere in that section toggles its state. This makes it
convenient to expand a section, scroll through it a bit, and then
close it up to return to the header overview. Double clicking
button 3 closes up all sections. Outlining can be tuned, even turned off, via
the Preferences dialog under the Occasionals menu (called ...).
Outlining doesn't interfere with jumping to a section via the
Sections or Highlights menus or during searching, as
sections automatically open up as needed. (Try this: go to
To the extent it follows conventional formatting, a manual page is parsed to yield its section and subsection titles (which are directly available from the Sections pulldown--the leftmost menu, which appears as a page icon) and references to other man pages from throughout the page including its SEE ALSO section. One may jump directly to a section within a man page by selecting the corresponding menu entry.
Within a man page or raw text file or pipe, you may add ad hoc highlighting, as though with a yellow marker (underlining on monochrome monitors). Highlighted regions may then be scrolled to directly through the Highlights pulldown menu. To highlight a region, select the desired text by clicking button 1, dragging to the far extent of the desired region and releasing the button; Hi changes to a + to indicate that clicking it will highlight that span. On subsequent text selections, if the selection overlaps one or more existing highlights, Hi changes to a -, indicating that clicking it will remove those highlights. To remove all the highlights over a large area, close those outline sections and select across collapsed text before clicking -. A shift-click on the menu title tours through all the highlights on the page. A complete set of pages with highlighting is available under the Volumes menu.
Highlighting information is robust against changes to and reformatting of the page. Thus you can justify expending some effort in marking up pages with the knowledge that if a man page does change, as when the corresponding software package and its documentation are updated, TkMan will try to reposition them to the corresponding positions in the new pages. The success of the algorithm can be measured by comparing the "highlights repositioned automatically" vs "highlights unattachable" statistics under Occasionals/Statistics and Information. As of this writing, my personal statistics report that 6866 highlights have been reattached without incident, 614 have been automatically repositioned on a changed page, 38 have been automatically carried forward to a moved page, and a mere 7 were unattachable. Moreover, highlights follow a page if it is moved. If the current page has no highights and its name matches that of a page with highlights that no longer exists, then what probably happened is that the page was moved and you are asked whether this is indeed the case and thus whether to reassociate the highlights to this new page. Thus, say you have highlighted a number of pages in Tcl 7.6/Tk 4.1. Updating to Tcl/Tk 8.0 will both reassociate the annotation set to the new file name and reposition the annotations within the page--all automatically, asking for permission first.
Here's how highlight reattachment works. When you highlight a region, the starting and ending positions are saved along with some of the content of the highlighted region and context. When that page is viewed again, if those positions still match the context, the highlight is attached there (this is an exact match). If not, the context is searched forward and backward for a match, with the closer match chosen if there are matches in both directions (a repositioned match). If no match is found with the full context, gradually less and less of it is tried, reasoning that perhaps the content of the context has been changed (repositioned, but with less confidence, triggering a warning dialog). If still no match is found (an orphan), the highlight is reported at the bottom of the page, where it must be reattached manually before leaving the page or it will be forgotten. (With TkMan v1.8b3 and earlier, highlights were attached by positions only, and when the page modification date changed, the user had the choice of applying highlights at those same positions regardless of the text there now or throwing out the highlights wholesale. Old style highlights are automatically updated to the new style that can be automatically and robustly repositioned. The next time an old style page is viewed, the old style highlights are applied as before, and from those positions new style highlights are composed.) The annotation reattachment mechanism is inspired by Stanford's ComMentor system and, post facto, Larry Wall's patch.
You can move about the man page by using the scrollbar or typing a number of key combinations familiar to Emacs aficionados. Space and C-v page down; delete and M-v page up. Return pages down, expanding collapsed outline sections as it encounters them. (vi fans will be happy to hear that C-f and C-b also page down and page up, respectively.) C-n and C-p scroll up and down, respectively, by a single line. M-< goes to the top and M-> to the bottom of the text. One may "scan" the page, which is to say scroll it up and down with the mouse but without the use of the scrollbar, by dragging on the text display with the middle mouse button pressed. Like Emacs, C-space will mark one's current location, which can be returned to later with C-x, which exchanges the then-current position with the saved mark; a second C-x swaps back. Following an intradocument hyperlink in Texinfo automatically marks the location of the link source.
C-s initiates an incremental search. Subsequently typing a few letters attempts to find a line with that string, starting its search at the current match, if any, or otherwise the topmost visible line. A second C-s finds the next match of the string typed so far. (If the current search string is empty, a second C-s retrieves the previous search pattern.) C-r is similar to C-s but searches backwards. Escape or C-g cancels searching. Incremental search can be used to quickly locate a particular command-line option or a particular command in a group (as in csh's long list of internal commands).
The document map runs alongside the scrollbar. It has various marks at positions proportional to their position in the document. White bars indicate section and subsection heads, setting the major divisions. Blue indicates hyperlinks. Yellow indicates highlights. Orange indicates search hits. You can click on the document map to scroll to that part of the document, opening the corresponding outline section if necessary. The document map gives a quick sense of the structure or the page. I've found it especially useful in display the distribution of search hits.
At the bottom of the screen, type in a regular
expression to search for (see Tcl's
To quickly search for the current selection, set in any X application, click Meta-Button-1 or Alt-Button-1 or Control-Button-1 (pick one that doesn't conflict with your window manager) anywhere in the text display. If no selection is set, the search is made for the word under the cursor.
The Tab key moves the focus from the man page type-in line to the text view of the man page to the search line and back around. Shift-Tab jumps about in the opposite direction.
The Occasionals menu, labeled ... at the extreme right,
holds commands and options which you probably won't use
frequently. Help returns to this
information screen. Although virtually made obsolete by TkMan, Kill Trees
makes a printout of the current man page on dead, cut, bleached trees, helping to starve the
planet of life-giving oxygen. (This option is enabled only when viewing a manual page.)
A list of printers appears in the cascade menu; this
list may be edited in Preferences/Misc. (Even if only one printer is available,
it placed in the cascade menu, rather than being directly available. This is a feature.)
(If the [tn]roff source is not available, TkMan
asks if it should try to reverse compile the man page. If successful, this
produces much more appealing output than an
As with xman one may instantiate multiple viewers. When there is more than one viewer you may choose man pages in one viewer and have their contents shown in another. Use the Output pulldown (which is labelled with the destination viewer number and which appears and disappears as relevant) to direct one viewer's output destination to another. With this feature one may easily compare two similar man pages for differences, keep one man page always visible, or examine several man pages from a particular volume listing or a SEE ALSO section. Output only affects the display destination of man pages.
TkMan builds at startup an internal database of all manual page names in order
to quickly search for a particular name.
If you install new manual pages or otherwise change the contents of man page directories after
TkMan as been started, invoke Rebuild Database.
In order to pick up changes in
When exited via the Quit button, TkMan saves its state. One may guard against losing highlighting, shortcuts and other would-be persistent information without quitting by invoking Checkpoint state to .tkman; Quit, don't update performs the opposite operation.
At the bottom right corner of the screen, Mono toggles between the proportionally-spaced font and a monospaced one, for use in those man pages that rely on a fixed-width font to align columns. Quit exits TkMan, of course, after saving some state information (see below). To exit without saving status information, select the Quit option from the Occasionals (...) menu.
A special entry under the Volumes menu calls up a list of
GNU Texinfo (aka info) books. As distinct from other Texinfo
readers--
Furthermore, TkMan provides a different interface to Texinfo files. Other readers navigate among "nodes". At a given point, one may be able to go to the next or previous node in sequence or up to the parent node. In other words, in navigating the "info-space", you only have immediate context information. At least for me, this leads to being "lost in info-space". TkMan's Texinfo reader provides an outliner user interface, which gives much more positional context. The little number to the right of the section title reports the number of subsections it holds. I think an outlining interface is well matched to the usually highly hierarchically structured Texinfo files.
Texinfo books can be very large; Elisp's manual is 18MB for example. Other info readers show parts of corresponding formatted files that consume approximately the same amount of disk space as their source. In contrast, TkMan processes the source files to extract only the hierachy information and caches this on disk; usually this amounts to about 2% of the source file size, after compression (no cacheing takes place if processing can be done in less than 1.5 seconds). Moreover, main memory use is minimized by loading in only those sections that have been opened for viewing in the outline. (Actually, for any opened section, the next section is prefetched and preformatted, so that it is immediately available if you're reading consecutive sections.)
If some stick-in-the-mud sys admin has not enabled TkMan's Texinfo reader, you can set it up for individual use. In Preferences/Database set Texinfo index directory to the directory in which to find a file named dir.tkman as well as to store one cache file per Texinfo book (regardless of the number of files that comprise it). This can be the same directory as present Texinfo directory. The dir.tkman file is a list of Texinfo files just like the dir file used by other info readers, except paths are full paths to each top source file. I've included my dir.tkman as a pattern. (Texinfo support could be extended to handle multiple info directories but I don't think that's necessary now as just have one short index files per info manual regardless of how many constituant files the manual has, whereas before the info directory was lengthened with many files per book.) The Texinfo volume is shown and reports errors in the file. This file read from disk every time it changes so you can dynamically experiment with it without restarting TkMan. Texinfo files must be suffixed with .texi or .texinfo to be recognized as such. In fact, a file need not be found in a dir.tkman list; any file with those suffixes are treated as Texinfo files, whether they are "top level" files that recursively include all the others in the book, or not. Texinfo source files can be compressed. If you're the effective sys admin for a shared repository as indicated by a writable Texinfo cache directory that is not in your home directory, you can build all the Texinfo cache files via the menu .../Rebuild Database/Texinfo. Otherwise, cache files are built on demand and added if have you have write permission to the cache directory.
Searching uses
Texinfo tags not supported: @image, @kbdinputstyle, @macro, @exdent, hyperlinks across Texinfo documents. Let me know if any of these is heavily used, and where. Also, nested tables and lists can get confused.
If you care to put your man pages under RCS revision source
control, you can optionally have TkMan display a man page with
differences--
The RCS archive is searched for the newest revision that has
differences. This way when you install new documentation you can
check it into RCS right away. This might not be suitable for
documentation that is frequently revised, as that for one's own
project perhaps. For these cases, you can specify the exact RCS
branch to diff against by associating the symbolic name checkpoint
with that branch (see
Version difference information is cached into tiny, compressed files with one line per change plus those lines deleted from the old version. Like Texinfo cache files, differences cache files are created on demand as one views files, or can be built/updated all at once with the .../Rebuild Database/Man page version (RCS) caches menu. Version difference information is cached into a subdirectory called RCSdiff under the place where the corresponding cached manual page would be stored, which is either .../man/catn or, if .../man/catn is not writable, in a separate directory tree specifically for this purpose.
As well, for manual pages with version information, TkMan dynamically introduces a pseudo-section that displays the version log, with hyperlinks that call up older versions. These older versions can be highlighted as stored as shortcuts.
Difference information is given on a line by line basis. (I tried
If you're using this option, don't compress the corresponding man page source as RCS doesn't like this. You can still compress cached formatted pages regardless.
If you are taking advantage of both Glimpse and man page versioning, you can prevent glimpse from indexing RCS versioning information by giving each RCS directory a chmod -x RCS.
The Preferences... choice in the Occasionals pulldown menu (called ...) brings up a graphical user interface to setting various attributes of TkMan, including fonts, colors, and icons. Click on a checkbutton at the top of the window to bring up the corresponding group of choices. After making a set of choices, the Apply button reconfigures the running application to show these changes, OK sets the changes for use now and in the future, Cancel quits the dialog and sets all choices to their settings as of the time Preferences was called up, and Defaults resets the settings in the current group to those set by TkMan out of the box. I suggest touring all the options to discover what all's available, tweaking to preference along the way.
The first line in the Fonts group specifies the font to use for the general user interface-- labels on buttons and text in menus. The first menu in the line labeled Interface sets the font family, the next menu sets the font size, and the last the font styling (normal, bold, italics, bold-italics). Text display makes these settings for the text box in which the manual page contents are displayed. For listings of all man pages in a particular volume (as chosen with the Volumes menu), you may wish to use a smaller font so that more names fit on the screen at once. The text added/changed/deleted choices-- which apply only if you are showing man page version differences as described above--use the same font size as Text display.
Colors sets the foreground and background colors to use for the the general user interface, the buttons of the user interface, and the manual page text display box. In addition it sets the color (or, with editing of the .tkman file, font) in which to show various classes of text in the text box, including manual page references, incremental search hits, regular expression search hits, and highlighted regions.
The See group specifies what information and controls to display. Usually manual page headers and footers are uninteresting and therefore are stripped out, but a canonical header and footer (along the date the page was installed in the man/mann directory and by whom) to be shown at the bottom of every page can be requested. In an effort to maximize screen real estate devoted to displaying content, you can choose to hide all menus and buttons (the row with Sections, Highlights, Volumes at top; and Search, Mono, Quit at bottom) until they made are active, either by tabbing into that line or by moving the mouse into that region. This is for the experienced user who knows where things are. Solaris and IRIX systems come with many "subvolumes"--that is volumes with names like "3x" and "4dm" that form subgroupings under the main volumes "3" and "4", respectively--and you make use tkmandesc commands to add your own subvolumes. You can reduce the length of the main Volumes menu by placing all volumes in such groups as cascaded menus. When a highlighted passage is jumped to via the Highlights menu, some number of lines of back context are included; the exact number of lines is configurable. Around the man page display area runs a buffer region of a few pixels, the exact width of which is configurable.
You have the option to view manual pages as outlines whereby sections and subsections can be collapsed and expanded. The choices here control the initial outline displayed when a page is first displayed. You can have all sections collapsed or all expanded, or turn off outlining altogether. More interestingly, you can have all collapsed but for those that match a pattern. This defaults to match the sections long Names, short Descriptions, Synopsis, Author, and See Also. The pattern is matched against the name of the section appended with the number of lines in that section. The number of lines is used to expand sections only if they are long enough to be interesting or short enough to leave screen real estate for other sections.
It is likely that any text you highlighted on a page is important, and you can elect to show this text even inside otherwise collapsed outline sections. In this way, highlighted text can serve as a combination note and "in-place bookmark": Sometimes just the excerpted lines containing the highlighted text provides sufficient information; if not, click on the highlight and the section will expand and scroll to that text (with a configurable number of lines of back context). You can turn off this option (never), or just excerpt the highlights when the page is first shown (at first), after which any action that opens or collapses an outline section dismisses the excerpts. Setting the option to always keeps the corresponding category of text always visible and uses a plain font as opposed to at first's italics. Likewise for manual page references. Likewise for searches, except that searches first close up all outline sections. It can be helpful to have some words jump out on the page, as for instance words that indicate danger ("warning", "unsafe"), standards conformance ("internationalization", "POSIX"), pointers to documentation in different formats ("Texinfo", "PostScript", "HTML"), or system-specific options in general software ("Solaris", "Macintosh"), to name a few. The regular expression on the Autosearch line are automatically found in the manual page and highlighted to immediately grab the eye, on their first character so as not to overwhelm the screen. In general, the more internal structure, like command line options and subcommands, the greater the value of Notemarks. A second regexp of less urgent strings is also autosearched, but not reported as Notemarks; you see them when viewing that part of the page. Notemarks are another reason to use the outlining interface, for with text collapsed to more or less fit on one screen, you can actually see them all immediately, rather than scrolling (or not) to see them (or not).
Sometimes even after opening selected sections and showing highlights, some vertical screen
real estate remains. If so, this space is filled with as much information as fits from the highly
important Description section, if that section is not already fully expanded, thus
maximizing the information for a page that is shown on its first screen.
The Excerpt line lists, in priority order, the sections that should be excerpted,
either always in their entirity or as there is room on the first screen.
Perl 5 man pages aren't very amenable to outlining or excerpting:
they'll often have a couple line
If a page is short enought to fit on the screen in its entirety, outlining is superfluous and not applied. Also overriding the initial outline settings, the page always scrolls to show the last screen viewed, expanding sections as necessary.
If a man page has not been formatted by nroff, TkMan must
first pipe the source text through nroff. By turning on
Cache formatted (nroff'ed) pages in the Database
group, the nroff-formatted text is saved to disk (if
possible), thereby eliminating this time-consuming step the next time
the man page is read .
Actually, nowadays machines are so fast that you may as well
turn cacheing off.
The on & compress setting will
compress the page, which saves on disk space (often substantially as
much of a formatted page is whitespace), but will make it unavailable
to other manual pagers that don't handle compression (you may
be forced to use a character-based man pager over a dial-up line
or during system debugging after a crash).
If you're using
Volumes' (recent) choice will show all manual pages that have been added or changed within the past n days. If you usually use the GNU implementations of standard UNIX utilities, which usually boast enhanced functionality, you can redirect man page references to the GNU version for those that are named by taking the UNIX name and prepending a g (e.g., od ⇒ god). If you have this option switched on but have an exceptional case (for instance you want zip, the free file compressor compatible with PKZIP, and not gzip (which is a superior replacement for compress) prefix the name with a caret (^, as in "^zip").
Glimpse works best when searching for relatively uncommon words; guard against getting too many hits by setting the maximum number reported. By default Glimpse indexes are placed at the root of the corresponding man hierarchy, where they can be shared. For the case when an individual may not have write permission there, a single, unified index can be created and stored locally (though you lose control of it from Paths settings). Unified indexes are faster than distributed. On the other hand, rebuilding the index generally takes longer, since the distributed version will only have to rebuild the indexes for those directories that changed. On the third hand, glimpse can usually incrementally rebuild my unified index in just a couple of minutes. For unified indexes and also for "stray cats" (i.e., directories not part of a set of man hierarchy directories), you should specify an auxiliary directory to hold the index.
As mentioned above, TkMan displays Texinfo books by reading Texinfo source code. For better performance, TkMan caches indexes into these books, some of which are very long (18MB for Elisp). Although indexes are relatively small, 2% or so of the original, they still must be stored somewhere, specified here.
The Window group sets all the options relating to window management, including iconification. The pathnames of the icon bitmap and icon mask should be the full pathnames (beginning with a `/'). If Path name to icon bitmap is set to (default), the internal icon by Rei Shinozuka will be used. If your window manager has trouble with iconifying and deiconifying TkMan and you are using the (default) setting, try setting the icon to a path.
Miscellaneous. By default, man page links are activated by single clicking. If it is changed to double with Mouse click to activate hyperlink, the first click puts the name in the entry box so that it can be used as the apropos or glimpse pattern as well as for man searching. This click once to select, twice to launch follows the Macintosh convention.
TkMan can extract section headers from all manual pages, but only some manual page macros format subsection headers in a way that can be distinguished from ordinary text; if your macros do, turn this option on to add subsections to the Sections menu. If you find that many lines are being interpreted as subsections, turn it back off. The History pulldown, the down arrow to the right of the name typein box, must balance depth of the list against ease of finding an entry; set your own inflection point with this menu. Tk deviates from Motif behavior slightly, as for instance in highlighting buttons when they're under the cursor and in the file selection box, but you can observe strict Motif behavior.
There are four levels of configuration.
(1) Transparent. Simply use TkMan and it will remember your window size and placement, short cuts, and highlights (if you quit out of TkMan via the Quit button).
(2) Preferences editor (see Preferences above).
(3) Configuration file. Most interesting settings--those in the Preferences dialogs and more not available there--can be changed by editing one's own ~/.tkman file. Thus, a single copy of TkMan (i.e., the executable tkman) can be shared, but each user can have his own customized setup. (The file ~/.tkman is created/rewritten every time one quits TkMan via the Quit button in the lower right corner. Therefore, to get a ~/.tkman to edit, first run and quit TkMan. Do not create one from scratch as it will not have the proper format used for saving other persistent information, and your work will be overwritten, which is to say lost. As well, be careful not to edit a ~/.tkman file only to have it overwritten when a currently running TkMan quits.)
Options that match the defaults are commented out (i.e., preceded by a #). This is so that any changes in TkMan defaults will propagate nicely to end users, while maintaining a list of all interesting variables. To override the default settings for these options, first comment in the line.
The ~/.tkman save file is the place to add or delete colors to the
default set, which will subsequently become menu choices in
Preferences, by editing in place the variable
man(colors). One may also edit the order of Shortcuts
in the man(shortcuts) variable.
Other interesting variables include
man(highlight), which can be edited to change the background
in place of the foreground, or both the foreground and
background, or a color and the font as with the following
setting:
set man(highlight) {bold-italics -background #ffd8ffffb332}
Arbitrary Tcl commands, including tkmandesc commands (described below), can be appended to ~/.tkman (after the ### your additions go below line).
To set absolutely the volume names for which all directories should be
searched, edit the parallel arrays on these existing lines:
set man(manList) ...
set man(manTitleList) ...
Changing the order volumes in these lists (make sure to keep the two lists
in parallel correspondence) changes the precedence of matches when two or
more pages have the same name: the page found in the earlier volume in this list
is show first.
Additional useful commands include
(4) Source code. Of course, but if you make generally useful changes or have suggestions for some, please report them back to me so I may share the wealth with the next release.
Key bindings related to the text display box are kept in the
sb array in ~/.tkman (for more information on Tcl's
arrays, refer to the
Like xman, TkMan gives you directory-by-directory control over named volume contents. Unlike and superior to xman, however, each individual user controls directory-to-volume placement, rather than facing a single specification for each directory tree that must be observed by all.
By default a matrix is created by taking the product of directories in the
The interface to this functionality takes the form of Tcl commands, so you
may need to learn at least pidgin Tcl--particularly the commands that deal with Tcl lists
(including
Directory titles and abbreviations are kept in lists. Abbreviations MUST be unique (capital letters are distinct from lower case), but need not correspond to actual directories. In fact, volume letters specified here supercede the defaults in identifying a volume in man page searches.
The following commands are appended to the file ~/.tkman (see Customizing TkMan, above).
To recreate a cross product of current section lists:
manDescDefaults
This cross product is made implicitly before other tkmandesc commands.
Almost always this is what one expects. If it is not, one may suppress the
cross product by setting the variable manx(defaults) to a non-null, non-zero
value before other tkmandesc commands are invoked.
To add "pseudo" sections to the current volume name list, at various positions including
at end of the list, in alphabetical order, or before or after a specific volume:
manDescAddSects list of (letter, title pairs)
or manDescAddSects list of (letter, title) pairs sort
or manDescAddSects list of (letter, title) pairs before sect-letter
or manDescAddSects list of (letter, title) pairs after sect-letter
In manual page searches that produce multiple matches, the page found
in the earlier volume is the one shown by default.
To move/copy/delete/add directories:
manDescMove from-list to-list dir-patterns-list
manDescCopy from-list to-list dir-patterns-list
manDescDelete from-list dir-patterns-list
manDescAdd to-list dir-list
The dir-patterns-list uses the same meta characters as man
page searching (see above). It is matched against
Adding directories with manDescAdd also makes them available to Glimpse for its indexing.
Warning: Moving directories from their natural home slightly impairs searching speed when following a reference within a man page. For instance, say you've moved man pages for X Windows subroutines from their natural home in volume 3 to their own volume called `X'. Following a reference in XButtonEvent to XAnyEvent(3X11) first searches volume 3; not finding it, TkMan searches all volumes and finally finds it in volume X. With no hint to look in volume 3 (as given by the 3X11 suffix), the full volume search would have begun straight away. (Had you clicked in the volume listing for volume X or specified the man page as XButtonEvent.X, volume X would have been searched first, successfully.)
To help debug tkmandesc scripts, invoke manDescShow to dump to stdout the current correspondence of directories to volumes names.
(1) To collect together all man pages in default volumes 2 and 3 in all
directories into a volume called "Programmer Subroutines", add these lines
to the tail of ~/.tkman:
manDescAddSects {{p "Programmer Subroutines"}}
manDescMove {2 3} p *
To place the new section at the same position in the volume pulldown list
as volumes 2 and 3:
manDescAddSects {{p "Programmer Subroutines"}} after 2
manDescMove {2 3} p *
To move only a selected set of directories:
manDescAddSects {{p "Programmer Subroutines"}}
manDescMove * p {/usr/man/man2 /usr/local/man/man3}
(2) To have a separate volume with all of your and a friend's personal man
pages, keeping a duplicate in their default locations:
manDescAddSects {{t "Man Pages de Tom"} {b "Betty Page(s)"}}
manDescCopy *phelps* t *
manDescCopy *page* t *
(3) To collect the X windows man pages into two sections of their own, one
for programmer subroutines and another for the others:
manDescAddSects {{x "X Windows"}} after 1
manDescAddSects {{X "X Subroutines"}} after 3
manDescMove * x *X11*
manDescMove x X *3
(4) If you never use the programmer subroutines, why not
save time and memory by not reading them into the database?
manDescDelete * {*[2348]} (braces prevent Tcl from trying to execute [2348] as a command)
Alternatively but not equivalently:
manDescDelete {2 3 4 8} *
TkMan's tkmandesc capability is patterned after xman's mandesc files. By placing a mandesc file at the root of a man page directory tree, one may create pseudo volumes and move and copy subdirectories into them. Silicon Graphics has modified xman so that simply by creating a subdirectory in a regular man subdirectory one creates a new volume. This is evil. It violates the individual user's rights to arrange the directory-volume mapping as he pleases, as the mandesc file or subdirectory that spontaneously creates a volume must be observed by all who read that directory. By contrast, TkMan places the directory-to-volume mapping control in an individual's own ~/.tkman file. This gives the individual complete control and inflicts no pogrom on others who share man page directories. Therefore, mandesc files are not supported in any way by TkMan.
One may still share custom setups, however, by sharing the relevant lines of ~/.tkman. In fact, a tkmandesc version of the standard SGI man page directory setup is included in the contrib directory of the TkMan distribution. For assistance with SGI-specific directory manipulation, contact Paul Raines (raines@slac.stanford.edu).
I estimate that fully 75% of my time writing TkMan has been spent not in adding new features but in supporting all the many, gratuitous differences in the various flavors of UNIX. Amazingly, each is different from every other. TkMan confronts variations in man page organization, that is, directory structure. The same percentage holds for PolyglotMan, which deals with variations in the formatting of the pages themselves, things like what character sequence indicates italics and what do page headers and footers look like. The result of all this work is that you can do a simple installation of TkMan and it will embrace the specifics of your system's manual page installation.
Here's the classical organization. The
Here are all the ways that I can recall that various flavors of UNIX have "improved" the classical organization. Clearly TkMan can do all that it does without reliance on any extension beyond the classical organization, so how important were these "extensions"?
SunOS
Solaris
Ultrix
OSF/1 aka Digital UNIX
HP/UX
SCO
FreeBSD
Linux
BSDI
IBM AIX
SGI Irix - absolute worst by far
* TkMan used to have a variety of ways to set the
For history buffs, here are how a MANPATH would be set if it didn't
come from the environment: gmanpath's compiled-in
What's wrong with configuration files? BSDI, SCO, and Linux have
central configuration files. One problem is that they're all
different from one another and not used by other platforms--and at least some of them are constantly changing. So
general man page-related programs don't know about them, and for TkMan
they degenerate into yet another special case. Not only are these
configuration files not portable, they are useless at best or even
harmful. They are useless for a user of any sophistication as he will
set
There are several ways to examine the pages from multiple operating systems at the same time.
If you change your
Among man pagers, as far as I know only TkMan has integrated full text search, highlighting, outlining interface and Notemarks, man page versioning display, comprehensive volume listings including lists of recent pages and results of previous full text search, regular expression and fuzzy page name matching, document map, Preferences configuration panel, and is as widely portable, among other features. In other areas, such as adding hyperlinks, TkMan isn't unique, but it still probably does things better as a result of continually being refined since 1993 with the valuable suggestions and bug reports from thousands of users (the builtin Statistics and Information page lists some). Plus, TkMan has the coolest icon. And it's heaps more fun.
Below the term Texinfo refers to the source code for GNU documentation, and info to formatted Texinfo (which is compiled to a form suitable for display on a character terminal, or tty). As far as I know, only TkMan displays from Texinfo source, making possible its considerably higher quality formatting.
Of the seemingly innumerable man page and info viewers, here are a few of the more interesting ones I have seen:
Refer to http://math-www.uni-paderborn.de/~axel/tkinfo/ for a description of many more Texinfo viewers.
Copyright (C) 1994-2003 T.A. Phelps
initial prototype developed in 1993 at the
University of California, Berkeley
Computer Science Division
Two Years with TkMan, a retrospective paper that uses TkMan as an example for various techniques for writing faster and more robust Tcl/Tk programs, was named Best Paper of the 1995 Tcl/Tk Workshop. A Berkeley Computer Science Division technical report (CSD-94-802) is a version of the X Resource article before it was butchered by the editor.
Manual last revised on $Date: 2003/04/01 22:41:38 $