Ubuntu Manpage: prerex - interactive editor of prerequisite-chart descriptions

NAME

       prerex - interactive editor of prerequisite-chart descriptions

SYNOPSIS

       prerex [ options ]  [ basefile[.tex] [ chartfile[.tex] ] ]

DESCRIPTION

       prerex  is  an  interactive  program  for  editing  prerequisite-chart descriptions in the
       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.  Alternatively,  vprerex(1)  will  embed  a  prerex(1)  window  and  display   the
       corresponding PDF file alongside.

TERMINOLOGY

       A  prerequisite  chart  consists  of  several course boxes, linked by arrows.  Courses are
       either half or full, and may be required  or  optional  (or  neither).   Each  course  box
       contains  a  course  code  (upper left corner), a course title (lower half), and timetable
       information  (upper  right  corner).   An  arrow  is  either  a  prerequisite  (solid),  a
       corequisite  (dotted),  or  recommended  (dashed).   When  a  conventional  arrow would be
       inappropriate, a mini course just above a target box may be used.  A line of text may have
       been placed anywhere in the chart.

       In  some  implementations  of  the  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  prerex(1)  editor.   To  modify  the  default  curvature  (or  set  it  to zero), see
       prerex.sty(7).

COORDINATE SYSTEM

       A conventional two-dimensional coordinate system is  used  to  specify  the  locations  of
       diagram  elements;  the  origin (where x = 0 and 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.

       The  coordinates  of a box, mini, or text-line are those of its centre point.  An arrow is
       described  by  the  coordinates  of  the  centre  points  of   its   source   and   target
       boxes/minis/text-lines.

       The  notation  x0,y0:x1,y1  denotes  all  the  nodes  (course  boxes, minis, texts) in the
       rectangle whose northwest and southeast corners are at coordinates x0,y0 and x1,y1.

USAGE

       If prerex is invoked on one existing  file,  a  back-up  copy  is  made  of  it,  the  x,y
       coordinate grid is turned on, the file is processed by using a system call to pdflatex(1),
       and then the user gets a command summary and an interactive prompt of the form

              file.tex>

       If no file argument is 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 .tex extension, .tex is
       appended to it.

       If the file.tex file named does not already exist, a new "empty" chart file with that name
       is created, and then it is processed as above.

       If  a  second  filename  is  provided, the first filename is treated as the base file of a
       LaTeX document and the second as an included file that contains the chart  environment  to
       be  edited.  This allows more than one document to share an included chart file and allows
       more than one chart to be included in a single document.

       The user may enter commands at the interactive command prompt as follows:

       box x,y           edit a course box at x,y, if necessary, creating a new course box there

       mini x,y          edit a mini at x,y, if necessary, creating a new mini there

       text x,y          edit a text-line at x,y, if necessary, creating a new text-line there

       arrow x0,y0,x1,y1 edit an arrow from x0,y0 to x1,y1, if necessary,  creating  a  new  such
                         arrow

       cut xi,yi ...     (temporarily)  remove  the box, mini, or text at xi,yi (including arrows
                         into/out of the box/mini/text)

       paste [x,y]       re-insert most recently cut but not yet pasted box, mini, or text at x,y
                         (including  arrows  into/out  of  the box/mini/text), or at the original
                         coordinates if  x,y omitted

       xchange x0,y0 x1,y1
                         exchange the box, mini or text at x0,y0 with that  at  x1,y1.   This  is
                         implemented as a sequence of two cuts followed by two pastes to the same
                         points.

       delete [ x,y  | x0,y0,x1,y1  | x0,y0:x1,y1 ] ...
                         remove  the  specified  boxes,  minis,  texts,  or   arrows   (including
                         automatically all arrows into/out of each box/mini/text)

       undo              undo the most recent editing command (not already undone)

       shift  [-]s  [ x,y | x0,y0:x1,y1 ] ...
                         move specified diagram elements x units right [left]; if no elements are
                         specified, the whole diagram is shifted

       raise [-]r [ x,y | x0,y0:x1,y1 ] ...
                         move specified diagram elements y units up [down]; if  no  elements  are
                         specified, the whole diagram is raised

       write, !          save  to  the  current  chartfile.tex  and  process the chart by calling
                         pdflatex(1) on the base file.

       quit, exit, x, ^D turn off the coordinate grid, restore write-access, save to the  current
                         chartfile.tex, process the base file and exit.

       !cmd              restore  write  access  to chartfile.tex, execute shell command cmd, re-
                         load  and  re-process  the  base  file  (in  case  the  command  changed
                         anything), and remove write-access.

       Backup            copy  the  current  chartfile.tex  to  the  back-up file .chartfile.tex;
                         equivalent to !cp chartfile.tex .chartfile.tex

       Restore           delete the current chartfile.tex and editing buffer,  and  replace  them
                         using the current back-up in .chartfile.tex.

       grid [y/n]        turn on/off coordinate-grid background

       help, ?           print a command summary

       After  most  editing  commands, the editing buffer is automatically saved to chartfile.tex
       and the basefile is processed; the cut and  paste  commands  are  exceptions:  saving  and
       processing  take  place  only  when  all  outstanding  cuts  have been pasted.  Saving and
       processing can be forced by using the  write  (or  !)   command,  or  suppressed  for  all
       commands  (except  write  and  !)   by appending a ";" to the command immediately prior to
       entering it.  To exit the editor without saving to the current  chartfile.tex,  use  quit;
       (.i.e., quit followed by a semi-colon) or a similar combination.  Starting in Version 3.8,
       ^C and other interrupts result in the editing buffer being saved to  chartfile.tex  before
       the editor is exited.

OPTIONS

       -v      output program name and version number, and quit

       -h      output usage summary and quit

NOTES

The main difference between mini and 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). The text "line" may actually
be displayed as a paragraph by using a LaTeX \parbox.

To save the current state of chartfile.tex, use Backup or a comparable shell command. A
history list of interpreted commands is maintained and is accessible using the up-arrow
key.

If processing of the chart fails, 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.

Any (non-empty) prefix of a command suffices; for example, q, qu, or qui may be used
instead of 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.

While the TeX chart file is being edited by 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.

Since version 5.5, prerex no longer automatically calls a PDF viewer (because it may be
embedded in an instance of vprerex(1) which already provides a PDF display). If prerex is
being used by itself, a PDF viewer may be invoked using the !cmd shell-escape mechanism.
Also, prerex no longer interacts with the user until a PDF file is available; this is for
use with vprerex(1). For example, if the .tex file is initially read-only, prerex aborts.

FILES

       A  LaTeX style file prerex.sty(7) that implements the macro calls defined by the prerex(5)
       format must be available to [pdf]latex(1) to process the chart file.  Before  any  editing
       is allowed, chartfile.tex is copied to .chartfile.tex as a backup.

ENVIRONMENT

       The  most  convenient  viewing  program  to  use with prerex is one like gv(1), gsview(1),
       kghostview(1), kpdf(1) or okular(1) that may be configured to "watch" the pdf file and re-
       load  the  display automatically when the file changes.  evince(1) has a Reload button and
       xpdf(1) supports  re-loading  using  the  keystroke  "R",  but  re-loading  is  much  less
       convenient with acroread(1) and gpdf(1), which may have to be re-started.

       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  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  relevant  chart  file  is  presumably  being
       edited).

       The  prerex  package  at  http://www.ctan.org/tex-archive/graphics/prerex/ has a patch for
       kpdf(1) (now incorporated into 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  prerex
       prompt).

       At  the  same  site,  there is also source code for vprerex(1), a GUI front-end for prerex
       which is similarly prerex-enabled.

BUGS

       prerex analyzes chart files without using TeX; thus, macro calls  are  not  expanded,  and
       anything  in  the  chart  file  before  or after the (first) \begin{chart} ... \end{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
       not preserved and may interfere with command parsing.

       From  version 5.6, prerex no longer supports the latex -> dvips -> ps2pdf toolchain as  an
       option.

AUTHOR

       R. D. Tennent (rdt@cs.queensu.ca)

DEPENDENCIES

       prerex uses the  GNU readline(3) and history(3) libraries.