  rTc User Guide
  Version 2.0a
  Richard M. Offer, richardo@x.co.uk
  Jul 1995

  rTc is Copyright (c) 1993,1994,1995 Richard M. Offer.	rTc is covered
  by the GNU Public License, see the section Copying for details on your
  rights. Additional parts are copyright The Board of Trustees of the
  University of Illinois and David Koblas.

  1.  Introduction




  This is the User Guide for rTc, a Motif-based program launcher (don't
  be scared, the program does't (really) need a manual anywhere near as
  big as this to use it, but the instructions on configuring the various
  optional features before compiling it are quite big).

  The documentation has been written using a hacked Linuxdoc-SGML DTD,
  but I've supplied versions in preformatted in PostScript, HTML and
  plain ASCII. The Linuxdoc-SGML package has the advantage of being able
  to produce HTML (for on-line help), LaTeX (hense PostScript for nice-
  looking printed docs); and nroff/ascii output (for man pages) from a
  single input file.

  1.1.	About rTc







  rTc is a simple to use, but fully functional program launcher utility
  for Unix workstations running X/Motif. As well as the usual feature of
  executing commands, it also allows the user to :- customize the
  command before it is executed (ie. allowing the user to specify a
  printer); limit the number of invocations of a particular command (ie.
  only allowing the user to start one instance of a word processor); a
  help display system (including optional HTML support); a clock (with
  reminder facility); and mailbox and disk-space watchers ("how many
  messages do I have ?" and "how much space is there ?") .


  Since rTc is a simple X client it can be used with any window manager,
  in fact if you link it with IXI's Wintif(TM) library (blatant
  advertising :-)) it will even look and feel like a Windows 3.1
  program!

  1.1.1.  Copying



     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.


  The HTML browser widget is Copyright (c) 1993, Board of Trustees of
  the University of Illinois (see the file libhtmlw/HTML.c for its
  license).

  The GIF reading function used in the HTML browser is Copyright (c)
  1990 - 1994, David Koblas. (koblas@netcom.com), see the file
  src/gifread.c for its license.

  1.1.2.  This version

  This release is in response to the extended beta test I had for
  version 2.0, a few bug-fixes (mainly on platforms I hadn't tested on)
  and the re-introduction of audio feedback. The rest of this document
  assumes I am talking about version 2.0.


  The raison d'etre for this new, improved version of rTc has been to
  increase configurability, both at compile time (if you don't want a
  feature you shouldn't need to compile it in) and run-time. This has
  been achieved by re-writing the program to be be more modular (I would
  say object-orientated, but I don't know what it means). There are no
  interdependencies between different options, so any may be left out,
  and it is easy to add new ones without having to worry about
  combatability with existing code.

  Run-time configurability has been increased so that the user can
  specify:- the style of the program (do error messages use dialogs or a
  status line); the type of messages displayed (only Errors,
  Errors+Warnings, Errors+Warnings+Output); the type of user (expert or
  beginner, beginner mode has a simpler interface). There is a also the
  facility to specify two description files, a system and a personal
  one. The personal one may add entries to the menus specified in the
  system file, but not remove them.

  A list of some the features of rTc are :-


  o  Simple line-based menu descriptions.

  o  Two input files, the system one is read first, the personal one may
     add entries to the menus.

  o  Personally tested on 4 more platforms (SunOs, Solaris 2.2, HPUX
     (all X11R5/Motif 1.2), Linux X11R6/Motif 2.0))

  o  A much improved help system with:

  o  HTML support.

  o  the text may now be stored in separate files.

  o  the help files are searched for in a colon separated list of
     directories (a set-able X-resource).

  o  support for multiple screens.

  o  bitmaps (and, if supported XPM) files are searched for in a colon
     separated list of directories (a set-able X-resource).


  o  improved clock/reminder. Reminders may now be set on any day and
     will be remembered across sessions.

  o  a new mail-box watcher (ala biff), displays how many messages in
     the specified mailbox.

  o  a disk space watcher (displays how much space is free in a
     specified partition).

  o  a re-start option has been included to re-read the description
     files.

  o  user-defined panels, allowing the user to configure a command
     before it is executed.

  o  hierarchical (ie walking) menus.

  o  limits may be set on the number of times a program may be executed.



  1.2.	Upgrading from version 1.3

  There has, unfortunetly, been a few incompatible changes in the
  description syntax between versions 1.3 and 2.0. I have provided a
  small awk script to convert version 1.3 files to the new syntax
  (update.awk). The list of changes is :-


  o  f.title has been replaced with f.label (only in menus, in panels it
     has been removed).

  o  f.exec has been changed to f.button (if in a menu) or f.command (if
     in a panel).

  o  f.info and f.msg-area have been discontinued.

  To use the update.awk script requires a version of awk to be installed
  on your system, simply type :-


  ______________________________________________________________________
  % awk -f update.awk input
  ______________________________________________________________________



  Where input is the old (v1.3) rTc description file. The new file is
  written to stdout.

  While the awk script corrects the syntax, the options (particularly
  the time options) may need to be modified by hand to get identical
  results.

  1.3.	Obtaining the Source code

  The latest version of the source code can always be found via:-


  The rTc home page. (http://www.robots.ox.ac.uk:5000/~vanye/rtc/).

  This is the master site, (which also includes this guide in HTML
  format on-line).

  For those without WWW access the source may be accessed directly at :-

  The Oxford University Robotics Research Groups FTP server
  (ftp://ftp.robots.ox.ac.uk/pub/linux/motif/rtc-2.0.tar.gz).


  Please note this machine is remarkably unreliable, and I can no longer
  just walk over to it and kick it (its about 100miles away), so the WWW
  page is preferable.

  Due to these sites belonging to an ex-employer I am currently
  investigating other alternatives, but both of these should be okay at
  least until the end of the year.

  For the vast majority of you (and as a means of getting it mirrored at
  other sites), I've also put it on The X Consortium FTP Server
  (file://ftp.x.org/contrib/applications/rtc-2.0.tar.gz).




  1.4.	Apologies

  This version was originally intended to ship before Christmas, then I
  delayed it until after Christmas, now easter is leaving us fast.  I'm
  sorry, I've had a lot on recently (moved jobs, moved cities, moved
  house, oh and of course the usual family and personal problems). One
  of the advantages of my new job is the increase in the number of
  architectures I have access to: I still have access to Linux and SGI
  Irix 5.2, but now SunOs, Solaris, HPUX and AIX have been added (AIX
  hasn't been tested yet).

  I had intended to write some new features specific to X11R6 in this
  version, unfortunetly I am still having some problems with Motif 2.0
  under X11R6 on Linux (my main development environment). I have managed
  to compile and test rTc under X11R6/Motif 2.0, but my Motif 2.0 setup
  is not yet stable enough to use it as the base for development (if
  you're interested--the file selection box doesn't work at all, and
  XmGetPixmap appears to go into an infinite loop).


  As I had slipped so far and still have no idea how long it will be
  before I managed to get X11R6 and Motif 2.0 working happily together,
  I've bit the bullet and decided to ship what I've got now.

  I hope to include some Motif 2.0 specifics (ie. spin-box, combo-box,
  container, and notebook widgets in panels), however if you would
  rather see R6 specifics (ie. session management--not much use until
  there are session aware clients) in the next version (2.1) then if you
  let me know, I can see what the relative response is.

  However I don't expect another release for a while as I'd like to put
  off active development (ie. I'll only be bug fixing) to give me some
  time to write another program, change-is-as-good-as-a-rest and all
  that.

  1.5.	Thanks

  I'd like to thank all those who have contacted me with ideas/requests
  for enhancements/or bug reports, especially Mark Davis
  (mark@taylor.infi.net) who had lots of ideas and infinite patience
  while we tried to port it to SCO ODT.


  I could't put every request into this version, maybe next time...



  2.  Trying it Out



  2.1.	Compiling rTc



  1. Unpack the compressed tar file. (left as an exercise to the reader)

  2. change directory to the top of the rTc distribution. (you should
     see subdirectories:- doc; include; libRws; libhtmlw; and src (along
     with some other files)).

  3. Edit include/rtc-config.h to reflect those options you want in the
     final binary, and the definitions of some rTc defaults, see Section
     ``Configuring rTc before Building'' for more details. You may need
     to modify the Imakefile to set the locations of header files and
     libraries.

  4. Type the following at a prompt.

     ___________________________________________________________________
     % xmkmf
     % make Makefiles
     % make depend
     % make
     ___________________________________________________________________





  2.2.	Running rTc

  As a simple test of rTc, try running it with the example files, as
  shown below.


     If WANT_SYSTEM was defined

	________________________________________________________________
	% cd src
	% ./rtc -f user-file --system-file system-file
	________________________________________________________________




     If WANT_SYSTEM was not defined

	________________________________________________________________
	% cd src
	% ./rtc -f user-file-complete
	________________________________________________________________



  Notes:-

  1. Using user-file on its own (with no accompanying system file) is
     not a good idea (it will probably crash, since it only adds to a
     menu structure that is expected to be already created).

  2. As these files test all the features, there may be some warning
     messages if support for a feature has not been compiled in,
     either:- ignore the message; remove the offending line; or
     recompile with the support added.



  I personally start rTc from .xinitrc as the last client, making it the
  controlling client (meaning that when rTc terminates, my X session
  terminates).

  2.3.	Installing rTc

  rTc does not need to be installed before it can can be used (see
  previous section), and you may need to be root to do this:-


  ______________________________________________________________________
  % make install
  % make install.man
  ______________________________________________________________________




  The installation of the manual only installs the unformatted man page,
  the user guide and preformatted man page are not touched.




  3.  Description Files



  3.1.	Shell Variables

  Any environment variable may appear in the description file, for
  evaluation and substitution when the line is parsed. Environment
  variables are denoted by prefixing them with a $ symbol, just as in
  any shell script. A variable name is considered to continue until the
  next whitespace; where this would lead to an incorrect name being
  searched for, it may be bracketed by {}, ie.

  ______________________________________________________________________
	  f.mail-box	"$USER %d" ${HOME}/Mail
  ______________________________________________________________________


  Would be interpreted the same as:-

  ______________________________________________________________________
	  f.mail-box	"vanye %d" /home/vanye/Mail
  ______________________________________________________________________



  Here $USER is terminated by a space, whereas $HOME isn't, hense the
  need to enclose it in {}.

  3.2.	Options


  There area number of options that may be applied to enhance or
  otherwise affect a specific entry in a menu or panel. Options are
  included in square brackets ([]) after the label (and before anything
  else on the line), whitespace is used to separate multiple options
  inside the [].
  Not all options are available on every entry, see the entry for
  details of those allowed.



     H=name
	This entry has some help text, called name associated with it.
	The help text may be either plain ascii of HTML text.


     F=file
	This entry has a help file associated with it. The file may
	contain either plain, formatted text or HTML source, and the
	appropriate browser will be selected (to be interpreted as HTML
	a file must have < as its first character). If no file is
	specfied, then a file with the same name as the first word in
	the entries label will be searched for. The file must not be
	fully specifed, it will be seached for in the directory list
	gived by the X-resource helpFilePath.


     I=file
	Specifies an X bitmap (or alternatively if colour icons are
	supported--X pixmap) file to be used instead of the text label
	for the entry. The file will be searched for in the directory
	path specified in iconFilePath.


     N=number
	Limits the number of times this entry may be executed. Once this
	limit is reached, trying to run anymore will be ignored and a
	message will be displayed.


     T=number
	Specifies a time, in minutes (or seconds if the number is
	suffixed with s).


     D=cmd
	Specifies a default. this is only used inside panel definitions.
	The cmd should be the actual default, not the name of the
	default.



  3.3.	Menu Syntax

  For an example of the syntax in use, see Appendix ``Annotated Example
  of Description Syntax''.


     Menu menu name
	Starts a menu definition, called menu name. Any number of
	entries may appear between this and the corresponding EndMenu.
	Note: the effect of starting another menu before finishing the
	first is undetermined (ie. don't do it).


     AddToMenu menu name
	Adds the following entries (until the next EndMenu) to the menu
	menu name. If menu name hasn't already been defined the results
	are unspecified (that well known euphamism for "will probably
	crash").


     EndMenu
	Ends a menu definition started with Menu or AddToMenu.


     f.button
	Creates a button in the current menu. The button will be labeled
	button, and when selected will execute the shell command cmd.


	Relevent options: H, F, I, N, T.


	If the T option is specified, this will display a dialog
	informing the user that the command has been started and to
	please wait. After the time expires the dialog will be
	destroyed.


     f.menu
	Creates a button (labeled label) that when selected pulls down
	the menu menu name.


	Relevent options: H, F, I.


     f.label
	Creates a simple label. This can be used as a title in a
	pulldown menu.


	Relevent options: I.


     f.separator "
	Creates a separator.



     f.quit
	Creates a button (labeled label) that when selected brings up a
	dialog to confirm whether you wish to quit rTc. Valid responses
	are, Yes, No or Restart. Restart terminates the current rTc and
	restarts it--re-reading the description files.


	Relevent options: H, F, I.



  These are the basics, others (optional) are discussed on a package-by-
  package basis in the next section.

  3.4.	Optional Packages


  3.4.1.  The Mail-Box watcher

  This is a simple package that provides visual feedback when new mail
  arrives, ala biff. Any number of mailboxes can be watched (although
  read access is requred), with differing frequencies of checking for
  new mail.

  When new mail does arrive the mail-box label is flashed at an
  increasing rate.

     f.mail-box
	Creates a button (labeled label) that displays the number of
	messages in the mail box mail box. The label label should have a
	place holder for the number of messages to be put (denoted by
	%d), ie "$USER %d", would display as something like "vanye 27"
	(if I had 27 messages in my mailbox).

  If the time option is set, the mail box is only checked when the
  period expires. If no time option is explicitly set the file is
  checked only every 15minutes.

  If the mail box is selected, the number of messages is re-counted
  there and then, without waiting for the next timed update.

  Relevent options: H, F, T.

  3.4.2.  The Disk-Space Watcher

  This package displays the amount of free disk space, colour coded, of
  a specified partition. The colours are specified on the line (and are
  therefore specific to that one instance of the disk space watcher.


     f.disk-space
	...colour_n=max_n:min_n" Calculates the free space in the
	partition (in Mbyte), and displays it in the label (which should
	have a place holder marked by %g).


	The text string is coloured depending on the free space and the
	break points specified in max and min. Perhaps the easiest way
	to explain is through an example:

	________________________________________________________________
		f.disk-space "%.4gMb in /" / green=:5 yellow=5:3 orange=3:1 red=1:
	________________________________________________________________


     this keeps a monitor on the slash (/) partition and colours it
     according to these rules :-


	1. If there is more than 5Mb of space then colour it green.

	2. If there is bewteen 5Mb and 3Mb then colour it yellow.

	3. If there is betwenn 3Mb and 3Mb then colour it orange.

	4. If there is less than 1Mb then colour it red.

     If one of max or min is not specified then it is taken to be
     infinity (positive if the max is missing, negitive if the min is
     missing).


  If an optional time is not specified, the values are updated every 30
  minutes.

  If the label is selected, the disk space is re-calculated, without
  waiting for the next timed update.

  Relevent options are H, F, T.




  3.4.3.  The Clock and Reminder

  The clock (or rather the reminder) has been considerablt enhanced in
  this version, it is now possible to save reminders between invocations
  of rTc in a reminder file.



     f.clock
	The label string is used to format the display via the
	strftime(3) library function. This allows place holders to be
	put in the label, and these will be substituted for when it
	becomes time for the label to be updated. The actual place
	holders are likely to be system dependent, but the more common
	ones are below:-


		    Place Holder   Meaning
		    -----------------------------------------
		    %H		The hour (24 hour clock)
		    %I		The hour (12 hour clock)
		    %M		The minute
		    %S		The second
		    %p		Either "am" or "pm"



  The time  will be updated every minute unless overrode by setting the
  time option.

  If the clock is selected, a reminder pop-up will appear. This panel is
  spilt into four main sections:- the date/time section; the reminder
  action area; a list of all reminders; and an area for the entry of the
  reminder text.






     To Add a Reminder

	1. set the correct date and time, using the sliders.

	2. type the text into the message field.

	3. click the button labeled ->. This adds the reminder to the
	   list.

	4. repeat until all the required reminders have been set.

	5. click on button labelled OK to save the new reminders.


     Removing a Reminder

	1. select the reminder you want to remove in the list.

	2. click on the button labelled Del..

	3. repeat until all the required reminders have been deleted.

	4. click on button labelled OK to update the reminder file.



     Changing a Reminder

	1. select the reminder you want to edit in the list.

	2. click the button labeled <-. This loads the reminder into the
	   date/time and message fields.

	3. set the correct date/time and message.

	4. click the button labeled ->. This updates the reminder in the
	   list.

	5. repeat until all the required reminders have been changed.

	6. click on button labelled OK to save the new reminders.




  3.4.4.  The Help System

  The help system now encompasses two means of describing the message
  (files and embedded text), and two formats of text (HTML and plain
  formatted ascii). A context--sensitive option is provided as well as
  the facility to hand-craft a help menu (and add any number of entries
  to it).

  Two browsers are available, one for plain formatted text, the other
  (optional) for HTML text. The actual one used is determined by whether
  the first character of the text is < (-- This is avery loose
  definition, which has been forced on me since there is no standard
  language definition--) . If it is (and support for HTML is built in)
  the text will be interpreted as HTML, otherwise it is assumed to be
  plain ascii text.

  The HTML viewer is not meant to replace Mosaic, it can only read files
  via NFS, only GIF pictures may be embedded, the spawning of external
  viewers is not supported, and it does not store a history of files it
  has viewed, so movement betwen pages has to be written into the pages
  themselves.



     f.help-menu
	This has the same syntax (ans effect) as f.menu, the only
	difference is that the Motif style guide will be followed by
	making the menu button appear on the right hand side of the
	menu-bar. An extra feature has been built in, if you request
	context sensitive help for this button, a copyright panel with
	configuration information (indicates which options are
	supported) will be dispalyed.


	Valid options are H, F, I.



     f.help-on-context
	Creates a button in the current menu, that, when selected will
	start the context sensitive system: the mouse cursor will change
	shape; an object should be selected (ie. clicked on); any help
	registered for that object will be displayed.


	To obtain context help for an object that is not immediately
	visible (ie. in a menu not currently poped-up), give the object
	keyboard focus and press the help key (this is usually F1).


     f.help-text
	Creates a button that when selected displays the help stored in
	the help object name. See HelpText/EndHelp for more details.


	Valid options are H, F, I.


     f.help-file
	Creates a button (labelled label) that when selected reads that
	file filename and dispalys it according to its type (plain of
	HTML). The file will be searched for in the directories given by
	the X-resource helpFilePath.

	Valid options are H, F, I.


     HelpText name
	Starts reading the file and storing the text as the object named
	name. Reading will only be terminated by the word EndHelp
	appearing at the beginning of a line.


     EndHelp
	Ends a help text definition started with HelpText.



  3.4.5.  Panels

  This is the largest of all the optional features, purely because of
  the number of new keywords added to the description syntax.



     Panel name
	Starts a panel definition, called name.


     EndPanel
	Ends a panel definition previously started with Panel.


     f.panel
	Creates a button in the current menu, (labeled label) that when
	selected pops up the panel panel name.



     f.command cmd
	This will be the command executed when the Execute button
	(located at the bottom of the panel) is pressed. The string cmd
	may contain both environment variables (denoted by $name) and
	rTc variables (denoted by @name). An rTc variable may only be
	set by another object in the same panel.


	The command object is never seen, it is simply a convenient
	metaphor for storing information accessed by the rest of the
	panel.



     f.text
	Creates a text entry object in the current panel, the string
	prompt is used as a prompt. When requested the current contents
	of the textfield are put in the rTc variable name





     f.file
	Creates a file selector with a prompt prompt. The directory dir
	is used as the starting directory. The current file selected is
	put into the rTc variable name.





	The file selector comprises: a scrollable list of files, a text
	entry (so new filenames may be entered) and a directory label.
	In the list of files, files are represented by a light font,
	directories by a bold one. Note: This is a brand new Motif
	Widget, there may be some problems with it, see Appendix ``''
	for more details.


     f.scale
	{min,max,incr}" Creates a scale setting the current value to the
	rTc variable name. The scale ranges between min and max in steps
	of incr (only via the keyboard). If none of these are specified
	the defaults are 0, 100, 1 respectively.





     f.list
	{item 1} {item 2} ..."	Creates a list containing item 1, item 2
	etc and setting name to be the currently selected item. Only one
	item may be selected at any time.





     f.toggle
	{label,cmd} {label,cmd} ..."  Creates a series of toggles (only
	one of which may be set at any time). Each toggle will be
	labelled with the correspoding label, and when set, the rTc
	variable name will be set to the respective cmd.






  3.5.	Command Execution

  When it comes time to execute a command, the shell given by the
  environment variable SHELL is used (rather than forcing all comands
  through sh. Of course if SHELL is not set, then there is no choice,
  but to hope that /bin/sh is available.

  If the msgLevel has been set to Information (this requires userType to
  be Expert), then any output generated by the executed program is
  captured and presented to the user. either via the status area or
  dialogs as required.



  4.  X Resources



  4.1.	General Application Resources


  The following application resources are available in rTc, most have
  command line equivilents.



     userFile (Type String)
	The users description file, the default is set during
	compilation as SITE_USERS_FILE, but as distributed this is
	.rtcrc.


     systemFile (Type String)
	The second source of menu descriptions, this file is read first,
	then the userFile. The default is controlled by SITE_SYSTEM_FILE
	during compiling, but as distributed this is
	/usr/local/lib/rtc/system.rtcrc.

	This resource is only used if WANT_SYSTEM_FILE is set during
	compiling.



     maximumSize (Type Boolean)
	Setting this to True (the default) makes rTc resize so that it
	fills the whole width of the screen.


     reminderFile (Type String)
	The file to use for saving reminders, this must be writable by
	the user running rTc. The default is set during building, but as
	distributed .rtc-reminders is used.

	This resource is only used if WANT_CLOCK is set during
	compilation.


     singleScreen (Type Boolean)
	If False (the default) rTc will run a copy of itself on every
	available screen. This is only usefull if you have a multi-
	screened display (ie. me).

	Multi-screen support is only added if WANT_MULTI_SCREEN is set
	during compilation.


     userType (Type String)
	Either Beginner or Expert, this is used to simplify the user
	interface in the panels (if set to beginner). If set to
	beginner, it overrides the setting of msgLevel setting it to
	Error. The default is Beginner.


     msgStyle (Type String)
	One of StatusArea, Dialogs or Console; this changes the method
	by which messages are presented to the user. If StatusArea (the
	default), a small-single-line (scrollable) status area is added
	below the menu-bar, for Dialogs each message is shown in its own
	dialog, and Console send the message to stdout.


     msgLevel (Type String)
	One of Errors, Warnings, Information or Diagnostics (with each
	increasing the number of messages generated).


     helpFilePath (Type String)
	A colon separated list of directories to search for a help file.
	Each directory must include the trailing `/'. The default is
	specified during compilarion and will be site specific.

	This is only used if WANT_HELP is set during building.


     iconFilePath (Type String)
	A colon separated list of directories to search for any icon
	file. Each directory must include the trailing '/'. The default
	is specified during compilation and will be site specific.


     messageBeep (Type Boolean)
	If True (default False) then rTc will generate a beep everytime
	a message is output.


     messageBeepVolume (Type int)
	The volume for the beep used when messages are output, default
	50.


     messageBeepDuration (Type int)
	The duration of the message beep (in milliseconds) default 25).


     executeBeep (Type Boolean)
	If True (default False) then rTc will generate a beep everytime
	a command is executed.


     executeBeepVolume (Type int)
	The volume for the beep used when commands are executed, default
	20.


     executeBeepDuration (Type int)
	The duration of the message beep (in milliseconds) default 10).


  Note: Both helpFilePath and iconFilePath have a common behaviour; each
  will only use the first match it finds.


  4.2.	Advanced X-Resources


  4.2.1.  Fonts

  To maintain a common look through the whole program, the fonts used
  have been grouped under the following charsets:-



     menu-buttons
	All buttons in the menus.

     message
	general purpose dialog messages.

     option-info
	used for the copyright and configuration dialogs.

     panel-button
	used for the buttons at the bottom of the panel (Execute, Done,
	Default).

     panel-prompt
	used for each prompt in a panel.


  5.  Command Line Arguments

  The command line options are simply shorthand for setting the X-
  resources.



     --user-file file
	Uses file as the user description, -f is an alias for --user-
	file.


     --system-file file
	Uses file as the system description file.


     --icon-file-path dir_1:dir_2:...
	Sets the iconFilePath resource to be the list of colon separated
	directories. Note that each directory must have the trailing
	separator '/'.


     --help-file-path dir_1:dir_2:...
	Sets the helpFilePath resource to be the colon separated list of
	directories. Note that each directory must have the trailing
	separator


     --reminder-file file
	Uses file as the file in which to store reminders.


     --status-area
	Uses a status area to present information to the user.


     --dialogs
	Uses dialogs to present information to the user.


     --console
	Send the messages to stdout.


     --error
	Sets the level of reported messages to allow error messages
	only.


     --warn
	Allows the user to see both error and warning messages.


     --info
	Any information messages generated by rTc are also visible (as
	well as errors and warnings). Information messages include
	output generated by an executed program.


     --beginner
	Simplifies the user interface a little (hardly visible), and
	enforces only error messages to be passed to the user.


     --expert
	removes the restrictions that --beginner sets.


     --single
	only runs rTc on the current display.


     --help
	prints out a usage message, -h is an alias for this.


     --mbeep
	switched on message beeps.

     --no-mbeep
	switched off message beeps.


     --ebeep
	switched on execute beeps.

     --no-ebeep
	switched off execute beeps.


  F.  Installing rTc


  This is a source distribution that will need to be configured and
  compiled for your specific machine. The program was developed on my
  Linux toaster (with MetroLink's Motif 1.2.2 and OSF Motif 2.0), I have
  personally tested it on SGi Irix 5.2, HPUX 9.0, SunOs 4.1.n and
  Solaris 2 using IXI Premier Motif (1.2.4), and have reports of it
  working on SCO ODT 3.0. Version 1.3 also ran on Irix 4.0 (ie. X11R4/Xm
  1.1), but I have since moved jobs, and no longer have access to any
  X11R4/Xm 1.1 machines, so I can't verify whether this is still true. I
  you have an R4/Xm 1.1 environment and are having problems with
  compiling rTc, then please feel free to contact me and together we can
  probably sort it out.


  F.1.	Configuring rTc before Building


  The main configuration parameters are in the file include/rtc-
  config.h, which is spit into two sections: the first sets default
  values for several parameters (each has a name starting with SITE_);
  the second states which of the optional features are to be built into
  the program (each starts with WANT_). Other configuration parameters
  are generated automatically (ie. the version of Motif and X installed
  on the system)--these are prefixed with HAVE_.

  If you change any of the variables in include/rtc-config.h, you must
  remake the Makefiles (make Makefiles) before they are recognised.

  F.1.1.  Site Dependent Defaults

  The following variables are used inside rTc:


  o  SITE_USER_FILE

  o  SITE_ICON_PATH

  o  SITE_INIT_MSG

  o  SITE_SYSTEM_FILE (-- only used if WANT_SYSTEM_FILE is set.--)

  o  SITE_REMINDER_FILE (-- only used if WANT_CLOCK is set.--)

  o  SITE_HELP_PATH (-- only used if WANT_HELP is set.--)

  o  SITE_MAIL_SEPARATOR (-- only used if WANT_MAILBOX_WATCHER is
     set.--)

  o  SITE_SUPPORT


     SITE_USER_FILE
	The name of the file to contain the users menu descriptions, a
	sensible value would be .rtcrc. This preovides the default for
	the X-resource userFile


     SITE_ICON_PATH
	The default for the X-resource iconFilePath, used to locate the
	icons (X bitmaps, and WANT_COLOUR_ICONS has been set, X
	pixmaps). This is a colon separated list of directories to
	search, each directory must include the trailing `/'. This is
	the default for the X-resource iconFilePath.


     SITE_INIT_MSG
	A string that is displayed in the status window as soon as rTc
	is started. This is only used if the MsgStyle is StatusArea. The
	default as distributed includes the version number and a
	copyright date, change this as you see fit, except put your name
	as the copyright owner :-) (one suggestion would be to put a
	local contact name).


     SITE_SYSTEM_FILE
	The name of the file used for the system menu descriptions. This
	is used as a default for the X-resource systemFile.


     SITE_REMINDER_FILE
	The name of the file used to store any reminders between
	sessions. A typical filename would be reminderFile.


     SITE_HELP_PATH
	A colon separated list of directories to use when searching for
	help files. This has the same syntax requirements as
	SITE_ICON_PATH. It is used as a default for the X-resource
	helpFilePath
     SITE_MAIL_SEPARATOR
	This string is used as the split between messages in any mail-
	spool. My system uses "From ", but your mileage may very.


     SITE_SUPPORT
	This string is displayed in the help panel, the default holds
	the rTc email address and WWW page. If you don't want anything
	shown, set it to an empty string, you can't simply remove the
	line.


  F.1.2.  Optional Features


  The following symbols are used to select which optional features are
  to be included in the compiled program.


  o  WANT_MULTI_SCREEN

  o  WANT_COLOUR_ICONS

  o  WANT_SYSTEM_FILE

  o  WANT_CLOCK

  o  WANT_MAILBOX_WATCHER

  o  WANT_DISK_WATCHER

  o  WANT_HELP

  o  WANT_HTML

  o  WANT_PANELS

  o  WANT_FILE

  o  WANT_LIMIT_EXEC

  o  WANT_EDITRES

  o  WANT_BROKEN_FORM_WORKAROUND



     WANT_MULTI_SCREEN
	Adds support for machines with more than one display (ie. my
	machine at work).


     WANT_COLOUR_ICONS
	rTc supports colour icons via the XPM library (which must be
	installed). If this is set, then the src/Imakefile may need to
	be edited to include the locations of the XPM library and header
	files. If your version of Motif supports Xpm files directly (ie.
	Metrolink 2.0), you should still set this as otherwise some
	icons may appear to have white (rather than transparent)
	backgrounds.


     WANT_SYSTEM_FILE
	Provides an easy way of loading menu descriptions from two files
	(a system file, and a user file). The system file is read first,
	then the users personal one.
     WANT_CLOCK
	Provides a digital clock that can be embedded in the menu-bar.
	Along with the clock, simple reminders can be set (these are now
	remembered across sessions).


     WANT_MAILBOX_WATCHER
	Provides a mailbox watcher (ala biff) that displays the number
	of messages currently in the (user specified) mailbox. More than
	one mailbox can be specified, and when new mail arrives the
	users attention is attracted visually.


     WANT_DISK_WATCHER
	Provides visual feedback of the availble disk space in (user
	specified) disk partitions, The amount of (free) disk space is
	shown, and this can be coloured coded depending on user
	specified ranges.


     WANT_HELP
	A basic help system that uses plain formatted text can be
	obtained by setting this variable. For a more advanced help
	facility see WANT_HTML.


     WANT_HTML
	If this is defined, then support for the HTML widget in Mosaic
	is included. This means that the help files can be in HTML
	format, complete with images (only GIF format is currently
	supported). This is not meant to replace Mosaic and as such can
	only access files via NFS and not any of the numerous transport
	protocols Mosaic supports. Note, WANT_HELP must be defined as
	well.


     WANT_PANELS
	Extends rTc to allow commands to be configured before being
	executed. The configuration is via a panel, comprising a number
	of user interface objects (text entry, toggles, scales, lists,
	file selectors) described in simple terms in the description
	files.


     WANT_FILE
	This version of rTc sees the first release of the file-selector
	as a widget (previously it was implemented as a convenience
	function--it is now a true Motif widget). If you have any
	problems with the new implementation of the file selector, then
	it can be removed pending its fixing.


     WANT_LIMIT_EXEC
	Some commands may be limited in the number of times that they
	are executed (ie. only one copy of a word processor may be run
	at any one time). This option adds extra handling to allow this,
	however there is no easy (and efficient) way of doing this, so a
	brute force approach has had to be adopted. This will slow down
	the execution (all be it, very slightly) of all commands,
	whether they make use of the facility or not. For this reason to
	obtain this feature you have to explicitly ask for it (by
	setting this variable).


     WANT_EDITRES
	Adds support for the editres protocol, so that the internal
	structure of the program's X-resources may be examined while it
	is running.


     WANT_BROKEN_FORM_WORKAROUND
	Some implementations of the form widget are broken in their
	geometry management, there is no real solution (except not to
	use the form), defining this may work--but don%quot; hold your
	breath.




  F.2.	Porting to Other Platforms

  rTc has been ported to the following platforms:-


  o  Linux (1.0.9) with XFree86 2.1/Motif 1.2.2 (Metrolink) --main
     development platform.

  o  Linux (1.0.9) with XFree86 3.1/Motif 2.0 (OSF)

  o  SunOs 4.1.2 with X11R5/Motif 1.2.4 (IXI Premier Motif)

  o  Solaris 2.2 with X11R5/Motif 1.2.4 (IXI Premier Motif)

  o  HPUX 9.01 with X11R5/Motif 1.2.4 (IXI Premier Motif)

  o  SGI Irix 5.2 with X11R5/Motif 1.2.4 (IXI Premier Motif)

  o  SCO ODT 3.0.

  o  AIX

  The most recent of ports was the SCO ODT, some of the things to watch
  out for in porting are :-


  o  NeedVarargsPrototypes in misc.c, some platforms define this and
     still expect K&R style varargs (SCO ODT 2.0).

  o  If you want to use the Disk Space watcher, you will have to find
     out how your system handles the statfs or statvfs() system calls.
     and add the correct header files to include/Rtc.h at the
     appropriate point (see the comments)


  G.  Quick Reference Manual Page



  G.1.	NAME


  rtc -- a Motif based program launcher.


  G.2.	DESCRIPTION

  rTc is a Motif application that controls the execution of other
  programs.

  This is only a quick reference man page, for more details see the
  Users Guide.

  G.3.	SYNTAX


    Keyword		Options       Arguments
    Menu		  -	    menu name
    AddToMenu		-	    menu name
    EndMenu		-
    f.button		H,F,I,N,T     "label" cmd
    f.menu		H,F,I	 "label" menu name
    f.label		I	     "label"
    f.separator		-	    ""
    f.quit		H,F,I	 "label"
    f.mail-box		H,F,T	 "label" mail box
    f.disk-space	 H,F,T	 "label" part col=max:min ...
    f.clock		H,F,T	 "label"
    f.help-menu		H,F,I	 "label" menu name
    f.help-on-context	H,F,I	 "label"
    f.help-text		H,F,I	 "label" name
    f.help-file		H,F,I	 "label" filename
    HelpText		-	    name
    EndHelp		-
    Panel		 -	    name
    EndPanel		-
    f.panel		H,F,I	 "label" panel name
    f.command		H,F,N,T       cmd
    f.text		H,F,D	 "prompt" =name
    f.file		H,F	   "prompt" =name dir
    f.scale		H,f,D	 "prompt" =name {min,max,incr}
    f.list		H,F,D	 "prompt" =name {item} ...
    f.toggle		H,F,D	 "prompt" =name {prompt,cmd}...



  G.4.	RESOURCES

  The following table describes the command line arguments and the
  associated X-resources.


  Resource		Class		 Type	Default		Cmd Line Equiv.
  -----------------------------------------------------------------------------------------------------------------
  userFile		UserFile	      String	SITE_USER_FILE	--user-file
  systemFile		SystemFile	    String	SITE_USER_FILE	--system-file
  maximumSize		MaximumSize	   Boolean	True		 --minimum-size switches it off
  reminderFile		ReminderFile	  String	SITE_REMINDER_FILE   --reminder-file
  singleScreen		SingleScreen	  Boolean	False		--single
  userType		UserType	       -	Beginner	     --expert or --beginner
  msgStyle		MsgStyle	       -	StatusArea	   --dialogs, --status-area or --console
  msgLevel		MsgLevel	       -	Warning		--error, --warn or --info
  helpFilePath		HelpFilePath	  String	SITE_HELP_PATH	--help-file-path
  iconFilePath		IconFilePath	  String	SITE_ICON_PATH	--icon-file-path
  messageBeep		MessageBeep	   Boolean	False		--mbeep
  messageBeepVolume	MessageBeepVolume     Int	50		   none
  messageBeepDuration	MessageBeepDuration   Int	20		   none
  executeBeep		ExecuteBeep	   Boolean	False		--ebeep
  executeBeepVolume	ExecuteBeepVolume     Int	20		   none
  executeBeepDuration	ExecuteBeepDuration   Int	10		   none



  G.5.	FILES

  These can all be changed by configuring (before compiling), but the
  following are as distributed.


   .rtcrc

   .rtc-reminders

   /usr/local/lib/rtc/system.rtcrc




  G.6.	SEE ALSO


  execvp(2), sh, csh, bash.

  The RTC User Guide.







  H.  Undocumented-Documented Hacks


  What do I mean by Undocumented-documented Hacks? Well those sneaky
  little tricks that are undocumented (as far as future support is
  concerned), but documented (otherwise you wouldn't know about them).


  Setting either the systemFile or userFile to -- will make rTc ignore
  that particular file (so no error messages if it can't find it).



  I.  Example of Description Syntax






























  Menu Top
    f.menu	"System"	[ F= ] system
    f.menu	"Other Hosts" [ H=other-hosts I=term.xpm ] hosts
    f.menu	"Apps"	  [ F=rtc.html ] apps
    f.clock	"GMT %I:%M %p"
    f.mail-box	"${USER}: %2d" [ T=1 ] /usr/spool/mail/$USER
    f.mail-box	"Rtc: %2d" /users/offer/Mail/rtc
    f.disk-space  "%.4gMb in ${HOME}" $HOME green=:40 yellow=40:10 orange=10:5 red=5:
    f.disk-space  "%f Mb in /" / green=:5 yellow=5:3 orange=3:1 red3=1:
    f.panel	"FTP .." [ I=../include/ftp.xpm ] file-getter
    f.help-menu	"Help" /
  EndMenu

  Panel file-getter
    f.command	echo "ftp\n@EMAIL\nbin\nget @GETFILE @SAVEFILE\n"  | ftp @HOST

    f.text	"Get filename" =GETFILE
    f.text	"Save Flename" =SAVEFILE
    f.text	"Password" [D=vanye@robots.ox.ac.uk ] =EMAIL

    f.list	"Site" [D=sunsite.unc.edu ] =HOST {sunsite.unc.edu} {src.doc.ic.ac.uk} {ftp.sgi.com}

  EndPanel

  Menu system
    f.label	"System"
    f.separator
    f.button	"Lock Screen..." [ I=xlock.xpm ] xlock
    f.button	"Print..."	print
    f.separator	""
    f.exit	"Quit"
  EndMenu

  Menu hosts
    f.button	"arthur" /usr/local/bin/rcmd arthur-the-toaster
  EndMenu

  Menu apps
    f.button	"Word Processing"	[ T=10 N=1 ] wordp
    f.button	"Spreadsheet"		[ N=1 ] xspread
  EndMenu

  #name to help lookup

  HelpText other-hosts

  This lists a number of other machines
  that you may log into.

  EndHelp
















