_Slideshow_ Quick Start
=======================

Stand-alone:

 1. Double-click the "Slideshow" executable, or run "slideshow"
    from the command line.

 2. Click the "Tutorial" button.

On in DrScheme:

 1. Open "tutorial-show.ss", which is in the "slideshow" collection.
    
    The path depends on your PLT install directory:
       <plt install dir>/collects/slideshow/tutorial-show.ss

 2. Set DrScheme's language to "(module ...)".
 
    Use the "Choose Language" menu item in the "Language" menu.

 3. Click DrScheme's "Execute" button.


     ---------- !! IMPORTANT SECURITY INFORMATION !! ----------

   Do not run any Slideshow program in DrScheme unless you know the
   creator of the slide program and/or trust the slide
   program. Instead, run untrusted programs with the "Slideshow"
   executable or "slideshow" command-line program.

   A Slideshow program has access to the full PLT Scheme language,
   which means that it can write to files and establish network
   connections (possibly sending your private information elsewhere).

   When you use the "Slideshow" executable or "slideshow" command-line
   program, however, the slide program is prevented from writing to
   the filesystem or creating network connections.


Slideshow Overview
==================

Slideshow is a library for creating presentation slides. Unlike
Powerpoint, Slideshow provides no WYSIWYG interface for constructing
slides. Instead, like SliTeX, a presentation is generated by a
program.

For constructing slide images, Slideshow builds on the "texpict"
collection's utilities for constructing images. More specifically,
all of the functions provided by `(lib "mrpict.ss" "texpict")'
are available for creating images.

In addition to the "mrpict.ss" functions, Slideshow provides functions
for constructing paragraphs and bulleted lists, staging parts of a
slide, managing fonts, viewing the slides, and scaling slides for a
particular display.

For boring text slides, the functions listed in this document are
sufficient to construct slides. More interesting slides --- with
images and diagrams --- require the more general picture-construction
functions in "texpict".

Slideshow Modules
=================

The _slideshow.ss_ module acts as a language that includes:

 - the Slideshow function for creating slides (defined here)
 - all of MzScheme
 - (lib "mrpict.ss" "texpict")
 - (lib "utils.ss" "texpict")

The _slide.ss_ module is like "slideshow.ss", but it does not
re-provide MzScheme. Thus, "slide.ss" is a non-language version of
"slideshow.ss", and it can be imported with `require' into a module in
any language.

The _run.ss_ module is the same as "slideshow.ss" for backward
compatibility.

  [The "slideshow.ss" and "slide.ss" modules also check the MzScheme
   parameter `current-command-line-arguments' to configure the slide
   mode.]

The rest of this section repeats much of the information that is in
"tutorial-show.ss" (see "Quick Start" at the top of this
documentation).

The main Slideshow function is `slide/title', which adds a slide to
the presentation with a given title and content. For example, the
Hello World presentation can be defined by the following module:

 (module hello-world (lib "slideshow.ss" "slideshow")
   (slide/title
    "How to Say Hello"
    (t "Hello World!")))
 
The `t' function creates a pict containing the given text in the
default font and style.

Executing the above module pops up a slide-presentation window. Type
Alt-q (or Meta-q) to end the slides. More controls:

   Alt-q, Meta-q, or Cmd-q             :  end slide show
   Esc                                 :  if confirmed, end show
   Right arrow, Space, f, n, or click  :  next slide
   Left arrow, Backspace, Delete, or b :  previous slide
   g                                   :  last slide
   1                                   :  first slide
   Alt-g, Cmd-g, or Meta-g             :  select a slide
   Alt-p, Cmd-p, or Meta-p             :  show/hide slide number
   Alt-c, Cmd-c, or Meta-c             :  show/hide commentary
   Alt-d, Cmd-d, or Meta-d             :  show/hide preview
   Alt-m, Cmd-m, or Meta-m             :  show/hide mouse cursor
   Shift with arrow                    :  move window 1 pixel
   Alt, Meta, or Cmd with arrow        :  move window 10 pixels

In general, each element after the title string for `slide/title' is a
pict that will be centered on the slide. The picts are stacked
verically and top-aligned, with `gap-size' separation between each
pict.

 (module hello-world (lib "slideshow.ss" "slideshow")
   (slide/title
    "How to Say Hello"
    (t "Hello World!")
    (t "Goodbye Dlrow!")))

The `slide/title/center' form centers the stacked picts vertically
instead of putting them at the top of the slide:

 (module hello-world (lib "slideshow.ss" "slideshow")
   (slide/title/center
    "How to Say Hello"
    (t "Hello World!")
    (t "Goodbye Dlrow!")))

Various functions format paragraphs and generate bullted items for
lists. For example, `item/page' creates a bulleted paragraph that
spaces the width of the slide:

 (module hello-world (lib "slideshow.ss" "slideshow")
   (slide/title
    "How to Say Hello"
    (page-item "If you want to create an example, you"
               "can always do something with" (bt "Hello World!"))
    (page-item "It's a bit silly, but a follow-up example"
               "could be" (bt "Goodbye Dlrow!"))))

In this example, `bt' is like `t', except that it makes the text bold.
The `page-item' function accepts a mixture of strings and picts, and
it formats them as a paragraph.

Staging Slides
==============

The `slide/title' function creates a slide as a side effect. It can be
put inside a function to abstract over a slide:

 (module hello-world (lib "slideshow.ss" "slideshow")
   (define (make-slide-n n)
     (slide/title
      "How to Generalize Slides"
      (page-item "This is slide number" (number->string n))))

   (make-slide-n 1)
   (make-slide-n 2)
   (make-slide-n 3))

The `slide/title' function also has built-in support for some common
multi-slide patterns. Each element argument to `slide/title' after the
title is usually a pict, but there are a few other possibilities:

  * If an element is 'next, then a slide is generated containing only
    the preceeding elements, and then the <elems> are re-processed
    without the 'next. Multiple 'next elements generate multiple slides.

  * If an element is 'alts, then the next element must be a list of
    element lists. Each list up to the last one is appended to the
    elements before 'alts and the resulting list of elements is
    processed. The last lists is appended to the preceeding elements
    along with the remaining elements (after the list of lists) and the
    result is re-processed.

  * A 'nothing element is ignored (useful as a result of a branching
    expression).

  * 'next! is like 'next, except that it is preserved when consensing
    (see below on the --condense flag).

  * 'alts~ is like 'alts, except that it is *not* preserved when
    consensing (see below on the --condense flag).

  * A comment produced by `comment' is ignored, except when commentary
    is displayed.

Here's an example to illustrate how 'next and 'alts work:

 (module multi-step (lib "slideshow.ss" "slideshow")
  (slide/title
   "Example"
   (page-item "First step")
   'NEXT
   (page-item "Second step")
   'NEXT
   'ALTS
   (list (list (page-item "Tentative third step")
               'NEXT
               (page-item "This isn't working... back up"))
         (list (page-item "Third step that works")))
   'NEXT
   (page-item "Fourth step")))

[The code above is case-insensitive; 'NEXT and 'ALTS are capitalized
 merely to stand out.]

Display Size and Fonts
======================

Slideshow is configured for generating slides in 1024x768 pixel
format. When the current display has a different size as Slideshow is
started, the Slideshow display still occupies the entire screen, and
pictures are scaled just before they are displayed. Thus, one picture
unit reliably corresponds to a "pixel" that occupies 1/1024 x 1/768 of
the screen.

The `text' form for generating text pictures takes into account any
expected scaling for the display when measuring text. (All Slideshow
text functions, such as `t' and `page-para', are built on `text'.) In
particular, scaling the picture causes a different font size to be
used for drawing the slide (rather than bitmap-scaling the original
font), and changing the font size by a factor of K does not
necessarily scale all text dimensions equally by a factor of K
(because, for most devices, each character must have integer
dimensions). Nevertheless, using the `current-expected-text-scale'
parameter, Slideshow is usually able to produce good results when the
slide is scaled.

More generally, different font sets on different platforms can change
the way a slide is rendered. For example, the `tt' font on one
platform might be slightly wider than on another, causing different
line breaks, etc. Beware.

Beware also of using bitmaps in slides when the presentation screen
will not be 1024x768. In that case, consider using `size-in-pixels'
(with the caveat that the resulting picture will take up different
amounts of the slide on different displays).

Transition Animations
=====================

Any number of transition actions can be installed after a slide is
created and before the next slide is created. The first animation
applies to the most recently created slide, and during presentation
time, it starts when the next slide is requested; after all animations
complete, the next slide appears immediately.

If the presenter requests the next slide before an animation sequence
completes, Slideshow breaks all animations and continues immediately
to the next slide. Animations are not execute when jumping to a slide
or moving backward through the slide set.

Command-line Options
====================

The _start.ss_ module can be invoked directly, in which case a module
file name should be provided on the command line to provide the slide
content. Setup PLT creates a "Slideshow" executable that runs
"start.ss".

Thus, if the above example is in multi-step.ss, then

   slideshow multi-step.ss

runs the slides.

The "Slideshow" executable accepts a number of command-line flags.
Use the --help flag to obtain a list of other flags.

Printing
========

The -p or --print command-line flag causes slideshow to print slides
instead of showing them on the screen. Under Unix, the result is
always PostScript. For all platforms, -P or --ps generates PostScript.

PS-to-PDF converters vary on how well they handle landscape
mode. Here's a Ghostscript command that converts slides reliably
(replace "src.ps" and "dest.pdf" with your file names, and put the
command all on one line):

  gs -q -dAutoRotatePages=/None -dSAFER -dNOPAUSE -dBATCH 
     -sOutputFile=dest.pdf -sDEVICE=pdfwrite -c .setpdfwrite 
     -c "<</Orientation 3>> setpagedevice" -f src.ps

Procedure Reference
===================

> (slide/title title-string element ...) - Creates a titled slide. See
  the overview for information about `element's. The space between the
  title and content is twice `gap-size'.

  When this function (or one of its variants) is first called in
  non-printing mode, then the viewer window is opened. Furthermore,
  each call to the function (or a variant) `yield's, so that the
  viewer window can be refreshed, and so the user can step through
  slides.

> (slide/title/tall title-string element ...) - Like `slide/title',
  except that the space is inserted between the title and the slide
  content is only `gap-size'.

> (slide/title/center title-string element ...) - Like `slide/title',
  except that the slide content is centered vertically under the
  title. If the content has steps an alternatives, each individual
  slide's content is center-top aligned with the largest individual
  slide's bounding box.

> (slide element ...) - Like `slide/title', but without the title.

> (slide/center element ...) - Like `slide/title/center', but without
  the title.

> (slide/title/inset title-string slide-inset element ...)
> (slide/title/tall/inset title-string slide-inset element ...)
> (slide/title/center/inset title-string slide-inset element ...)
> (slide/inset slide-inset element ...)
> (slide/center/inset slide-inset element ...)
  Like `slide/title', etc., except that an inset is supplied. A slide
  inset is created with `make-slide-inset'.

> (slide/name title-string element ...)
> (slide/name/tall title-string element ...)
> (slide/name/center title-string element ...)
> (slide/name/inset title-string slide-inset element ...)
> (slide/name/tall/inset title-string slide-inset element ...)
> (slide/name/center/inset title-string slide-inset element ...)
  Like `slide/title', etc., except that the title string is used only
  for naming the slide, as in the Alt-g dialog, and does not appear at
  the top of the slide. The content area is therefore the same size as
  `client-page'.

> (make-slide-inset left-inset top-inset right-inset bottom-inset) -
  Creates a slide inset, which describes a number of pixels to inset
  a slide on each side. Each inset must be an exact, non-negative
  integer.

> (t string) - Same as (text string (current-main-font) (current-font-size))
> (it string) - Same as (text string `(italic . ,(current-main-font)) (current-font-size))
> (bt string) - Same as (text string `(bold . ,(current-main-font)) (current-font-size))
> (bit string) - Same as (text string `(bold italic . ,(current-main-font)) (current-font-size))
> (tt string) - Same as (text string `(bold . modern) (current-font-size))
> (rt string) - Same as (text string `roman (current-font-size))
> (titlet string) - Like `t', but using the default slide-title font and color.

> (para width-n ielement ...) - Generates a paragraph picture of width
  `width-n'. Each ielement is either a string or a pict; strings are
  split at spaces for word-wrapping to fit the page, and space is
  added between elements. However, if a string element starts with a
  punctuation mark (e.g., a comma), no space is added before the
  element.

> (para* width-n ielement ...) - Like `para, except that the
  paragraph is only as wide as necessary, which may be less than
  `width-n'.

> (page-para ielement ...) - Like `para, except that the width
   is `client-w' (see below).

> (page-para* ielement ...) - Like `para*', except that the width
   is `client-w' (see below).

> (item width-n ielement ...)
> (item* width-n ielement ...)
> (page-item ielement ...)
> (page-item* ielement ...)
  Like `para, etc., except that a bullet is placed in front of the
  paragraph, and the paragraph is indented on the left.

> (item/bullet bullet-pict width-n ielement ...)
> (item*/bullet bullet-pict width-n ielement ...)
> (page-item/bullet bullet-pict ielement ...)
> (page-item*/bullet bullet-pict ielement ...)
  Like `item', etc., but with a given bullet pict.

> (subitem width-n ielement ...)
> (subitem* width-n ielement ...)
> (page-subitem ielement ...)
> (page-subitem* ielement ...)
  Like `item', etc., except that a hollow bullet is used, and the
  width for the `page-' versions is inset from `client-w'.


> (para/c width-n ielement ...)
> (para*/c width-n ielement ...)
> (page-para/c ielement ...)
> (page-para*/c ielement ...)
  Like `para, etc., except that text is centered within the paragraph.

> (para/r width-n ielement ...)
> (para*/r width-n ielement ...)
> (page-para/r ielement ...)
> (page-para*/r ielement ...)
  Like `para, etc., except that text is right-aligned within the
  paragraph.

> (clickback pict thunk)
  Creates a pict that embeds the given one, and is the same size as
  the given pict, but that when clicked during a presentation calls
  `thunk'.

> (most-recent-slide) - Returns a slide structure that be supplied to
  `re-slide' to make a copy of the slide. Transition animations before
  or after the slide (if any) are not included in the resulting slide.

> (retract-most-recent-slide) - Cancels the most recently created
  slide, and also returns a slide structure that be supplied to
  `re-slide' to restore the slide (usually in a later position).
  Transition animations after the slide (if any) are lost, while
  transitions before the slide remain in place (but are not part of
  the returned slide).

> (re-slide slide [pict]) - [Re-]inserts a slide, optionally
  `lt-superimpose'ing the given additional pict.

> (start-at-recent-slide) - Sets the starting slide for the talk to
  the most recently created slide. If this function is used multiple
  times, the last use overrides the realier uses.

> (scroll-transition x y w h dx dy [secs steps-k]) - inserts a scroll
  animation that shifts the screen rectangle (x, y, x+w, y+h) by `dx'
  and `dy', taking `secs' time and animating with `steps-k' steps.
  See also "Transition Animations", above.

> (pause-transition secs) - inserts a delay "animation" with no
  drawing effect.   See also "Transition Animations", above.

> (comment string-or-pict ...) - Combines strings and picts to be used
  as a slide element for (usually hidden) commentary. Use the result
  as an argument to `slide', `slide/title', etc.

> (make-outline { symbol/s string-or-pict subitems } ...)  - Returns a
  function that takes a symbol and generates an outline slide. Each
  trio of arguments defines a section for the outline:

   - The symbol/s names the section, either with a single symbol or a
     list of symbols. When the outline function is called later to
     make an outline, the given symbol is compared to the section's
     symbol(s), and the section is marked as current if the symbol
     matches.

   - The string-or-pict is used as the displayed name of the
     section.

   - The subitems are displayed when the section is active. It can be
     #f or null (for historical reasons) if no subitems are to be
     displayed. Otherwise, it should be a procedure that takes a symbol
     (the same one passed to the outline maker) and produces a pict.

> (size-in-pixels p) - Scales p so that p is displayed on the screen
  as (pict-width p) wide and (pict-height p) tall. The result is just
  p for a 1024x768 display.


> font-size - The default font size, 32. This size is in pixels for a
  1024x768 screen; see also the "Display Size and Fonts" section, above.
> gap-size - (* 3/4 font-size)

> current-font-size - Parameter for the font size used by `t', etc.,
  initialized to `font-size'.
> line-sep - Amount of seperating between paragraph lines.
> title-size - Font size used for slide titles, derived from `font-size'.
> main-font - Font specification used for `t' by default
> current-main-font - Parameter for the font specification
  used for `t'. Its argument must be a text-style (see
  texpict for details).
> current-title-color - Parameter for the color used by titles/`titlet'

> (with-font f thunk) - Calls `thunk' with
  `current-main-font' set to `f', which must be a
  text-style (see texpict for details)

> red - a color name like "red", possibiliy selected by the user.
> green - a color name like "green"
> blue - ...
> purple - ...
> orange - ...

> bullet - a bullet pict
> o-bullet - a hollow bullet pict

> client-w - (syntax) useable width of the screen
> client-h - (syntax) useable height of the screen
> get-client-w - returns useable width of the screen
> get-client-h - returns useable height of the screen

> full-page - (syntax) an empty pict that is the same size as the
              client area
> titleless-page - (syntax) an empty pict that is the same size as
                   the client ares minus the title area
> get-full-page - returns full-page
> get-titleless-page - returns titleless-page

> margin - (syntax) client margin within the full screen, 20
> get-margin - returns client margin within the full screen, 20
> set-margin! - sets `margin' and updates `client-w', `client-h',
                `full-page', and `titleless-page'

> title-h - (syntax) the height of a title string
> get-title-h - returns the height of a title string

> set-title-h! - sets `title-h' and updates `titleless-page'; this
  usually makes sense only in combination with a change to
  `current-format-slide'

> current-slide-assembler - a parameter whose value is a function for
  assembling slide content into a single pict; the assembling function
  takes a string-or-false for the title, a separation for the title
  and pict (if any), and a pict for the slide content (not counting
  the title); the result is 'lt-superimpose'd with the client area
  (but the result pict might draw outside the client region to paint
  the screen margins, too); see also `set-title-h!',
  `current-page-number-font', `current-page-number-color', and
  `set-page-numbers-visible!'

> current-page-number-font - font used to draw slide numbers
> current-page-number-color - color used to draw slide numbers
> set-page-numbers-visible! - determines whether slide numbers are
  initially visible

> printing? - #t if the slides are begin durected to PostScript output
> condense? - #t if slides are being condensed (see overview)
> (skip-slides n) - increment the slide counter by `n' without adding
  any slides.

> (done-making-slides)
  Notifies the slide viewer that no further slides will be registered,
  which is mainly useful in printing mode. This procedure is called
  automatically after loading a file when Slideshow is run as a
  application.

> (set-use-background-frame! on?) - enables or disables the creation
  of a background frame, which is typically useful only when insets
  are active. The last enable/disable during slide creation takes
  effect once and for all.

> (enable-click-advance! on?) - enables or disables slide advance
  as a result of a mouse click.

------------------------------------------------------------
_code.ss_
------------------------------------------------------------

The "code.ss" module provides functions and syntax for typesetting
Scheme code a la SlaTeX. It instantiates `code@' from `(lib "code.ss"
"typeset")', providing Slideshow's `current-font-size' and `line-sep'
to the unit, and re-exporting the unit's exports from the module.

The "code.ss" module also exports a `code' macro generated by
`define-code' from `(lib "code.ss" "typeset")':

> (code datum ...) - typesets the `datum' sequence to produce a pict;
                     see `define-code' from "code.s"" in the "texpict"
                     collection for more information.

See documentation for "code.ss" in the "texpict" collection for more
information.


Finally, "code.ss" exports a `define-code/string/scale' macro:

> (define-exec-code (pict-id runnable-id string-id)
    datum ...)

The `pict-id' is bound to the result of `(code datum ...)', except
that if an underscore by itself appears anywhere in a `datum', then
the underscore and the following expression are not included for
`code'.

Meanwhile, `runnable-id' is bound to a syntax object that wraps the
`datum's in a `begin'. In this case, underscores are removed from the
`datum's, but not the following expression. Thus, an underscore is
used to comment out an expression from the pict, but have it present
in the syntax object for evaluation.

The `string-id' is bound to a string reprsentation of the code that is
in the pict. This string is useful for copying to the clipboard with
`(send the-clipboard set-clipboard-string string-id 0)'.


> (define-exec-code/scale scale-expr (pict-id runnable-id string-id)
    datum ...)

Like `define-exec-code', but with a scale to use when generating the
pict.



------------------------------------------------------------
_step.ss_
------------------------------------------------------------

The "step.ss" module provides syntax for breaking a complex slide into
steps (that are more complex than can be handled with 'next and 'alts
in a `slide' sequence).

> (with-steps (id ...) expr) - evaluates `expr' once for each `id',
  skipping an `id' if it ends with "~" and `condense?' from
  "slideshow.ss" is true

  Within `expr', several keywords are bound:

>   (only? id) - returns #t during the evaluation of `expr' for
    `id', #f otherwise
>   (vonly id) - returns the identity function during the evaluation of
    `expr' for `id', `ghost' otherwise
>   (only id then-expr)
>   (only id then-expr else-expr) - returns the result of `then-expr'
    for step `id', the result of `else-expr' (defaults to `values')
    otherwise.

>   (before? id) - returns #t before ... for `id'
>   (vbefore id) - returns the identify function ... `ghost' otherwise
>   (before id then-expr)
>   (before id then-expr else-expr) - returns the result of `then-expr'
    before step `id', ...
    

>   (after? id) - return #t during and after ... for `id'
>   (vafter id) - ...
>   (after id then-expr)
>   (after id then-expr else-expr) - returns the result of `then-expr'
    during and after step `id', ...

>   (between? a-id b-id) - returns #t during and after ... for `a-id',
    but #f after evaluation for `b-id'
>   (vbetween a-id b-id) - ...
>   (between a-id b-id then-expr)
>   (between a-id b-id then-expr else-expr) - returns the result of 
    `then-expr' during and after step `a-id' and before step `b-id', 
    ...

>   (between-excl? a-id b-id) - returns #t during and after ... for
    `a-id', but #f during and after evaluation for `b-id'
>   (vbetween-excl a-id b-id) - ...
>   (between-excl a-id b-id then-expr)
>   (between-excl a-id b-id then-expr else-expr) - returns the result of 
    `then-expr' after step `a-id' and before step `b-id', ...

> (with-steps~ (id ...) expr) - like `with-steps', but when
  `condense?' from "slideshow.ss" is true, then `expr' is evaluated
  only for the last `id' (independent of whether its name ends in "~")


------------------------------------------------------------
_slides-to-picts.ss_
------------------------------------------------------------

> (get-slides-as-picts path width height condense?) - executes the
  Slideshow program indicated by `path' in a fresh namespace, and
  returns a list of picts for the slides. Each pict have the given
  `width' and `height', and `condense?' determines whether the program
  is executed in condense mode.