;;; -*- Mode:Common-Lisp; Package:PICTURE; Base:10; Fonts:(MEDFNB HL12B HL12BI) -*-

;;; Change history:
;;;
;;;  Date      Author	Description
;;; -------------------------------------------------------------------------------------
;;; 10/01/87    TWE	Updated for the scale menu item.
;;;  9/14/87    TWE	Updated for landscape mode.
;;;  5/21/87	TWE	Initial creation.

#|

This file defines the command that displays helpful information for the user.

The following is a list of the sections in this help description.
 INTRODUCTION
 WINDOW LAYOUT 
 CREATING OBJECTS
 ALTERING OLD OBJECTS
 SAVING THE PICTURE
 GLOBAL ENVIRONMENT
 KEYBOARD

|#


(DEFUN DISPLAY-HELP-INFORMATION ()
  (DECLARE (SELF-FLAVOR PICTURE-WINDOW))
  (SI:WITH-HELP-STREAM (WINDOW :LABEL "Picture commands" :SUPERIOR W:MOUSE-SHEET)
    (SEND WINDOW :SET-PROCESS CURRENT-PROCESS)
    ;; Window configuration stable now, let keyboard process proceed.
    (SETQ W:KBD-TERMINAL-TIME NIL)
    (FORMAT WINDOW "
                         LaTeX Picture program

INTRODUCTION

This program was written to enable one to enter pictures into a LaTeX
document without having so specify each object manually.  The author
of this program has defined pictures for LaTeX by hand and discovered
that it is a very tedious process.  That discovery eventually let to
the implementation of the LaTeX Picture program, which allows one to
specify LaTeX picture objects in a WYSIWYG (What You See Is What You
Get) manner.  Great care has been taken to attempt to simulate on the
screen what one would see LaTeX generate.

Since its initial creation, this program has been enhanced to support
landscape mode.  This allows one to use the LaTeX Picture program to
generate foils via SliTeX which contain graphics.

WINDOW LAYOUT

The layout of the LaTeX Picture program consists of a set of 4 types
of windows: Picture Window, Interaction Window, Status Window and
menus window(s).  The Picture Window is where all of the graphics are
drawn which represent the graphics one would see on a page generated
by LaTeX.  When the LaTeX Picture program is first brought up one will
see tiny dots in this window.  These dots form a grid which allows one
to connect objects like lines and boxes in a regular fashion.  This
grid can be altered via the `Toggle Grid State' menu item (see below
for details).  The Interaction Window is where all messages of general
interest appear.  The following messages appear in this window:
command identification which indicate which menu item was clicked on,
error messages, login prompts, filename prompts, and object
identification (when the user clicks the mouse near an object in the
Picture Window).  All keyboard input is entered in the Interaction
Window.  When the user uses the mouse to specify some component of an
object (for example the initial position of a line) information is
displayed in the Status Window which indicates the numerical position
of this component on the page.  Normally this will only be useful when
one is concerned about exact placement of objects.


CREATING OBJECTS

To use the LaTeX Picture program, specify the type of objects to be
drawn by clicking on menu items, and specify the other non-textual
information via the mouse.  After all objects have been specified,
click on the `Write TeX file' menu item, and then enter the filename
when prompted.  This file contains all of the information by LaTeX to
draw the picture.  It is recommended that one use the \\input command
from another file rather than physically placing the contents of this
file into another one.  A picture, once written, can be reloaded by
clicking on the `Read Picture file' menu item.  This actually reads in
a file which makes reconstruction of the picture easy; it does not
read in the .TEX file.  This means that if one edits the .TEX file
that those changes will not be recognized if one clicks on the 'Read
Picture file' menu item.

After clicking on a menu item to draw a specific type of object,
another menu will appear which shows the attributes of that object.
If the menu appears in a poor position, just move the mouse away and
it will reappear an a different location.  For all objects, one must
specify the initial position before specifying anything else.  After
specifying a value for an attribute, one may change it to something
else at any time.  For example, one can specify an initial position
for a hollow box, then specify the size of the box and then go back to
specify a different initial position.  The placement of the mouse
cursor within menu items it not done like it is in other applications.
This placement attempts to guess what item the user will position the
mouse on next.  The initial mouse cursor placement on all object
creation menus is on the `initial position' menu item.  Often one will
not need to move the mouse at all on an object creation menu.


ALTERING OLD OBJECTS

In addition to the object creation commands, there are commands to
manipulate existing objects - edit, copy and delete.  Each of these
commands is `sticky', in that once it is invoked, it will remain as
the current mode until another command is entered.  This allows, for
example, one to edit a collection of objects.  The `Scale' menu item
gives one another way to alter old objects.  See GLOBAL ENVIRONMENT
for more details.

SAVING THE PICTURE

The file operation commands are the interface between the picture on
the screen and the file system.  When one writes out a TeX file, two
files are actually written - a .TEX file and a .PICTURE file.  The
.TEX file is suitable for input directly into a LaTeX document - no
changes should be necessary.  The .PICTURE file is used by the LaTeX
Picture program to reconstruct the image that corresponds to the file.
Neither file should be edited directly unless one is certain that the
Picture program will not need to read them.


GLOBAL ENVIRONMENT

The next set of commands deal with altering the global environment of
a picture.

LaTeX supports two thicknesses for line segments: thick and thin.  The
`Change Line Thickness' menu item allows one to alter the current
setting.

The LaTeX Picture program also supports all of the linear dimensions
that are supported by LaTeX, such as inches and millimeters.  The
`Change Units' menu item allows one to change the current unit of
measure.  After specifying a unit, all objects are automatically
scaled to reflect the new unit so that they do not change their
position or size.  Most users will not care anything about units or
where things are placed.  The 'Change Units' menu item allows those
other users to fine tune their picture.

The `Specify margins' menu item allows one to draw the margins which
LaTeX will be using to format your picture.  The author has found this
helpful since LaTeX will have trouble drawing pictures that are too
large horizontally to fit on a page.  Keep in mind that the margin
graphic is only an aid for the user.  It has no relation to the actual
page layout used by LaTeX.  It is also not displayed on the page; one
need not turn it off when saving the picture.

The `Toggle Grid State' menu item deals with the grid.  If you have
used the graphics editor (GED) you are probably already familiar with
grids.  A grid makes it easy for one to have the boundaries of objects
touch one another.  If the grid is turned on, the default, this will
happen automatically.  If the grid is turned off then one has complete
freedom (down to the pixel level) in placing objects on the screen.
One can also change the dimensions of the grid box in the X or Y
dimensions so it is more in tune with the objects being drawn.  All
objects will have at least the initial position be on a grid point.
Some objects, such as hollow boxes and dashed boxes will have all
edges be on grid points.  Other objects, such as lines and vectors,
will have the second endpoint be on a grid point if it is possible.
The author normally only turns off the grid when placing text stacks
in a proper position.  Most often the placement of a text stack will
not be ideal when the grid is turned on.


The `Scale' menu item allows one to scale the entire picture by a
specified amount.  The user enters a number and all objects are scaled
by that amount.  For example, a scale factor of .5 would make all
objects half their previous size.  There are some objects which may
not be effected by this command.  Text in general does not scale.
Also, circles have upper bounds for their size which may not be
exceeded.  The thickness of line segments also does not change.

KEYBOARD

If you don't like using the mouse so much, you can use the keyboard
for some of the commands.  The following command characters are
defined:
~
    ")
    (DOLIST (ELEMENT COMMAND-CHARACTER-LIST)
      (FORMAT WINDOW "~%~20<~@:C~>  ~A" (FIRST ELEMENT) (THIRD ELEMENT)))))