Debian Codegraph @

texmf-dist/doc/metapost/slideshow/slideshow.txt

raw
1 Making pdf slides with metapost and ghostscript
2
3 Patrick McPhee
4
5 Introduction
6
7 slideshow is a small macro package which simplifies the process of
8 creating slide-show style presentations using plain metapost and
9 ghostscript. The package assists in producing slides with dimensions
10 6.4 inches wide by 4.8 inches high, which the user is then expected to
11 convert into a pdf file using ghostscript as a PS distiller.
12
13 This is probably not the best way of producing presentations, but it's
14 put forward for interest's sake. I do not intend to formally support
15 this package, however I will accept bug reports at [email protected],
16 and will endeavour to fix incompatibilities with tremendously useful
17 metapost packages such as metaobj.
18
19 Usage
20
21 Simply inputing slideshow.mp has several effects:
22 - each slide is given a default background which is a hundred-step
23 gradient from fairly-dark blue to medium-dark blue;
24 - the default font is changed to helvetica 8r;
25 - prologues is set to 2;
26 - a list of figures suitable for passing as an input file to ghostscript
27 is written to a file called `jobname'.ps;
28 - pdfmarks are written which cause the pdf file to automatically go
29 into full-screen mode, have a random transition pattern with
30 duration of .5 seconds between each page, crop the pages to 6.4 by
31 4.8 inches, and set the creation date and creator in the pdf info
32 dictionary;
33 - several macros and variables are defined, which might conflict with
34 other packages. They should all be documented in this report.
35
36 After creating all the metapost figures, run the file `jobname'.ps
37 through ghostscript, using the pdfwrite device. ghostscript comes with a
38 batch file called ps2pdf which can be used to do this, but a sufficient
39 command line is:
40 gs -sDEVICE=pdfwrite -sOutputfile=jobname.pdf -dNOPAUSE jobname.ps quit.ps
41
42 other parameters are possible. I've noticed smaller pdf files are
43 generated by specifying a high resolution and a corresponding geometry
44 (e.g., adding the flags -r10000 -g64000x48000 generates a smaller file
45 than the above).
46
47 The macros defined by slideshow provide support for
48 - storing author and document information in the PDF info directory;
49 - automatically generating new figure numbers;
50 - automatically saving and restoring the contents of the previous
51 figure, to allow slides to be built up, step-by-step;
52 - maintaining a vertical list of bullet points;
53 - drawing labels and bullets in yellow, after the default style of the
54 leading presentation graphics package;
55 - wrapping long text to fit within boundaries;
56 - adding hyperlinks within the presentation.
57
58 Reference
59
60 This section is intended to be a complete reference to all the macros
61 and variables defined or changed by slideshow. If naming conflicts
62 arise between this and truly useful macro packages, I will likely
63 change some or all of these names to use a common prefix.
64
65 Document information
66
67 The document information macros add entries to the PDF docinfo
68 dictionary. Except for copyright, these can be seen in the acrobat
69 reader document info dialog box, and in equivalent places in other PDF
70 viewers.
71
72 These macros should be called once at the start, although they can be
73 called more than once (the last call wins) anywhere before the last
74 slide is shipped out. They are all optional. Do not include parentheses
75 in the arguments.
76
77 author(string)
78 sets the /Author entry;
79 title(string)
80 sets the /Title entry;
81 subject(string)
82 sets the /Subject entry;
83 keywords(string)
84 sets the /Keywords entry;
85 copyright(string)
86 adds a dictionary entry called /Copyright. Copyright is not a standard
87 docinfo entry, but non-standard entries are explicitly allowed by the
88 language specification, and it seems like a good idea;
89 moddate(string)
90 overrides the /ModificationDate entry. The format should be
91 D:yyyymmddhhmiss+GMTOFFSET, but everything after year is optional,
92 and the specification suggests that other formats are just fine, too;
93 createdate(string)
94 overrides the /CreationDate entry. slideshow.mp always calls createdate
95 with the current date as an argument. However, some common metapost
96 implementations don't actually return the current date, or you may have
97 your own reasons for wanting to override the automatically-generated
98 date. The format is the same as for moddate.
99
100 Constants and pseudo constants -- these could be left alone, or set once
101 once at the start:
102
103 slideshowversion - internal
104 1.0 for this release. The decimal portion will change if the file
105 changes in an upwardly compatible manner, and the integer portion will
106 change if the file changes in an upwardly incompatible manner (e.g., the
107 names of macros change).
108
109 lawidth - number
110 the width of the figure. Can be used for positioning or drawing a frame
111 without worrying about the actual dimensions. The default is 6.4
112 inches. If lawidth is set, it must be set before slideshow.mp is input,
113 and laheight must also be set;
114
115 laheight - number
116 the height of the figure. The default is 4.8 inches. If laheight is
117 set, it must be set before slideshow.mp is input, and lawidth must also
118 be set;
119
120 background - picture
121 a lawidth by laheight rectangle filled with a blue gradiant. It is
122 placed behind the user's figure during endfig processing, after lastpicture
123 has been saved. A new background can be set by assigning a picture to
124 background (but see also header and footer). This can be done even in
125 the midst of a series of continuations.
126
127 textcolour - color
128 The colour used by the bullet, blabel, header, and footer macros. By
129 default, yellow.
130
131 defaultfont - string
132 set to phvr8r (helvetica in 8r encoding) rather than the metapost
133 default cmr10
134
135 defaultscale - number
136 amount of scaling for bullet points. takes mp default of 1
137
138 thick nib - pen
139 a relatively thick pen
140
141 thin nib - pen
142 a relatively thin pen
143
144 borigin - pair
145 The upper left corner of the bounding box for bullet points;
146
147 borigin.in - pair
148 The upper left corner of the bounding box for indented bullet points.
149 Indented bullet points are generated using bullet.in or bpoint.in;
150
151 blimit - pair
152 The lower right corner of the bounding box for all bullet points. It
153 could be useful to adjust blimit on the fly, e.g., to make room for a
154 figure at the right-hand side of a slide;
155
156 bulletpic - picture
157 The picture used as a bullet when displaying bulletted text. The
158 default is a right-pointing arrow taken from the Zapf Dingbats font. It
159 needs to be reset if textcolour is set;
160
161 baselineskip - number
162 distance between lines of text in a multi-line bullet point (default 11 bp)
163
164 parskip - number
165 distance between bullet points (default 5 bp)
166
167 parskip.in - number
168 distance between indented bullet points (default 1 bp)
169
170 boff - pair
171 the offset between the bullet and the corresponding text. The y
172 component is normally 0, but could be non-zero if it needed to;
173
174 bpos - number
175 current vertical offset from borigin. This is shared by bullets and
176 indented bullets. It might be useful to set this rather than using the
177 y component of boff;
178
179 bpos.prev - number
180 Internal-use variable which saves and restores bpos in continuous mode;
181
182 headerpos - pair
183 The location for the slide header. The header is set to the right of
184 the headerpos;
185
186 footerpos - pair
187 The location for the slide footer. The footer is set to the left of the
188 footerpos;
189
190 psfile - string
191 The name of a file which will be fed to ghostscript. The default name
192 is <jobname>.ps where the metapost input file is <jobname>.mp. If this
193 is set, it must be set before the first slide.
194
195 prologues - number
196 slideshow sets this to 2
197
198 extra_beginfig
199 slideshow adds stuff to extra_beginfig, which might cause conflicts
200 with other packages;
201
202 extra_endfig
203 slideshow adds stuff to extra_endfig, which might cause conflicts
204 with other packages;
205
206
207 Slide management
208
209 nextfig
210 calls beginfig with a figure number one larger than the previous call.
211 The advantage of this is that you don't have to keep track of the
212 figure numbers;
213
214 lastpicture - picture
215 the image of the last slide to be shipped out. This is saved
216 automatically at the end of each slide, and restored automatically if
217 continuations is set to 1;
218
219 continuations - numeric
220 Internal variable used to determine whether continuation mode is on or
221 off (1 for on, 0 for off). This should not be manipulated directly -- use
222 the continue, endcontinue, and discontinue macros instead;
223
224 docontinue - macro
225 overlays currentpicture with lastpicture. This is called automatically
226 by extra_beginfig, and has effect only if continuations is 1;
227
228 continue - macro
229 sets continuations to 1. This causes lastpicture to be assigned to each
230 new slide automatically, which allows slides to be built up
231 incrementally without repeating the previous part of the definition;
232
233 discontinue - macro
234 suspends continuation for the next slide
235
236 endcontinue - macro
237 sets continuations to 0. This stops lastpicture being assigned to each
238 new slide, and is the default behaviour;
239
240 Useful macros and variables for creating individual slides
241
242 drawgradient(colour1, colour2)
243 fills a rectangle lawidth by laheight with a hundred-step gradient from
244 colour1 at the top to colour2 at the bottom. This is used to assign a
245 gradient to background, for that oh-so-professional look;
246
247 bullet(string or picture)
248 Adjusts bpos down by parskip (unless there are no bullets on the
249 slide), then adds a bullet point to the current picture at (borigin -
250 (0, bpos)). If the argument is a string, it will be roughly broken into
251 line fragments up to xpart blimit - xpart borigin lines long, and
252 printed in defaultfont scaled defaultscale, with colour textcolour. If
253 the bullet doesn't fit on the current slide, a new slide will be
254 started with only that bullet point on the background. The formatted
255 argument is offset from the bulletpic by boff;
256
257 bullet.in(string or picture)
258 the same as bullet, but using borigin.in instead of borigin, and
259 parskip.in instead of parskip. Additional bullet types bullet.<tag> can be added by
260 defining a pair called borigin.<tag> and a numeric called
261 parskip.<tag>. Note that bpos is shared by all bullets, so it may have
262 to be manipulated to get the desired effect;
263
264 bpoint(string or picture)
265 creates a single-bullet figure (useful in continuation mode);
266
267 bpoint.in(string or picture)
268 creates a single-indented-bullet figure;
269
270 blabel(string or picture, pair)
271 as label, but withcolor textcolour. blable.rt et al also work
272
273 dotblabel(text or picture, pair)
274 as blabel, but with a dot. dotblabel.lft et al also work
275
276 breaktowidth(string, numeric)(height) -> picture
277 Sets the string infont defaultfont scaled defaultscale. If the string
278 is wider than the numeric argument, breaks it on spaces using the naive
279 algorithm (i.e, add characters to a picture until it's too wide, then
280 break at the most recent space). height should be passed the name of a
281 numeric variable, which will be set to the height of the figure less
282 baselineskip. Each line of text is set baselineskip apart.
283
284 headerpic - picture
285 If this is set, it is automatically drawn on each figure after the
286 lastpicture has been saved, but before the figure is shipped out. The
287 headerpic is not shifted before being drawn;
288
289 footerpic - picture
290 If this is set, it is automatically drawn on each figure after the
291 lastpicture has been saved, but before the figure is shipped out. The
292 footerpicis not shifted before being drawn;
293
294 header(string or picture)
295 assigns a value to headerpic. If the argument is a string, it is set in
296 defaultfont scaled defaultscale * magstep 1 and positioned with its
297 lower-left corner at headerpos. header and footer can be called at any
298 time, and the macro will take effect the next time a figure is shipped
299 out;
300
301 footer(string or picture)
302 assigns a value to headerpic. If the argument is a string, it is set in
303 defaultfont scaled defaultscale and positioned with its lower-right
304 corner at footerpos;
305
306 drawheader
307 called internally to draw headerpic
308
309 drawfooter
310 called internally to draw footerpic
311
312 folio -> string
313 expands to a string with the current figure number
314
315 encodefont(string, string)
316 The first string is the tfm-file name and the second is the postscript
317 font name. The macro defines a new font which is encoded using the 8r
318 encoding. This is necessary if you want to use most characters outside
319 the normal ascii range. If you look at the top of a metapost output
320 file which was generated with prologues=2, you'll see something like
321 this:
322 /phvr8r /Helvetica def
323 to re-encode the font, put
324 encodefont("phvr8r", "Helvetica");
325 before the first figure.
326
327 To use encodefont, you must set prologues to 0, and you must copy
328 the definitions for fshow and all other fonts (by default, pzdr)
329 using specials. Alternately, if 8r encoding is needed for only one
330 slide, you could use encodefont only for that figure.
331
332 Hyperlinking
333
334 hyperbullet(string or picture, string)
335 as bullet, but defines a pdfmark to link to a destination with the same
336 name as the second argument. The link boundary is the bounding box.
337 There is no border drawn;
338
339 hyperlabel(string or picture, pair, string)
340 as blabel, but defines a pdfmark to link to a destination with the
341 same name as the second argument. The link boundary is the bounding
342 box. There is no border drawn;
343
344 hyperdest(string)
345 labels the current page for hyperlinks using the name given as the
346 argument.
347
348 dolink(path or picture, string)
349 creates a hyperlink with the boundary being the bounding box of
350 the first argument, and the destination named in the second argument.
351 Does not draw anything, so it can be used to put a link which
352 isn't strictly related to drawing elements.
353
354 Additional notes
355
356 In addition to document info pdfmarks generated in response to the
357 author, title, subject, keywords, and copyright macros, slideshow
358 automatically generates pdfmarks which automatically put the pdf file in
359 full-screen mode, and which set the transition for each page to random
360 with a duration of .5 seconds.
361
362 I use 6.4x4.8 inches for the dimensions because this matches the
363 proportions of a PC screen.
364
365 Metapost and ghostscript generally require some configuration. If you
366 use the computer modern fonts (e.g., in a btex ... etex section for math),
367 you need to obtain PS versions of these fonts and configure both dvips
368 and ghostscript to use them. dvips has a file called psfonts.map, which
369 maps TeX font metric file names to postscript font names and font files.
370 dvips can look in other places for mapping information, and many
371 installations will have a separate file called bsr.map. So far as I can
372 tell, metapost always uses psfonts.map from the dvips configuration.
373 The contents of bsr.map must be added to psfonts.map for the CM fonts
374 to work. Similarly, ghostscript has a file called Fontmap which contains
375 equivalent mappings. There is a Fontmap-format file for the CM fonts
376 on CTAN, which should be copied to the ghostscript lib directory. The
377 ghostscript Fontmap file should be edited and the line
378
379 (Fontmap.BSR) .runlibfile
380
381 added to the end (Fontmap.BSR might not be the name of the file on CTAN
382 -- please use the correct file name instead). Once this configuration
383 change is made, everything should work well.
384
385 Example
386
387 Here's an example, which draws a triangle and puts text at each corner,
388 then links back to the start so we can see it happen again:
389
390 input slideshow;
391 pair points[];
392 nextfig;
393 points0 = (.5lawidth, .9laheight);
394 ypart points1 = ypart points2 = .1laheight;
395 xpart points1 = lawidth - xpart points2 = .3lawidth;
396
397 pickup thin nib;
398
399 draw points1..points0 withcolor textcolour;
400 hyperdest("start");
401 endfig;
402
403 % build on previous slide for next few
404 continue;
405 nextfig;
406 pickup thin nib;
407
408 draw points0..points2 withcolor textcolour;
409 endfig;
410 nextfig;
411 pickup thin nib;
412
413 draw points2..points1 withcolor textcolour;
414 endfig;
415
416 nextfig;
417 blabel.top("A", points0);
418 endfig;
419 nextfig;
420 blabel.lft("B", points1);
421 endfig;
422 nextfig;
423 blabel.rt("C", points2);
424 endfig;
425
426 % new sequence of slides ...
427 discontinue;
428 nextfig;
429 hyperlabel("The End" infont defaultfont scaled magstep 2, (.5lawidth, .5laheight), "start");
430 endfig;
431 end