Copyright (c) 2004-2011 by David Reed. This application and its source code are distributed under the terms of the BSD License, which should be included in this distribution.
iMan is not currently maintained. This repository contains the version of iMan that was current as of 2012.
iMan is a graphical viewing application for UNIX man pages (textual documentation files). iMan provides a Mac OS X native Aqua interface as an alternative to use of the man program via the Terminal. This directory contains almost everything you'll need to build or make changes to iMan: source code, resources, and and links to the third-party frameworks needed (see below).
iMan is divided into two main parts, an application and an engine framework. The application, mostly controller layer, manages iMan's UI and interacts with the model layer,
iManEngine.framework. The engine framework handles the low-level duties of asynchronously interfacing with the command line tools (man, groff, and makewhatis), parsing output, and sending that output in displayable form back to the UI. The engine could fairly easily be embedded in other applications that need this functionality.
Currently, iMan consists of the following major controller classes:
The delegate of
NSApplication, handles various minor tasks and service invocations, including dispatching requests to load
man:URLs. Also responsible for re-indexing, update checking, and maintaining the page database.
The "viewing window" class,
iManDocumenthandles loading and display of man pages, as well as
A fairly straightforward preference window controller. It will trigger re-scans of the page database when manpaths are edited.
iManIndexingWindowControllerHandles updating the indexes and displaying progress.
iManURLHandlerThis class is invoked to handle clicks on URLs of scheme "man:" and "x-man-page:" (see iMan.scriptTerminology). It calls through to
A variety of small support classes and categories are, hopefully, more or less self-explanatory.
iManEngine.framework holds (among others) the following classes:
iManPageThis class represents a single page. It abstracts away all the work of rendering pages, which is done asynchronously via
This class represents a section (e.g., "1", "3ssl"). It maintains references to subsections (section 3 has 3pm and 3ssl) and to pages under that section. Note that pages are stored as paths, not as
iManPageis to rendering manpages,
iManSearchis to searching them. It provides an API that supports future expansion (like SearchKit indexing/searching), though currently it provides only
whatissearches. Its work is also done asynchronously via
iManIndexrepresents one of the theoretically more than one indexes used by
iManSearch(right now, there is only the singleton
iManAproposIndex). It also handles the low-level business of updating indices via
iManMakewhatisOperation. The index is stored in a file in our Application Support directory.
iManPageDatabasemaintains an index of all of the manpages found in the currently configured manpaths so that they may be looked up quickly by name and section. This class is thread safe.
iManPageCacheThis singleton class manages the cache of
iManPageinstances. It watches for pages to finish rendering and saves the cached version to disk in a background thread.
iManEnginePreferencesThis class manages manpaths and tool paths. Called by both UI and engine. This class is thread safe.
iMan also requires three external libraries:
- RegexKitLite, by John Englehart. A modified version of Mr. Englehart's supplied example
RKLMatchEnumerator.mis included with iMan.
- Sparkle, by Andy Matusczak.
- RBSplitView, by Rainier Brockerhoff
Place Sparkle.framework, the RegexKitLite folder, and the RBSplitView folder in the base iMan directory of the source checkout and the project will find them (if versions or directory names have changed, you may need to adjust references within the project file).
The source code is fairly lightly commented. (Better documentation is on the to-do list). Documentation for iManEngine is included in HeaderDoc comments. If you have questions (or patches, or bugs, or improvements, or...), please send me an email.
-- David Reed