path: root/Master/texmf-dist/doc/metapost/slideshow/slideshow.txt

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