path: root/macros/latex/contrib/flipbook/flipbook-doc.tex

\documentclass[a4paper,twoside]{article}

\usepackage[utf8]{inputenc}
\usepackage{xspace}
\usepackage{url}

\usepackage[debug]{flipbook}

% Where animations are put in the corners.
\lhead[top left]{}
\rhead[]{top right}
\lfoot[bottom left\\
  \fbInputF{./Images/Anims/anASCII/an}{tex}{0.3}]{}
\rfoot[]{bottom right\\
  \fbInputB{./Images/Anims/anASCII/an}{tex}{0.3}
}

% One can use a higher footer if it looks nicer.
%\addtolength{\footskip}{1cm}


\def\Flipbook{{\bf Flipbook}\xspace}
\def\flipbook{{\bf flipbook}\xspace}

\title{The \Flipbook Package\\
  --- Documentation ---}
\author{
  Olivier Buffet\\
  \url{firstname.lastname@loria.fr}
}

\begin{document}

\maketitle

\begin{abstract}
  How to add flip book animations in the corners of your \LaTeX{}
  documents.
\end{abstract}

\section{About Flip Book Animations}

\subsection{Introduction}

The \LaTeX{} \flipbook package is a small package intended to help you
add flip book animations in the corners of your documents. A flip book
(or ``flick book'') is a book in which each page represents one image
of an animation, so that one obtains a smooth animation by quickly
flipping the book's pages (usually by releasing the pages held with
your thumb).\footnote{As anything you can think of is already
  somewhere on the internet, please go on youtube and check out a
  video on how to use a flipbook: \url{http://www.youtube.com/} .}

The present package only serves to put such animations in corners of
documents (in one of the four ``external'' corners of pages). This
document for example has two flip book animations: one in the bottom
right corner of odd pages, and one in the bottom left corner of even
pages.

Useful links:
\begin{itemize}
\item \url{http://www.flipbook.info/}
\item \url{http://en.wikipedia.org/wiki/Flip_book}
\end{itemize}

\subsection{Ordering}

An important observation is that, flip book animations from left and
right corners go in opposite directions. In traditional flip books,
full page animations are printed on right pages, and the animation
starts on the first page. IMHO, for corner animations on standard
A4/letter paper, it seems reasonable for the animations to go:
\begin{itemize}
\item from the end of the document to its beginning in (top/bottom)
  right corners, and
\item from the beginning of the document to its end in (top/bottom)
  left corners.
\end{itemize}
The idea is that one uses its thumb to release new images (/pages) on
top of previous images in the animation.

Whatever your choice of ordering, a consequence of the fact that left
and right pages are associated with opposite orderings is that each of
this package's commands comes in two versions: one for left corners
and one for right corners. The commands defined in this package are of
the form \verb+\fbCOMMAND*+ where \verb+COMMAND+ is the command name
and \verb+*+ has to be replaced by \verb+F+ or \verb+B+ to specify if
you want to use an animation going Forward of Backward.


\section{About this Document}

Below are instructions to use the \flipbook package. The \LaTeX{}
source of two documents serve as examples of how to use {\tt flipbook.sty}
 style file:
\begin{itemize}
\item {\tt flipbook-doc.tex}: this documentation, which contains a
  very basic ASCII art animation, and can thus be compiled with both
  \LaTeX{} of pdf\LaTeX{},
\item {\tt flipbook-ex.tex}: an example with animations based on PNG or
  PDF images, so that the compilation requires pdf\LaTeX{}.
\end{itemize}

This package requires the following packages:
\begin{itemize}
\item {\tt fancyhdr},
\item {\tt graphicx},
\item {\tt verbatim},
\item {\tt scalefnt},
\item {\tt everypage},
\item {\tt ifthen}.
\end{itemize}
One could easily make a lighter version without some of them (e.g., in
case of incompatibilities with other packages).

\section{Creating Your Own Flip Book Animations}

\subsection{Initialization}

Whatever the type of animation to use, using this package first
requires going through the following two steps:
\begin{enumerate}
\item In most cases, your document will be printed on both sides
  (thanks to modern printers), requiring to distinguish left and right
  (even and odd) pages.

  You should thus make sure to specify the ``twoside'' option when
  specifying your documentclass. For example, the first line in the
  source code for this documentation is:
\begin{verbatim}
\documentclass[a4paper,twoside]{article}
\end{verbatim}

  In case your document is to be printed on a single side, you can
  specify the ``oneside'' option for your documentclass instead, as
  in:
\begin{verbatim}
\documentclass[a4paper,oneside]{article}
\end{verbatim}
  Note that, in this case, all pages are considered to be right pages.

\item Then, to make use of the \flipbook package, add the following
  line in the preamble:
\begin{verbatim}
\usepackage{flipbook}
\end{verbatim}
\end{enumerate}

\subsection{Using Standard Graphics}

Here are the instructions to create your own flip book animations
using standard graphics (either vector or bitmap images):
\begin{enumerate}
\item For each animation, put a {\bf numbered} sequence of
  eps/pdf/png/jpg images in a directory.
\item Use the {\tt fancyhdr} commands (also in the preamble) to create
  your animations, for example (with two different approaches for
  placement):\footnote{See Section~\ref{sec:other} if you need to use
    other commands.}
\begin{verbatim}
\lfoot[~ \\
  \fbImageF{./Images/Anims/an2/im}{pdf}{scale=0.18}]{}
\rfoot[]{\thepage
  \setlength\unitlength{1cm}
  \begin{picture}(0,0)
    \put(2.5,-2.5){
      \fbImageB{./Images/Anims/an3/im}{png}{scale=0.25}
    }
  \end{picture}
}
\end{verbatim}
  Please, be careful when placing your images: they should be as close
  to the corner as possible, but your printer should still print them
  properly (most printers leave a white border out).
\item An important point is the use of the \verb+fbImage*+ command
  (where \verb+*+ is \verb+L+ or \verb+R+ depending whether one is
  working in the left or right corner). Assuming:
  \begin{itemize}
    \item that one set of images is in directory \verb+DIR+ with a name such as
      \verb+PREFIXnn.png+,
    \item and that you want all of them to be scaled by a factor of
      \verb+.2+ (other options of the \verb+includegraphics+ command
      are possible),
    \end{itemize}
    then you have to use the command:
    \\
    \verb+\fbImage*{./DIR/PREFIX}{png}{scale=0.2}+
\end{enumerate}

Note: The \verb+graphicx+ package is used to display pictures using
the \verb+\includegraphics+ command.

\subsection{Using ASCII Art}

The previous section has shown how to use the \verb+fbImage*+ command
to display images. Two other commands are provided to display text:
\begin{itemize}
\item \verb+fbInput*+: allows including a \verb+tex+ file; in the
  present document it is used in the bottom right corner as follows:
\begin{verbatim}
\fbInputB{./Images/Anims/anASCII/an}{tex}{0.3}
\end{verbatim}
the three arguments are (i) the directory and prefix of the ``image''
files, (ii) the suffix of the ``image'' files, and (iii) the scale;
\item \verb+fbVerb*+: allows including a raw text file (in verbatim
  mode); in the present document it is used in the bottom left corner
  as follows, showing the source of \LaTeX{} files:
\begin{verbatim}
\fbVerbF{./Images/Anims/anASCII/an}{tex}{0.3}
\end{verbatim}
\end{itemize}

\subsection{Debugging}

If nothing appears, this may be because your images are placed outside
the page (tune the coordinates of the \verb+\put+ command).

Another common cause of missing pictures is that your images are not
found (no error message is displayed because there would typically be
too many of them).

To facilitate tracking such mistakes, one can call the package with
the ``debug'' option. It prints a warning message for each ``missing
file'' (1) in the console, and (2) instead of the missing file (so, if
no message is displayed, this may be that the coordinates are wrong).

\section{Comments}

\subsection{Other Means of Controlling Headers and Footers}
\label{sec:other}

With some document classes (e.g., \verb+book.cls+ or
\verb+thloria.cls+), you may prefer using the \verb+\OddHead+,
\verb+\EvenHead+, \verb+\OddFoot+, \verb+\EvenFoot+ commands. Here is
an example validated with \verb+thloria.cls+:
\begin{verbatim}
%-------------------------------------------------------------------
%                             flipbook
%-------------------------------------------------------------------

% display flipbook at the bottom right of each normal page
\EvenHead{{\leftmark}{\thepage\hfil{\slshape\leftmark}}}
\OddHead{{\leftmark\rightmark}{{\slshape\rightmark}\hfil\thepage}}
\OddFoot{
  \hfil
  \setlength\unitlength{1cm}
  \begin{picture}(0,0)
    \put(0.25,-1.75){
      \fbImageB{../Images/Anims/an2/im}{pdf}{scale=0.25}
    }
  \end{picture}
}
\EvenFoot{}

% display also on special pages (chapter titles, etc)
\pagestyle{Fancy}
\fancyhf{}

\fancypagestyle{plain}{
  \fancyhead{}
  \renewcommand{\headrulewidth}{0pt}
  \fancyfoot[RO]{
    \setlength\unitlength{1cm}
    \begin{picture}(0,0)
      \put(0.25,-1.75){
        \fbImageB{../Images/Anims/an2/im}{pdf}{scale=0.25}
      }
    \end{picture}
  }
} 
\end{verbatim}

\subsection{Warning: File Size}

Do not forget that animations include many pictures and that each
picture uses disk space. Be careful to prefer vector graphics, or
possibly avoid high-quality bitmap pictures, if you want to keep your
file size reasonable.

\subsection{Going Further}

This package provides simple commands to create flip books based on
vector/bitmap images, or ASCII art.

It should be easy to use various packages to generate animations using
\LaTeX{}, e.g., using pstricks, tikz, or generating files thanks to
external applications (using shell escape)...

\subsection{TODO}

Ideas for the future:
\begin{itemize}
\item Make it possible to define lists of animations (one per usable corner).
\item Allow references to animations, as for floats
  (figure/table/algorithm/...), or at least to the interval of pages
  corresponding to a given animation.
\end{itemize}

\subsection{Your Creations}

I'd be happy to know about your \LaTeX{} documents
(reports/theses/books/...) including flip books. 

\subsection{Acknowledgments}

Thanks to Christophe Thiéry, Cláudia Tavares, Arnaud Glad and Stephen
Willshaw for their help and feedback.

\newpage
A
\newpage
A
\newpage
A
\newpage
A
\newpage
A

\end{document}


% Local IspellDict:        american
% (The above line tells ispell to run by default with an american dictionary.)