\documentstyle{report}
\begin{document}
\title { {\sl apeX}\\
Advanced Programming Environment\\
for X Window Systems }
\author{Alexander Gounares }
\date{5 January 1993 }
\maketitle
\newpage
\pagenumbering{roman}
\tableofcontents
\chapter{Introduction }
\pagenumbering{arabic}

\section{Overview }


	Welcome to {\sl apeX}!  {\sl apeX} is a free development tool intended to help increase a developer's productivity.  In particular, {\sl apeX} tries to address the following problems:

\begin{itemize}
	\item How do you help developers read and understand large programs?
	\item How do you make it easier for developers to write new code, reusing older  code as appropriate?
	\item How do you document code so that the documentation does not clutter the code, yet is readily available when needed?
\end{itemize}

	To address these problems, {\sl apeX} is organized into two main functional units,the {\sl Navigator} and the {\sl Object-Linking Editor}.  The {\sl Navigator} allows users to graphically browse through the call structure of a program, including both calls to and from a particular function.  The {\sl Navigator} is tightly integrated with the editor, so that at any point the user can easily view the code of a particular function (when available, of course!).

	The {\sl Editor } is a standard full-featured Openwindows texteditor, augmented with Object-Linking capabilities.  Technically, this means that a user can create, view, and execute links between two arbitrary sections of text in two arbitrary files.  At the simplest level, this allows users to attach more
detailed comments to source code.  Thus, source code can be extensively documented without excess clutter. 
 
	Since link descriptions can be passed to a shell and executed, users can
attach virtually anything as documentation--audio comments, technical papers,
even movies animating the algorithms used!  More importantly, these attachments
are available at click of a mouse button from the source code.

	Two other tools are included within the {\sl apeX} program itself: a shell with an built-in version-control interface and a scratch pad, for jotting to-do-lists and other notes.


	The rest of this document is arranged as a `How to' book.  Each major tool has a chapter; each chapter is simply a list of what you can do and how to do it.  Detailed information on the source code itself can be found in Appendix B.

\section{Author's Note }

	{\sl apeX} was literally built using itself (after the first 50 lines or so!).  I personally have found it to be a very useful development tool.  If you use it, let me know what you think.  If you do not, let me know as well.  I am 
very interested in hearing what features people like and do not like, and what
could be done to make the program better.

	For the time being, I can be reached at {\tt agg@cs.princeton.edu }(or
Alex Gounares c/o Princeton University CS Department, Princeton, NJ 08544).

\section{Licensing}

	This program and its related documentation are Copyright \copyright 1993 by Alex Gounares and covered under the GNU General Public License (see Appendix C).

\section{Acknowledgements}

	I am indebted to the following people for their help with this project:
\begin{itemize}
	\item Dr. Hanson, Princeton University ( {\tt drh@cs.princeton.edu}).  My advisor, what can I say? :)  His comments help shape a good deal of the Object-Linking capabilities.
	\item Shankar, Hewlet Packard, ( {\tt shankar\%hpclscu@hpda.hp.com }).  The lexer from his ansi-c parser posted to the Net is used in {\sl apeX}'s C parser.
	\item Jon Thompson, Princeton University ( {\tt jontomp@phoenix.princeton.edu }).  Jon was a beta user before the code had any semblance of stability.  His comments and bug-finding have been invaluable.
\end{itemize} 


\chapter{apeX Editor}

\section{Loading Files}

	To load a file, select the ``Load File...'' option from the ``File" menu at the top of the window.  A file browser will pop up, allowing you to search for and select the desired file.
  
	Note that {\tt *.apex } files are produced by {\sl apeX} automatically when a file has object link information.  In order to avoid losing information, it is important to load the {\tt .apex} file instead of the plain text file (since when {\sl apeX} loads a {\tt .apex} file, it overwrites the plain text file).  {\sl apeX} attempts to detect when you will may loose information by loading the wrong file and will issue a warning message.

	When files are loaded, the filename is added to the ``File'' menu.  Simply selecting the filename will load the file into the editor.  This makes it easier to swap between several frequently used files.

\section{Saving Files}

	To save a file, select ``Save File'' from the ``File'' menu.  Note that when your text has been edited, this will be the default menu choice, so that simply clicking on the ``File'' menu button will save your file.  When there are no edits, the ``File'' menu button defaults to ``Load File''.

	If your text has object link information, an additional file, {\tt <your\_filename>.apex} will be produced containing the link information.  The text of your file will be also be saved normally in the file {\tt <your\_filename>}.  If there is no object link information in your file, then no {\tt.apex} file is produced.

\section{Saving as a New File}

	To save text as a new file, simply select ``Save As...'' from the ``File'' menu button.  A file browser will then pop up.  Either select an existing file to replace or enter a new filename in the ``File:'' field and click on the save button.


\section{Include a Text File}

	If you wish to include a text file into the current document, then select ``Include File...'' from the ``File'' menu.  Note that you can only include text files.  Currently, there is now way to include a file with object-link information (i.e. a {\tt .apex} file).

\section{Finding a Line Number}

	If need to see a particular line from a file (to find a compile bug, for
example), click on the ``View'' button (or select ``Select Line at Number'' from
the ``View'' menu).  A popup will appear prompting you for the line number.

\section{Pretty-printing C Source and Other ``Extras'' Options.}

	The options in the ``Extras'' menu work on highlighted text.  For example, highlighting C source and selecting ``Pretty-Print C'' will pass the text through indent for nice formatting.  Selection rules are the standard Openwin rules, i.e., single click and drag to highlight a visible range, double click to highlight a word, triple click to highlight a line, quadruple click to highlight the entire file, and click with the left mouse button at the head and a click with the middle mouse button at the end to highlight an arbitrary range of text.

\section{Splitting {\sl Editor} Views}

	The editor view can be split in two by clicking the right mouse button over the scrollbar and selecting ``Split View''.  This allows you to view and edit two portions of the same file simultaneously.  Note that you can also split a split view to make three views and so on.

\section{Object Link Overview}

	Links join two arbitrary sections of text.  Additionally, each link itself can contain a description.  Note that this description can be passed to a shell and executed (using the ``Run'' button), so that it is possible to attach audio comments, pictures, movies, etc. to text.

	There are a few concepts and definitions to become familiar with.  The terms ``link'' and ``object'' and ``object link'' are fairly interchangeable and refer to the actual link joining two sections of text.  A ``Link Head'' refers to the head of a link (i.e. the end of the link that is in the current file).  Similarly, ``Link Tail'' refers to the other end.  It is possible for a link to have both its head and tail in the same file.  The link description is simply optional text attached to the link itself.

\section{Executing (Running) Links}

	Links may be executed by clicking on the ``Run'' button on the editor (the button with the running stick-figure image).  If the currently selected link has a description, the description will be passed to a shell and executed.  If no description is available, the text of the link tail will be passed to the shell instead.

	The currently selected link is shown at the bottom left corner of the editor.  If no link is currently selected, the bottom left corner will read ``No Object Selected''.  Additionally, the currently selected link is usually underlined, although it is possible to remove the underlining and still have the link selected.


\section{Displaying the Link Description}

	The second button from the left (with an arrow to the link between two objects) is the Link Description button.  If there is a currently selected link, then clicking on this button will display the description text in a Scratch Pad window.

\section{Displaying the Link}

	The third button from the left (with an arrow to the link tail) is the Display Link button.  If there is a currently selected link, then clicking on this button will create a new editor with the link file loaded and the link tail highlighted.  Currently, there is no way to control which editor should load the file--a new editor is always created.

\section{Show the Previous Link}

	The ``{\tt <<}'' button selects and underlines the link previous to the currently selected link.  If there is no current link, or the current link is the first one, then the last link is selected and underlined.

\section{Show the Next Link}

	The ``{\tt >>}'' button selects and underlines the link after the currently selected link.  If there is no current link, the first link is shown.  If the current link is the last one, the first link is shown.

\section{Creating a New Link}

	The create button is the large circle near the middle of the editor tool bar.  Selecting this button pops up the Object Link Create window.  This window allows you define the head, tail, and description of a link.  A three way toggle on the popup selects which element of the link to define.  The highlight text button is used to select highlighted text from an {\sl apeX Editor} as either the link head or link tail.  The selected text will appear in the text subwindow.  The link description may be entered directly in the text subwindow.

	Note that it is not necessary to have a link tail, and that if text is highlighted when the ``Create'' button is pressed, it will default as the link head.  Thus, to simply add a more detailed comment to a section of code, one simply highlights the code, presses ``Create'', enters the additional comments, and then hits ``Apply'' on the Object Link Create popup window.

\section{Deleting a Link}

	The ``X'' button deletes the currently selected link.  A prompt will appear asking for verification.  If there is no currently selected link, the button has no effect.


\section{Modifying a Link }

	Currently there is no direct way to modify a link.  The workaround is to simply delete a link and recreate it.

\section{Finding a Specific Link }

	Clicking on the ``List'' button brings up a popup with a list of all links in the document.  Selecting a link from the list will underline line it and set it as the currently selected link.  The ``Show first link'' button will underline and select the first link (if any) in the highlighted text.  If no text is highlighted, then the first link (if any) in the currently visible text is underlined and selected.


\section{Which Version of {\sl apeX}?}

	The ``Info...'' menu choice under the ``?'' help menu button displays a popup with the {\sl apeX} logo.  The current version number is displayed on the title bar.  Be sure to include the version number in any correspondence about {\sl apeX}.


\chapter{Navigator}

\section{Creating a Datafile }

	The {\sl Navigator} relies upon datafiles produced by a language parser to draw call graphs.  With this distribution, there is a c parser that will parse both K\&R and Ansi C programs.  Typically parsing is added to the makefile to automate the process.  See Chapter 6 for more details.

\section{Loading a Datafile }

	When the {\sl Navigator} starts up, it automatically loads a file called ``apex.parse'' in your current directory (if one exists).  If you wish to load a different file, then select ``Load Datafile...'' from the ``File'' button menu.  A file browser will popup, allowing you to select the desired file.

	Note that the default datafile ({\tt apex.parse }) is customizable.  See the chapter on Customization for more details.

\section{Reloading a Datafile }

	The {\sl Navigator} remembers which datafile is currently loaded into memory.  By clicking on the ``File'' button (or by selecting ``Reload Datafile'' from the menu), the {\sl Navigator} will reload the datafile, replacing the current information.  This feature allows you to update the {\sl Navigator}'s information as the source code changes.

\section{Viewing the Call Graph }

	Functions are drawn as boxes in a tree.  Double clicking on the function name will show either the calls from or to that function (depending on wether the toggle at the top is set to ``Calls'' or ``Called By'' respectively).  Both calls to and from a function can be shown simultaneously.  Calls to a function have an arrow drawn on the connecting lines to indicate the reverse order of the tree.

	The following color scheme is used: on color machines, calls from a function are red lines and calls to are yellow, on black and white, all lines are simply black.  Defined functions (i.e. functions for which the parser has analyzed source) appear have their names drawn in blue (black on black and white).  Library functions (i.e. functions for which no code was analyzed) are drawn with black names (reverse video on black and white).

	For both color and black and white, the size of the box surrounding defined functions is proportionally to the complexity of the given function.  Specifically, the size is equivalent to the natural log of the program volume Halstead metric.  For those unfamiliar with this Halstead metric, it is simply the $((Number\;of\;operators)+(Number\;of\;operands))*((log_2)(number\;of\;unique operators) + (number\;of\;unique\;operands) ) $.  

	Some people have found this metric to be well correlated with the error rate for a function, i.e. functions with a larger volume tend to have more errors.  However, the real intent of the metric as far as the {\sl Navigator} is concerned is as a visual cue to your program.  Large boxes tend to be the `heavy hitters', where the real work of a program is done, while the smaller boxes tend to be auxiliary functions.  Thus, when looking at a new program, it is easy to tell where the real meat of a program lies.

\section{Displaying the Source to a Function }

	To see the source for a defined function (see the previous section), click the right mouse button over the function name.  Selecting ``Display Source'' will display the source code starting at the first line of the function definition in the default editor for the {\sl Navigator} (i.e. the editor from which you hit the ``Nav'' button).  If you wish to display the source into another editor or into a new editor, simply use the pullright menu from the ``Display Source'' option and select the desired editor.

	Note that the {\sl Navigator} is aware of {\tt .apex} files.  If a {\tt .apex } file exists for a particular source file, the {\tt .apex} file will be loaded in lieu of the source file, so that object link information will be display as well.

\section {Changing the Layout of the Call Graph }

	The call graph can be laid out in either a top to bottom or right to left fashion.  Selecting ``Horizontal layout'' or ``Vertical layout'' will change the layout of the call graph appropriately.

\section{Eliminating Subtrees }

	Subtrees can be pruned from a call graph in two ways.  To eliminate a single subtree, simply select ``Prune this node'' from the menu attached to the function name.  To prune a group of nodes, simply select a group using the middle mouse button and use ``Prune Selected Nodes'' from the main ``View'' menu.

\section{Splitting the View }

	As with the editor windows, the call graph view can be split multiple times by clicking the right mouse button over a scrollbar and selecting ``Split View''.

\chapter{apeX Shell}

\section{Overview of the Version Control Interface }

	The {\sl apeX} version control interface is based on the GNU RCS version control system.  The shell scripts distributed with this version work with RCS, although any other system may be used in its stead by modifying the scripts.

	For those unacquainted with RCS, there are several important concepts to understand.  First is the check in, check out methodology.  When saving a file into the version control systems, you are said to `check in' the file.  With RCS, files are automatically assigned new version numbers when they are checked in.  Removing files from the version control system is called checking out.

	RCS also includes the concept of a lock, namely that only one person can check out a file, edit it, and then check the modified file back in.  That person is said to have a `lock' on the file.  All other users check out the file as `read only'.

\section{Specifying a List of Files }

	The files to check in or out are specified by glob pattern matching in the ``File:'' field of the {\sl apeX} Shell.  This pattern is passed directly to the shell as the file arguments to the checkin/checkout shell scripts.

\section{Checking In Files }

	To check in a list of files, select the ``Check In'' toggle and click on the ``Apply...'' button.  A check in popup will soon appear prompting for additional information.  Simply type the description you wish to log as your message for this checkin and then click on ``Apply''.

	If you wish to specify a new release level for the check in, select ``New'' from the ``Automatic/New'' toggle and specify the new release number.  Make sure that the release number specified is greater than the current release number.  RCS will return with an error is the number is less than or equal to the current release.

	The ``Locked Checkout'' option specifies whether or not you wish to immediately do a locked check out on the files being checked in.  Specifying this option will allow you to continue to edit your files without interruption.

\section{Checking Out Files }

	To check out a list of files, select the ``Check Out'' toggle on the main {\sl apeX} shell and click on the ``Apply...'' button.  A check out popup will appear prompting for additional information.

	If you wish to simply check out the latest versions of the requested files, simply click on the ``Apply'' button.  To checkout a specific version of the files, select ``Specific Version'' from the ``Latest Version / Specific Version'' toggle and then enter the version number in the ``Version Number:'' field.  Note that this version number will apply to all of the requested files.

	The ``Locked Checkout'' option specifies whether or not you wish to check the files out as locked.  Depending on your site configuration, you may not be able to check the files back in unless they have been checked out as locked.

\section{Splitting Views }

	As with the {\sl Navigator} and the {\sl Editor}, you can split the view of the shell by clicking the right mouse button over the scrollbar and selecting ``Split View''.

	Note also that the shell comes with the same features as the Openwindow's cmdtool program.  Clicking the right mouse button while in the shell will bring up the menu of options.

\section{CAUTION: Exiting the Shell }

	Do not type ``{\tt exit }'' while in the shell.  This will exit the shell process only, but unfortunately the current version of {\sl apeX} has no way of restarting the shell process.  The only workaround is to restart {\sl apeX}.


\chapter{apeX C Parser }

	The {\sl apeX} C parser works as a straight filter, inputting pre-processed C files and outputting a datafile for use with the {\sl apeX} {\sl Navigator}.  The C parser produces call graph and Halstead metric information from both K\&R and ANSI C files.

	Note that C files must be preprocessed in order for the parser to correctly get source filename information.  The easiest way to do this is by using the ``-E'' flag of your C compiler and add an entry into your makefile like the following:

\begin{verbatim}
PSRC= foo.c

a.out:	foo.c
    cc -E foo.c > apex.parse
    cc foo.c
\end{verbatim}

	For an example of how to do this efficiently for a large program, see the {\tt Makefile} for {\sl apeX} itself.

\chapter{Customization}

\section{Overview }
	{\sl apeX} uses the X resource database to handle user-customization.  To set an option, simply edit your .Xdefaults file in your home directory and add the desired entries.  In order for the changes to take effect, you must either restart your X server or run the xrdb program and then restart {\sl apeX}.

\section {{\sl apeX} X Resources }
\begin{enumerate}
\item {\tt apex.checkin:		apex\_ci }

	The shell script to call to check files into the version control system.

\item {\tt apex.checkout:		apex\_co }

	The shell script to call to check files out of the version control system.

\item {\tt apex.datafile:		apex.parse }

	The default datafile that the {\sl Navigator} loads on startup.

\item {\tt apex.fileFilter:		*.apex }

	The default filter to appear in the file browsers.

\item {\tt apex.nav3d:		1 }

	Whether or not to use the 3-d effect on the {\sl Navigator} background.

\item {\tt apex.navStart:		main}

	The default root of the {\sl Navigator} call graph tree

\item {\tt apex.rcsPattern:	*.[chly] [Mm]akefile }

	The default pattern for files to check in/out of the version control system.

\item {\tt apex.tabwidth:		8 }

	The tabwidth for all text subwindows.

\end{enumerate}
\chapter {To Do (abridged) }

	
	In no particular order, these are the things I'd like to do for the next version:
\begin{itemize}
	\item An integrated make utility ala emacs or PC compilers, so that I could simply click on an error and see/edit the line in the source code.
	\item A more robust and thorough version control system.
	\item A completely revamped system architecture for {\sl apeX}.  {\sl apeX} is getting to be a rather large, ungainly program (even though it's only 8000 lines or so!).  I do not think that one large, monolithic program will solve everybody's problems.  Instead, the editor, navigator, and all the other tools should become independent tools that cooperate with each other via message passing.  The introduction to Sun's Tooltalk provides a good example of this architecture (indeed, they use a CASE tool as their example).

	The benefit of this proposed system is that you could use as many or few tools as you like.  More importantly, it would be much easier to incorporate new tools into the environment.  All a new tool has to know is some subset of the messages understood and generated by the other tools.  For example, a make utility would only need to know ``Display file at line number'' to interact with the editor.  Thus, it is irrelevant to the make tool wether the editor is an Openwin texteditor, an {\sl apeX} Object-linking editor, emacs, or even ed.

\item An improved editor, where object links appeared as little icons in the text.  Simply clicking on an icon should follow the link (or execute as appropriate).  This could even be combined with a knowledge of the parse files, so that simply clicking on a function call would change the text view to the source of the function.  Italicized comments, bold keywords, etc, ala Borland Turbo {\tt C++} for Windows would, of course, make a nice final touch.
\end{itemize}

\appendix
\chapter {Running apeX}
\section{Environments}
	{\sl apeX} currently runs only on Sparcstations with the Openwindow libraries installed (it is not necessary to run Openwindows, however).  If you use twm (or variant) as a window manager, you need to make sure the following lines are in your {\tt \$HOME/.twmrc}:

\begin{verbatim}
	LeftTitleButton "target" = f.delete
    where "target" is a 16x16 icon from /usr/include/X11/bitmaps.
    Alternatively, try
	\# Add a menu to each window managed by twm or tvtwm
	LeftTitleButton ":menu" = f.menu "OL.menu"

	menu "OL.menu" $\{$
	    "Quit"         f.delete
	$\}$
\end{verbatim}

\section{Command Line Arguments}

	{\sl apeX} takes the following arguments (in any order):

{\tt	apex [file 1] [file 2] ... [file n] [X options] }

	where X options are the following (taken from the xview man page).  Note
that only the options pertinent to {\sl apeX} are listed here.

\begin{verbatim}

     Argument(s):   -Wx, or -scale
     Type:          string    ("small",    "medium",     "large",
                    "extra_large")
     Resource Name: Window.Scale
     Default:       medium
     Description:   Sets the initial  scale  of  the  application
                    (larger  or  smaller).   small  is 10 pixels,
                    medium is 12 pixels, large is 14  pixels  and
                    extra_Large  is  19  pixels.   The  font.name
                    resource will override the scale.
     Example:       cmdtool -scale extra_large


     Argument(s):   -Wt, -fn, or -font
     Type:          string
     Resource Name: Font.Name
     Default:       lucida-sans
     Description:   Sets the name of the font used for the appli-
                    cation  (not control areas). To find out what
                    fonts are available, use the xlsfonts command
                    (see  reference manual page for more informa-
                    tion).  It is also possible to see the avail-
                    able  fonts  for the Open Windows server with
                    one of the NeWS demo  programs  in  the  demo
                    Navigator.  Start this by choosing "demos..."
                    from the default root menu.  If the font  you
                    specify  cannot  be  found,  you  see will an
                    error message such as:

                    XView warning: Cannot load font 'galant-24' (Font package)
                    XView warning: Attempting  to  load  font  '-
                    b&h-lucida-medium-r-normal-sans-*-120-
                    *-*-*-*-*-*' instead (Font package)

     Example:       cmdtool -fn fixed

     Argument(s):   -Wp, or -position
     Type:          integer integer
     Resource Name: Window.X and Window.Y
     Default:       depends on window manager
     Description:   Sets   the   initial    position    of    the
                    application's  base  frame  in  pixels.   The
                    upper left corner of the screen is  at  posi-
                    tion (0,0), with the x-axis increasing to the
                    left, and the y-axis increasing downward.  To
                    determine  framebuffer  size, one can use the
                    <eeprom> command on the  local  machine.   To
                    determine  screen  size for a remote display,
                    one can use  Xlib  functions  (see  the  Xlib
                    Programmers  Manual).  These values will also
                    be generated by the "Save  Workspace"  option
                    on the root menu into the $HOME/.openwin-init
                    file when using the Open Look Window Manager.
     Example:       cmdtool -Wp 100 200

     Argument(s):   -WP, -icon_position
     Type:          integer integer
     Resource Name: Icon.X Icon.Y
     Default:       depends on window manager
     Description:   Sets the position of the  application's  icon
                    in pixels.  Uses the same semantics as
                    -position for base frames.
     Example:       cmdtool -WP 400 20


     Argument(s):   -Wi, and +Wi
     Type:          boolean
     Resource Name: Window.Iconic
     Default:       +Wi
     Description:   These options control how an application will
                    come up, open or closed (iconified).
     Examples:      cmdtool +Wi      (will make the cmdtool  come
                    up open)
                    cmdtool -Wi      (will make the cmdtool  come
                    up closed)

     Argument(s):   -Wf, or -foreground_color
     Type:          integer integer integer
     Resource Name: Window.Color.Foreground
     Default:       0 0 0
     Description    See Description in -Wb below.

     Argument(s):   -Wb, or -background
     Type:          integer integer integer
     Resource Name: Window.Color.Background
     Default:       255 255 255
     Description:   These options allow the user to  specify  the
                    foreground color (e.g., the color of the text
                    in a textsw), or the background color  (e.g.,
                    the  color that the text is painted on) of an
                    application.   The  three  values  should  be
                    integers between 0 and 255.  They specify the
                    amount of red, green and blue that is in  the
                    color.    See  -fg and -bg below for informa-
                    tion on similar functions.
     Example:       cmdtool -Wf 0 0 255 -Wb 100 100 100
                    (would come up with a blue foreground, with a
                    gray background)

     Argument(s):   -fg, or -foreground
     Type:          string  (color  name,  or  hexidecimal  color
                    specification)
     Resource Name: Window.Color.Foreground
     Default:       black
     Description:   See Description in -bg below.

     Argument(s):   -bg, or -background
     Type:          string  (color  name,  or  hexidecimal  color
                    specification)
     Resource Name: Window.Color.Background
     Default:       white
     Description:   These options are similar to the -Wf and  -Wb
                    options,  except that they take a color argu-
                    ment in the form of a predefined  color  name
                    (lavender,   grey,   goldenrod,   etc.)  from
                    $OPENWINHOME/lib/rbg.txt,  or  a  hexidecimal
                    representation.   The hexidecimal representa-
                    tion is of the form pound sign  (#)  followed
                    by the hexidecimal representation of the red,
                    green and blue aspects of the color.
     Examples:      cmdtool -fg blue -bg gray
                    (comes up with a blue foreground, with a gray
                    background)
                    cmdtool -fg #d800ff -bg white
                    (comes up with a purple  foreground,  with  a
                    white background)

     Argument(s):   -WH, or -help
     Type:          none
     Resource Name: none
     Default:       none
     Description:   Prints a description  of  the  valid  command
                    line arguments for the application.

     Argument(s):   -sync or -synchronous, and +sync or +synchro-
                    nous
     Type:          boolean
     Resource Name: Window.Synchronous
     Default:       +synchronous
     Description:   These options allow you to make  the  connec-
                    tion  that  the  application has with the X11
                    server either synchronous  (-sync)  or  asyn-
                    chronous (+sync).

     Argument(s):   -Wr, or -display
     Type:          string (host:display{.screen})
     Resource Name: Server.Name
     Default:       taken from the DISPLAY environment variable
     Description:   Sets the name of the X11 server on  which  to
                    connect.  host  is the name or address of the
                    machine on whose server you  have  permission
                    to  display.  display is a number correspond-
                    ing to the server on  which  to  display  for
                    that machine, and screen corresponds to which
                    screen for the server.  See reference  manual
                    page on <xhost> for more details on adding to
                    permissions list.
     Examples:      cmdtool -display foobar:0
                    (will bring  up  a  cmdtool  on  the  default
                    screen of the display #0 of host foobar)
                    cmdtool -display foobar:0.1
                    (will bring up a  cmdtool  on  screen  #1  of
                    display #0 of host foobar)

     Argument(s):   -Wdr, or -disable_retained
     Type:          boolean
     Resource Name: Window.Mono.DisableRetained
     Default:       Not Retained on color systems,  and  Retained
                    on monochrome systems
     Description:   This option is useful for  applications  run-
                    ning  on  a  monochrome display, where server
                    memory is at a minimum.  For performance rea-
                    sons,   monochrome  windows  are  by  default
                    retained by the server.  Using retained  win-
                    dows  will use more memory in the X11 server;
                    however, it also speeds  up  repainting  when
                    the  window is covered and uncovered by other
                    windows.  When true, monochrome  windows  are
                    not retained, thus saving server memory.

   
     Argument(s)    -rv (or -reverse), and +rv (or +reverse)
     Type:          boolean
     Resource Name: Window.ReverseVideo
     Default:       False
     Description:   These options control whether the  foreground
                    and background colors of the application will
                    be reversed.  If  True,  the  foreground  and
                    background  colors  will be swapped.  The -rv
                    flag will set this to  True,  while  the  +rv
                    will  set  it  to False.  This is really only
                    useful on monochrome displays.
\end{verbatim}

\chapter{Source Code Description }

\section{Overview }
	This appendix documents some of the data formats and structures used in {\sl apeX}.  In this distribution, the code is unfortunately poorly documented and commented, due to, ah, time restrictions.  Feel free to contact me with any questions, however.

\section{{\tt .apex } File Formats }

	Links are stored in a very straightforward fashion.  Essentially, a .apex file is simply the original text with with link information inserted.  Link information is encoded in the following format:

{\tt $\backslash$n<!@ <link id> <link to filename> <link tail id> <optional description> @!>$\backslash$n }

where {\tt <link id>} is the unique (to the file) number identifying the link, {\tt <link to filename>} is the filename (stripped of directory information) of the file where the link tail resides, {\tt <link tail id>} is identifying number of the link node to which the current link node is connected, and {\tt <optional description>} is just arbitrary text.  (Note that the description is currently limited to 10000 characters.)

\section{{\tt apex.parse } Datafile Formats }

	The datafile for the {\sl Navigator} is basically a list of function definitions.  For each function defined in the source, the following information is generated:

\begin{verbatim}
[G|S] function_name filename line_number program_volume number_of_function_calls
function_call_1
function_call_2
...
function_call_n
\end{verbatim}

	A ``{\tt G}'' indicates that the function has global scope while ``{\tt S}'' indicates that the function is static to the file.  See the upcoming section on {\tt symbol.c} for more detailed information on how this static flag is used.

\section{The Source Itself }

	The {\sl apeX} source code itself basically builds a number of objects, each of which has its own windows and callback functions.  Every frame within {\sl apeX} has its own object structure where all of the xview item and other information is contained.  A pointer to this object is attached as CLIENT\_DATA for each xview object.

	The next section lists the source files and provides a brief description of the functions present in each file.  Since there are over 200 functions in {\tt apeX}, only those functions that would be most useful to somebody writing {\sl apeX} extensions are documented.

	Of course, the best way to navigate through the code is to use {\sl apeX} itself!  An {\tt apex.parse} file for the source code is included with the source code distribution.

\section{Source Files}

\subsection{{\tt alloc.c}}
	This file contains functions for allocating memory.  Currently, all out of memory errors terminate the process, although ideally they would behave a bit more nicely.

\subsection{{\tt apex.c}}
	This file contains {\tt main}.  {\tt main} simply processes the arguments and creates an {\sl Editor} for each filename present.

\subsection{{\tt apex\_help.c}}
	The important function in this file is {\tt set\_help\_button}.  This function creates a ``?'' help button at the top right corner of the {\tt Panel} passed in as an argument.  The callback for this button ({\tt misc\_help\_proc}) creates the help popup from the NULL-terminated string array argument in {\tt set\_help\_button}.

	The help strings take the following format:
\begin{verbatim}
static char *help[] = {
	"Title for help",
	"B",	"Topic",
	"b",	"text for topic",
	0 };
\end{verbatim}

	The string {\tt "B" } indicates that the subsequent string should be drawn in bold.  Any other string results in normal text.
\subsection{{\tt apex\_options.c}}
	This file contains functions for getting user-defined values from the X resource database manager.

\subsection{{\tt apex\_shell.c}}
	This file creates both the {\sl apeX Shell} and the version control interfaces.  Note that unlike other the other modules, the {\tt Shell} object is statically allocated as {\tt main\_shell}.  Since XView only allows one shell {\tt TERMSW} per process, there was no point to dynamically allocating a variable.  The callbacks, however, all operate on pointers to the {\tt Shell} object.

	Those wishing to modify the actual calls to RCS should look at {\tt cip\_apply\_proc} and {\tt cop\_apply\_proc } (for `check in apply callback' and `check out apply callback' respectively).  These two functions call the support shell scripts {\tt apex\_ci} and {\tt apex\_co}.  

\subsection{{\tt editor.c}}
	The useful functions in this file are {\tt new\_editor} and {\tt set\_editor}.  {\tt new\_editor} will create a new editor and load in the specified file.  {\tt set\_editor} will just load a file into the given editor and forward to the given line number.  Note that {\tt set\_editor} simply loads the requested file.  It is up to the calling function to determine if a {\tt .apex} file should be loaded instead (see {\tt show\_text\_proc} in {\tt navigator.c}).

\subsection{{\tt file\_browser.c}}
	The file browsers work in a slightly different fashion that the other objects in {\sl apeX}.  {\tt create\_generic\_browser} creates an imcomplete file browser object.  All of the callbacks necessary for browsing the file system are in place, but no `action' buttons or callbacks (i.e. ``Load File'') are created.  It is up to the calling function to install these action buttons.  See the function {\tt create\_load\_browser\_proc } for an example.

\subsection{{\tt file\_io.c}}
	This file contains the functions to load and save {\tt .apex} files.  The {\tt set\_editor} function in {\tt editor.c} should eliminate the need to explicity call any of these functions.

\subsection{{\tt misc.c}}
	This file contains miscellaneous utitility functions.  {\tt split\_name} will split a full path name into the directory and filename components.  {\tt szJoin} will join a directory name and a filename into a newly allocated string.  At some point, other {\sl apeX} source files need to be retrofitted to use this function for source code cleanliness.

\subsection{{\tt navigator.c}}
	The important functions in this file are {\tt load\_data} and {\tt add\_leaf}.  {\tt load\_data} loads a datafile into an on-line symbol table.  Note that the symbol table also uses a string space hash table to help minimize data storage.  Any changes in the datafile format will affect this function.

	{\tt add\_leaf} actually creates the function `box' that is drawn on the screen and attaches the menu.  Additions (e.g. new boxes or additional menu choices) are likely to modify this function.

	Note that {\tt navigator.c} relies heavily on the SlingShot XView extension package available from {\tt export.lcs.mit.edu}.  The tree drawing source in the {\tt navigator.c} source is based on the {\tt tlstool.c} example program provided in the SlingShot distribution.

\subsection{{\tt object.c}}
	This file contains the functions used to create and manipulate links.  In particular, the functions prefaced with {\tt obj\_} (such as {\tt obj\_delete\_proc }) deal directly with the link information.  Note that links are stored as a doubly-linked list within the {\tt File} structure of the {\tt Editor} object (see {\tt load\_file} in {\tt file\_io.c}).

	Another useful function in this file is {\tt get\_block}.  This function determines which text (if any) in an {\sl Editor} is highlighted.

\subsection{{\tt object\_list.c}}
	This file contains the functions that create and manipulate the ``List'' popup.  It should be a good example of how to interface to the link information.
 
\subsection{{\tt s\_pad.c}}
	This short file creates the Scratch Pad popup windows.  Note that as currently implemented, the {\tt set\_sp*} can only deal with strings under 20000 characters.  Longer strings will overflow the internal edit buffers in the {\tt TEXTSW}.  At some point, this needs to be made more robust.

\subsection{{\tt state\_server.c}}
	The state server essentially maintains a list of which editors are currently active.  This is primarily needed know when to quit {\sl apeX} versus just the {\sl Editor} window.
	
\subsection{{\tt symbol.c}}
	This file contains all the functions needed for manipulating a symbol table (used by the {\sl Navigator} to store call graph data).  Two hash tables are actually maintained, one for the symbols themselves and another for all strings.  Uniquely storing unique strings helps cut down on memory usage.

	An astute reader will have noticed by this point that the datafile format does not explicity specify calls to local, static functions versus calls to global functions.  For example, given the following files,

\begin{verbatim}
foo.c:

static a(){
    ...
}
bogus(){
    a();
}
\end{verbatim}

and

\begin{verbatim}
goo.c:

a(){
    ...
}
\end{verbatim}

and

\begin{verbatim}
hoo.c:

bug(){
    a();    /*which a does it call???*/
}
\end{verbatim}

the datafile entries for {\tt bogus} and {\tt bug} do not say which function {\tt a} is called.

	This scope problem is resolved by the {\tt lookup} function in {\tt symbol.c}.  {\tt lookup} takes an additional filename argument, so that if a symbol exists and is defined in filename, then that symbol is returned (even if other symbols with the same name exist).  Otherwise, the global symbol (if any) with a matching name is returned.

\chapter{GNU General Public License }
\begin{verbatim}
		    GNU GENERAL PUBLIC LICENSE
		       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                          675 Mass, Cambridge, MA 02139, USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.
\end{verbatim}
\section{Preamble }
\begin{verbatim}
  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.
\end{verbatim}
\newpage
\section{GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION }
\begin{verbatim}

  0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.

    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

  5. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

  7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

  10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

			    NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

		     END OF TERMS AND CONDITIONS
\end{verbatim}
\newpage
\section{Appendix: How to Apply These Terms to Your New Programs }
\begin{verbatim}

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) 19yy  <name of author>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19yy name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  <signature of Ty Coon>, 1 April 1989
  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.
\end{verbatim}
\end{document}
