slidedhow doc in metapost (luecking, 23 Jul 2007 13:47:15)

git-svn-id: svn://tug.org/texlive/trunk@5001 c570f23f-e606-0410-a88d-b1316a301751

5 files changed, 431 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/metapost/slideshow/slideshow.txt b/Master/texmf-dist/doc/metapost/slideshow/slideshow.txt
new file mode 100644
index 00000000000..539b8c32a4e
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/slideshow/slideshow.txt
@@ -0,0 +1,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
diff --git a/Master/texmf-dist/doc/metapost/slideshow/sshowex.pdf b/Master/texmf-dist/doc/metapost/slideshow/sshowex.pdf
new file mode 100644
index 00000000000..e9351c39b64
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/slideshow/sshowex.pdf
diff --git a/Master/texmf-dist/doc/metapost/slideshow/sshowex2.pdf b/Master/texmf-dist/doc/metapost/slideshow/sshowex2.pdf
new file mode 100644
index 00000000000..7ae3d578261
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/slideshow/sshowex2.pdf
diff --git a/Master/texmf-dist/doc/metapost/slideshow/sshowex3.pdf b/Master/texmf-dist/doc/metapost/slideshow/sshowex3.pdf
new file mode 100644
index 00000000000..60006b14c12
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/slideshow/sshowex3.pdf
diff --git a/Master/texmf-dist/doc/metapost/slideshow/sshowintro.pdf b/Master/texmf-dist/doc/metapost/slideshow/sshowintro.pdf
new file mode 100644
index 00000000000..6bff15103a7
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/slideshow/sshowintro.pdf