head	1.7;
access;
symbols;
locks; strict;
comment	@% @;


1.7
date	92.11.25.16.36.22;	author lacey;	state Exp;
branches;
next	1.6;

1.6
date	92.11.25.15.53.35;	author lacey;	state Exp;
branches;
next	1.5;

1.5
date	92.11.24.22.24.08;	author lacey;	state Exp;
branches;
next	1.4;

1.4
date	92.11.24.21.05.12;	author lacey;	state Exp;
branches;
next	1.3;

1.3
date	92.11.24.18.36.40;	author lacey;	state Exp;
branches;
next	1.2;

1.2
date	92.11.24.16.54.00;	author malingka;	state Exp;
branches;
next	1.1;

1.1
date	92.11.24.04.00.16;	author lacey;	state Exp;
branches;
next	;


desc
@@


1.7
log
@*** empty log message ***
@
text
@\documentstyle[titlepage,fullpage,psfig]{article}

\newcommand{\tiscreen}{{\em task information screen}}
\newcommand{\pscreen}{{\em project screen}}
\newcommand{\pcscreen}{{\em PERT chart screen}}
\newcommand{\gcscreen}{{\em Gantt chart screen}}
\newcommand{\poscreen}{{\em export options screen}}
\newcommand{\flsscreen}{{\em file load-store screen}}
\newcommand{\xplan}{{\em xplan}}

\title{{\LARGE\bf User Manual for the \xplan\ Project Planning Tool}
\author{{\Large\it Brian Gaubert, Mark M. Lacey, Richard Malingkas, Michael Marlow} \\
{\Large Department of Computer Science} \\
{\Large Michigan State University} \\
\vspace*{2.5in} 
\mbox{} \\
{\Large Software Engineering, CPS470} \\
{\Large Instructor: Dr.\ B. Cheng} \\
{\Large Teaching Assistant: G.C. Gannod} \\
\vspace*{2.5in}
\mbox{} \\
{\Large Fall 1992}
\date{November 25, 1992}
}}

\begin{document}
\maketitle

\pagenumbering{roman} % number table of contents and list of figures
		      % with roman numerals

\tableofcontents      % make a table of contents for the document
\clearpage            % begin a new page

\listoffigures        % list of figures used in the document
\clearpage            % begin a new page

\pagenumbering{arabic} % start numbering pages with arabic numerals

\input{intro}
\input{function}

\input{scenario}

\input{installation}

%
% You know the drill
%
\section{References}

For more information on the project planning tool that we are
presenting, refer to \cite{prj-desc}, \cite{prj-plan},
\cite{req-spec}, \cite{prelimin-design}, \cite{detailed-design} and
\cite{test-spec} in Appendix \ref{sec-ref}.  For more information on
PERT and Gantt charts, and critical path analysis in particular, see
\cite{cpa}.  The definitive reference for \LaTeX\ is
\cite{latex-manual}.  A good source for general information on XView
along with details of implementing XView programs is
\cite{xview-manual}.

\appendix

\section{Project File Grammar}

The format of the project files for \xplan\ follows in BNF form.
Italicized items are non-terminals and bold text represents
terminals.  Following the BNF grammar is a sample file.

\noindent{\em project}\/ := {\em tasklist}\/ \\
{\em project}\/ := $\lambda$ \\
{\em tasklist}\/ := {\em taskblock}\/ \\
{\em taskblock}\/ := {\em taskblockhead taskblocktail}\/ \\
{\em taskblockhead}\/ := {\bf begin tasks} \\
{\em taskblocktail}\/ := {\em tasksublist}\/ {\bf end tasks} \\
{\em tasksublist}\/ := {\em atask}\/ {\em tasksublist}\/ \\
{\em tasksublist}\/ := {\em atask}\/ \\
{\em atask} := {\bf task = \{} {\em alist}\/ {\bf \}} \\
{\em alist} := {\em assignment}\/ {\bf ;} {\em alist} \\
{\em alist} := {\em assignment}\/ {\bf ;} \\
{\em assignment} := {\em stringassign} \\
{\em assignment} := {\em dependencylist} \\
{\em assignment} := {\em resourcelist} \\
{\em assignment} := {\em numberassign} \\
{\em assignment} := {\em booleanassign} \\
{\em assignment} := {\em taskblock} \\
{\em stringassign} := {\bf name = string} \\
{\em stringassign} := {\bf description = string} \\
{\em stringassign} := {\bf parent = string} \\
{\em dependencylist} := {\em dependhead dependencytail} \\
{\em dependhead} := {\bf begin dependencies} \\
{\em dependencytail} := {\em dependency}\/ {\bf end dependencies} \\
{\em dependencytail} := {\em dependency}\/ {\bf ,} {\em dependencytail} \\
{\em dependency} := {\bf string} \\
{\em resourcelist} := {\em resourcehead resourcetail} \\
{\em resourcehead} := {\bf begin resources} \\
{\em resourcetail} := {\em resource}\/ {\bf end resources} \\
{\em resourcetail} := {\em resource}\/ {\bf ,} {\em resourcetail} \\
{\em resource} := {\bf string} \\
{\em numberassign} := {\bf duration = unsigned} \\
{\em numberassign} := {\bf float = unsigned} \\
{\em numberassign} := {\bf plannedstart = unsigned} \\
{\em numberassign} := {\bf actualstart = unsigned} \\
{\em numberassign} := {\bf forecaststart = unsigned} \\
{\em numberassign} := {\bf earlieststart = unsigned} \\
{\em numberassign} := {\bf lateststart = unsigned} \\
{\em numberassign} := {\bf plannedend = unsigned} \\
{\em numberassign} := {\bf actualend = unsigned} \\
{\em numberassign} := {\bf forecastend = unsigned} \\
{\em numberassign} := {\bf earliestend = unsigned} \\
{\em numberassign} := {\bf latestend = unsigned} \\
{\em booleanassign} := {\bf milestone =} {\em boolean} \\
{\em booleanassign} := {\bf deliverable =} {\em boolean} \\
{\em boolean} := {\bf true}\\
{\em boolean} := {\bf false}\\

And now, a sample file:

\begin{verbatim}
begin tasks

task = {
	 name = "task 1";
         description = "This is a sample description...";
	 duration = 3;
	 planned_start = 2343;
	 planned_end = 92333;
	 float = 7;
	 milestone = false;
	 deliverable = false;
         begin resources
            "Mark M. Lacey",
            "Richard Malingkas"
         end resources;
}

task = {
	 name = "task 2";
	 description = "This is the description for task 2";
	 duration = 7;
	 float = 2;
	 milestone = true;
	 deliverable = false;
         begin dependencies
             "task 1"
         end dependencies;
         begin resources
             "Brian Gaubert",
             "Mike Marlow"
         end resources
}
\end{verbatim}


\section{Bibliography}

\label{sec-ref}

\bibliographystyle{plain}
\bibliography{user-manual}

%
% HINT!!!!:  Think about the worst user manual you've
% ever encountered.  Consider what you didn't like
% about it; was it missing something, was it redundant,
% was it incorrect?  After you've thought about these
% characteristics that you found undesirable, write
% the document with the intent of not emulating the
% worst manual you've ever seen.  ^^^  
%
% 
%
\end{document}


@


1.6
log
@*** empty log message ***
@
text
@d64 91
@


1.5
log
@*** empty log message ***
@
text
@d1 11
a11 4
\documentstyle[fullpage,psfig]{article}
\begin{document}
\thispagestyle{emtpy}
\title{{\LARGE\bf User Manual for the xplan Project Planning Tool}}
d24 3
a26 1
}
d28 11
a38 3
\clearpage
\tableofcontents
\clearpage
@


1.4
log
@*** empty log message ***
@
text
@d26 1
a26 10
%
% Provide a simple tutorial that includes a
% generic scenario for using the system.  Provide
% screen dumps, etc.  Make sure that this tutorial
% is representative of the types of operations found in
% a typical session.  As with the previous section,
% you can change the name if you find another more
% desirable.
%
\input{user-scenario}
@


1.3
log
@The main user-manual.
(.tex file, that is)
@
text
@d1 1
a1 1
\documentstyle[fullpage]{article}
d11 1
a11 1
{\Large Instructor: Dr. B. Cheng} \\
@


1.2
log
@add \input{user-scenario}
change some sentences, forgot which ones :-)
@
text
@d4 1
a4 1
\title{{\LARGE\bf User Manual for xplan Project Planning Tool}}
d23 2
a24 9
%
% Purpose of tool, scope.  Also, describe any assumptions
% you may be making about the abilities of the user.
% (i.e. Does the user need a Ph.D. in Astrophysics
% with a Masters in Quantum Mechanics to run your
% tool or can a regular bum that thinks computers
% are evil use it?)
%
\section{Introduction}
a25 87
The xplan project planning tool was developed for processing PERT/Gantt
chart information to perform project management duties.  The user of this 
software is one of two customers.  The first customers are Dr. Cheng and
Jerry Gannod at Michigan State University for the course CPS 470. All 
documentation regarding the development and usage of xplan will be available
to them.  The second group of customers are the Internet community at large
for whom xplan will be publicly available via anonymous ftp sites as freeware
according to the Free Software Foundations policy. For those customers, only
the source code and Postscript versions of this User Manual will be available.

The purpose of xplan is to help the user perform project management duties.
The user will input information describing the tasks necessary to perform
a project. xplan is applicable to any type of project that has several tasks
and the tasks have time dependencies that affect the progress of the final
project.  The user enters and loads text information into xplan
that describes project tasks, and task related information.   Some examples 
of projects that may be planned with xplan are manufacturing projects in
organizations using total quality management techniques, research projects, 
software development, business, and personal projects that progress over a
considerable length of time.  Projects whose time line spans a period of 5
years or less may have their critical path calculated by xplan. Only one
project at a time may be entered into and processed by xplan. The specific
terms describing the input and output parameters of xplan are defined
and explained in later sections of this document.

The user of xplan is assumed to be familiar the basics of running
software using a graphical user interface (GUI) in a Unix and X
Windows computing environment. The xplan software is provided on an
``as is'' basis, and it is the user's responsibility to know how to
perform the necessary activities for installing, compiling, and
running xplan on their system.  xplan comes with built in help
facilities that may be called by the graphical user interface for the
users convenience.  The only interface provided to the user is the
xplan graphical user interface built with the OpenWindows Developer's
Guide Guide 3.0 widget set.  The user does not need that widget set to
operate xplan, but it would be necessary if the user wanted to
translate the text descriptions and on-line help features of xplan
into a language other than English. While the user does not need to
know about X Windows, the user must have X Windows to run the xplan
PERT/Gantt chart generator software.

\subsection{Hardware Requirements}

The development team of Michigan State University students who created
xplan designed the software to be run in a Unix and X Windows
environment on Sun SPARC 1 and 2 machines.  A graphics display
terminal is necessary for drawing the PERT/ Gantt charts in xplan's
GUI.  Since no special meaning is attached to color, either a color or
black and white graphics display terminal will work for xplan.
Furthermore, a 3 button mouse and a keyboard are necessary for
interacting with xplan's GUI.  Sun SPARC 2 machines are the preferred
platform because the increased hardware power will allow xplan to run
faster.  The difference in performance will most likely be observed
for projects which push the performance limits of xplan by having a
large number of tasks spread over a five year period. Other hardware
platforms that support a Unix and X Windows environment may also run
xplan.  For example, xplan could be installed to run on other
workstations like various Sun models, NeXT, Hewlett Packard, or
Apollo.  However, the authors provide no support for other hardware
platforms. Furthermore, customers who are part of the Internet
community will need the necessary network hardware and software
connections for anonymous ftp to the public access site at Michigan
State University for obtaining copies of the xplan source code and
documentation.
 
\subsection{Software Requirements}

The software requirements for compiling and running xplan are the
following.  xplan was written to run in a Unix and X Windows
environment. The user will need to have a gcc ANSI C compiler, X
Windows, and X Libraries for compiling the xplan software.
Furthermore, since xplan was specifically designed to produce results
which may be incorporated into other documents, the LaTeX document
processing software is necessary for obtaining LaTeX file formatted
output of PERT/Gantt charts.  The user may then use LaTeX to
incorporate these charts in the documents they prepare and process
with LaTeX.  Those documents may then be printed to hard copies of
paper or overhead slides for reports and presentations.  Also, ASCII
text files may be used to save and input PERT/Gantt chart information.
If the user wanted to translate the language of xplan's GUI into
another language which may be represented by the ASCII character set,
the OpenWindows Developer's Guide version 3.0 will be necessary for
modifying xplan's GUI.  For instance, a user may obtain xplan via
anonymous ftp from Michigan State, and decide to translate the GUI
language into French so users in France may use xplan for project
planning.

a26 104
% Include Online help facilities.  Describe what each
% feature of the system is.  Describe fully what
% different options/selections will provide to the user.
% For instance, describe what each button allows the
% user to do.  btw, you can change the name of the section
% if you like.  If there are special languages that the
% user must know for input into the system, include 
% the description of that language here.
%
\section{Functionality Description}

xplan is designed to be simple to learn and simple to use software.
The user controls every aspect of xplan with the graphical user
interface (GUI). The user will use the three button mouse to control
the GUI and keyboard for entering text information to xplan.  Also,
the user may specify an ASCII text file of PERT/Gantt chart
information to be loaded into xplan.  Note that the ASCII text input
file must be in the proper xplan input format.  That feature is
basically used for saving previous xplan work sessions on a project.
The user should never prepare an ASCII text file for input by hand,
since xplan's GUI is so simple to use.  The user may output the
PERT/Gantt chart information created by xplan to a LaTeX file format.
The user may use the LaTeX document processing system for
incorporating PERT/Gantt charts into professional quality documents.
xplan was designed to allow the user to use the LaTeX document
processing system in the spirit of free software.  Since xplan is
provided free of charge, and LaTeX is free software, xplan is the tool
of choice for the budget conscious user.  If the user is unfamiliar
with LaTeX, we recommend obtaining a copy of the LaTeX user manual,
since LaTeX is used after xplan finishes its duties.  xplan is
designed to be used interactively with the GUI in real time, so batch
processing of PERT/Gantt charts is not available with xplan.
  
Before we discuss the details of using xplan, let's first describe
what PERT/Gantt charts are.  A Gantt chart is basically a time line
showing a bar graph of the period of time the tasks of a project take
to complete.  The PERT chart is different from the Gantt chart.  The
PERT chart is for Performance Evaluation and Review Techniques.  Tasks
are illustrated graphically so the user may see the dependencies of
the various tasks of a project.  All dependencies are calculated based
on time of completion for a particular task.  Basically, in a project,
some tasks must be completed before others may start or be completed.
xplan has a variety of dates which help forecast when one task may be
completed, based on the progress of previous tasks on which that task
is dependent.  xplan calculates a critical path for the PERT/Gantt
chart project.  The critical path is the path through the PERT chart
that shows when a project may be completed, based on which task
dependencies control the ultimate time length of a project.

The information items needed to describe a task are: task description,
task name, options, task time, task dates, task dependencies, and task
resources.  The task name is the name of one particular task in a
project.  That task is represented as a box in the PERT chart, and a
bar in the Gantt chart.  The task description is an 800 ASCII
character text description of what that task is.  The task options are
boxes to check whether or not the particular task is a milestone or
deliverable.  A milestone is a major event in the project management
process such as the completion and review of a part of the project.  A
deliverable is a working piece of the project such as documentations
or a computer program's source code.  A deliverable is an important
piece of the project work which is usually delivered to a projects
managers or customer.  The task times are the task duration and the
task float time.  The task duration is the length of time a task takes
to be completed.  The task float time is the allowable amount of time
past the tasks planned end date that the task is allowed to remain
incomplete before adversely affecting the total project's time length.
Regarding task dates, each task has start dates and end dates.  Those
dates are the planned, actual, forecast, earliest, and latest starting
and ending dates of a certain task.  Please note that all measurements
of time are in days, and all dates are described to a day in the
Julian calendar.  Finally, the last items of task related information
are the task dependencies and task resources.  The task dependencies
is a list of all other tasks in the PERT/Gantt chart project that must
be completed before the task may start or complete.  The resources is
a list of all resources that a task may utilize. Resources may be a
list of words describing the people, software, organizations, tools,
and facilities that may be employed to complete the task.  There is no
categorization of the resources, so the user enters them in any
desired order.  No sorting of the resources or dependencies is
provided by xplan.

To use xplan, no knowledge of special computer languages is necessary
to operate the software. The language appearing on the GUI windows,
help menus, and control button labels is English.  The user may enter
task names and descriptions in any human language that may be
described by the ASCII character set.  However, all numbers which
represent dates and times must be ASCII numbers.  Since xplan is
provided free of charge, the user may access the source code to
translate the text of the labels and help menus to a language other
than English as long as they have the OpenWindows Developer's Guide
3.0 and the new language may be represented by the ASCII character
set.  However, if the user wishes to modify the software, they must do
it in accordance with the Free Software Foundations policies regarding
the release of freeware and identify the original authors of xplan.

The best way to learn how to use xplan is to experiment with it.  The
online help features and the GUI are self-explanatory in regards to
the function and usage of xplan and xplan's menus.  However, for the
novice user, the following section will provide an example of how
xplan may be used to create and use PERT/Gantt charts for a project
whose tasks are described in the xplan input format.


%
d37 1
a37 7
%
% Provide a description of the steps needed to 
% install the system.  This should include any
% details not mentioned in the introduction (i.e.
% environment setup, etc.)
%
\section{Installation Procedure}
a38 16
The installation procedure for xplan is the following.  First, please
note that xplan is distributed in a compressed tar file format via the
Internet community and anonymous ftp sites.  Once you find the
location of the xplan distribution file, ftp it to your machine
operating with a Unix and X Windows environment capability.
Uncompress and extract the distribution file in the directory you
create for running xplan.  Execute the makefile for xplan, and then
type ``xplan'' after compilation on your machine is successful.  You
are now ready to run xplan and create PERT/Gantt charts for managing
your projects.  If you have LaTeX installed, you may output the
PERT/Gantt charts to the LaTeX file format for document processing
with LaTeX.  Note that your system must have the gcc ANSI C compiler,
Unix, X Windows, and the X libraries for successful compilation of the
xplan software.  You may input and output ASCII text files to xplan
via the GUI once you are running xplan.

d56 1
a56 1
\section{Bibliograph}
@


1.1
log
@Initial revision
@
text
@d5 1
a5 1
\author{{\Large\it Brian Gaubert, Mark M. Lacey, Richard Malingka, Michael Marlow} \\
d233 1
a233 135
\section{User Scenarios}

Now that you are ready to begin using xplan's power to plan your
projects, let's illustrate a sample xplan work session.  First, you
must obtain and compile the xplan system software (Please see the
Installation Procedure section of this document).  While reading the
following example, please refer to the figures of actual xplan
graphical user interface (GUI) windows and popup windows.

Once you have a working copy of xplan on your system, just type
``xplan'' to run this PERT/Gantt chart generator project planning
tool.  You will see a window labeled ``xplan''.  The four buttons at
the top are your top level control buttons, and the textpane below
with the vertical scroll bar is the task list window for a particular
project. If you click on the ``File'' button to the far left with the
left mouse button, a popup window will appear to allow you to specify
the directory and file from which to load an ASCII text file
containing a project's task information.  Clicking on the right mouse
button will popup a menu with the options ``Load, New Project, Save,
Save As...''.  Selecting the ``Load'' button will allow you to specify
the directory and ASCII text file containing project task information.
Selecting the ``New Project'' button will delete all of the
information in xplan's database for a project.  However, another popup
window will appear to confirm that you actually want to delete this
project's information from xplan.  Selecting the ``Save'' button will
save all of the projects task information to the last save file
specified for that project. Selecting the ``Save As...'' button will
allow you to save all of the projects task information to another file
name.  Each time you input from, or save to a project file, you have
the option of specifying which Unix directory the project file is
located in.

Using the left mouse button to select the ``chart'' button in the
middle left of the ``xplan'' window will automatically calculate and
display the PERT chart for your project.  Using the right mouse button
to select the ``chart'' button will popup a window that gives you the
choice of calculating and displaying a PERT chart or a Gantt chart.
Selecting the right mouse button on the middle right ``Analyze''
button on the ``xplan'' window will display a popup menu with the
options to ``Find Critical Path, Check Dependencies, Date
Calculation''. Selecting only the left mouse button on the ``Analyze''
button will automatically calculate the critical path. Selecting the
right mouse button on the far right ``Export'' button of the ``xplan''
window will allow you to produce LaTeX file format outputs of your
Projects tasks, and PERT/Gantt charts.  You will have a popup window
with the options ``Generate Task Sheet, Generate PERT Chart, Generate
Gantt Chart, Options'' The first three choices are for generating the
LaTeX file format output of the respective information for your
project.  The ``Options'' choice on the popup menu for the ``Export''
button will create another popup window labeled ``Export Options'' in
which you may specify the file name and directory of the LaTeX file
you are saving your projects PERT/Gantt charts and task information
to.

In general, the left most button automatically executes the first
choice on a graphical user interface (GUI) control button.  While
selecting the right most mouse button brings up the popup window for
that control button.  In that popup window for the control button, you
use the leftmost mouse button to select the option of your choice in
the popup menu.  Generally, all popup windows have a switch at the top
left of them. The left most mouse button may be used to flip that
switch to dismiss a popup window when it is no longer necessary for
you.  To fully quit execution of the xplan software, you use the close
window function of X Windows.  Note, if you destroy the main window
labeled ``xplan'' while you are in a work session, your project
information will be lost!  In general, xplan provides double check
popup windows to confirm that you want to delete data.

In the xplan softwares main menu labeled ``xplan'' the task names for
a project are listed in the textpane control window with the vertical
scroll bar underneath the four control buttons. If you selected an
ASCII text format input file, you will see task names listed.  If you
are starting from scratch, you will see nothing in this text pane.  To
input task information into a blank textpane on the ``xplan'' window,
you click right mouse button in the ``Tasks'' textpane to see the
popup window labeled ``Scrolling List''.  If you select the ``Locate
Choice'' option, you may search for a particular task in the main task
list for your project which xplan is calculating PERT/Gantt charts
for.  If you select the ``Edit List'' option, you may change, or
delete an existing task you click on with the mouse button to
high-light in the ``Tasks'' textpane.  If you select the ``Insert''
option of the ``Scrolling List'' popup window's ``Edit List'' popup
window, you may enter a new task into xplan's database for your
project.  Whenever a task's information is to be created or edited by
the GUI, a popup window labeled ``Task Information'' will appear with
all of the task related information described in the Functionality
Description section of this document.  For items such as Task Name,
Task Description, Task Options, Task Dates, and Task Times, you may
directly type in this popup window.  To display and edit Task
Dependencies and Task Resources Lists, you click the left button of
the mouse on the control buttons labeled ``Dependencies'' and
``Resources'' in the ``Task Information'' window.  After you have
finished creating or editing a task, you must decide if you want to
save that tasks new information.  Pressing the left button of the
mouse on the ``Apply'' button of the Task Information popup window
will save the new task, or changes made to an old task's information.
Pressing the left button of the mouse on the ``Reset'' button will
cancel the changes made to an existing task, or not create the new
task.

These windows operations are self-explanatory for the user who is
familiar with using graphical user interfaces (GUI) designed for
software running in an X Windows environment.  However, if you need
help while running xplan in real time, you may use the help facilities
provided by the GUI.  If are using the Sun SPARC 1 or 2 workstation,
click on the ``radio help'' key and use the mouse to select the GUI
control button, textpane, or popup window you desire help information
for.  The GUI and online help capabilities for xplan were developed
with OpenWindows Developer's Guide 3.0 for use on a Sun SPARC station.
If you are not using a Sun SPARC station, you will need to consult you
workstation's manual for how to utilize the equivalent of the ``radio
help'' key on a Sun SPARC 1 or 2.

For additional help, this manual is included in the xplan delivery
package of a compressed tar file.  This manual is provided in
Postscript format for the user to view either online, or generate a
hard copy by using a Postscript laser printer.

After you have created a project task list in xplan for your project
and viewed the PERT/Gantt charts, you may save your work to ASCII text
file format for further xplan processing at a later date, or to the
LaTeX file format for incorporating PERT charts, Gantt charts, and
Project Task Information into professional quality documents written
with the LaTeX document processing system.  Those documents regarding
your project may then be put into postscript format for electronic
distribution on computer networks and the Internet, or laser printed
in a hard copy format to paper or overhead slides for presentations.
Again, we recommend that the user obtain the LaTeX Users manual if
unfamiliar with LaTeX.  Since LaTeX is also provided as shareware, the
budget conscious user can productively utilize the xplan software by
using it in conjunction with LaTeX as part of a total document
processing system for generating reports and information regarding the
status of the project being managed.


@
