HELP OVERVIEW Robert Duncan, July 1996
Using the Poplog X User Interface.
CONTENTS - (Use <ENTER> g to access required sections)
1 The Poplog Control Panel
2 The Menu Bar
2.1 The File Menu
... The File Dialog
... The Library Tool
2.2 The Project Menu
2.3 The Options Menu
... File
... Store Management
... Ved
... Pop-11
2.4 The Help Menu
... The Help Tool
3 Notes for Experienced Users
3.1 X Resources
4 Related Information
-----------------------------------------------------------------------
1 The Poplog Control Panel
-----------------------------------------------------------------------
The Poplog control panel provides your first entry point into Poplog. It
should appear automatically whenever you run Poplog with the %x option
to start up an X connection, or call sysxsetup from within a program. If
you don't see the control panel, or would prefer never to see it again,
refer to the section Notes for Experienced Users below.
The title bar of the control panel window shows the Poplog version
number: you should quote this if ever you have an enquiry about Poplog
or need to report a problem. Choose the Customer Support option from the
Help menu for details of how to do this.
The top of the control panel window is spanned by a menu bar containing
the buttons
File Project Options Help
These are described in detail below.
Beneath the menu bar is a panel of buttons labelled with the standard
subsystem names:
Pop-11 Prolog Common Lisp Standard ML
Use these buttons to choose the primary subsystem for your Poplog
session: this determines the top-level compiler for the base window, the
default search paths for documentation and library files, and the
default file extension. Choose the Languages|Subsystems option from the
Help menu for more details.
You may find that some of the subsystem buttons are insensitive so that
they don't respond to selection: this indicates that those subsystems
have not yet been loaded into Poplog. Which subsystems are available
initially depends on the command you used to enter Poplog, but you can
load others interactively if you wish: the Subsystems help file explains
how.
Neither the menu bar nor the button panel has useful resizing behaviour,
so you may find that your window manager will not allow you to resize
the control panel, but you can position it on screen wherever it's most
convenient for you.
-----------------------------------------------------------------------
2 The Menu Bar
-----------------------------------------------------------------------
Many of the menu options call up functions from Poplog's XVed editor:
choose the Editor|Overview option from the Help menu for an introduction
to XVed or see TEACH * XVED
2.1 The File Menu
------------------
Open...
Opens an XVed window on a named file: this may be an existing file,
or a new one that you want to create. Selecting this option pops up
the Open File dialog box in which you can enter the file name: how
to do this is described below. Once you have selected a file name,
press the Open button to view that file or Cancel to cancel the
operation and dismiss the dialog.
Choosing this option is the same as running the XVed command
<ENTER> openfile
Compile...
Compiles a named file which must already exist. Selecting this
option pops up the Compile File dialog box in which you can enter
the file name: the box is shared with the Open File operation, so
details are remembered between the two. Press the dialog Compile
button to compile the selected file: the appropriate language
compiler will be determined from the file extension.
Choosing this option is the same as running the XVed command
<ENTER> compilefile
Library...
Displays the Library Tool described below. Choosing this option is
the same as running the XVed command
<ENTER> librarytool
Interaction
Opens an interactive (or ``immediate mode'') XVed window in which
you can evaluate expressions directly: the language for the
interaction is determined from the currently-selected subsystem
button on the control panel.
Choosing this option is the same as running the Ved command
<ENTER> im
Interactive buffers aren't normally marked as writeable by XVed: if
you want to save a record of your interaction, you must first make
the buffer writeable with the command
<ENTER> set vedwriteable
Save All
Saves all XVed buffers marked as writeable which have been changed
since the last save. If there are no such buffers, this option will
be insensitive. Each named buffer will be written to its associated
file: the previous version of the file will normally be saved as a
backup. Each unnamed buffer will pop up a Save File dialog from
which you can either choose a name under which to save the buffer,
or cancel the save in which case that buffer will be left unwritten.
Choosing this option is the same as running the Ved command
<ENTER> w
Exit
Terminates your Poplog session. Selecting this option pops up a
Confirm dialog box which allows you to choose whether or not you
really want to exit: press the Exit button to leave Poplog or Cancel
to carry on. If you have changed some XVed buffers and not saved
their contents, a simple Exit will discard those changes; press the
Save Files and Exit button to do a Save All before quitting.
Closing the control panel from your window manager menu should
provide an alternative means of leaving Poplog.
... The File Dialog
--------------------
The file-chooser dialog is used by the Open File and Compile File
options from the control panel File menu and by various options from the
XVed buffer File menu (if present) to let you select a file name. While
the dialog is up, you cannot otherwise interact with Poplog: if you
don't want to choose a file immediately, press the Cancel button to
dismiss the dialog and cancel the pending operation.
To select a file, either type the file name directly into the text box
provided, or use the mouse or keyboard to select a name from the list of
files offered to you. The file list is initialised with files in the
current directory. To change the display, select a directory name
instead of a file name and press the Filter button: the list of files
will change to show the files in that directory.
The list of files is further constrained to those which match the
specified Filter: this can be treated as a standard file pattern, using
special characters such as '?' to match any character and '*' to match
any sequence of characters. The filter is initialised to match program
files of the primary subsystem, but you can change it to restrict or
expand the list of files displayed: use the Filter button to redisplay
the list if the filter is changed.
Once you have selected a file, press the left-most button in the box --
labelled Open or Compile as appropriate -- to initiate the operation on
that file.
... The Library Tool
---------------------
The Library Tool provides easy access to a selection of Poplog source
libraries and their associated documentation.
Use the Language buttons to choose the subsystem you are interested in:
this need not be the same as the primary subsystem selected on the
control panel. Descriptions of some of the libraries supplied with that
subsystem are displayed in the Descriptions list. Use the mouse or
keyboard to browse this list and select a library: the name or names of
the relevant library files will be displayed in the Libraries text
field. If you already know the name of the library you want you can type
it directly into here.
Use the buttons at the bottom of the dialog to act on your chosen
library:
Help
Displays documentation for the library
Show
Displays the library source code
Compile
Compiles the library: this option will only be available if the
relevant subsystem is loaded
Use the Dismiss button to close the Library Tool window: it can be
reopened from the File menu and will remember your last selection.
2.2 The Project Menu
---------------------
This provides a subset of options from the Project menu in the Project
Tool window. To learn more about projects choose Project Tool from the
Help menu or see HELP * POP_UI_PROJECTTOOL
New
Starts a new project.
Open...
Opens an existing project.
Save
Saves the current project. This option will be insensitive if there
is no current project.
Close
Closes the current project. This option will be insensitive if there
is no current project.
2.3 The Options Menu
---------------------
Use the dialogs on this menu to set your preferences for Poplog,
including the editor and the language subsystems.
Options dialogs are organised into sets of sheets or pages displaying
the values of user-assignable Poplog variables. Changing the values on
an options sheet does not automatically update the corresponding
variables: you must press the Apply button on that same sheet to make
those changes take effect. If you don't like the changes you have made,
press the Reset button to restore things as they were before the Apply,
or the Set Defaults button to go back to some default state (typically
how things were on entry to Poplog).
If you press Apply on any sheet, the Save Options button is enabled on
the menu. Use this to save any applied changes to disk such that they
will be restored each time you run Poplog in the future.
Save Options
Saves the values of any options sheets which have been modified and
applied since the last save; if there are no such sheets, this
option will be inactive. Different sheets save their values in
different ways; most will update your init files ("init.p",
"vedinit.p", etc.).
Selecting any other menu item will display one of the Options dialogs.
The choice of items will vary depending on which components of Poplog
you have loaded, but those described below are typical for a standard
system.
... File
---------
Variables controlling the File dialog and the creation of new files.
Initial search directory
The initial directory used by the File dialog: an empty string
means the current directory
Initial search pattern
The initial filter pattern used by the File dialog
File creation mode (UNIX only)
See REF * pop_file_mode
File backups
See REF * pop_file_versions
... Store Management
---------------------
Variables controlling dynamic storage allocation.
Maximum heap size
See REF * popmemlim
Minimum heap size
See REF * popminmemlim
Garbage collection algorithm
See REF * pop_gc_copy
Garbage collection ratio
See REF * popgcratio
Garbage collection trace
See REF * popgctrace
... Ved
--------
Editor preferences, controlling both Ved and XVed. Use the menu button
at the top of the dialog to select from the following pages:
General
Ved global variables.
Auto write
See REF * vedautowrite
Preserve in input
Whether to preserve tabs and/or trailing spaces in files when
they are read into Ved.
See REF * vedreadintabs, * vedreadintrailspaces
Tab style
See REF * vedhardtabs
Page up/down
See REF * vedscrollscreen
Status line display
See REF * vedstatusshowcols
Command history
See REF * vedstatusbufferlimit
XVed
XVed application resources.
Auto Window Placement
See REF * AutoWindowPlacement
Always Raise Window
See REF * AlwaysRaiseWindow
Set Input Focus
See REF * SetInputFocus
Warp Pointer
See REF * WarpPointer
Show File Name
See REF * ShowFileName
Set Line Break On Resize
See REF * SetLineBreakOnResize
Search Does Select
See REF * SearchDoesSelect
Auto Cut
See REF * AutoCut
MultiClick TimeOut
See REF * MultiClickTimeOut
Max Windows
See REF * MaxWindows
XVed Window
XVed currentWindow and defaultWindow resources.
Number of Rows
Number of Columns
The size of the window text area in characters
See REF * numRows, * numColumns
Foreground
Background
Status Foreground
Status Background
Colours for the text area of the window
See REF * foreground, * background, * statusForeground
* statusBackground
Font
Bold Font
Italic Font
Bold Italic Font
Fonts for the text area of the window
See REF * font, * boldFont, * altFont, * boldAltFont
Pointer Shape
X cursor shape in the text area of the window
See REF * pointerShape
... Pop-11
-----------
Pop-11 language preferences. Use the menu button at the top of the
dialog to select from the following pages:
Printing
Standard printing options.
Maximum depth
See REF * pop_pr_level
Output radix
See REF * pop_pr_radix
Fractional places
See REF * pop_pr_places
Exponential format
See REF * pop_pr_exponent
Ratio format
See REF * pop_pr_ratios
Quoted strings
See REF * pop_pr_quotes
Exceptions
Controls printing of exception -- mishap and warning -- messages.
Minimum detail level
See REF * pop_message_min_detail
Maximum backtrace length
See REF * pop_mishap_doing_lim
Show system procedures
See REF * popsyscall
Compile Mode
Sets Pop-11 compile mode flags described in HELP * COMPILE_MODE
2.4 The Help Menu
------------------
Most of these options use XVed to display standard Poplog HELP and TEACH
files and so provide short-cuts into the Poplog documentation system.
Choose the Editor|Overview option for details of how to navigate through
the help system.
Overview
Displays this file -- HELP * POP_UI_OVERVIEW
Project Tool
Displays HELP * POP_UI_PROJECTTOOL
Search...
Displays the Help Tool described below: use this to search for help
available on particular topics. Choosing this option is the same as
running the XVed command
<ENTER> helptool
Editor ->
Overview
Displays HELP * POP_UI_EDITOR_OVERVIEW
XVed Reference
Displays REF * XVED
Command Reference
Displays REF * VEDCOMMS
Keyboard
Displays the standard function key bindings for your keyboard.
Choosing this option is the same as running the Ved command
<ENTER> hkeys
Languages ->
Subsystems
Displays HELP * SUBSYSTEMS
Pop-11
Displays HELP * POP11
Prolog
Displays HELP * PROLOG
Common Lisp
Displays HELP * CLISP
Standard ML
Displays HELP * PML
About Poplog...
Pops up the Poplog Information dialog which summarises Poplog
copyright, version and supplier information. Click the mouse
anywhere in the dialog to dismiss the window.
News
Displays HELP * NEWS
Customer Support
Displays HELP * POPLOG
User Group
Displays HELP * PLUG
Licence
Displays HELP * POPLOG_LICENCE
... The Help Tool
------------------
The Help Tool provides a simple mechanism for searching the on-line
documentation of Poplog.
Type into the Subject field the name of the topic you are interested in
and press the Search button: a list of references matching the subject
will be displayed in the Search Results box. To follow up a reference,
select it from the list of results and press View Document.
Only single-word subjects are allowed and searching is restricted to
document titles and keywords: you can't, for example, search for all
documents containing the words input and output. Partial matches on the
subject are reported however, so to maximise the number of references
found you should stick to significant roots of words (so try copy rather
than copying).
By default, searching is restricted to the documentation of the primary
subsystem selected on the control panel. Use the Language toggle buttons
to widen the search to other subsystems.
The File Types buttons let you restrict the search to particular
documentation types corresponding to the four principal documentation
categories of Poplog: HELP, REF, TEACH and DOC. The Search Indexes
button determines whether the search includes indexed keywords, or is
restricted to document titles only. In this context, "keywords" are
typically identifier names.
-----------------------------------------------------------------------
3 Notes for Experienced Users
-----------------------------------------------------------------------
The Poplog User Interface is built from the library LIB * POPLOG_UI. It
is normally supplied ready-built as part of the startup saved image
loaded with all the standard Poplog commands so that calling the
standard X setup procedure sysxsetup -- either directly, or indirectly
via the %x command-line option -- will automatically run the UI startup
procedure pop_ui_setup.
Whether the control panel window appears or not is determined by the
boolean variable poplog_ui_enabled: this is normally true, so the
control panel is created by default.
If you don't want the control panel to appear automatically, you should
set the variable poplog_ui_enabled to false in your "init.p" file: in
case you are running Poplog without the UI library loaded, it's wisest
to guard this assignment in a conditional compilation, like this:
#_IF DEF poplog_ui_enabled
false -> poplog_ui_enabled;
#_ENDIF
If you want subsequently to create the control panel by hand, do:
true -> poplog_ui_enabled;
pop_ui_setup();
More information about the programming interface to the UI is available
in REF * POP_UI
3.1 X Resources
----------------
You can use the X defaults mechanism to customise standard UI resources
such as fonts and colours, but there are no application-specific
resources that can be sensibly changed. The UI uses *XptDefaultDisplay
for its X connection and the default class name is Poplog, so the
following line added to your .Xdefaults file or similar would change the
background colour of all windows created from the default display,
including the UI:
Poplog*background: LightSalmon
Individual components of the interface can be addressed as follows:
Poplog*controlTool
The main control panel
Poplog*projectTool
The Project Tool window
Poplog*helpTool
The Help Tool window
Poplog*libraryTool
The Library Tool window
Poplog*fileTool
The file-chooser dialog
-----------------------------------------------------------------------
4 Related Information
-----------------------------------------------------------------------
TEACH * XVED
Notes on using the XVed editor
HELP * SUBSYSTEMS
An introduction to the Poplog language subsystems
REF * POP_UI
Procedures and variables of the Poplog User Interface
HELP * POPLOG_UI
The Poplog User Interface library
+-+ C.x/x/pop/help/pop_ui_overview
+-+ Copyright University of Sussex 1996. All rights reserved.