pan(l)

NAME
pan - Post A Note Open Look program

SYNTAX
pan [args...]

DESCRIPTION
The pan program keeps track of multiple text notes. Each note has its own window and associated attributes. The position, size, and visibility of each note is maintained across invocations along with the note text.

A note may be in one of three states: Visible, Hidden, or Veiled. A visible note has a window mapped to the display. A hidden note is not mapped to the display. A veiled note is a note which has been dismissed via the window manager's window menu. It is not mapped, but the permanent state is still "Visible". This feature allows a note to be unmapped, but made visible automatically upon the next invocation of pan. A veiled note may be exposed just like a hidden note.

The pan program accepts all standard Open Look command line arguments.

In addition, pan accepts the following command line arguments:

-d<directory>
    Set the initial pan directory. This overrides the X resource initialDirectory.

All notes are automatically saved to disk when the pointer moves outside of the note window, or upon loss of the keyboard focus. Note that saving to disk is only done if changes have been made.

The pan program has one base window from which many functions may be accessed. Each note consists of a separate window which may or may not be mapped to the display. The base window has the following buttons:

New Note
    Clicking on this button with mouse button 1 causes a new blank note to be created and made visible. This new note is created in the default folder.

    Clicking on this button and holding with mouse button 3 will bring up a menu of folders in which a new note may be created.

Hide Notes
    Clicking on this button causes all visible notes to be unmapped from the display.

Expose Notes
    This button has a menu attached to it. Clicking with mouse button 1 selects the default action. Pressing mouse button 3 brings up a menu. The menu items are:

    All
        Expose (make visible) all notes. This option can be limited in scope via the windowMax X resource. This is the default action.

    <Folders>
        An additional entry for each folder is displayed. By moving the pointer right, a menu of all hidden notes in that folder is displayed. The first entry is the item "All". Selecting this will expose all notes in the folder. This action is also limited by the windowMax X resource. The remaining items are individual notes within the folder.

Action
    This button has a menu attached to it. Clicking with mouse button 1 selects the default action. Pressing mouse button 3 brings up a menu. The menu items are:

    Create Folder...
        Selecting this menu item brings up another window that allows a folder name to be entered. When this is done, pan will create a new folder. This is the default menu item. This may be changed with the actionDefault X resource.

    Move Note...
        This menu item will bring up a window with 3 lists. The first list is the folder from which to move notes. The second list is the folder to which notes will be moved. The third list is the list of notes in the source folder. Select the appropriate source and destination folders, then select the note or notes to be moved and click on the "Apply" button. The selected notes will be moved to the destination folder.

    Print Note
        This menu item will bring up a menu of all folders, similar to the Expose menu. Sliding the pointer to the right while holding mouse button 3 down reveals a list of all notes in the selected folder. Highlight the one to be printed and release the mouse button to cause the note to be printed.

    Destroy Folder...
        This menu item will pop up a window with a list of all available folders. Selecting a folder and then clicking the "Apply" button will cause all notes in that folder to be destroyed. The folder itself will then be destroyed. This is an extremely destructive function and should be used with great care.

    Quit
        Cause pan to exit.

Search:
    This is a text entry field. It can be used to enter a regular expression. Upon pressing the return key, pan will search for a note with a title matching the RE and expose it if there is a single match. If more than one note matches, a list window will be displayed allowing multiple selections of notes to expose.

In addition, there is an abbreviated menu button to the right of the Search: text entry field. Using the X resource searchMenu, a list of regular expressions may be specified from which to build a menu. This allows shortcut exposures without typing in the text entry field. Using this menu does not destroy the contents of the text entry field. The default menu has only 1 regular expression: '.'.

NOTE WINDOWS
Each note window contains the following items:

Title
    This is a scrolling text entry item. A note title may be entered here. The title does not become active until the return key is pressed.

Hide
    Clicking on this button will cause this note to be hidden.

Action
    This is a menu button. Clicking on it with mouse button 1 will cause the default menu item to be selected. Clicking on it with mouse button 3 will display a menu with the following items:

    Print
        This item will cause the note to be printed.

    Width <n>
        This item will cause the note's width to expand so the text subwindow can accommodate at least <n> characters before wrapping. See the X resource setWidth for a more detailed explanation.

    Destroy
        This menu item will cause this note to be destroyed. There is no way to recover a note after this action is taken.

RESOURCES
The pan program will query the X server for resource information. The following items of information are examined by pan:

pan.initialDirectory (string)
    This resource may be defined with a directory name. Pan will read this directory for notes upon startup instead of reading the default directory. Note that the -d command line argument can override this.

    The current default directory is "$HOME/.pan". It will be created automatically by pan if necessary. Note that a directory other than the default will not be automatically created.

pan.printCommand (string)
    This resource may be defined to be a command that will cause a note to be printed.

    The current default command is "/usr/ucb/lpr $FILE". Another command, including flags may be substituted. Two special variables are available: $FILE, and $NOTETITLE. The first will contain the full path and file name of the note selected to be printed. The second will contain the full title of the note selected to be printed. If a postscript printer is available, a nicely formatted printout may be obtained by using 'mp -o -s "$NOTETITLE" $FILE | lpr'. Don't include the single quotes in the .Xdefaults file. I use them for emphasis only.

pan.confirmDestroy (boolean)
    This resource controls whether pan will display a confirmation notice when the destroy button on a note is selected.

    The default value is False.

pan.noticeBeep (boolean)
    This resource controls whether notices displayed by pan will be accompanied by an audible beep.

    The current default is True.

pan.iconTransparent (boolean)
    This resource controls whether or not the icons used by pan have a transparent background. It is retained for backwards compatibility. Icon masks are now used, so this attribute currently has no effect.

    The default value is False.

pan.folderOrder (string)
    This is a string resource. It consists of a comma separated list of folder names. This resource allows the order in which folders appear in the menus to be specified. Any folders not explicitly mentioned are added to the end of the list in the order in which they are encountered when reading the directory.

    The default value is "Miscellaneous".

pan.defaultSearch (string)
    This resource allows the specification of a default search string to appear in the "Search:" field in the base window.

    The default value is "".

pan.folderInTitle (boolean)
    This resource specifies whether or not to display a note's folder name along with the note title in the window manager's title bar.

    The default is False.

pan.textFont (string)
    This resource allows the specification of an alternate font to be used in the text subwindow. I highly recommend using a fixed with font in this resource if the Width menu item on a note is to be used. I have found that a good font is "8x13". (Quotes for emphasis only.)

    The default font if this resource is not set is chosen by the XView toolkit, and depends upon the -scale option.

pan.windowMax (integer)
    This resource limits the number of windows that may be exposed as the result of a single expose action. If the number would be exceeded, and the expose action is interactive, a confirmation notice is posted before pan will continue the operation. If the operation is from the pan control language, windowMax notes are exposed, then the action is halted silently.

    Use a value of -1 to disable this feature. A value of 0 will cause confirmation to occur for every expose action. Any other value will allow that many notes to be exposed before confirmation is requested.

    The default value is 20.

pan.actionDefault (string)
    This resource allows the default menu item on the Action menu button on the main pan window to be chosen. This option is case sensitive and the value must be spelled exactly as seen in the menu including the periods.

    The default value is "Create Folder...". (Quotes for emphasis only.)

pan.menuTextLength (integer)
    This option specifies the maximum number of characters of the note titles that will appear in the Expose Notes and Print Note menus. This allows for more or less of a title to be displayed in a menu. Note that by default the font used in menus is proportional. Because of this, pan will calculate the pixel width of a string of menuTextLength characters from the average character width, then build a specific menu item adding or subtracting characters to get as close to the calculated value as possible. This allows some titles to squeeze in a few extra characters, and generally makes the menu items line up better.

    The default value is 20.

pan.setWidth (integer)
    This resource specifies the character width that a note window will be set to when the note's Width <n> menu item is chosen. Note that this works best if a fixed width font has been specified with textFont. The default text subwindow font size is reported inaccurately by XView, (especially when -scale is used), making it difficult to accurately calculate a proper window size. Even with a fixed width font, the window size is only approximate because XView provides no way that I can find to determine the scrollbar width, or the window border widths. See topMargin for a more detailed explanation of window border settings.

pan.logging (boolean)
    This resource is used to prevent pan from creating a log file during command execution. See the section on Control Language for more information.

    The default is True.

pan.topMargin (integer)
pan.bottomMargin (integer)
pan.leftMargin (integer)
pan.rightMargin (integer)
    These resources are used to indicate the pixel widths of the window manager's frame that is placed around pan windows. The defaults are set to reasonable values for olwm and olvwm. If another window manager is used, set these resources to appropriate values. Failure to do this can cause pan to incorrectly calculate window sizes and widget positions.

pan.checkInterval (integer)
    This resource is used to control how often the control language file is checked for new commands. The value should be specified in seconds.

    The default value is 60 seconds.

pan.searchMenu (string)
    This resource may be used to specify a list of note titles that will be used to build the shortcut search menu. The items must be space or comma separated, and both single and double quotes are supported in case a title contains whitespace.

    The default value is ".".

pan.noteWidth (integer)
pan.noteHeight (integer)
    These resources are used to indicate a preferred width and height for a newly created note. By default, pan tries to create a note as small as possible, while making sure that all buttons and text items are visible. This may be overridden by specifying both resources. If only one is specified, it is ignored. The values for both are specified in terms of pixels. Note that if these resources are used, pan will not be able to adjust automatically to the use of the -scale option.

    The default value for both is -1 which means pan will determine the appropriate size based on the scale and the fonts requested.

CONTROL LANGUAGE
New to Pan V3.0 is a command line interface and general control language. Most of the features available in pan through the windowing interface can now be used from the command line via a program called pancmd. See the manual entry for pancmd for more information on how to use the command. This section describes the actual control language since it is part of the pan program.

The following actions are supported by the control language:

    o Note Creation
    o Note Exposure
    o Note Hiding
    o Note Veiling
    o Note Printing
    o Note Movement Between Folders
    o Folder Creation
    o Pan Process Exit

Note that no destructive commands have been implemented. The following is a list of the commands and their syntax. The convention I use in describing the syntax is to surround optional arguments with "[]", and to indicate user required parameters with "<>".

When specifying a parameter for a command, if whitespace must be embedded, single or double quote marks may be used around the parameter.

Note Creation
    newnote [folder <folder>] [title <title>] [size <width> <height>]
        [location <x> <y>] [hidden|visible|veiled] [file <name>]

    This command causes pan to create a new note. All parameters are optional. If no parameters are specified, the default action is to create a note as if the "New Note" button had bee clicked on with mouse button 1.

    The folder and title options may be used to specify the note's folder and title respectively. The size and location options will control the note's size and location respectively. The parameters for these options are to be specified in pixels. By default, a new note is visible, but any of the three states may be specified for the note. The optional file parameter specifies a full path name of a file from which the contents of the note are to be loaded.

    Example:

        newnote title Termcap size 500 200 location 10 10 visible
            file /etc/termcap

Note Exposure
    expose title <title RE> [windowmax <max # to expose>]

    This command causes pan to expose all notes (up to the X resource pan.windowMax) with titles that match the given regular expression. If the windowmax parameter is given, it temporarily overrides the maximum set in the X resource database.

    Example:

        expose title "Phone Numbers"

Note Hiding
    hide title <title RE>

    This command will cause all notes with titles matching the given regular expression to be hidden.

    Example:

        hide title "To Do List"

Note Veiling
    veil title <title RE>

    This command will cause all notes with titles matching the given regular expression to be veiled.

    Example:

        veil title "Meeting Tomorrow"

Note Printing
    print folder <folder> title <title RE>

    This command will cause all notes within the specified folder that have titles matching the given regular expression to be queued for printing. In order to not overload the computer, pan will start only one print command (specified by the X resource pan.printCommand) at a time. When the print process exits, the next matching note will be queued. This queuing process is done asynchronously in the background so that the pan process can still respond to other commands and user interaction.

    Example:

        print folder Reference title .

Note Movement Between Folders
    move source <folder> title <title RE> destination <folder>

    This command will move notes between folders. All notes with titles matching the given regular expression in the source folder are moved to the destination folder.

    Example:

        move source Miscellaneous title "[Xx] [Ww]indow" destination X_Notes

Folder Creation
    newfolder folder <name>

    This command will create a new folder. The folder name may not contain whitespace or slash characters.

    Example:

        newfolder folder X_Notes

Pan Process Exit
    quit

    This command causes the currently running pan command to exit.

NOTES
The pan program will accept drag and drop files from the Open Look file manager. For this feature to work, the file icon must be dropped directly into the text subwindow of the note. Dropping the icon anywhere else will not have any effect.

A late addition to this version of pan is the ability to drag a note to another application. The drag and drop target (the small square in the upper, right-hand corner of the note windows) may be used for this purpose.

If the note file directories are examined, occasionally files with names ending in a "%" character will be seen. These files are created automatically by the Open Look text subwindow package, and are simply old versions of the note files being edited.

WINDOW CLASS
Pan supports three different window classes for use with window manager properties such as minimal decor. The first is "PanMain". This is the class for the main window. The second is "PanNote". This is the class for all notes. The third is "Pan" (assuming the executable name is not changed). This is used for all pop up windows, such as the create folder window.

FILES
Default note directory:
    $HOME/.pan

Note files:
    Note_%d_%d
    Note_%d_%d.info

    where the "%d" instances are replaced by unique id numbers.

FILE FORMAT
The "Note_%d_%d" file is a plain ASCII file containing the note text. Lines are delimited by the newline character.

The "Note_%d_%d.info" file is a plain ASCII file currently containing 3 lines.

The first line contains 4 whitespace separated numbers followed by a text word. The 4 numbers describe the note window's start x, start y, width, and height. The text word is either "VISIBLE" or "HIDDEN" describing whether the note is mapped to the display by default or not.

The second line of the file contains the note title.

The third line is an ASCII representation of the decimal number returned by time(3) describing the note's creation date and time.

An example might be:
4	424	349	206	HIDDEN
Note title
664129826

BUGS
Occasionally, when a new note is created, the focus is initially in the text sub-window instead of in the title panel item. This appears to be a problem with XView.

Under OW3.0, if PgUp/PgDn is pressed when at the top/bottom of the file, the window beeps as many times as there are lines visible. This also appears to be a problem with XView. I have been told that there might be a patch from Sun for this problem, but I haven't tried to verify it.

The text sub-window package in xview creates files ending with a "%" character and doesn't delete them. Periodically it is a good idea to remove them by hand to recover disk space. If you accidentally destroy a note that had text in it, you might be able to recover the text by looking through the files ending with a "%" character.

ACKNOWLEDGEMENTS
My thanks to the many people who submitted bug reports and requests for enhancements. I have tried to incorporate as many of the ideas I received as possible into version 3.0 of Pan. I'm not listing specific names here because I didn't keep track of the people, just the requests. Sorry. Next time I'll keep the names too.

If you don't find your enhancement request in this release, don't despair! I was unable to include everything I wanted to because of the demands of my real job. If you don't see it, and you still want it, feel free to request the feature again.

AUTHOR
Jeffrey Bailey