NAME¶
prerex.sty - a LaTeX document style for prerequisite charts
DESCRIPTION¶
prerex.sty defines macros that
[pdf]latex can use to draw charts
consisting of labelled course boxes linked by arrows that represent pre- and
co-requisite requirements. In addition to the usual
[pdf]latex output,
auxiliary files will be generated containing image-map data for the
hyperlinked nodes in the diagram and a shell script to crop a PNG image
generated from a Postscript or PDF chart.
If the source file satisfies the constraints of the
prerex(5) format, a
chart description may be edited using the
prerex(1) interactive editor
(as well as any conventional text editor).
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 can contain a
course
code (upper left corner), a course
title (lower half),
and
timetable information (upper right corner). An arrow can be either
a
prerequisite (solid), a
corequisite (dotted), or
recommended (dashed). When a conventional arrow would be inappropriate,
it is possible to use a
mini course "box" (consisting of just
a course code) just above a target box. An arbitrary line of text may be
placed anywhere on the chart.
COORDINATE SYSTEM¶
A conventional two-dimensional Cartesian 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. The diagram height is
configurable; the width is determined by the values of
\textwidth and
an adjustable
\unit length, which defines the absolute value of a
coordinate unit. It is possible to put a coordinate grid with labelled axes in
the background of a chart. 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.
USAGE¶
The command
\usepackage{prerex} should appear in the document preamble.
This will define a LaTeX environment
- \begin{chart} ... \end{chart}
within which the following commands may be used to produce course boxes, minis,
text-lines, and arrows. The order of commands is not significant except that
the commands for the source and target boxes of an arrow should
precede
the command for the arrow.
COURSE BOXES¶
The commands producing course boxes have the following forms:
- \halfcourse
x,y:{code}{title}{timetable}
- \fullcourse
x,y:{code}{title}{timetable}
- \reqhalfcourse
x,y:{code}{title}{timetable}
- \reqfullcourse
x,y:{code}{title}{timetable}
- \opthalfcourse
x,y:{code}{title}{timetable}
- \optfullcourse
x,y:{code}{title}{timetable}
where
x,y are the coordinates of the
centerpoint of the box,
relative to the origin of the coordinate system at the lower-left corner of
the diagram. The
code, title, and
timetable arguments are
arbitrary (well-bracketed) text, possibly with LaTeX markup.
The following are similar but take an additional argument to specify the
(non-default) background color of the course box:
- \halfcoursec
x,y:{code}{title}{timetable}{color}
- \fullcoursec
x,y:{code}{title}{timetable}{color}
- \reqhalfcoursec
x,y:{code}{title}{timetable}{color}
- \reqfullcoursec
x,y:{code}{title}{timetable}{color}
- \opthalfcoursec
x,y:{code}{title}{timetable}{color}
- \optfullcoursec
x,y:{code}{title}{timetable}{color}
MINI COURSE BOXES AND TEXT LINES¶
A mini course "box" is produced by a command of the form
- \mini x,y:{code}
The following instruction places a line of text centered at the coordinates:
- \text
x,y:{text-line}
There are several differences between minis and text-lines. The maximum length
allowed for a course-code may be less than that for a text-line. A sans-serif
font and a reduced font size is used for a course-code. A course-code may be
hyperlinked but a text-line is not (except when the coordinate grid is on). A
\parbox command may be used in the
text-line argument if more
than one line is desired.
ARROWS¶
Arrows between course boxes (or from a mini or text-line to a course box) are
produced by commands of the form
- \prereq x0,y0,x1,y1:
- \coreq x0,y0,x1,y1:
- \recomm x0,y0,x1,y1:
These produce, respectively, solid, dotted, and dashed arrows from the course
box (or mini or text-line) centered at coordinates
x0,y0 to the course
box centered at coordinates
x1,y1.
Arrows by default have a non-zero curvature (unless they are very short). It is
possible to override the default curvature for a particular arrow by using the
instructions
- \prereqc x0,y0,x1,y1;c:
- \coreqc x0,y0,x1,y1;c:
- \recommc x0,y0,x1,y1;c:
where
c is an integer in the range 0-100 specifying the desired
curvature; for example,
c=0 will produce a
straight arrow. To
change the default curvature, the user program may redefine the
\DefaultCurvature command.
WEB LINKS¶
Course boxes (including minis) may be hyperlinked. The default URL for course
boxes is
course-code.html where
course-code is the
code
argument of the course box. The URL scheme may be changed by the user by
re-defining the
\CourseURL command.
COORDINATE GRID¶
The following command produces a coordinate grid, which is useful for editing a
diagram:
- \grid
The grid lines will be covered by course boxes and arrows. The
\grid
command also redefines the
\CourseURL command so that, if the mouse
cursor is placed over a box or mini in (some) PDF viewers, the
coordinates of the box, mini, or text-line will be displayed as
follows: in the status bar in
xpdf and
gpdf, and in a
"tooltip" in recent versions of
kpdf (now re-named
okular),
evince, and the Adobe Reader. Similarly, the
coordinates of the source and target boxes of arrows are displayed if the
mouse hovers over the mid-point of an arrow, Such coordinate displays make it
easier to edit chart descriptions. When the grid is on, the mid-point of every
arrow is highlighted by a "bullet".
The
prerex package at
http://www.ctan.org/tex-archive/graphics/prerex/ has a patch for
kpdf/
okular(1) to make it display URIs in tooltips and also
capture coordinates of course boxes, arrows and background points in the X
selection clipboard (for pasting into a command being composed at the
prerex(1) prompt). There is also a GUI frontend
vprerex(1) to
the
prerex(1) editor which incorporates a minimalistic prerex-enabled
PDF viewer.
STAND-ALONE COMMANDS¶
The following commands may be used outside a
chart environment, such as
in the explanatory notes for a chart:
- \solidarrow
- \dottedarrow
- \dashedarrow
- \lightbox
- \boldbox
- \dashedbox
CONFIGURATION¶
The following are defined by the style file but may be re-defined by the user:
- \newcommand{\DefaultCurvature}{20}
where the argument should be in the range 0-100; 0 means no curvature.
- \newcommand{\CourseURL}[3]{#3.html}
where the arguments supplied at the call are the
x and
y
coordinates of the box or mini and the course code.
- \newcommand{\background}{LightYellow}
where
LightYellow is defined by
- \definecolor{LightYellow}{rgb}{1.0,
1.0, 0.878431}
- \setlength{\unit}{5.7816pt}
which defines the absolute size of a coordinate unit; this yields 10 pixels per
coordinate unit if the chart is converted to an image at 125 dpi.
- \newcommand{\dpi}{125}
- \newcommand{\PixelsPerUnit}{10}
These must be re-defined together if the image-map data are to be correct.
- \setcounter{diagheight}{75}
which is the
y-coordinate of the top of the diagram (reduced to 65 in
landscape mode); the nominal diagram width is
\textwidth /
\unit
+
10.
The following define the thicknesses of the three kinds of arrows, and the
thickness of bold boxes:
- \newcommand{\solidwidth}{0.5pt}
- \newcommand{\dottedwidth}{0.8pt}
- \newcommand{\dashedwidth}{0.5pt}
- \newcommand{\boldwidth}{1.0pt}
The following command is used to change to a smaller size for course codes,
timetable information, and mini-course codes:
- \newcommand{\smallersize}{\relsize{-3}}
The following command defines the baseline adjustment for the stand-alone arrows
and boxes; this parameter is font-dependent.
- \newcommand{\baselineAdj}{-0.5ex}
DEPEDENCIES¶
This implementation of
prerex.sty uses
pgf (version 1.18 or later)
with add-on package
tikz. The following additional packages are used:
relsize, calc, ifthen, multido, textcomp,
zref-savepos and
hyperref. Either pdflatex(1)
or latex(1) followed by
dvips(1) (and possibly
ps2pdf(1)) may be used.
To convert a chart to a compact but reasonably high-quality image, it is
suggested to use the
convert(1) tool of
ImageMagick(1) as
follows:
- convert -density 125 chart.ps chart.png
or
- convert -density 125 chart.pdf chart.png
The density parameter specifies the number of pixels per inch; if this is too
small, the image is of poor quality, and if it is too large, the image file is
too big. By default, the shell script generated by
prerex.sty crops the
image at the southeast corner. It is possible to use a PNG compression
application such as
optipng(1) to reduce the file-size of the cropped
image (without loss of quality).
IMPLEMENTATION DETAILS¶
To improve the appearance, boxes are drawn with slightly rounded corners. The
half-course boxes are assigned a minimum height to give a more uniform
appearance to horizontal rows of such boxes. The mini and text boxes have
white frames and their fill colour is white, which is assumed to be the
background colour of the chart. A text box is not normally hyperlinked;
however, if the coordinate grid is on, it is hyperlinked and its chart
coordinates are encoded in the URI.
Arrows with a small height and arrows whose source and target points have equal
x or y coordinates are always draw straight (using a specialized and simpler
macro) unless an explicit non-zero curvature argument is provided. If the
coordinate grid is on, a hyperlink with the source and target coordinates is
placed at the mid-point of the arrow. A wider background white edge is drawn
below an arrow to improve the appearance of crossing arrows; the background
also ensures visibility of the arrow when the coordinate grid is on. A thin
white arrow (with a visible arrowhead) is drawn beneath the visible arrow to
obtain a thin arrowhead.
When the coordinate grid is drawn, the
CourseURL command is re-defined to
pass node coordinates in URIs. Also, two "anchor" hyperlinks are
inserted at the southwest and northeast corners of the diagram to allow
prerex-enabled PDF viewers to compute chart coordinates.
To support HTML versions of charts,
prerex.sty generates a script to crop
a chart image at the southeast corner, allowing descriptive notes below the
chart to be treated as ordinary text. Also, it generates image-map data for
use with an HTML image map. To obtain absolute page coordinates, the
zsavepos, zposx and
zposy commands are used; the page
coordinates are converted into pixel coordinates for cropping and image-map
use.
LICENSE¶
prerex.sty and this document may be distributed and/or modified under the
conditions of the LaTeX Project Public License.
AUTHOR¶
R. D. Tennent (rdt@cs.queensu.ca)
SEE ALSO¶
ImageMagick(1),
convert(1).
dvips(1),
evince(1),
gpdf(1),
kpdf(1),
latex(1),
okular(1),
optipng(1),
pdflatex(1),
prerex(1),
prerex(5),
ps2pdf(1),
tikz(1),
tgf(1),
vprerex(1), and
xpdf(1).