Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/x/volume17/tcleditr/part14

Text File | 1992-03-17 | 53.7 KB | 1,522 lines

Newsgroups: comp.sources.x
Path: uunet!cis.ohio-state.edu!zaphod.mps.ohio-state.edu!mips!msi!dcmartin
From: [e-mail] (Charlie Crowley)
Subject: v17i015: point text editor (TCL and TK), Part14/16
Message-ID: <[e-mail]>
Originator: dcmartin@fascet
Sender: [e-mail] (David C. Martin - Moderator)
Organization: Molecular Simulations, Inc.
References: <[e-mail]>
Date: Wed, 18 Mar 1992 14:19:27 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Charlie Crowley)
Posting-number: Volume 17, Issue 15
Archive-name: tcl-editor/part14

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 13 (of 15)."
# Contents:  doc/userman.1
# Wrapped by [e-mail] on Tue Mar 10 15:05:49 1992
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'doc/userman.1' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'doc/userman.1'\"
else
echo shar: Extracting \"'doc/userman.1'\" \(51929 characters\)
sed "s/^X//" >'doc/userman.1' <<'END_OF_FILE'
X\documentstyle{article}
X
X% $Header: /nfs/unmvax/faculty/crowley/x/pt/doc/RCS/userman.tex,v 1.2 1992/03/04 17:06:40 crowley Exp crowley $
X
X\sloppy
X
X\textwidth      6.5in
X\oddsidemargin  0in
X\evensidemargin 0in
X
X\topmargin      0in
X\headheight     0in
X\headsep        0in
X\textheight     8.5in
X\topskip        0in
X
X\parindent      0in
X\parskip        5pt
X
X\begin{document}
X
X\thispagestyle{empty}
X
X\vspace*{2in}
X
X\begin{center}
X\Huge
The Point Text Editor for X \\
X\vspace{0.35in}
X\Large
Version 1.3 \\
X7 February 1992 \\
X\vspace{1in}
Charles Crowley \\
Computer Science Department \\
University of New Mexico \\
Albuquerque, New Mexico 87131 \\
X505-277-5446 (office) or 505-277-3112 (messages) \\
[e-mail]
X\end{center}
X
X\newpage
X
X\tableofcontents
X
X\newpage
X
X
X
X\section{Getting Started}
X
Point is a text editor for X that uses the mouse much more extensively
than most text editors.
You can do most editing using only the mouse.
The editor was designed for programmers and hence it is optimized
for browsing programs.\footnote{
X    It seems to me that programmers spend much more time looking
X    at programs that actually editing them.}
Point supports any number of windows and makes it easy to move and copy
text within and between windows and provides a range of
search commands.
Point uses Tcl (tool command language) in its implementation.
Tcl is the macro language of the editor and provides an interprocess
communication mechanism as well.
X
X
X
X\subsection{Building Point}
X
The README file in the Point distribution tells how to build Point.
It uses the Tk toolkit which should be available from the same ftp
site you obtained Point from.
It requires X11 R4 but does not use the Xt intrinsics
or any Xt-based widget set.
X
X
X
X\subsection{Learning about Point}
X
In  sections \ref{sect:browser} and \ref{sect:text}
I will describe the default configuration of Point.
This will show you almost all of the features of Point but after
you are familiar with it you will probably want to customize
Point to your own tastes.
In sections \ref{sect:options} and \ref{sect:customize}
I describe how to customize Point.
X
I recommend you start by reading the manual page and try Point out first.
The manual page has everything you need to get started using Point.
X
X
X\subsection{Executing Point directly}
X
You need two files to start Point and they should both be in the
same directory:
X\begin{itemize}
X\item {\tt point} --- the executable file
X\item {\tt ptsetup.tcl} --- the configuration file
X\end{itemize}
There are other ways for Point to find its configuration file
which are described below.
X
You start Point with the command:
X\begin{verbatim}
X     point [-nobrowser] [-nb] [file ...]
X\end{verbatim}
X
Point starts with a file browser (unless you specified the
X{\tt -nobrowser} or {\tt -nb} command line option) and 0 or more text windows
X(depending on how many file names you put on the command line).
X
When Point begins it looks for its configuration file first in {\tt .ptrc}
in your home directory.
Normally this file consists of the single line of the form:
X\begin{verbatim}
X     source pathName/ptsetup.tcl
X\end{verbatim}
If it does not find {\tt .ptrc} then it looks for {\tt ptsetup.tcl}
in the current directory.
X
After reading its startup file, Point looks for a local (per directory)
setup file named {\tt .ptdirrc} in the current directory.
If this file is found, it is also read and interpreted.
X
In fact, whenever Point changes directories, it looks for a {\tt .ptdirrc}
file in the new directory and reads and interprets it if it is present.
XFor example, you might want to change the text colors so you could tell
from looking at the colors in a window which directory it was started from.
Or you could open a window displaying a help file for the directory
you are changing to.
X
The idea behind this is that that in general you will use
X{\tt .ptrc} so you can start Point from any directory.
But when you are just starting to use Point it is easiest just
to have {\tt ptsetup.tcl} in the current directory and Point will
find it there.
X
The file {\tt ptsetup.tcl} contains setup information that
Point requires to run correctly.
Point will not work if this file is not read.
You can change parts of this file to reconfigure Point.
The descriptions that follow describe one configuration of Point.
Most of the behaviors described can be changed by editing {\tt ptsetup.tcl}
or while Point is running through the PREFS pull down menu.
This is explained in more detail
in sections \ref{sect:options} and \ref{sect:customize}.
X
X
X
X\subsection{Executing Point indirectly}
X
It is faster to start Point once and always leave it running
because it takes a fairly long time to start (10 to 15 seconds).
You start it with a file browser window and select new files
to edit from it.
There is a Unix command for communicating with a running
copy of {\tt point} called {\tt pt}:
X\begin{verbatim}
X     pt [-browser] [-b] [-wait] [-w] [-interp interpName] [file ...]
X\end{verbatim}
This command first checks to see if Point is running.
If not, it starts Point with the {\tt -nobrowser} option
X(unless you specified the {\tt -browser} or {\tt -b} command line option).
The {\tt -b} option is an abbreviation of {\tt -browser}.
Then it sends a message to Point to open a window on each
file specified on the command line.
If {\tt -wait} (or {\tt -w} its abbreviation) is specified
X{\tt pt} waits for all of the windows it requested to be closed
and then {\tt pt} will exit.
Otherwise {\tt pt} will exit immediately after asking {\tt point} to
open the windows.
If the {\tt -interp} option is specified the next argument is the
name of the interpreter to which {\tt pt} will send messages.
The default value if {\tt point}.
It is also the name of the Unix command to start Point that {\tt pt}
will use if no interpreter by that name is running.
X
The Point startup file {\tt ptsetup.tcl} defines three variables
X{\tt location1}, {\tt location2} and {\tt location3} which
specify three window geometries.
Be default, {\tt pt} puts new windows at {\pt location1}.
But {\tt pt} also takes arguments of the form {\tt -1}, {\tt -2}, ...
X{\tt -9} and will place the windows of subsequent file names
in the respective {\tt locationN}.
You can specify as many of these {\tt -N} flags and filenames
as arguments.
X
There are two major uses of {\tt pt}.
The first is to open a group of files that is easy to specify
with the shell filename wild card specifications.
XFor example you might execute:
X\begin{verbatim}
X     pt *.c
X\end{verbatim}
as a fast way of opening windows on all the .c files.
The second use of {\tt pt} is to use Point as an editor
that is called as a subprocess of another program to
edit a file.
A primary example is a mail program such as {\tt mail},
X{\tt elm} or {\tt xmail}.
XFor such programs you specify {\tt pt} as your editor of choice.
It will start {\tt pt} with a file name of a temporary file
X(for the body of a mail message for example) and {\tt pt} will
open a Point window on the file and wait until the window is closed.
X
X
X
X
X\section{File Browser Window} \label{sect:browser}
X
A file browser comes up when Point begins
X(unless you specified the {\tt -nobrowser} command line option).
You can create new file browsers at any time.
You can create a file browser from the text window menu.
If you close all the file browsers and all the text windows
you can still start up new ones with the {\tt pt} command.
X
X
X
X\subsection{Screen Layout}
X
Point puts up two types of main windows: file browsers and text windows.
A file browser contains a list of all open windows and a list of
files in the current directory (plus some titles and menus).
The contents of these windows are described in detail in this and the
next section.
X
The default file browser contains one column lists of file names.
If you resize the window to make it wider it will automatically
use as many columns as will fit in the window.
X
The defaults for window locations are set up with the following
screen layout in mind.
X(This can all be changed by the user with setup files.)
There are four main places for windows:
the northeast, northwest, southeast and southwest quadrants of the screen.
The southeast and southwest quadrants contain xterm windows,
the northeast quadrant contains a file browser
and the northwest quadrant contains a stack of text windows.
Normally you only look at one text window at a time so they are
stacked on top of one another.
You can zoom the windows vertically while you are working on
them to see more text.
X
X
X
X\subsection{Title bar}
X
Point assumes the window manager will provide a title bar for
each file browser.
The name of the window is set to the name of the directory
displayed in the file browser window.
The ``\verb+~+'' notation for your home directory is used in
the directory name in the title bar.\footnote{
X    The format of the title line can be specified by the user.
X    See the {\it titleFormat} and {\it iconFormat} options.}
X
X
X
X\subsection{Open window list}
X
This pane shows the names of the files in the open windows.
This list is both for your reference and for topping and moving the
listed windows.
Clicking on the name of an open window with the left mouse button
will bring that window to the top of the stacking order
and moved to geometry 502x410+0+0.
The middle and right mouse buttons will move the window to different
predefined locations on the screen.
Clicking on a file name in the open window pane with the middle
X(or right) mouse button causes the window to be moved to the second (or third)
predefined window locations with geometry 502x390+530+415
X(or 502x39+-530+0).\footnote{These geometries and the effect each each
mouse button can be redefined using the ptsetup.tcl startup file
or through the PREFS menu.}
X
An asterisk ({\tt *}) is put at the end of the file name
if the file has been edited but not yet saved.
The asterisk will also appear after the name on the title bar
of the text window containing the file.
X
X
X
X\subsection{File browser menu bar}
X
A menu of file selection commands appears above the list of files.
In this section we will go through each menu and item and
give (in parentheses) the Point name
for the command and a short description of the command.
A later section in this manual describes all the Point commands in detail.
X
This describes the file browser menu using the default Point
configuration file {\tt ptsetup.tcl}.
The menu bar contains only three items because the browser is usually thin.
X
X\begin{description}
X
X\item[MENU] (pull down menu)
This menu provides access to most of the other menus.
They are all pull right menus and are described below.
X
X\item[New]
This command allows you to create new browsers.
XEach browser will display the current directory.
If you click with the middle mouse button you get a browser right
next to the initial one.
If you click with the right mouse button you get a browser one browser
width away from the initial one.
If you click with the left mouse button you get a browser in the same
position as the initial one.
X
X
X\item[DIRS] (pull down menu)
This is the same as the DIRS pull right menu described below.
X
X\item[PREFS] (pull right menu)
This pull right menu contains a number of cascaded submenus which are
noted by a {\tt =>} at the end of the item name.
When the mouse is moved to such an item the submenu appears beside
the item.
An item ending in ``{\tt ...}'' will bring up a dialogue box
and is used for options that require you to type in a string.
There are also check boxes for boolean options and radio buttons
for ``one-of-several'' options.
Most Point options can be changed (or examined) from this menu.
X
X\item[New] (OpenFileOrCD)
This uses the current X selection as the name of a file or a directory.
If it is a file, Point will open a new window on that file.
If it is a directory then the file browser will change to that directory.
The X selection is the one made most recently and can be
from any program that can claim the X selection.
XFor example you can select a name in an {\tt xterm} window
and open the file (or change to the directory) with this command.
The list of files in the file browser claims the X selection for
a file name you select so if you click on a file name and
the click on this command that file will be opened.
The mouse button you click with determines the geometry of
the new window (if it is a file name):
X    \begin{description}
X
X    \item[Left mouse button] (OpenFileOrCD 502x410+0+0)
X
X    \item[Middle mouse button] (OpenFileOrCD 502x390+530+415)
X
X    \item[Right mouse button] (OpenFileOrCD 502x390+530+0)
X
X    \end{description}
X
X\item[DIRS] (pull right menu) (CD directoryName)
This is a menu of directories you can jump to by selecting a menu item.
You will want to put the directories you go to frequently
on this list.
You can do that by editing the {\tt ptsetup.tcl} file.
X
X\item[MISC] (pull right menu)
This is a menu of commands that are used  infrequently.
X    \begin{description}
X
X    \item[About Point ...] (MakeAboutBox)
X    Pop up a dialogue box giving information about
X    the version of Point you are using.
X
X    \item[Cancel copy mode] (CancelModes)
X    Cancel duplicate (also called copy) mode.
X
X    \item[Print statistics] (PrintStats)
X    Print some statistics about the effectiveness of Point's caches.
X
X    \item[Delete file] (exec rm [selection get])
X    Delete the selected file.  A convenience function.
X
X    \item[Insert ASCII ...] (MakeAsciiBox)
X    Begin up a dialogue box that allows you to insert
X    a character using its numerical ASCII code in decimal.
X
X    \item[Save all unsaved files] (SaveAllFiles)
X    Save all files that have been edited but not yet saved.
X
X    \item[Set debug ...] (MakeDebugBox)
X    Set an internal debugging variable.
X    This usually has no effect in distributed versions.
X
X    \item[Information] (print [Sel get])
X    Display (in the {\tt xterm} window Point was started in)
X    the character position
X    of the first and last characters of the selection.
X
X    \item[6x13] (BrowserFont 6x13)
X    Change the font used in the file browser for displaying
X    file names to {\tt 6x13}.
X
X    \item[6x13bold] (BrowserFont 6x13bold)
X    Change the font used in the file browser for displaying
X    file names to {\tt 6x13bold}.
X
X    \item[5x8] (BrowserFont 5x8)
X    Change the font used in the file browser for displaying
X    file names to {\tt 5x8}.
X
X    \item[*clean-medium-r*6*50*] (BrowserFont *clean-medium-r*6*50*)
X    Change the font used in the file browser for displaying
X    file names to a font that is about the smallest font in
X    X that might be considered legible by some people.
X    This will allow you to see a LOT of file names.
X
X    \item[8x13] (BrowserFont 8x13)
X    Change the font used in the file browser for displaying
X    file names to {\tt 8x13}.
X
X    \end{description}
X
X\item[ * ] (Option set filePattern *)
This causes the list of files to be regenerated.
It is used when you know the directory has changed.
Point does not monitor changes in the directory being
displayed so this allows you to be sure you are seeing
an accurate file name list.
X
X\item[New browser] (Browser 490x415+656+0 big)
This creates another file browser.
You might use this if you want to change to another directory
to find a file but you will want to go back to this directory
right after that.
This allows you to keep both contexts and might be used
if you are interrupted while editing a file and need to
look at another file.
X
X\item[Del file] (exec rm [selection get])
Deletes the selected file.
X
X\item[Close] (CloseBrowser)
Close this file browser but do not exit Point.
X
X\item[QUIT] (pull right menu)
This command bring up a menu that allows you to choose one of
three ways of quitting Point.
You can automatically save all unsaved files,
discard the edits for all unsaved files
or have Point ask you individually whether to save
each unsaved file.
X
X\end{description}
X
X
X
X\subsection{File list}
X
The largest pane of the file browser window contains a list of files
and directories in the current directory.
The directories are listed first and are displayed with a ``{\tt /}''
appended to the directory name.
You can change directories by double clicking on the directory name
in the file list.
X(You can also jump directly to directories using the ``DIRS''
menu from the menu line.)
If you double click with the left mouse button the browser changes its
display to that directory.
If you double click with the middle mouse button a new browser is created
in the position next to the initial browser.
That new browser will display the directory you double clicked on.
If you double click with the right mouse button a new browser is created
in the position one browser width over from the position
of the initial browser.
X
If you select a file name from the list, it is highlighted
and it the object of the next command from the menu bar.
If you double click on a file name a new window is created
that shows that file.
Double clicking on a file name is the most common way to open a new window.
X
If you double click on the file name with the left
mouse button the new window is placed in the first predefined
location (geometry of 502x410+0+0).
If you click with the middle mouse button you get the second
predefined location (geometry of 502x390+530+415) and the right mouse
button gets you the third predefined location (geometry of 502x390+530+0).
This are the same locations you get for existing windows by clicking
on their names in the open window list.\footnote{
Remember that these locations and the meaning of the various mouse
button clicks can be changed by editing the startup file ptsetup.tcl.}
X
X
X
X\subsection{Message line}
X
The message line contains messages to you from Point and can also
used to type in directory names and file patterns.
X
X
X
X\subsection{Typical usage of the file browser window}
X
The main use of a file browser is to select file names of files to open.
Double clicking on a file name opens a window on that file.
I use a multicolumn file name display to allow as many names as
possible to be displayed at once.
I like to get a sense of the whole directory.
The {\tt twm} window manager has a vertical zoom function
that is handy for quickly expanding and reducing
the file browser window.
X
Typically I open most windows in the NW position ---
my main position for windows.
I usually zoom vertically the NW window I am currently looking at and unzoom
it when I need to use the SW quadrant.
Zooming and unzooming is easy with the {\tt twm} window manager
or with the Point {\tt Zoom} command.
I open a window in the NE quadrant when I want to use it
together with the window in the NW quadrant.
XFor example, if I am copying code from one window to another
or if I am looking up a definition of a procedure or global
data object.
X
A typical situation would be the case where I want to add a
timeout to some part of the code (say to do auto-repeating).
I get the window in which I want to put the timeout in the NW quadrant
and in the NE quadrant I put up a window containing a file where
I have already implemented a timeout facility.
Rather than look up how to use the facility in the manual,
I just copy the setup calls and the timeout callback procedures
and modify them for the current situation.
Then I might bring up the resource file in the NE quadrant
and modify it by adding resources for the new widgets I am adding.
X
If I need to look at three files at the same time or if I need
to quickly look at another file while already looking at two files,
I use the SE quadrant location.
X
The ``New'' command can be used if you have the name of the
desired file in a window somewhere, either in a Point text
window or in an {\tt xterm} window or any window that sets the
XX primary selection.
A relative path name must be relative to the directory
shown in the file browser window since that is Point's
working directory.
X
The DIRS menu allows you to move around the file tree
by jumps --- it contains the names of directories
you use a lot.\footnote{
Point caches directory listings so if you jump to a directory
that you have seen before (and it hasn't changed since then)
it should come up pretty fast.}
You can also move up and down the directory tree
by clicking on directory names (including {\tt ../}) in the file name listing.
X
X
X
X\section{Text Windows} \label{sect:text}
X
XEach open file is displayed in a text window.
A file can be displayed in several windows at the same time.
Point will keep the display in each window consistent
with the other windows showing the same file.
Text windows can be moved and resized with the window manager.
X
X\subsection{The Active Window}
X
One of the text windows on the screen will be the {\em active window}.
This is the window that commands act on.
The last window the mouse sprite entered is the active window.
If you execute a command from the menu in a window then the commands
will always affect that window
X(because the mouse cursor must be in that window in order to
access the menu).
X
X
X\subsection{Text Window Menu Bar}
X
The menu bar contains both direct commands and pull-down menus.
Here I will list the commands on the menu bar and briefly
indicate their function.
In this section I will describes the menu bar of the default
Point configuration as specified in the file {\tt ptsetup.tcl}
distributed with Point.
All of these commands are described in more detail in a later section.
The Point command names are in parentheses.
X
X\begin{description}
X
X\item[FILE] A menu of file and window related commands.
X    \begin{description}
X
X    \item[Set text colors ...] (MakeColorBox)
X    A dialogue box is opened which will allow you to
X    change the foreground and background color of normal
X    text and of selected text.
X
X    \item[Set text font $=>$] (pull right menu)
X    A submenu of fonts to change the text font of this window
X    (only).
X
X    \item[PREFS] (pull right menu)
X    This pull right menu contains a number of cascaded submenus which are
X    noted by a {\tt =>} at the end of the item name.
X    When the mouse is moved to such an item the submenu appears beside
X    the item.
X    An item ending in ``{\tt ...}'' will bring up a dialogue box
X    and is used for options that require you to type in a string.
X    There are also check boxes for boolean options and radio buttons
X    for ``one-of-several'' options.
X    Most Point options can be changed (or examined) from this menu.
X
X    \item[Zoom vertical] (Zoom)
X    The window is resized to be the full height
X    of the screen (and the same width as it was before).
X
X    \item[Zoom full] (Zoom \{\}full)
X    The window is resized to be the full size of the screen.
X
X    \item[Move window $=>$] (pull right menu)
X    A submenu is displayed allowing you to move
X    the window to one of the four quadrants of
X    the screen.
X    \begin{description}
X
X        \item[Move to NE] (MoveWindow 502x410+0+0)
X
X        \item[Move to NW] (MoveWindow 502x390+530+415)
X
X        \item[Move to SE] (MoveWindow 502x390+0+415)
X
X        \item[Move to SW] (MoveWindow 502x390+530+0)
X
X    \end{description}
X
X    \item[Save file] (SaveFile)
X    The file in the active window is saved to disk.
X
X    \item[Save as ...] (SaveAs)
X    A new name is requested (with a dialogue box)
X    and the file is written to disk with that name.
X
X    \item[Open selection] (OpenWindow [selection get])
X    The X selection is used as the name of a file
X    and a window is opened to display that file.
X    A new window is created even if there is an existing
X    window open on that file.
X
X    \item[Open ...] (Browser 490x415+656+0)
X    A file browser is created with the specified geometry.
X
X    \item[Close $=>$] (pull right menu)
X    The window is closed and the submenu selection determines
X    whether the file in the window is automatically saved
X    (if it has been changed), is not saved (even if it has
X    been changed) or if the user is asked whether to save
X    the file (if it has been changed).
X    \begin{description}
X
X        \item[and save] (CloseWindow save)
X
X        \item[and ask] (CloseWindow ask)
X
X        \item[and discard edits] (CloseWindow nosave)
X
X    \end{description}
X
X    \item[About Point ...] (MakeAboutBox)
X    Pop up a dialogue box giving information about
X    the version of Point you are using.
X
X    \item[Quit Point $=>$] (pull right menu)
X    Point is exited and the submenu selection determines
X    whether the changed files are automatically saved
X    (if they have been changed), not saved (even if they have
X    been changed) or if the user is asked whether to save
X    each file (if it has been changed).
X    \begin{description}
X
X        \item[And save all] (QuitPoint save)
X
X        \item[And ask] (MakeQuitBox)
X
X        \item[And discard edits] (QuitPoint discard)
X
X    \end{description}
X
X    \end{description}
X
X\item[EDIT] A menu of editing related commands.
X    \begin{description}
X
X    \item[Insert X selection] (InsertSelectedString)
X    The X (primary) selection is inserted at the
X    insertion point.
X
X    \item[Cancel copy mode] (CancelModes)
X    Cancel copy (also called duplicate) mode.
X
X    \item[Indent selected lines] (IndentSelection)
X        A macro that indents (by one tab) every line that
X        is spanned by the selection.
X
X    \item[Outdent selected lines] (IndentSelection 1)
X        A macro that removes the first character of
X        every line that is spanned by the selection.
X
X    \item[Search and Replace ...] (MakeReplaceBox)
X    The command pops up a dialogue box that allows you to search
X    for a string and replace it with another strings.
X    The search and replace operation can be interactive
X    (asking you for verification of each replace) or batch.
X
X    \item[Regex Search and Replace ...] (MakeRegexReplaceBox)
X    The command pops up a dialogue box that allows you to search
X    for a string that matches a regular expression
X    and replace it with another strings.
X    The search and replace operation can be interactive
X    (asking you for verification of each replace) or batch.
X
X    \item[Define Selected Macro] (DefineMacro)
X        The selection will be used as the name of the
X        macro that the {\tt execMacro} will run.
X
X    \item[Execute Macro] (ExecMacro)
X        Execute the macro whose name was defined by the
X        {\tt DefineMacro} command.
X
X    \item[Execute Selection as Tcl] (ExecSel)
X        The selection is interpreted by Point's tcl
X        interpreter.  This can be used to define
X        (or redefine) a macro (if the selected text
X        is a macro definition).
X
X    \item[Scrap $=>$] (pull right menu)
X    A submenu allows you to either:
X    \begin{description}
X
X        \item[Insert from] (InsertFromScrap) insert the contents
X            of the scrap buffer at the insertion point
X
X        \item[Delete sel to] (DeleteToScrap) delete the selection
X            to the scrap buffer
X
X        \item[Copy sel to] (CopySelToScrap) copy the selection to
X            the scrap buffer
X
X        \item[Exchange sel with] (ExchangeScrap) exchange the
X            contents of the scrap buffer with the selection
X
X    \end{description}
X
X    \item[Copy $=>$] (pull right menu)
X    A submenu allows you to either:
X    \begin{description}
X
X        \item[Note destination] (CopyToHereMode) remember the
X            destination of the copy
X
X        \item[Sel to destination] (CopyToHereMode) copy the
X            selection to the remembered destination
X
X        \item[Cancel copy mode] (CancelModes) cancel a pending copy
X
X    \end{description}
X    The mouse sprite changes to a pointing hand when
X    you select a destination and changes back to an arrow
X    when you complete the move.
X
X    \item[Change Case $=>$] (pull right menu)
X    A submenu allows you to either:
X    \begin{description}
X
X        \item[To upper] (ChangeCaseOfSel toupper) change the case
X            of the selection to upper case
X
X        \item[To lower] (ChangeCaseOfSel tolower) change the case
X            of the selection to lower case
X
X        \item[Toggle case] (ChangeCaseOfSel toggle) to switch the
X            case of the selection
X
X    \end{description}
X    Only letters in the selection are affected.
X    All other characters in the selection are unaffected.
X
X    \item[Undo/Again/Redo $=>$] (pull right menu)
X    A submenu of commands for undoing, redoing and repeating commands:
X    \begin{description}
X        \item[Repeat last edit] (Again mostrecent)
X        The last edit is repeated but using the current selection.
X
X        \item[Last edit (this file)] (Again thisfile)
X        The last edit in this file is repeated
X        but using the current selection.
X
X        \item[Undo one edit] (Undo 1)
X        A previous edit is undone.
X        The first undo undoes the most recent edit and subsequent
X        undoes undo earlier edits.
X
X        \item[Redo one edit] (Redo 1)
X        The most recently undone edit is redone.
X
X        \item[Begin block undo] (Undo begin)
X        Mark the beginning of a sequence of edits that you want to
X        be all undone (and redone) together.
X
X        \item[End block undo] (Undo end)
X        Mark the end of a sequence of edits that you want to
X        be all undone (and redone) together.
X
X        \item[Show command history] (ShowUndoStack)
X        Pop up a dialogue box which shows the command history for
X        the file in this window.
X    \end{description}
X
X    \item[Redraw Window] (Redraw)
X    Redraws the text in the window.
X
X    \end{description}
X
X\item[GOTO] A menu of commands that move the window around in the text.
X
X    \begin{description}
X
X    \item[Goto Selected Line \#] (GotoLine [selection get] lof)
X        Go to the selected line number
X
X    \item[Goto Line \# ...] (MakeGotoBox) A dialogue box pops up
X        to allow you to type in a line number
X
X    \item[Goto Selection] (ShowSelection) move to the last place
X        you jumped from in this file
X
X    \item[Find Selected CTag] (CTag [selection get])
X        Find the selected C tag
X
X    Point implements C tags (like vi and emacs).
X    It uses the {\tt tags} file in the current directory
X    (created with the Unix {\tt ctags} command).
X    Point also will search certain files to determine which of them
X    contain a keyword.
X    The option {\tt keywordPattern} determines which files are searched.
X
X    \item[Find CTag ...] (MakeCtagBox) A dialogue box pops up
X        to allow you to type in a C tag
X
X    \item[Find Selected Keyword] (GetSelectedKeyword)
X        Find the selected keyword
X
X    \item[Find Keyword ...] (MakeKeywordBox)
X        A dialogue box pops up to allow you to
X        type in a keyword
X
X    \item[Find Matching bracket] (FindMatchingBracket)
X        If the first character of the
X        selection is a bracket then it will find the
X        matching bracket (taking nesting into consideration).
X        This works for: (, ), [, ], \{, and \}.
X
X    \item[Search for string $=>$] (SearchForString)
X    Forward is towards the end of the file and backward to towards
X    the beginning of the file.
X    A submenu allows you to either:
X
X    \begin{description}
X
X        \item[$>>$ for selected RE] (SearchForSel 1 forward)
X            search forward for a string that matches the
X            selected regular expression
X
X        \item[$<<$ for selected RE] (SearchForSel 1 backward)
X            search backward for a string that matches the
X            selected regular expression
X
X        \item[$>>$ for last RE] (RegexSearch \{\} forward)
X            search forward for the a string that
X            matches the last regular expression used
X
X        \item[$<<$ for last RE] (RegexSearch \{\} backward)
X            search backward for the a string that
X            matches the last regular expression used
X
X        \item[$>>$ for last string] (RepeatSearch forward)
X            search forward for the last
X            string that was searched for
X
X        \item[$<<$ for last string] (RepeatSearch forward)
X            search backward for the last
X            string that was searched for,
X
X        \item[$>>$ for selection] (SearchForSel 0 forward)
X            search forward for the next
X            instance of the selected string
X
X        \item[$<<$ for selection] (SearchForSel 0 backward)
X            search backward for the next
X            instance of the selected string
X
X        \item[For string ...] (MakeSearchBox normal)
X            a dialogue box pops
X            up which allows you to enter a string to search for.
X            The dialogue box also allows you to change two
X            search options: whether case is considered in
X            the search and whether the string can be part
X            of another string or must be a whole word.
X            The dialogue box also allows you to search
X            forward or backwards
X
X    \end{description}
X
X    \item[Move in file to $=>$] (pull right menu)
X    A submenu allows you to either:
X
X    \begin{description}
X
X        \item[Beginning] move to the first line of the file
X            (GotoLine 1 top)
X
X        \item[Last place] move to the last place you jumped
X            from in this file (MoveToLastPlace)
X
X        \item[End] move to the last line of the file (MoveToEndFile)
X
X    \end{description}
X
X    In addition you can move the mouse sprite into the ``GOTO'' box and
X    type a line number (ending it with any non-digit) and the
X    window will go to that line number.
X    This saves waiting for a dialogue box to pop up
X    (as selecting ``Line \# ...'' would require) but you have no
X    feedback as you type the digits.
X
X    \end{description}
X
X\item[$<<$] Searching backward.
X
X    \begin{description}
X
X    \item[Left button] (SearchForSel 0 backward)
X        Search backward (towards the beginning of the file)
X        for the next occurrence of the selected string.
X
X    \item[Middle button] (MakeSearchBox normal) Bring up a dialogue box
X        asking for a string to search forward for.
X
X    \item[Right button] (RepeatSearch backward)
X        Search backward (towards the beginning of the file)
X        for the last string that was searched for.
X
X    \end{description}
X
X\item[$>>$]  Searching forward.
X
X    \begin{description}
X
X    \item[Left button] (SearchForSel 0 forward)
X        Search forward (towards    the end of the file) for
X        the next occurrence of the selected string.
X
X    \item[Middle button] (MakeSearchBox regex) Bring up a dialogue box
X        asking for a string to search forward for.
X
X    \item[Right button]  (RepeatSearch forward)
X        Search forward (towards the end of the file)
X        for the last string that was searched for.
X
X    \end{description}
X
In addition you can type an incremental search string into
either ``$<<$'' or ``$>>$''.
Move the mouse sprite inside either search button
X(no button press is necessary),
type a non-ASCII character to clear the search string
X(a function key is usually a handy choice),
then type in the letters of the string to search for.
The search is incremental in that after each character of the string
is typed, the string so far is searched for.
If you type a backspace the last character in the search string is
erased (although the search will {\em not} back up to where it was before
that character was typed).
X
X\item[Close] Closing the window.
X
X    \begin{description}
X
X    \item[Left button] (CloseWindow save)
X        Close the window and save the file (if ti has been changed).
X
X    \item[Middle button] (CloseWindow ask) Close the window and ask about
X        saving the file (if it has been changed).
X
X    \item[Right button] (CloseWindow nosave)
X        Close the window and do not save the file.
X
X    \end{description}
X
X\item[Sv] Saving the file in the window.
X
X    \begin{description}
X
X    \item[Left button] (SaveFile) Save the file in the window.
X
X    \item[Middle button] (SaveAs) Save the file in the window
X        with a new name.
X
X    \item[Right button] (Redraw) Redraw the window.
X        (This doesn't fit here but there was a free slot.)
X
X    \end{description}
X
X\item[Jump] moves the window around in the file it is showing.
X
X    \begin{description}
X
X    \item[Left button] (GotoLine 1 top) Jump to the beginning
X        of the file.
X
X    \item[Middle button] (MoveToLastPlace) Jump to the last place
X        in the file that you jumped from (for any reason).
X
X    \item[Right button] (MoveToEndFile) Jump to the end of the file.
X
X    \end{description}
X
X\item[Tag] finds tags and keywords in certain files.
X    This command is described more fully in the sections that follow.
X
X    \begin{description}
X
X    \item[Left button] (CTag [selection get]) Find the selected tag.
X
X    \item[Middle button] (MakeCtagBox) A dialogue box pops up to allow
X        you to type in the C tag.
X
X    \item[Right button] (MakeKeywordBox)
X        Search all the {\tt *.c} and {\tt *.h} files
X        in the current directory (this can also be changed)
X        for the keyword.
X        A dialogue box is put up with a scrolling list of all
X        the files found to contain the keyword at least once.
X        You can click on the file names in this scrolling
X        list to open a window on that file or to top the window
X        continuing that file if one is already open.
X        when you click on the file name in the scrolling list
X        an asterisk will be prepended to the name so you can
X        keep track of which ones you have already looked at.
X
X    \end{description}
X
X%\item[insDel] Inserts and deletes.
X%    \begin{description}
X%    \item[Left button] (InsertFromScrap) Inserts the scrap buffer
X%        into the text.
X%    \item[Middle button] (InsertXSel) Inserts the X selection
X%        into the text.
X%    \item[Right button] (DeleteToScrap) Deletes the selection to
X%        the scrap buffer.
X%    \end{description}
X
X\item[+Do-] Again and undo.
X
X    \begin{description}
X
X    \item[Left button] (Redo 1) Redoes the last edit that was
X        undone with ``Undo'' and has not yet been redone.
X
X    \item[Middle button] (Again mostrecent) Repeats the last edit using
X        the current selection.
X
X    \item[Right button] (Undo 1) Undoes the most recent edit.
X        Repeated invocations will undo earlier and earlier
X        edits.
X
X    \end{description}
X
X\item[Zz] Affects the case of all the letters in the selection.
X
X    \begin{description}
X
X    \item[Left button] (ChangeCaseOfSel toupper) Changes them to all
X        upper case.
X
X    \item[Middle button] (ChangeCaseOfSel toggle) Switches the case
X        of each letter in the selection.
X
X    \item[Right button] (ChangeCaseOfSel tolower) Changes them to all
X        lower case.
X
X    \end{description}
X
X\item[MoveW] Moving windows to predefined locations.
X
X    \begin{description}
X
X    \item[Left button] (MoveWindow 502x410+0+0)
X        Top the window and move it to the specified geometry.
X
X    \item[Middle button] (MoveWindow 502x390+530+0)
X        Top the window and move it to the specified geometry.
X
X    \item[Right button] (MoveWindow 502x390+530+415)
X        Top the window and move it to the specified geometry.
X
X    \end{description}
X
X\item[Line\#] jumps the window to a line number.
X
X    \begin{description}
X
X    \item[Left button] (GotoLine [selection get] lof)
X        Jump to the line number indicated by the selection.
X        Either the X selection or
X        the Point selection, whichever was made more recently.
X
X    \item[Middle button] (MakeGotoBox) Bring up a dialogue box
X        to ask for a line number to go to.
X
X    \item[Right button] (Zoom) Zooms (or unzooms) the
X        window to the full height of the screen.
X
X    \end{description}
X
X    In addition you can move the mouse sprite into the ``Line\#'' box and
X    type a line number
X    (ending it with any non-digit---a function key is typically used
X    although {\tt vi} users might want to use {\tt G})
X    and the window will go to that line number.
X    This saves waiting for a dialogue box to pop up but you have no
X    feedback as you type the digits.
X
X\item[HELP] (HelpMenu) A menu of help topics.
X    When you select one of them, a text window is opened on a file
X    of help text about that topic.
X
X\end{description}
X
X
X
X\subsection{Text Pane}
X
This shows a part of the file being edited.
Usually some text will be {\it selected}.
Selected text is shown in the selected text colors or is underlined.\footnote{
Underlining looks nicer and is less obtrusive
than reverse video on some monochrome displays.}
Many commands operate on the selected text.
The position just in front of the first selected
character is called the {\it insertion point}.
X
X\subsubsection{Typing in text}
X
New text is entered by typing.
Text is inserted at the insertion point (in front of the selection).
The backspace or delete keys both erase the previous character.
Shift-backspace and shift-delete erase the previous word.\footnote{
The backspace, delete, shift-backspace and shift-delete keys
work any time, not just during text insertion.}
X
X\subsubsection{Selecting text}
X
The selection is the focus of almost all editing and many other commands
in Point.
The selection always contains at least one character.
X
There are two methods of selected text.
To select text by drawing through it:
X\begin{enumerate}
X\item move the mouse sprite to the beginning of the intended selection,
X\item press the left mouse button,
X\item move the mouse sprite to the end of the intended selection,
X\item release the left mouse button.
X\end{enumerate}
X
To select text by clicking on the two end points of the selection,
that is, by extending the selection:
X\begin{enumerate}
X\item move the mouse sprite to the beginning of the intended selection,
X\item click (press and release) the {\em left} mouse button,
X\item move the mouse sprite to the end of the intended selection,
X\item click the {\em right} mouse button.
X\end{enumerate}
X
Normally text is selected by character (this is called
X{\em character mode}) but
if you double click the left mouse button
you change to {\em word mode}, which
means that the selection will be extended (or contracted) by full words.
A word is either a single punctuation character or a contiguous
string of letters, digits and underscores ({\tt \_}).
If you triple click the mouse button you change to {\em line mode}
and the selection is extended (or contracted) in units of whole lines.
To use the draw through method of selection for word and line mode,
you hold down the middle mouse button on the last of the multiple
clicks (the second click for word mode and the third click for line mode)
and drag the mouse over the words or lines you wish to select.
If you select in word (line) mode then the selection will extend
by words (lines) also.
X
Triple clicking on a line not only selected the line but it also
causes the line number of be displayed in the message line.
This is and easy way to determine the line number of a line.\footnote{
Another way it to turn on line numbering.}
X
X
X
X\subsubsection{Scrolling}
X
Point implements two distinct kinds of scrolling.
The first kind will be called ``line to top'' scrolling
which is the default.
It works as follows.
X
The scroll bar on the left indicates where you are in the file
and how much of the file is showing in the window.
Clicking the right mouse button on the scroll bar scrolls down
X(towards the end of the file) by a certain number of lines.
This command scrolls the line the mouse sprite is at to the top
of the window.
Clicking the left mouse button scrolls up so that the top line of the
window moves to the line the mouse sprite is on.
X
Setting the {\tt button1ScrollsDown} option to {\tt False} will reverse
the meaning of the left and right buttons.
X
If you hold down either the left or right mouse buttons,
the scrolling will continue (in units determined by where
the mouse sprite is) as long as you hold down the button.
X
Clicking the middle mouse button on the scroll bar jumps the
window to that part of the file, that is, the scrollbar slider will
move to where the mouse sprite is.
If you press and hold down the middle mouse button you can
drag the text up and down by moving the mouse.
The display will follow your movements until
you release the middle mouse button.
X
The arrow buttons on the top and bottom of the scroll bar are not
used in ``line to top'' scrolling and the slider is for your information
only, it does not affect scrolling in any way.
X
The second kind of scrolling will be called ``Macintosh'' scrolling
and it is the usual default for Tk toolkit scrollbars.
It used only the left mouse button
X(although the other buttons also work and do the same thing
as the left mouse button).
X
The arrow buttons on the top and bottom of the scrollbar scroll
the text by one line up or down when clicked on.
If you press and hold down the left mouse button on an arrow button
the scrolling will autorepeat at regular intervals after a short
initial delay.
X
If you click below the slider the text will scroll down
X(towards the end of the file) by one screenfull).
Similarly a click above the scrollbar scrolls up one screenfull.
Both of these will autorepeat as well.
X
If you press the left mouse button on the slider and move the mouse,
the display and the slider will scroll with the mouse
until you release the mouse button.
X
The default is ``line to top'' scrolling.
If you want ``Macintosh'' scrolling you must set the Point option
X{\tt tkScrolling} to ``true''.
X
Point does not wrap long lines.\footnote{
X    I plan to add it as an option in the near future.}
Instead you can scroll horizontally using the scroll bar on the bottom
of the text window.
X
X
X\subsubsection{Mouse menu commands}
X
The middle and right mouse buttons can be used to execute commands.
There are five commands associated with each of these two buttons:
no motion, north (up), east (right), south (down) and west (left).
To execute one of these five commands, you press the mouse button,
move the mouse in one of these four directions
X(or do not move for the no-motion command).
A menu pops up after a short delay (0.6 seconds)
but you do not need to wait for the menu to pop up in order
to execute a command.
The menu comes up as a reminder if you hesitate.
If you set the {\tt mouseSpriteMenu} option to true,
then the mouse sprite is used to display the menu items.
X
If you want to cancel in the middle of a mouse menu command,
click the left mouse button.
X
The commands on the {\bf MIDDLE MOUSE BUTTON} are:
X\begin{description}
X\item[No motion---Dup] (CopyToHereMode) this command is executed in pairs.
X    The first time you execute this command the insertion point is
X    recorded by Point.
X    Then you can select some text in this window or in another window.
X    The second time this command is executed, the selected text
X    is inserted at the insertion point recorded by the first time
X    and the new insertion point is at the end of the newly copied text.
X\item[North---Del] (DeleteToScrap) the selected text is deleted.
X\item[South---Ins] (InsertFromScrap) the text in the scrap buffer (usually
X    the last text deleted) is inserted at the insertion point.
X\item[East---Copy] (CopySelToMouse) the selected text is inserted at the
X    point where the mouse sprite was when you began the mouse menu command.
X    The insertion is by characters, words or lines depending on how
X    the text was selected.
X\item[West---Move] (MoveSelToMouse) the selected text is inserted at the
X    point where the mouse sprite was when you began the mouse menu
X    command and deleted from where it was.
X    The insertion is by characters, words or lines depending on how
X    the text was selected.
X\end{description}
X
The commands on the {\bf RIGHT MOUSE BUTTON} are:
X\begin{description}
X\item[No motion---Ext] (ExtendSelection)
X    The selection is extended to this point.
X\item[North---$<<$] (Search [selection get] backward)
X    The selected text is searched for towards the beginning of the file.
X\item[South---$>>$] (Search [selection get] forward)
X    The selected text is searched for towards the end of the file.
X\item[East---Undo] (Undo 1) The last edit is undone.
X\item[West---Again] (Again mostrecent)
X    The last edit is repeated using the current selection.
X\end{description}
X
X
X
X\section{Keystrokes} \label{sect:keys}
X
Keystrokes meanings are defined in the startup file {\tt ptsetup.tcl}.
Here is a table of the key binding the distributed {\tt ptsetup.tcl} file.
X
X\begin{tabular}{llllll}
XF1 & delete selection to scrap & F6 & redo last undone edit \\
XF2 & insert scrap buffer & F7 & scroll down \\
XF3 & repeat last search backwards & F8 & scroll up \\
XF4 & repeat last search forwards & F9 & undo last edit \\
XF5 & repeat last edit  \\
X\end{tabular}
X
Also the cursor keys (usually shown as up, down, left and right
pointing arrows) move the selection on character in the indicated
direction.
If the left or right arrows are shifted or controlled they
will move one word in the indicated direction
X(instead of only one character).
The Home and End keys (if any) move the selection to the beginning and end
of the line respectively.
XFinally the PageUp and PageDown keys (if any) scroll the window.
X
X
X
X\subsection{Hints for using function keys}
X
I have found that, in practice, I only use a few function keys
in normal editing.
Because the function keys are not labeled it is hard to remember
what commands they invoke.
XFor this reason it does not seem to be useful to put commands you
do not use quite often on function keys.
Labeling the function keys on your keyboard can help but I find
that I use very few function keys even though I define them all.
X
My editing style is to do certain commands exclusively from function keys.
The function keys I use regularly are: delete (F1), insert (F2),
repeat search forward (F4) and again (F5).
I use them together with mouse commands to get a higher command bandwidth.
XFor example, in making a number of identical changes I select the
text to change with the mouse and use F5 (again) to make the changes.
I sometimes use F4 (repeat last search) to select the text to change.
Then I can get into a rhythm and make the changes quickly.
X
I am sure you will develop a style of function key use that
fits your editing style.
The idea is to get the maximum command bandwidth and that is done by
executing some commands with keys and some with the mouse.
The right mix is a matter of personal preference.
X
X
X
X\section{Useful Concepts} \label{sect:concepts}
X
In this section we will discuss a variety of things that are
useful in understanding how Point works.
X
X
X\subsection{ Managing the Selection }
X
Point does not follow the usual X conventions with respect to its selection.
When you select something in Point it also becomes the X (primary)
selection.
This means that you can copy Point's selection into {\tt xterm} windows
by clicking the middle mouse button.
Point notes when it loses the X selection but it {\it does not}
deselect the Point selection.
It remains the Point selection and it remains highlighted.
This is where it differs from the usual X conventions.
If you make a Point selection and then another X selection
X(say in an {\tt xterm} window) then both will be highlighted.\footnote{
I may make this behavior an option in a later version.}
X
There is a special command to insert the X selection into the
text (at the insertion point in front of the selection, as always).
This could be the Point selection but is more likely to some text
you selected from another window.
If Point had deselected its selection you would not be able to see
where the X selection will be copied.
X
All the Point commands that use the selection as an argument
X(search for selection, goto selected line number,
find selected ctag, find selected keyword, open selected file name,
delete selected file name and CD to selection)
use the X selection, not necessarily the Point selection
X(although usually the Point selection will also be
the X selection).
X
The file browser file name list makes the file name you select
the X selection.
X
A hint about the selection:
setting the selection also sets the insertion point.
Use double and triple clicking to get the insertion point
at the beginning of a word or line.
This is usually faster than trying to click on the first
character of the word or line
because word or line is a much bigger target than a single character.
X
X
X
X\subsection{ Typing in characters }
X
Normally typed characters are inserted in front of the selection
X(at the {\it insertion point}).
If the {\it overType} option is True then typed characters replace
characters of the text.
X
If the {\it insertReplaces} option is True and the selection contains
more than one character,
then the selection is deleted before the character is inserted.
This provides behavior that is similar to the way most Macintosh
text editors work.
Both replace styles are useful and the convenience of each
depends on what you are used to.
With {\it insertReplaces} False you can select the insert point
quickly with double and triple clicks but you have to hit the
delete key (F1) before typing in replacement text.
With {\it insertReplaces} True you can replace text easily without
using the delete key but you have to be careful to set the
insertion point to be a single character.
X
X
X
X
X\subsection{ Moving and Copying }
X
Moving and copying is very common in editing code.
Whenever I have to write new code I try to find some similar code,
copy it over and modify it rather than starting from scratch.
There are two kinds of copy and Point implements both kinds.
The first I will call ``copy-to-from'' and it is implemented
by the Point command {\tt CopyToHereMode}.
It is where you first specify
the destination of the copy and then the source.
This copy is in the ``Copy $=>$'' submenu of the Edit Menu.
It is also attached to the no-motion command of the middle
mouse button.
X
A typical use is to duplicate one or more lines.
XFirst select the line(s).
END_OF_FILE
if test 51929 -ne `wc -c <'doc/userman.1'`; then
    echo shar: \"'doc/userman.1'\" unpacked with wrong size!
fi
# end of 'doc/userman.1'
fi
echo shar: End of archive 13 \(of 15\).
cp /dev/null ark13isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 15 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0
--
--
Molecular Simulations, Inc.            mail: [e-mail]
796 N. Pastoria Avenue                uucp: uunet!dcmartin
Sunnyvale, California 94086            at&t: 408/522-9236