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.
