summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/metapost/slideshow/slideshow.txt
blob: 539b8c32a4ec1480ae2442ece2938bea52e2b063 (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
Making pdf slides with metapost and ghostscript

Patrick McPhee

Introduction

slideshow is a small macro package which simplifies the process of
creating slide-show style presentations using plain metapost and
ghostscript. The package assists in producing slides with dimensions
6.4 inches wide by 4.8 inches high, which the user is then expected to
convert into a pdf file using ghostscript as a PS distiller.

This is probably not the best way of producing presentations, but it's
put forward for interest's sake. I do not intend to formally support
this package, however I will accept bug reports at ptjm@interlog.com,
and will endeavour to fix incompatibilities with tremendously useful
metapost packages such as metaobj.

Usage

Simply inputing slideshow.mp has several effects:
  - each slide is given a default background which is a hundred-step
    gradient from fairly-dark blue to medium-dark blue;
  - the default font is changed to helvetica 8r;
  - prologues is set to 2;
  - a list of figures suitable for passing as an input file to ghostscript
    is written to a file called `jobname'.ps;
  - pdfmarks are written which cause the pdf file to automatically go
    into full-screen mode, have a random transition pattern with
    duration of .5 seconds between each page, crop the pages to 6.4 by
    4.8 inches, and set the creation date and creator in the pdf info
    dictionary;
  - several macros and variables are defined, which might conflict with
    other packages. They should all be documented in this report.

After creating all the metapost figures, run the file `jobname'.ps
through ghostscript, using the pdfwrite device. ghostscript comes with a
batch file called ps2pdf which can be used to do this, but a sufficient
command line is:
   gs -sDEVICE=pdfwrite -sOutputfile=jobname.pdf -dNOPAUSE jobname.ps quit.ps

other parameters are possible. I've noticed smaller pdf files are
generated by specifying a high resolution and a corresponding geometry
(e.g., adding the flags -r10000 -g64000x48000 generates a smaller file
than the above).

The macros defined by slideshow provide support for 
  - storing author and document information in the PDF info directory;
  - automatically generating new figure numbers;
  - automatically saving and restoring the contents of the previous
    figure, to allow slides to be built up, step-by-step;
  - maintaining a vertical list of bullet points;
  - drawing labels and bullets in yellow, after the default style of the
    leading presentation graphics package;
  - wrapping long text to fit within boundaries;
  - adding hyperlinks within the presentation.

Reference

This section is intended to be a complete reference to all the macros
and variables defined or changed by slideshow. If naming conflicts
arise between this and truly useful macro packages, I will likely
change some or all of these names to use a common prefix.

 Document information

 The document information macros add entries to the PDF docinfo
 dictionary. Except for copyright, these can be seen in the acrobat
 reader document info dialog box, and in equivalent places in other PDF
 viewers.

 These macros should be called once at the start, although they can be
 called more than once (the last call wins) anywhere before the last
 slide is shipped out. They are all optional. Do not include parentheses
 in the arguments.

 author(string)
   sets the /Author entry;
 title(string)
   sets the /Title entry;
 subject(string)
   sets the /Subject entry;
 keywords(string)
   sets the /Keywords entry;
 copyright(string)
   adds a dictionary entry called /Copyright. Copyright is not a standard
   docinfo entry, but non-standard entries are explicitly allowed by the
   language specification, and it seems like a good idea;
 moddate(string)
   overrides the /ModificationDate entry. The format should be
   D:yyyymmddhhmiss+GMTOFFSET, but everything after year is optional,
   and the specification suggests that other formats are just fine, too;
 createdate(string)
   overrides the /CreationDate entry. slideshow.mp always calls createdate
   with the current date as an argument. However, some common metapost
   implementations don't actually return the current date, or you may have
   your own reasons for wanting to override the automatically-generated
   date. The format is the same as for moddate.

 Constants and pseudo constants -- these could be left alone, or set once
                                   once at the start: 

 slideshowversion - internal
   1.0 for this release. The decimal portion will change if the file
   changes in an upwardly compatible manner, and the integer portion will
   change if the file changes in an upwardly incompatible manner (e.g., the
   names of macros change).

 lawidth - number
   the width of the figure. Can be used for positioning or drawing a frame
   without worrying about the actual dimensions. The default is 6.4
   inches. If lawidth is set, it must be set before slideshow.mp is input,
   and laheight must also be set;

 laheight - number
   the height of the figure. The default is 4.8 inches. If laheight is
   set, it must be set before slideshow.mp is input, and lawidth must also
   be set;

 background - picture
   a lawidth by laheight rectangle filled with a blue gradiant. It is
   placed behind the user's figure during endfig processing, after lastpicture
   has been saved. A new background can be set by assigning a picture to
   background (but see also header and footer). This can be done even in
   the midst of a series of continuations.
 
 textcolour - color
   The colour used by the bullet, blabel, header, and footer macros. By
   default, yellow.

 defaultfont - string
   set to phvr8r (helvetica in 8r encoding) rather than the metapost
   default cmr10

 defaultscale - number
   amount of scaling for bullet points. takes mp default of 1

 thick nib - pen
   a relatively thick pen

 thin nib - pen
   a relatively thin pen

 borigin - pair
   The upper left corner of the bounding box for bullet points;

 borigin.in - pair
   The upper left corner of the bounding box for indented bullet points.
   Indented bullet points are generated using bullet.in or bpoint.in;

 blimit - pair
   The lower right corner of the bounding box for all bullet points. It
   could be useful to adjust blimit on the fly, e.g., to make room for a
   figure at the right-hand side of a slide;

 bulletpic - picture
   The picture used as a bullet when displaying bulletted text. The
   default is a right-pointing arrow taken from the Zapf Dingbats font. It
   needs to be reset if textcolour is set;

 baselineskip - number
   distance between lines of text in a multi-line bullet point (default 11 bp)

 parskip - number
   distance between bullet points (default 5 bp)

 parskip.in - number
   distance between indented bullet points (default 1 bp)

 boff - pair
   the offset between the bullet and the corresponding text. The y
   component is normally 0, but could be non-zero if it needed to;

 bpos - number
   current vertical offset from borigin. This is shared by bullets and
   indented bullets. It might be useful to set this rather than using the
   y component of boff;

 bpos.prev - number
   Internal-use variable which saves and restores bpos in continuous mode;

 headerpos - pair
   The location for the slide header. The header is set to the right of
   the headerpos;

 footerpos - pair
   The location for the slide footer. The footer is set to the left of the
   footerpos;

 psfile - string
   The name of a file which will be fed to ghostscript. The default name
   is <jobname>.ps where the metapost input file is <jobname>.mp. If this
   is set, it must be set before the first slide.

 prologues - number
   slideshow sets this to 2

 extra_beginfig
   slideshow adds stuff to extra_beginfig, which might cause conflicts
   with other packages;

 extra_endfig
   slideshow adds stuff to extra_endfig, which might cause conflicts
   with other packages;


 Slide management

 nextfig
   calls beginfig with a figure number one larger than the previous call.
   The advantage of this is that you don't have to keep track of the
   figure numbers;

 lastpicture - picture
   the image of the last slide to be shipped out. This is saved
   automatically at the end of each slide, and restored automatically if
   continuations is set to 1;

 continuations - numeric
   Internal variable used to determine whether continuation mode is on or
   off (1 for on, 0 for off). This should not be manipulated directly -- use
   the continue, endcontinue, and discontinue macros instead;

 docontinue - macro
   overlays currentpicture with lastpicture. This is called automatically
   by extra_beginfig, and has effect only if continuations is 1;

 continue - macro
   sets continuations to 1. This causes lastpicture to be assigned to each
   new slide automatically, which allows slides to be built up
   incrementally without repeating the previous part of the definition;

 discontinue - macro
   suspends continuation for the next slide

 endcontinue - macro
   sets continuations to 0. This stops lastpicture being assigned to each
   new slide, and is the default behaviour;
                   
 Useful macros and variables for creating individual slides

 drawgradient(colour1, colour2)
   fills a rectangle lawidth by laheight with a hundred-step gradient from
   colour1 at the top to colour2 at the bottom. This is used to assign a
   gradient to background, for that oh-so-professional look;

 bullet(string or picture)
   Adjusts bpos down by parskip (unless there are no bullets on the
   slide), then adds a bullet point to the current picture at (borigin -
   (0, bpos)). If the argument is a string, it will be roughly broken into
   line fragments up to xpart blimit - xpart borigin lines long, and
   printed in defaultfont scaled defaultscale, with colour textcolour. If
   the bullet doesn't fit on the current slide, a new slide will be
   started with only that bullet point on the background. The formatted
   argument is offset from the bulletpic by boff;

 bullet.in(string or picture)
   the same as bullet, but using borigin.in instead of borigin, and
   parskip.in instead of parskip. Additional bullet types bullet.<tag> can be added by
   defining a pair called borigin.<tag> and a numeric called
   parskip.<tag>. Note that bpos is shared by all bullets, so it may have
   to be manipulated to get the desired effect;

 bpoint(string or picture)
   creates a single-bullet figure (useful in continuation mode);

 bpoint.in(string or picture)
   creates a single-indented-bullet figure;

 blabel(string or picture, pair)
   as label, but withcolor textcolour. blable.rt et al also work

 dotblabel(text or picture, pair)
   as blabel, but with a dot. dotblabel.lft et al also work

 breaktowidth(string, numeric)(height) -> picture
   Sets the string infont defaultfont scaled defaultscale. If the string
   is wider than the numeric argument, breaks it on spaces using the naive
   algorithm (i.e, add characters to a picture until it's too wide, then
   break at the most recent space). height should be passed the name of a
   numeric variable, which will be set to the height of the figure less
   baselineskip. Each line of text is set baselineskip apart.

 headerpic - picture
   If this is set, it is automatically drawn on each figure after the
   lastpicture has been saved, but before the figure is shipped out. The
   headerpic is not shifted before being drawn;

 footerpic - picture
   If this is set, it is automatically drawn on each figure after the
   lastpicture has been saved, but before the figure is shipped out. The
   footerpicis not shifted before being drawn;

 header(string or picture)
   assigns a value to headerpic. If the argument is a string, it is set in
   defaultfont scaled defaultscale * magstep 1 and positioned with its
   lower-left corner at headerpos. header and footer can be called at any
   time, and the macro will take effect the next time a figure is shipped
   out;
                                   
 footer(string or picture)
   assigns a value to headerpic. If the argument is a string, it is set in
   defaultfont scaled defaultscale and positioned with its lower-right
   corner at footerpos;
 
 drawheader
   called internally to draw headerpic

 drawfooter
   called internally to draw footerpic

 folio -> string
   expands to a string with the current figure number

 encodefont(string, string)
   The first string is the tfm-file name and the second is the postscript
   font name. The macro defines a new font which is encoded using the 8r
   encoding. This is necessary if you want to use most characters outside
   the normal ascii range. If you look at the top of a metapost output
   file which was generated with prologues=2, you'll see something like
   this:
     /phvr8r /Helvetica def
   to re-encode the font, put
     encodefont("phvr8r", "Helvetica");
   before the first figure.

   To use encodefont, you must set prologues to 0, and you must copy
   the definitions for fshow and all other fonts (by default, pzdr)
   using specials. Alternately, if 8r encoding is needed for only one
   slide, you could use encodefont only for that figure.

 Hyperlinking

 hyperbullet(string or picture, string)
   as bullet, but defines a pdfmark to link to a destination with the same
   name as the second argument. The link boundary is the bounding box.
   There is no border drawn;

 hyperlabel(string or picture, pair, string)
   as blabel, but defines a pdfmark to link to a destination with the
   same name as the second argument. The link boundary is the bounding
   box. There is no border drawn;

 hyperdest(string)
   labels the current page for hyperlinks using the name given as the
   argument.

 dolink(path or picture, string)
   creates a hyperlink with the boundary being the bounding box of
   the first argument, and the destination named in the second argument.
   Does not draw anything, so it can be used to put a link which
   isn't strictly related to drawing elements.

Additional notes

In addition to document info pdfmarks generated in response to the
author, title, subject, keywords, and copyright macros, slideshow
automatically generates pdfmarks which automatically put the pdf file in
full-screen mode, and which set the transition for each page to random
with a duration of .5 seconds.

I use 6.4x4.8 inches for the dimensions because this matches the
proportions of a PC screen.

Metapost and ghostscript generally require some configuration. If you
use the computer modern fonts (e.g., in a btex ... etex section for math),
you need to obtain PS versions of these fonts and configure both dvips
and ghostscript to use them. dvips has a file called psfonts.map, which
maps TeX font metric file names to postscript font names and font files.
dvips can look in other places for mapping information, and many
installations will have a separate file called bsr.map. So far as I can
tell, metapost always uses psfonts.map from the dvips configuration.
The contents of bsr.map must be added to psfonts.map for the CM fonts
to work. Similarly, ghostscript has a file called Fontmap which contains
equivalent mappings. There is a Fontmap-format file for the CM fonts
on CTAN, which should be copied to the ghostscript lib directory. The
ghostscript Fontmap file should be edited and the line

  (Fontmap.BSR) .runlibfile

added to the end (Fontmap.BSR might not be the name of the file on CTAN
-- please use the correct file name instead). Once this configuration
change is made, everything should work well.

Example

Here's an example, which draws a triangle and puts text at each corner,
then links back to the start so we can see it happen again:

 input slideshow;
 pair points[];
 nextfig;
   points0 = (.5lawidth, .9laheight);
   ypart points1 = ypart points2 = .1laheight;
   xpart points1 = lawidth - xpart points2 = .3lawidth;

   pickup thin nib;

   draw points1..points0 withcolor textcolour;
   hyperdest("start");
 endfig;
 
 % build on previous slide for next few
 continue;
 nextfig;
   pickup thin nib;

   draw points0..points2 withcolor textcolour;
 endfig;
 nextfig;
   pickup thin nib;

   draw points2..points1 withcolor textcolour;
 endfig;

 nextfig;
   blabel.top("A", points0);
 endfig;
 nextfig;
   blabel.lft("B", points1);
 endfig;
 nextfig;
   blabel.rt("C", points2);
 endfig;

 % new sequence of slides ...
 discontinue;
 nextfig;
   hyperlabel("The End" infont defaultfont scaled magstep 2, (.5lawidth, .5laheight), "start");
 endfig;
 end