.TH PREREX 1 2008-05-16 "prerex-4.1" ""
.SH NAME
prerex \- interactive editor of prerequisite-chart descriptions 
.SH SYNOPSIS
.BR prerex 
[
.IR options
]  [ 
.IR file [ .tex ]]
.SH DESCRIPTION
.B prerex
is an interactive program
for editing prerequisite-chart descriptions in the
.BR prerex (5)
format.
The user does not normally have to
be familiar with details of the format.  
The editor supports add, remove, cut-and-paste, and edit operations
on diagram elements, and shifts of a list of specified elements or the entire diagram.  The edited diagram 
may be saved, re-processed, and viewed in a PDF 
viewer, without exiting the editor.
.SH TERMINOLOGY
A prerequisite chart consists of several
.I course boxes,
linked by 
.I arrows.
Courses are either
.I half
or
.I full,
and may be
.I required.
Each course box contains a course
.I code
(upper left corner),
a course 
.I title
(lower half),
and
.I timetable
information
(upper right corner).
An arrow is either a
.I prerequisite 
(solid),
a
.I corequisite 
(dotted),
or 
.I recommended 
(dashed).
When a conventional arrow would be inappropriate,
a
.I mini 
course just above a target box may be used.
A line of text may have been placed anywhere in the chart.
.PP
In some implementations of the
.BR prerex (5)
format,
(some) arrows may be curved and by default have non-zero curvature.
The curvature of individual arrows may be edited
using the
.BR prerex (1)
editor.
To modify the default curvature
(or set it to zero),
see
.BR prerex.sty (7).
.SH COORDINATE SYSTEM
A conventional two-dimensional
coordinate system is used to specify the locations of
diagram elements;
the
origin (where
.I x = 0
and
.IR "y = 0" )
is at the lower-left corner of the diagram.
For convenience, a coordinate grid is normally displayed in the background while a diagram is
being edited.
.PP
The coordinates of a
.I box,
.I mini,
or
.I text-line
are those of its centre point.  
An
.I arrow 
is described by the
coordinates of the centre points of its source and target boxes/minis/text-lines. 
.SH USAGE
If 
.B prerex
is invoked on an existing file, a back-up copy is made of it, the 
.I x,y
coordinate grid is turned on, the file is processed by using
a system call to
.BR pdflatex (1),
(or, if the -l option has been used, successive calls to
.BR latex (1),
.BR dvips (1),
and
.BR ps2pdf (1)),
an attempt is made to open the pdf in
the program that is the value of environment variable PDFVIEWER
and
then the user gets 
a command summary and an interactive prompt 
of the form
.IP
.I file.tex>
.LP
If a file argument is not given on the command line, the user is prompted to supply a
file name.
In either case, 
if the file name provided does not have a 
.I .tex 
extension, 
.I .tex
is appended to it.
If the file is read-only, the user must confirm that it can be edited.
.PP
If the 
.I file.tex 
file named does 
.I not 
already exist, the user is asked to confirm that a new "empty" prerex-formatted file 
of that name should be
created, and then it is processed as above. If the response is 
not positive, the user is prompted to provide
another file name to be used. 
.PP
The user may enter commands at the interactive command prompt as follows:
.TP 18
.BI   box   " x,y"
edit a course box at
.I x,y, 
if necessary, creating a new course box there 
.TP
.BI  mini   " x,y"   
edit a mini at
.I x,y,
if necessary, creating a new mini there 
.TP
.BI text   " x,y"
edit a text-line at
.I x,y,
if necessary, creating a new text-line there 
.TP
.BI  arrow  " x0,y0,x1,y1" 
edit an arrow from
.I x0,y0 
to 
.I x1,y1,
if necessary, creating a new such arrow 
.TP
.BI  cut    " x,y"          
(temporarily) remove the box, mini, or text at 
.I x,y                         
(including arrows into/out of the box/mini/text)
.TP
.BI  paste " x,y"          
re-insert most recently cut but not yet pasted box, mini, or text at 
.I x,y                  
(including arrows into/out of the box/mini/text)
.TP
.BI  delete    " x,y"          
remove the box, mini, or text at 
.I x,y                         
(including arrows into/out of the box/mini/text)
.TP
.BI  delete   " x0,y0,x1,y1"  
remove the arrow from 
.I x0,y0 
to 
.I x1,y1                  
.TP
.B undelete
restore the most recently deleted but not yet undeleted box, mini, or arrow
(including arrows into/out of a box/mini)
.TP
.BI  "shift  [\-]"  x  " [" " xi,yi ..." ]        
move specified diagram elements 
.I x 
units right [left]; if no elements are specified, the whole diagram is shifted
.TP
.BI  "raise [\-]" y   " [" " xi,yi ..." ]
move specified diagram elements 
.I y 
units up [down]; if no elements are specified, the whole diagram is raised 
.TP
.B   "write, !"                   
save to the current
.I file.tex
and process the chart by calling
.BR pdflatex (1),
(or, if the -l option has been used,
.BR latex (1),
.BR dvips (1),
and
.BR ps2pdf (1)).
.TP
.B  "quit, exit, x, ^D"                  
kill the PDFVIEWER process,
turn off the coordinate grid, restore write-access, save to the current
.I file.tex,
process it (using 
.BR latex (1),
.BR dvips (1),
and
.BR ps2pdf (1)),
and exit.  
.TP
.BI  ! cmd            
restore write access to 
.I file.tex, 
execute shell command
.I cmd,
re-load and re-process 
.I file.tex 
(in case the command changed it),
and remove write-access.
.TP
.BI  file " newfile" [ .tex ]       
change
the current file name, save to it and process it. 
If 
the file name provided
does not have a 
.I .tex 
extension, 
.I .tex
is appended to it.
If the 
file named
already exists, the user is asked to confirm that it may be
overwritten. A new back-up file 
.I .newfile.tex
is created.  The existing 
.I file.tex
and
.I .file.tex
are preserved.
.TP
.B "Backup"
copy the current
.I file.tex
to the back-up file
.IR .file.tex; 
equivalent to
.BI !cp " file.tex .file.tex"
.TP
.B "Restore"
delete the current 
.I file.tex 
and editing buffer, and replace them using the current back-up
in
.I .file.tex.
.TP 
.BR grid  " [y/n]"
turn on/off coordinate-grid background         
.TP
.BR  "help, ?"
print a command summary                             
.LP
After most editing commands, the editing buffer is automatically
saved to
.I file.tex
and this is processed; the 
.B cut
and
.B paste
commands are exceptions: saving and processing
take place only when all outstanding cuts have been pasted.  
Saving
and processing
can be 
.I forced 
by using the
.B write 
(or 
.BR ! ) 
command,
or 
.I suppressed 
for 
all commands (except
.BR file ,
.BR write  ,
and
.BR ! )
by appending a ";" to the command immediately prior to entering it.
To exit the editor
.I without
saving to the current
.IR file.tex ,
use 
.B quit; 
or a similar combination.
Starting in Version 3.8,
.B ^C
and other interrupts
result in the editing buffer being saved to
.I file.tex
before the editor is exited.
.SH OPTIONS
.TP 8
.BR -l
use 
.BR latex (1) 
-> 
.BR dvips (1) 
-> 
.BR ps2pdf (1) 
(rather than the default 
.BR pdflatex (1))
to process the chart file during editing
.TP
.BR -v 
output program name and version number, and quit
.TP
.BR -h
output usage summary and quit
.SH NOTES
The main difference between 
.B mini 
and 
.B text 
is in the maximum lengths for the text displayed; the latter allows a full line of text, not 
merely a course code. Also a text-line does not have an associated URI (when
the grid is off).
.PP
The editor does 
.I not 
have a general "undo" mechanism.
To save the current state of 
.I file.tex, 
use 
.B Backup
or a comparable shell command, or use the 
.B file
command (described above) to start editing with a new
.I file.tex.
A history list
of interpreted commands
is maintained and is accessible using the up-arrow key.
.PP
If 
processing of the chart fails, 
.B prerex
will attempt to display the LaTeX error message from the log file. 
The chart file 
can be fixed using a conventional text editor or LaTeX-oriented  editor.
LaTeX processing should fail only if there is an initial problem
or if ill-formed LaTeX markup has been inserted into a text field.
.PP
Any (non-empty) prefix of a command suffices; for example,
.BR q ,
.BR qu ,
or
.B qui 
may
be used instead of
.BR quit .
Some of the commands will begin a dialogue with the user in
order to fill in or modify
properties; the prompts should be self-explanatory.  
.PP
While the TeX file is being edited by
.B prerex,
its protection is set to read-only (except
when it is being regenerated or restored, or during a shell-command execution), to try to
prevent inadvertent interference from concurrent editing; this is not fail-safe.
.SH FILES
A LaTeX style file 
.BR prerex.sty (7) 
that implements
the macro calls defined by the 
.BR prerex (5)
format must be available to
.BR [pdf]latex (1)
to
process the file.
Before any editing is allowed, 
.I file.tex
is copied to 
.I .file.tex
as a backup, and similarly if a
.B file
command is used.
.SH ENVIRONMENT
.PP
Environment variable
.B PDFVIEWER
should be defined in your environment if you want 
.BR prerex (1)
to open a pdf viewer during editing.
The most convenient viewing program to use with
.B prerex
is one like
.BR gv (1),
.BR gsview (1), 
.BR kghostview(1),
.BR kpdf (1)
or
.BR okular (1)
that may be configured to "watch" the pdf file and re-load the display automatically when the file changes.
.BR evince (1)
has a Reload button and
.BR xpdf (1)
supports re-loading using the keystroke "R", but 
re-loading is much less convenient with
.BR acroread (1)
and
.BR gpdf (1),
which
may have to be re-started.
.PP
Recent versions of some PDF viewers show the URIs of hyperlinks in a tooltip or in the status bar;
this mechanism is
used by some implementations of 
.BR prerex.sty (7)
to allow display of the coordinates of a box, mini, text-line, or arrow when the mouse hovers over it
(while the coordinate grid is on and the file is presumably being edited).
.PP
The 
.B prerex
package at 
.B http://www.ctan.org/tex-archive/graphics/prerex/
has a patch for 
.BR kpdf (1)
(now incorporated into
.BR okular (1))
to make it display URIs in tooltips and also to allow the user to
capture coordinates of course boxes, arrows, and
background points in the X selection clipboard (for pasting into a 
command being composed at the 
.B prerex 
prompt).
.SH BUGS
.B prerex 
analyzes prerex-format files without using TeX; thus,
macro calls are 
.I not
expanded, and
anything in the file before or after the (first)
.B "\ebegin{chart} ... \eend{chart}" 
environment
is ignored (but preserved) by the editor.
Lines that begin with "%" within the chart environment are 
preserved but other comments within the chart environment are
.I not
preserved and may interfere with command parsing.
.SH AUTHOR
R. D. Tennent (rdt@cs.queensu.ca)
.SH DEPENDENCIES
.B prerex
uses the  GNU
.BR readline (3)
and
.BR history (3)
libraries.
.SH SEE ALSO
.BR acroread (1), 
.BR dvips (1),
.BR evince (1), 
.BR gpdf (1),
.BR gsview (1), 
.BR gv (1), 
.BR kghostview (1),
.BR kpdf (1), 
.BR latex (1),
.BR okular (1),
.BR pdflatex (1),
.BR prerex (5),
.BR prerex.sty (7),
.PR ps2pdf (1),
.BR xpdf (1).