<commit_before>#lang scribble/doc
@(require "ss.ss"
          (for-label slideshow/play
                     slideshow/code))

@title[#:tag "play"]{Animations}

@defmodule[slideshow/play]{The @schememodname[slideshow/play] module
provides tools for generating animations as multiple, automatically
advanced slides.}

Many of the tools are based on a function that takes a number between
@scheme[0.0] and @scheme[1.0] inclusive and produces a
pict. The pict produced for the input @scheme[0.0] is
the starting image of the animation, and the pict produced for
@scheme[1.0] is the ending image, while intermediate values produced
intermediate images. For example,

@schemeblock[
(lambda (n)
  (cellophane (t "Hello") n))
]

corresponds to an animation that fades in the word ``Hello.''

@; --------------------------------------------------

@section{Generating Animated Slides}

@defproc[(play [gen ((real-in 0.0 1.0) . -> . pict?)]
               [#:steps steps exact-positive-integer? 10]
               [#:delay delay-secs real? 0.05]
               [#:skip-first? skip-first? any/c #f]
               [#:title title (or/c string? pict? #f 
                                    ((real-in 0.0 1.0) . -> . (or/c string? pict? #f)))
                        #f]
               [#:name name (or/c string? #f
                                  ((real-in 0.0 1.0) . -> . (or/c string? #f)))
                       title]
               [#:layout layout (or/c 'auto 'center 'top 'tall) 'auto])
         void?]{

Generates @math{@scheme[steps]+1} slides by calling @scheme[gen] on
equally-spaced values from @scheme[0.0] (inclusve) to @scheme[1.0]
(exclusive). Except for the first of the slides, each slide has a
timeout of @scheme[delay-secs], so that the next slide appears
automatically.

Normally, @scheme[play] is called via @scheme[play-n], which
effectively calls @scheme[gen] on @scheme[1.0] without a timeout to
complete the animation and stop the auto-advance of slides. The
@scheme[play-n] function also manages with multi-step animations.

If @scheme[skip-first?] is @scheme[#f], then one less slide is
generated, because @scheme[gen] is not called on @scheme[0.0].

The @scheme[title], @scheme[name], and @scheme[layout] arguments are
passed on to @scheme[slide], at least when @scheme[title] and/or
@scheme[name] are not functions. When @scheme[title] or @scheme[name]
is a function, the function is applied to the value used to produce
the slide content, and the resulting title or name is passed on to
@scheme[slide].

In condensed mode (i.e., when @scheme[condense?] is @scheme[#t]), any
slide that would be registered with a timeout is instead skipped.}


@defproc[(play-n [gen* (() (listof (real-in 0.0 1.0)) . ->* . pict?)]
                 [#:steps steps exact-positive-integer? 10]
                 [#:delay delay-secs real? 0.05]
                 [#:skip-first? skip-first? any/c #f]
                 [#:skip-last? skip-last? any/c #f]
                 [#:title title (or/c string? pict? #f 
                                      ((real-in 0.0 1.0) . -> . (or/c string? pict? #f)))
                          #f]
                 [#:name name (or/c string? #f
                                    ((real-in 0.0 1.0) . -> . (or/c string? #f)))
                         title]
                 [#:layout layout (or/c 'auto 'center 'top 'tall) 'auto])
          void?]{

Generates a sequence of slides by calling @scheme[gen*] with, for each
of its arguments, numbers from @scheme[0.0] to @scheme[1.0]. If
@scheme[gen*] accepts @math{n} arguments, then result is a sequence of
animations with a pause (i.e., not auto-advanced) between each of
@math{n} segments.

If @scheme[gen*] accepts a single argument, then @scheme[play-n] is
like @scheme[play], except that @scheme[gen*] is also called with
@scheme[1.0] to generate a slide with no timeout. If @scheme[gen*]
accepts multiple arguments, then slides are generated by calling
@scheme[gen*] with the first argument varying from @scheme[0.0] to
@scheme[1.0] while all other arguments are @scheme[0.0]. Then, the
first argument is held at @scheme[1.0] while the second argument varies
from @scheme[0.0] to @scheme[1.0], and so on.

For example,

@schemeblock[
(play-n (lambda (n1 n2) (cellophane (t "Hello") (* n1 (- 1.0 n2)))))
]
<commit_msg>fixed indentation of an example<commit_after>#lang scribble/doc
@(require "ss.ss"
          (for-label slideshow/play
                     slideshow/code))

@title[#:tag "play"]{Animations}

@defmodule[slideshow/play]{The @schememodname[slideshow/play] module
provides tools for generating animations as multiple, automatically
advanced slides.}

Many of the tools are based on a function that takes a number between
@scheme[0.0] and @scheme[1.0] inclusive and produces a
pict. The pict produced for the input @scheme[0.0] is
the starting image of the animation, and the pict produced for
@scheme[1.0] is the ending image, while intermediate values produced
intermediate images. For example,

@schemeblock[
(lambda (n)
  (cellophane (t "Hello") n))
]

corresponds to an animation that fades in the word ``Hello.''

@; --------------------------------------------------

@section{Generating Animated Slides}

@defproc[(play [gen ((real-in 0.0 1.0) . -> . pict?)]
               [#:steps steps exact-positive-integer? 10]
               [#:delay delay-secs real? 0.05]
               [#:skip-first? skip-first? any/c #f]
               [#:title title (or/c string? pict? #f 
                                    ((real-in 0.0 1.0) . -> . (or/c string? pict? #f)))
                        #f]
               [#:name name (or/c string? #f
                                  ((real-in 0.0 1.0) . -> . (or/c string? #f)))
                       title]
               [#:layout layout (or/c 'auto 'center 'top 'tall) 'auto])
         void?]{

Generates @math{@scheme[steps]+1} slides by calling @scheme[gen] on
equally-spaced values from @scheme[0.0] (inclusve) to @scheme[1.0]
(exclusive). Except for the first of the slides, each slide has a
timeout of @scheme[delay-secs], so that the next slide appears
automatically.

Normally, @scheme[play] is called via @scheme[play-n], which
effectively calls @scheme[gen] on @scheme[1.0] without a timeout to
complete the animation and stop the auto-advance of slides. The
@scheme[play-n] function also manages with multi-step animations.

If @scheme[skip-first?] is @scheme[#f], then one less slide is
generated, because @scheme[gen] is not called on @scheme[0.0].

The @scheme[title], @scheme[name], and @scheme[layout] arguments are
passed on to @scheme[slide], at least when @scheme[title] and/or
@scheme[name] are not functions. When @scheme[title] or @scheme[name]
is a function, the function is applied to the value used to produce
the slide content, and the resulting title or name is passed on to
@scheme[slide].

In condensed mode (i.e., when @scheme[condense?] is @scheme[#t]), any
slide that would be registered with a timeout is instead skipped.}


@defproc[(play-n [gen* (() (listof (real-in 0.0 1.0)) . ->* . pict?)]
                 [#:steps steps exact-positive-integer? 10]
                 [#:delay delay-secs real? 0.05]
                 [#:skip-first? skip-first? any/c #f]
                 [#:skip-last? skip-last? any/c #f]
                 [#:title title (or/c string? pict? #f 
                                      ((real-in 0.0 1.0) . -> . (or/c string? pict? #f)))
                          #f]
                 [#:name name (or/c string? #f
                                    ((real-in 0.0 1.0) . -> . (or/c string? #f)))
                         title]
                 [#:layout layout (or/c 'auto 'center 'top 'tall) 'auto])
          void?]{

Generates a sequence of slides by calling @scheme[gen*] with, for each
of its arguments, numbers from @scheme[0.0] to @scheme[1.0]. If
@scheme[gen*] accepts @math{n} arguments, then result is a sequence of
animations with a pause (i.e., not auto-advanced) between each of
@math{n} segments.

If @scheme[gen*] accepts a single argument, then @scheme[play-n] is
like @scheme[play], except that @scheme[gen*] is also called with
@scheme[1.0] to generate a slide with no timeout. If @scheme[gen*]
accepts multiple arguments, then slides are generated by calling
@scheme[gen*] with the first argument varying from @scheme[0.0] to
@scheme[1.0] while all other arguments are @scheme[0.0]. Then, the
first argument is held at @scheme[1.0] while the second argument varies
from @scheme[0.0] to @scheme[1.0], and so on.

For example,

@schemeblock[
(play-n 
 (lambda (n1 n2)
   (cellophane (t "Hello")
               (* n1 (- 1.0 n2)))))
]

{'fraction_non_alphanumeric': 0.14090698750578437, 'fraction_numerical': 0.017353077279037482, 'mean_word_length': 2.5271317829457365, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '239234', 'n_tokens_mistral': 2740, 'n_tokens_neox': 2624, 'n_words': 988}