summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/prerex/prerex.sty.7
blob: d71cf77aeeec15b066f58e7ce0d406f1c4615a0d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
.TH PREREX.STY 7 2014-02-28 "prerex.sty-6.4" ""
.SH NAME
prerex.sty  \- a LaTeX document style for prerequisite charts 
.SH DESCRIPTION
.B prerex.sty
defines macros that 
.B [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 
.B [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. 
.P
If the source file satisfies the constraints
of the
.BR prerex (5)
format, a chart description may be edited using the
.BR prerex (1)
interactive editor (as well as any conventional text 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 
or
.I optional
(or neither).
Each course box can contain a course
.I code
(upper left corner),
a course 
.I title
(lower half),
and
.I timetable
information
(upper right corner).
An arrow can be either a
.I prerequisite 
(solid),
a
.I corequisite 
(dotted),
or 
.I recommended
(dashed).
When a conventional arrow would be inappropriate, it is possible to use
a
.I 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.
.SH COORDINATE SYSTEM
A conventional two-dimensional
Cartesian 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.
The diagram height is configurable; the width is determined by
the values of
.I \etextwidth
and
an adjustable
.I \eunit
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
.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
The command
.B \eusepackage{prerex}
should appear in the document preamble.
This will define a LaTeX environment 
.IP
.BI \ebegin{chart} " ... " \eend{chart}
.LP
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 
.I precede
the command for the arrow. 
.SH COURSE BOXES
The commands producing course boxes have the following forms:
.IP 
.BI \ehalfcourse " x,y" :{ code }{ title }{ timetable }
.IP
.BI \efullcourse " x,y" :{ code }{ title }{ timetable }
.IP
.BI \ereqhalfcourse " x,y" :{ code }{ title }{ timetable }
.IP
.BI \ereqfullcourse " x,y" :{ code }{ title }{ timetable }
.IP
.BI \eopthalfcourse " x,y" :{ code }{ title }{ timetable }
.IP
.BI \eoptfullcourse " x,y" :{ code }{ title }{ timetable }
.LP
where
.I x,y
are the coordinates of the 
.I centerpoint 
of the box, relative to the origin
of the coordinate system at the lower-left corner of the diagram.
The 
.I code,
.I title,
and
.I 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:
.IP 
.BI \ehalfcoursec " x,y" :{ code }{ title }{ timetable }{ color }
.IP
.BI \efullcoursec " x,y" :{ code }{ title }{ timetable }{ color }
.IP
.BI \ereqhalfcoursec " x,y" :{ code }{ title }{ timetable }{ color }
.IP
.BI \ereqfullcoursec " x,y" :{ code }{ title }{ timetable }{ color }
.IP
.BI \eopthalfcoursec " x,y" :{ code }{ title }{ timetable }{ color }
.IP
.BI \eoptfullcoursec " x,y" :{ code }{ title }{ timetable }{ color }
.LP
.SH MINI COURSE BOXES AND TEXT LINES
A mini course "box" is produced by a command of the form
.IP 
.BI \emini " x,y" :{ code }
.LP
The following instruction places a line of text centered at the coordinates:
.IP
.BI \etext " x,y" :{ text-line } 
.LP
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
.B \eparbox 
command
may be used in the 
.I text-line 
argument if more than one line is desired.
.SH ARROWS
Arrows between course boxes (or from a mini or text-line to a course box) are produced
by commands of the form
.IP
.BI \eprereq " x0,y0,x1,y1" :
.IP
.BI \ecoreq " x0,y0,x1,y1" :
.IP
.BI \erecomm " x0,y0,x1,y1" :
.LP
These produce, respectively, solid, dotted, and dashed arrows from
the course box (or mini or text-line) centered at coordinates
.I x0,y0
to the course box centered at coordinates
.I x1,y1.
.PP
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
.IP
.BI \eprereqc " x0,y0,x1,y1;c" :
.IP
.BI \ecoreqc " x0,y0,x1,y1;c" :
.IP
.BI \erecommc " x0,y0,x1,y1;c" :
.LP
where
.I c
is an integer in the range 0-100 specifying the desired curvature; for example, 
.IR c= 0
will produce a 
.I straight 
arrow. To change the default curvature, the user program may redefine the
.B \eDefaultCurvature
command.
.SH WEB LINKS
Course boxes (including minis) may be hyperlinked.
The default URL for course boxes is 
.IR course-code .html
where
.I course-code
is
the 
.I code
argument
of the course box. The URL scheme may be changed by the user 
by re-defining the 
.B   \eCourseURL
command.
.SH COORDINATE GRID
The following command produces a coordinate grid, which is
useful for editing a diagram: 
.IP
.B \egrid 
.LP
The grid lines will be covered by course boxes and arrows.
The 
.B \egrid 
command
also redefines the 
.B \eCourseURL 
command 
so that,
if the mouse cursor is placed over a box or mini in (some) PDF viewers,
the 
.I coordinates
of the box, mini, or text-line will be displayed 
as follows: 
in the status bar in
.BR xpdf 
and
.BR gpdf ,
and in a "tooltip" in recent versions of
.BR kpdf " (now re-named"
.BR okular ),
.BR 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".
.PP
The 
.B prerex
package at 
.B http://mirror.ctan.org/graphics/prerex/
has a patch for 
.BR 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 
.BR prerex (1)
prompt).  There is also a GUI frontend 
.BR vprerex (1)
to the
.BR prerex (1)
editor which incorporates a minimalistic prerex-enabled PDF viewer.
.SH STAND-ALONE COMMANDS
The following commands may be used outside a 
.B chart
environment, such as in the explanatory notes for a chart:
.IP
.B \esolidarrow
.IP
.B \edottedarrow
.IP
.B \edashedarrow
.IP
.B \elightbox
.IP
.B \eboldbox
.IP
.B \edashedbox
.LP
.SH CONFIGURATION 
The following are defined by the style file but may be re-defined by the
user:
.IP
.BI   \enewcommand{\eDefaultCurvature}{ 20 }    
.LP
where the argument should be in the range 0-100; 0 means no curvature.
.IP
.BI   \enewcommand{\eCourseURL}[3]{ #3.html }
.LP
where the arguments supplied at the call are the
.I x
and
.I y
coordinates of the box or mini and the course code.
.IP
.BI   \enewcommand{\ebackground}{ LightYellow }
.LP
where 
.I LightYellow 
is defined by 
.IP
.BI       \edefinecolor{LightYellow}{ rgb }{ "1.0, 1.0, 0.878431" }
.IP
.BI   \esetlength{\eunit}{ 5.7816pt } 
.LP
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.
.IP
.BI   \enewcommand{\edpi}{ 125 }  
.IP
.BI   \enewcommand{\ePixelsPerUnit}{ 10 }  
.LP
These must be re-defined together if the image-map data are to be correct.
.IP
.BI   \esetcounter{diagheight}{ 75 }  
.LP
which is the 
.IR y -coordinate
of the top of the diagram (reduced to 65 in landscape mode);
the nominal diagram width is 
.IR \etextwidth " / " \eunit " + " 10.
.P
The following define the thicknesses of the three kinds of arrows,
and the thickness of bold boxes:
.IP
.BI   \enewcommand{\esolidwidth}{ 0.5pt }
.IP
.BI   \enewcommand{\edottedwidth}{ 0.8pt }
.IP
.BI   \enewcommand{\edashedwidth}{ 0.5pt }
.IP
.BI   \enewcommand{\eboldwidth}{ 1.0pt }
.LP
.P
The following command is used to change to a smaller size for course codes,
timetable information, and mini-course codes:
.IP
.BI   \enewcommand{\esmallersize}{\erelsize{-3}}
.LP
.P
The following command defines the baseline adjustment for the stand-alone arrows and boxes;
this parameter is font-dependent.
.IP
.BI   \enewcommand{\ebaselineAdj}{ -0.5ex }
.LP
.SH DEPEDENCIES
This implementation of 
.B prerex.sty
uses 
.B pgf
(version 1.18 or later)
with add-on package
.B tikz.
The following additional packages are used:
.B relsize,
.B calc,
.B ifpdf,
.B multido,
.B textcomp,
.B zref-savepos
and 
.B hyperref.
.I Either 
.BR pdflatex (1)
.I or
.BR latex (1)
followed by 
.BR dvips (1)
(and possibly
.BR ps2pdf (1))
may be used.
.P
To convert a chart to a compact but reasonably high-quality image, it is suggested to use the
.BR convert (1)
tool of 
.BR ImageMagick (1)
as follows:
.IP
.B convert 
.I -density 125 chart.ps chart.png
.LP
or
.IP
.B convert 
.I -density 125 chart.pdf chart.png
.LP
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 
.B prerex.sty
crops the image at the southeast corner.
It is possible to use a PNG compression application such as
.BR optipng (1) 
to reduce the file-size of the cropped image (without loss of quality).

.SH  IMPLEMENTATION DETAILS
.P
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. 
.P
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.
.P
When the coordinate grid is drawn, the 
.B 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.
.P
To support HTML versions of charts,
.B 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 
.B zsavepos, 
.B zposx
and 
.B zposy 
commands are used; the page coordinates are converted into pixel coordinates
for cropping and image-map use.
.SH LICENSE
.B prerex.sty
and this document may be distributed and/or modified under the
conditions of the LaTeX Project Public License.
.SH AUTHOR
R. D. Tennent (rdt@cs.queensu.ca)
.SH SEE ALSO
.BR ImageMagick (1),
.BR convert (1).
.BR dvips (1),
.BR evince (1), 
.BR gpdf (1),
.BR kpdf (1),
.BR latex (1),
.BR okular (1),
.BR optipng (1),
.BR pdflatex (1),
.BR prerex (1),
.BR prerex (5),
.BR ps2pdf (1),
.BR tikz (1),
.BR tgf (1),
.BR vprerex (1),
and
.BR xpdf (1).