% This is the documentation for the Lecturer package. % Author: Paul Isambert % Date: July 2010. % \input pitex \newif\ifextraline \output{% \ifnum\outputpenalty=10000 \outputpenalty=0 \fi \ifextraline \global\vsize=\dimexpr\vsize-\baselineskip\relax \ifnum\outputpenalty=\widowpenalty \global\extralinefalse \unvbox255 \else \Shipout \fi \else \ifnum\outputpenalty<\widowpenalty \Shipout \else \ifnum\outputpenalty=10000 \Shipout \else \global\extralinetrue \global\vsize=\dimexpr\vsize+\baselineskip\relax \unvbox255 \penalty0 \fi \fi \fi } \def\Shipout{% \removependingtitles \processmarginalia \shipout\vbox{% \box255 \ifpagenum \kern\numexpr3\ifextraline-1\fi\baselineskip \hbox to \hsize{\sectionfont\hfil\the\pageno}% \fi }% \global\extralinefalse \global\pagenumtrue \advancepageno } \newif\ifpagenum \setparameter document: author = "Paul Isambert" title = "\ltr's documentation" pdftitle = "Lecturer's documentation" version = 1.0 date = "07/23/2010" display = outlines \setparameter page: % pagewidth = 20cm pageheight = 26cm left = 4cm top = 3cm lines = 44 hsize = 13cm \setparameter font: command = \mainfont name = ChaparralPro- size = 10pt roman = Regular bold = Bold italic = Italic \setparameter font: command = \notefont name = ChaparralPro- size = 8pt roman = Regular bold = Bold italic = Italic \setparameter font: command = \sectionfont name = ChaparralPro- size = 12pt roman = Regular bold = Bold italic = Italic \setparameter font: command = \titlefont name = ChaparralPro- size = 60pt roman = Regular \setparameter font: command = \codefont name = LTYPE size = 8pt type = ttf roman = {} bold = B italic = O \setparameter section: font = "\sectionfont\sc" beforeskip = 4 afterskip = 1 minimum = 4 \setparameter subsection: beforeskip = 2 minimum = 2 font = "\sectionfont\it" bookmarkstyle = "/F 1" \setparameter section subsection: number = none color = ".8 0 0" \def\yax{% Y\kern-.1em \raise.15em\hbox{\sc a}\kern-.1em \lower.15em\hbox{X}% \antigobblespace } \def\ltr{\emph{Lecturer}\antigobblespace} \newfornoempty\attrloop{1}#2 {% \reverse\iffemptystring{#1}{#1\rm\char"007C\it}% \passarguments{#2}}[#1] \newcount\paramcount \def\jump{% \vskip-\lastskip \penalty0 \ifdim\dimexpr\pagegoal-\pagetotal<\dimexpr 3\baselineskip-\prevdepth\relax \clearpage \else \vskip\baselineskip \fi} \def\bookmark#1{% \advance\paramcount1 \pdfdest name {param_\the\paramcount} xyz \createbookmark[{/C [.4 .4 .4]}]{4}{#1}{param_\the\paramcount}% } \setcatcodes{_=12} \def\attr#1#2#3{% \jump \bookmark{#1}% \noindent\llap{\attrib{#1} }% \val{\it$<$\attrloop{}{#2 }$>$}\kern1em \reverse\iffemptystring{#3}{{\hskip0pt plus 15em\penalty0\hskip0pt(\it Default:~\tcode{#3})}} \par\noindent\ignorespaces } \def\attrib#1{\color{.4 .4 .4}{{\codefont#1}}} \def\val#1{\color{.8 0 0}{{\codefont#1}}} \def\param#1{{\codefont\bf#1}} \def\rcom#1{\attrib{{\com#1}}\antigobblespace} \def\defcom{\jump\Defcom} \def\Defcom#1#2/{% \noindent\llap{\rcom#1\kern.4em}#2\reverse\iffemptystring{#2}{\par\noindent}\ignorespaces} \def\draw#1 #2/{\jump\noindent\llap{\attrib{#1} }\val{#2}\par\noindent\ignorespaces} \def\Point#1#2{\tcode{(#1,#2)}} \def\point{\Point xy} \newdimen\seeindent \setbox0\hbox{\it See } \seeindent=\wd0 \def\sectionaction#1{% \note{% \hangindent1\seeindent \hangafter1 See \color{\usevalueor section:color {0 0 0}}{#1}}% } \newif\ifrightdemo \def\demo#1 #2 {% \ifrightdemo \rightdemofalse \else \rightdemotrue \fi \def\demofile{\tcode{LecturerDemo-#1.pdf}\antigobblespace}% \pdfximage height \dimexpr(10\baselineskip-4pt) page #2 {LecturerDemo-#1.pdf}% \setbox0=\hbox{\pdfrefximage\pdflastximage}% \def\par{% \endgraf \ifdim\prevgraf\baselineskip<10\baselineskip \kern\dimexpr(10\baselineskip-\prevgraf\baselineskip) \fi \let\par\endgraf}% \vskip\baselineskip \penalty0 \ifdim\dimexpr(\pagegoal-\pagetotal)<\ht0 \clearpage \fi \vbox to 8pt{% \ifrightdemo \hbox to\hsize{\hfill \pdfrefximage\pdflastximage} \else \hbox{\pdfrefximage\pdflastximage} \fi \vss}% \kern-\baselineskip \nointerlineskip \parshape 11 \ifrightdemo \repeatuntil{10}{0pt \dimexpr(\hsize-\wd0-\dimexpr(\baselineskip-1ex))} \else \repeatuntil{10}{\dimexpr(\wd0+1em) \dimexpr(\hsize-\wd0-1em)} \fi 0pt \hsize \noindent\vrule height 12pt depth 0pt width 0pt\ignorespaces } %\input grid \vbox to 4\baselineskip{% \vfil \hbox to \hsize{\titlefont \pdfcolorstack0 push {.8 0 0 rg}\pdfliteral {2 Tr}% L\hss e\hss c\hss t\hss u\hss r\hss e\hss r% \pdfliteral {0 Tr}\pdfcolorstack0 pop% }} \vskip\baselineskip \hfill Author: \usevalue document:author \par \hfill \tcode{zappathustra@free.fr} \par \hfill Date: \usevalue document:date \par \hfill Version: \usevalue document:version \par \vfil \noindent\ltr creates presentations mainly based on PDF features. It doesn't manipulate \TeX's typesetting process in a complex way to give the impression that slides are being layered, but use PDF's so-called optional content to produce exactly this: layers. It was originally meant to work with plain \TeX, but since writing for plain is one step away from writing for any format, it is format-independent, though the heavy hand it lays on the output routine might make it conflict with other code. In plain \TeX, things are innocuous; in La\TeX, though not thoroughly tested, \ltr works good, provided it is not in conflict with other packages; since it is pretty self-contained for what it's designed, things should work nicely. Finally, \ltr seems to be usable with Con\TeX t MkII, but not MkIV (except perhaps to make a handout). I welcome comments on use of \ltr in those formats, so I can improve it. As for engines, \ltr currently works with pdf\TeX\ and Lua\TeX\ only, because the code is dependent on pdf\TeX's primitives. My apologies to Xe\TeX\ users. I welcome drivers. The main drawback in using \ltr is it requires a `conforming reader,' as they say at Adobe, to work properly, that is a reader that understands advanced PDF code and a little bit of JavaScript. Which basically means Adobe's reader, available mostly everywhere, and free, but `as in free beer,' to make a quote. The main advantage is that typesetting (\TeX) and presentation flow (PDF) are neatly divided: each slide is a page \ital{typeset} by \TeX\ and \ital{manipulated on the screen} by PDF code. Beside the intellectual satisfaction, there are more direct benefits: for instance, the handout is already in the slide, even if it's not directly prepared as such. Better still, there's no need to prepare the manuscript in any way to adapt to the requirements of a presentation. A list or a table, for instance, can be displayed stepwise without changing the usual way you type them in: interspersed \rcom\step commands will do. \note{% If you don't feel like reading 30 pages of documentation, switch to the demonstrations distributed with \ltr. For an overview, go to the the \let\sectionaction\unbrace \tosection{demonstrations}{\color{\usevalueor section:color {0 0 0}}{Demonstrations}} section.}% % And the best feature in \ltr, as far as I'm concerned, is that you can put anything anywhere with a few commands. \stoppage \section{Basic things} \subsection{Loading} \noindent\ltr should be loaded as is customary in the format at work, i.e. in plain TeX: \example \input lecturer \example/ \noindent in La\TeX: \example \usepackage{lecturer} \example/ \noindent and in Con\TeX t: \example \usemodule[lecturer] \example/ \subsection{First things first} \noindent In \ltr, the content of a document is organized in slides, with steps to make things appear progressively on the screen when you're in fullscreen mode. A (default) slide is anything that appears between the following two commands: \defcom\slide\oarg{attributes}/ \Defcom\endslide/ In La\TeX\ you can use \verb"\begin{slide}" and \verb"\end{slide}", and in Con\TeX t \com\startslide and \com\stopslide. The \com\slide/\com\endslide pair can be used in all formats, though, which is why I'll use \com\slide and \com\endslide for the examples in this documentation. \defcom\step\oarg{attributes}/ To make the content of a slide appear progressively on the screen, % \note{% To advance in the presentation, use either a left click or a right arrow key; to move backward, use a right click or a left arrow; and you can also use \emph{\string\nextstep} and \emph{\string\prevstep} with buttons.}% % this command is used where necessary. By default, it does nothing else, i.e. it doesn't disturb typesetting and simply creates the flow of the presentation with PDF code. Here's an example: \example \slide Something visible. \step My first proposition. \step And then... \step this. \endslide \example/ \noindent which on the screen produces a paragraph with `\ital{Something visible. My first proposition.}' and another one with `\ital{And then... this.}' as is usual with \TeX. Except these paragraphs don't appear at once. A \com\step means you'll have to click to move on, and what follows it will appear on screen, whereas it is otherwise invisible (by default at least). In the example, `\ital{Something visible}' is already on the screen, since it is not in the scope of a \com\step command, but the rest appears piecewise, and it takes three clicks to reach the end of the slide. Conversely, when moving backward, either with a right click or a left arrow key, steps disappear. The \com\step command affects the content of what follows only, up to the next \com\step or to the slide's end. Something between the beginning of the slide and the first step is always visible. Everything between \com\slide and \com\endslide is only one page. Steps appear gradually because they are instructed to do so, but they are on the same page, as physically as is possible for a collection of bytes (which can be printed, though). \defcom\slideno\relax/ \Defcom\slidenumber/ The first of those is a count register holding the slide's number (i.e. \verb"\count0"). The second is a macro that returns its value. Now you know the best part of how things work. The rest, i.e. the optional \arg{attributes} and a bunch of other things, is only decoration, although it might be of interest too to enliven your slides. \subsection{Presentation and handout}[handout] \noindent\ltr allows you to easily produce a presentation for screen and a handout out of the same file. The output depends on the value of the \attrib{mode} attribute in the \param{job} \tosection{job}{Attributes for the job} parameter. If it is set to \val{presentation}, then steps behave as defined above. If it is set to \val{handout}, then only those steps that have the value \val{true} for the \attrib{handout} parameter appear on the page. Other steps are still present, but hidden; they can be turned on in the reader's layers panel, though. By default, all steps are visible in a handout. The following three commands take a more radical way. \defcom\presentationonly\arg{material}/ In presentation mode, \arg{material} is simply typeset. In handout mode, however, it is gobbled. Thus, it takes no space on the page, and can't be retrieved. \defcom\handoutonly\arg{material}/ The same thing the other way around. \defcom\presentationorhandout\arg{presentation}\arg{handout}/ In \val{presentation} mode, the first argument is executed, and the second one in \val{handout} mode. Note the difference between \example \step A\step[handout=false] B\step C \example/ \noindent and \example \step A\presentationonly{\step B}\step C \example/ \setbox0=\hbox{B} \noindent In presentation mode, both will produce `ABC'. In handout mode, though, the first example will produce `A\kern\wd0C', % \note{% In Adobe Reader, the \emph{layers panel} is in the navigation panel on the left, represented by two squares overlapping, usually below thumbnails and bookmarks.}% % with `B' still retrievable from the layers panel, and the second example will produce `AC', with no `B' anywhere. Both \com\presentationonly and \com\handoutonly ignore any space following their argument when they gobble it. \section{Settings things globally and locally} \noindent Slides and steps can have attributes that modify their behavior. These attributes can be set locally or globally, meaning they either affect the current slide/step or all slides/steps or all slides/steps belonging to a certain type defined with \com\setslide/\com\setstep. The way attributes are used is a matter of inheritance. At the top of the hierarchy, there are the \param{slide} and \param{step} parameters. Attributes to those parameters aplly to all slides and steps, unless they are given other values lower in the hierarchy. At the bottom of the hierarchy, each individual slide or step can be followed by attribute settings between brackets. The values given there override all inherited values, but they hold for the current slide or step only. In between, new types of slides and steps can be defined; they inherit attributes from the corresponding parameters, and transmit their own attributes to slides and steps of their kind. \subsection{Global settings} \defcom\setparameter \arg{parameter}:/ \noindent This is used to set the values to attributes for \arg{parameter}. % \note{% There are only three parameters in \ltr: \emph{job}, \emph{slide}, and \emph{step}. They're sufficient to build a presentation, and don't need to be created beforehand. Nonetheless, \yax's parameter syntax is used everywhere.}% % The syntax for the attributes, which is used in many other places in \ltr, is as follows: \example \setparameter parameter: attribute1 = valueA attribute2 attribute3 = valueB ... \par \example/ \noindent You might find this syntax somewhat bizarre, but it is handy. It is the \yax syntax, and if you want to know more about it, see the \yax documentation. Here's how it works: after \com\setparameter you type either \param{slide} or \param{step} (or \param{job}, as we'll see later). Then a colon, which might be preceded by a space. Then you type the name of an attribute, or the names of several attributes separated by a space, and then a `=' sign. Finally you give your value, which is ended by the following space. If a value must contain a space, or if it's empty, you must give it between braces or double quotes, as in: \example \setparameter step: attribute1 = "my value" attribute2 = {} ... \example/ \noindent Or, if a value begins or ends with a control sequence, % \note{% If you have any doubt, you can always rely on braces and quotes.} % it should be enclosed between braces or double quotes again, unless it is made of a single control sequence. Thus: \example \setparameter step: attribute3 = "\command{argument}" attribute4 = \controlsequence ... \example/ \noindent Finally, and most importantly, a \com\setparameter declaration is ended by \com\par which, and that's the cool thing, can be a blank line, since \TeX\ inserts a \com\par at each blank line. The \com\setparameter declaration can be used as often as you wish; there's no need to respecify each attribute on each declaration: they retain their last declared value, which \ltr uses when it needs it. \subsection{Local settings} \noindent Attributes are set locally when they are given between brackets after the \com\slide or \com\step commands. They will be used for this particular \com\slide or \com\step. % \note{% Quotes and braces are removed anyway. So you can use them too, although they're completely useless: the delimitator is the comma.}% % The syntax is the custom \verb"key=value" fashion: first the attribute, then the value, then a comma. Here you can forget what's just been said about values: no need for quotes or braces. On the other hand, you can't set several attributes at once, each one must take its own value. Thus the following step \example \step[ myatt = myval ] And now something terrific... \example/ \noindent will have the value \verb"myval" for the attribute \verb"myatt" (note how unwanted space is ignored), instead of the value given in the \com\setparameter declaration... or in its type, which we turn to right now (and then I promise we'll see what those attributes are). Any space after the right bracket is ignored, so that you don't have to put \verb"%" signs here and there. \subsection{Type settings} \noindent You can create new types of slides or steps and set their parameters with the \com\setslide and \com\setstep commands respectively. Note that there is no difference between creating and setting the attributes of a new slide/step, and simply setting the attributes to an already created slide/step : the same commands are used in both cases. \defcom\setslide\arg{list of slides}/ The \com\setslide command sets parameters for all slides in the space-separated \arg{list of slides} (and creates them if they don't exist yet), as in: \example \setslide{myslide myotherslide} attribute1 = valueA attribute2 = valueB ... \par \example/ \noindent To use the slide \verb"myslide", in plain \TeX\ you call \com\myslide and \com\endmyslide, in La\TeX\ you do \verb"\begin{myslide}" and \verb"\end{myslide}", and in Con\TeX t you use \com\startmyslide and \com\stopmyslide. Actually \com\myslide and \com\endmyslide work in all three formats, but they're not customary. Slides thus created inherit values from the \param{slide} parameter, except when new values are specified. In our example, \com\myslide and \com\myotherslide will have \verb"valueA" and \verb"valueB" for \verb"attribute1" and \verb"attribute2" respectively, instead of the values defined for those attributes in the \com\setparameter declaration. Both commands can still be followed by local settings between brackets, and they'll override the ones given here. So in \example \myslide[attribute2=myval] ... \endmyslide \example/ \noindent \com\myslide will have the values \verb"myval" for \verb"attribute2", \verb"valueA" for \verb"attribute1", and the values defined in the \com\setparameter declaration for all the other attributes. \defcom\setstep\arg{list of steps}/ This takes a list of commands, i.e. control sequences, as its first argument, and then attributes and values as in \com\setparameter. The commands are just concatenated, with nothing to separate them. Thus \example \setstep{\mystep \myotherstep} attribute1 = valueA attribute2 = valueB ... \par \example/ \noindent creates or modifies \com\mystep and \com\myotherstep, which in a slide will create a step with \verb"valueA" and \verb"valueB" for \verb"attribute1" and \verb"attribute2" respectively, overriding the value of the \param{step} parameter. The commands can still take values between brackets to set attributes locally. \section{Attributes for slides} \noindent The attributes that follow are to be used in the \com\setparameter declaration for the \param{slide} parameter, in the \com\setslide declaration, and as optional arguments to the \com\slide command and equivalent commands created with \com\setslide, for which I'll use \com\slide generically. \subsection{PDF and navigation}[pdfslides] \noindent First of all, if a \com\slide command takes anything between brackets, and if among it there is something that doesn't contain a `=' sign, i.e. something that is obviously no attribute setting, then this thing, let's call it a string, becomes the slide's title, and it is recorded in a macro called \com\slidetitle, which you can use in the slide itself. It is also used in bookmarks (if the slide is to be bookmarked), which leads us to our first attribute. \attr{pdftitle}{string}{slide's title} Suppose you want a slide with title \verb"Something about \TeX". Then if that string is used in a bookmark, the bookmark won't look very good, because of the \TeX\ operations contained in the \com\TeX command, which bookmarks don't understand, since bookmarks are pretty limited. This attribute sets the title of the slide for use in bookmarks (and in the layers panel too). % \note{% Layers, i.e. steps, are grouped in the layers panel under the heading of the slide where they belong.}% % It doesn't make much sense except as a local attribute, unless you define it with a command whose definition changes from slide to slide, involving for instance a counter. I a slide has no title, pdf or not, `Page \ital{n}' is used in bookmarks and layers, but the \com\slidetitle command remains empty (not undefined). \attr{bookmark}{true false}{true} If this is set to \val{true}, a bookmark is created with the slide's title. \attr{bookmarklevel}{number}{1} The level of the slide's bookmark. The higher the \val{number}, the \tosection{bookmarks}{Creating bookmarks} lower the slide in the hierarchy. The \val{number} needs not be an integer. \attr{bookmarkstyle}{{bookmark options}}{none} The style of the bookmark, i.e. the optional argument in the \rcom\createbookmark command. \attr{anchor}{name}{none} An anchor to navigate to the slide with a \rcom\goto command. % \note{% You can actually specify the \emph{anchor} for several slides at once, provided the value is a command that holds a variable changing with slides.}% This the optional \arg{anchor} in \rcom\createbookmark. Since two anchors can't have the same name, this attribute can be used with \com\slide only, not in the \com\setparameter and \com\setslide declarations. % %\needspace{7\baselineskip} \subsection{Dimensions}[dimensions] \attr{width}{dimension}{15cm} The width of the slide. \attr{height}{dimension}{12cm} The height of the slide. \attr{hsize}{dimension}{slide's \attrib{width} minus twice its \attrib{left}} The width of lines. \attr{left}{dimension}{2cm} The left margin, i.e. the distance between the slide's left border and the textblock. \attr{right}{dimension}{unspecified} The right margin, i.e. the distance between the textblock and the slide's left border. If present, this parameter is always obeyed, in the following way: if neither \attrib{left} nor \attrib{hsize} is specified, \attrib{left} is set to the value of \attrib{right} and \attrib{hsize} is computed accordingly; % \note{% Thus, to center the textblock on the slide, specify the \emph{right} attribute only. The same holds for \emph{bottom} to center vertically, and for areas it is also true of \emph{right}, \emph{bottom}, \emph{hshift*} and \emph{vshift*}.}% % if one is specified but not the other, the unspecified one is computed according to the specified one and \attrib{right}; and if both are present, \attrib{hsize} is ignored and the previous rule applies. What is inherited from global to type to local settings is the result of this calculation, i.e. values for \attrib{left} and \attrib{hsize}. If these are changed \attrib{right} won't be taken into account. Conversely, if \attrib{right} is specified, then \attrib{left} and \attrib{hsize} aren't inherited. If things were otherwise, \attrib{left} would always be specified (since inherited) and it'd be impossible to compute it according to \attrib{right} and \attrib{hsize}, since it always wins against the latter. Thus, assuming a slide width of 10cm, with the following: \example \setparameter slide: left = 2cm right = 1cm \setslide{slideA} left = 1cm \setslide{slideB} right = 2cm hsize = 5cm \example/ \noindent we have a default slide with a left margin 2cm wide, right margin 1cm, and a line length of 7cm. For \verb"slideA" nothing is recomputed, thus the left margin is 1cm but the line length is still 7cm, which gives a right margin of 2cm. And \verb"slideB" has a \attrib{right} attribute, which triggers a computation; \attrib{left} isn't inherited, thus only \attrib{hsize} is specified and \attrib{left} is computed accordingly (to 3cm, as you might imagine). \attr{vsize}{dimension}{slide's \attrib{height} minus twice its \attrib{top}} The height of the textblock. This isn't important for page breaks, since no page break occurs in \ltr, but for the \attrib{vpos} attribute, and the scaling of the page if any. \attr{top}{dimension}{1cm} The upper margin, i.e. the distance between the slide's top border and the textblock. \attr{bottom}{dimension}{unspecified} The bottom margin, i.e. the distance between the textblock and the slide's bottom border. Works exactly as \attrib{right} in the vertical dimension, i.e. it is al ways obeyed, but not inherited, etc. Note that in full screen mode, readers set the page so that its smallest dimension goes from one side of the screen to the other. Thus, with \example \setparameter slide: height = 12cm \par \setlide{myslide} height = 14cm \par \example/ \noindent \com\slide and \com\myslide will actually look like they have the same height but not the same width. And the type will appear smaller in \com\myslide. By the way, the dimensions 12cm and 15cm are default simply because they make \TeX's default 10pt Computer Modern look readable. \attr{baselineskip}{{dimension or glue}}{12pt} The baseline distance for the slide. Glue means something like \verb"2pt plus 1fill", which can be useful (see the \attrib{vpos} attribue below). \attr{topskip}{{dimension or glue}}{12pt} The distance between the first line's baseline and the top of the textblock. \attr{parskip}{{dimension or glue}}{0pt} The distance between paragraphs. \attr{parindent}{dimension}{0pt} The width of the paragraph's indentation for this slide. You might want the previous dimensions to be connected in % \note{% The slide's font, if any (see the \emph{} attribute below), is called before these dimensions are set, so the \emph{em} and \emph{ex} dimensions works properly.}% some way. For instance, by default, \attrib{hsize} is connected to the slide's \attrib{width} and \attrib{left}. This is because the latter two attributes set the \TeX\ dimensions that the \attrib{hsize} attribute refers to. So the order in which those dimensions are set is important. Here are the dimensions and the attributes that set them, in the order of the assignement: \def\setdim#1#2{\par\noindent\com#1 = \attrib{#2}} \vskip\baselineskip \setdim\baselineskip{baselineskip} \setdim\topskip{topskip} \setdim\parskip{parskip} \setdim\pdfpagewidth{width} \setdim\pdfpageheight{height} \setdim\pdfhorigin{left} \setdim\pdfvorigin{top} \setdim\hsize{hsize} \setdim\parindent{parindent} \par\noindent\attrib{vsize} \vskip\baselineskip \noindent Thus, the default value for the \attrib{hsize} attribute is \attrib{width} minus twice \attrib{left} for each slide, because it is set as: \example hsize = "\pdfpagewidth-2\pdfhorigin" \example/ \noindent Which leads to an important point: in \ltr, a \arg{dimension} can be an expression, since it is then embedded in a \com\dimexpr primitive. \attr{hpos}{ff fr rf rr}{fr} This controls the slide's horizontal justification. The values mean: \val{ff} is flushleft/flushright (i.e. text justified on both sides), \val{fr} is flushleft/raggedright (commonly called raggedright), \val{rf} is raggedleft/flushright (called raggedleft), and \val{rr} is raggedleft/raggedright (i.e. text centered). Here second-order infinite glue is used. \attr{vpos}{top center bottom}{center} This sets how the lines are set in the textblock. Slides typically doesn't have the same number of lines, so we can't simply treat them as usual pages in typesetting. This is how the text of a slide is vertically positionned in the area defined by \attrib{vsize}. The \val{top} value means the text is flushed at the top, the \val{bottom} value is the same thing at the bottom, and \val{center} means the text will be centered in the area. This positioning is done with first-order infinite stretch, so you can use some too, or higher-order stretch, in the slide's content, to achieve some effects. \attr{scale}{true false}{false} If the main content of a slide is higher than \attrib{vsize}, it is scaled to the desired dimension if this attribute is set to \val{true}. The bad news is it is also scaled horizontally, to keep proportions. \subsection{Content} \attr{everyslide}{code}{nothing} Material inserted at the beginning of each slide (in vertical mode). For instance after \tosection{areas}{Adding material to areas} \example \setslide{myslide} everyslide = "\position{title}{\slidetitle}" \example/ \noindent the title's slide will be inserted in the \verb"title" area for each slide called with the \com\myslide command. \attr{areas}{{list of areas}}{all} This denotes the areas that may appear on a given slide. The keyword \val{all}, which is default, means that all areas will be painted (provided they are visible or contain material). Otherwise, \val{list of areas} enumerates allowed areas, separating them with space. If an area isn't painted on a slide but nonetheless contains material, this material is lost (and not even processed in the first place). \attr{areas*}{{list of areas}}{none} The list of excluded areas, i.e. the reverse of the previous attribute. Areas belonging to that list aren't painted on the slide. If an area appears in both \attrib{areas} and \attrib{areas*}, it is painted unless is is simply implicitely present in \attrib{areas} with \val{all}. \subsection{Style} \attr{background}{{named color or shade or color expression}}{white} The background color of the slide. \tosection{colors}{Colors, shades, and images} \attr{foreground}{{named color or color expression}}{black} The slide's foreground color. \attr{image}{image}{none} An image inserted in the slide's background, above the background color. \tosection{images}{Images} The image is inserted at the slide's upper left corner, and has the width and height it was declared with. Since this parameter is inherited, to cancel it give as \arg{image} any name that is not a declared image; \ltr is in the middle of a shipout when it reads this attribute, so don't worry, you'll get no error message. \attr{font}{{font command}}{job's font} The font used to typeset the slide. This is actually just a placeholder for font commands, e.g. \com\it or \com\bfseries. If this attribute is used, it should be specified for all slide types, or the \param{job} parameter should have a value to its own \attrib{font} attribute. Otherwise, if a slide with a font information is followed by a slide without such information, the latter will use the font of the former. \pdfdest name {backtrans} xyz \attr{transition}{{named transition}}{none} This is the way the PDF reader will display, animate, enliven, \tosection{transitions}{Transitions} and perhaps discredit your presentation. A transition is a little animation conforming readers play when they go from one slide to the next. They work in full screen only. A \val{named transition} should be recorded beforehand with \rcom\newtransition unless you use the default values, in which case you can use at once \val{split}, \val{blinds}, \val{box}, \val{wipe}, \val{dissolve}, \val{glitter}, \val{fly} (no less), \val{push}, \val{cover}, \val{uncover} and \val{fade}. \section{Attributes for steps} \noindent The attributes that follow are to be used in the \com\setparameter declaration for the \param{step} parameter, in the \com\setstep declaration, and as optional arguments to the \com\step command and equivalent commands created with \com\setstep, for which I'll use \com\step generically. \subsection{PDF and navigation} \noindent As with slides, an entry without a `=' sign in the optional argument to the \com\step command becomes the step's name (which should be unique on a given slide). This name is mainly useful for referencing with the \attrib{on} and \attrib{off} attributes and the \com\showorhide command, but it is also used as the step's name in the layers panel of the reader (if it has one). Hence: \attr{pdftitle}{string}{step's default name} Set the name used in the reader's layers panel. Thus you can have a nice title here and keep an uninformative-but-less-painful-to-type name to refer to a step in the attributes that follow. (If a step has no name, it is referred to in the layers panel with `step \ital{n}' with \ital{n} set back to zero at each slide.) \attr{on}{{list of steps}}{none} This sets the steps that make the current step appear. % \note{% When moving backward, just like the controlling step will toggle its visibitity, steps tied with \emph{on} and \emph{off} will too.}% % If there is no \attrib{on} attribute, a step appears at its position in the source. If there's an \attrib{on} attribute, then it appears when the steps referred to in the list are reached. If the list of steps contains the keyword \val{here}, then the step also appear by itself. Steps in the list are separated by space. \attr{off}{{list of steps}}{none} This is the same thing as \attrib{on} in reverse: the step disappears when the steps in the list are reached. The \val{here} keyword can't be used. Note that a step with an \attrib{on} and/or \attrib{off} list % \note{% This means there's no transitivity in the \emph{on} and \emph{off} attributes: if step A is tied to step B and step B to step C, this doesn't mean A is tied to C (it can, too, of course).}% % doesn't follow the steps in those lists, i.e. it doesn't appear/disappear when they do, but simply when they are reached in the linear sequence of steps in the source (which coincide more often than not). In the following example, the first step will appear by itself. Then the second step appears, along with the fourth, and the first one disappears. Finally, when the third step appears the first reappears. Since the fourth step has no autonomy, after the third step a click will lead to the next slide (provided it's the end of the slide, of course). \example \step[on=here B,off=A] First. \step[A] Second. \step[B] Third. \step[on=A] Fourth. \example/ \attr{handout}{true false}{true} Steps whose value is \val{true} for this attribute are visible \tosection{handout}{Presentation and handout} on the page when the document is processed as a handout (i.e. \val{handout} is the value of the \attrib{presentation} attribute for the \param{job} parameter), no matter how they appear during a presentation. Thus the document can be printed without manipulating layers beforehand. \attr{visible}{true false}{false} When this attribute is \val{true}, then the step is visible on the page when it is opened. \note{% This kind of step of course doesn't take a click during the presentation. In the example on the left, you need only two clicks to display \emph{Three}.}% % For instance, in a slide with: \example \step One. \step[visible=true] Two. \step[handout=true] Three. \example/ \noindent the following happens: if we're in normal presentation mode, then the second step will be visible on the slide when it is displayed, whereas the other two will appear when clicking. On the other hand, in a handout, only the third step will be visible. With: \example \setparameter step: visible handout = true \example/ \noindent all steps will be visible by default, in both modes. \subsection{Content} \attr{left}{dimension}{0pt} The distance between the textblock's left border% \note{% You can create list items and sub-items by simply creating steps with positive \emph{left} and/or \emph{right}.}% % (defined by the slide's \attrib{left} attribute and the left) and the border of the step's text. \attr{right}{dimension}{0pt} Same as \attrib{left}, on the right. \attr{vskip}{skip}{0pt} The value of the vertical glue inserted each time a \com\step occurs in vertical mode.% \note{% As with slides, the step's font, if any (see below), is called before those dimensions are used, so the \emph{em} and \emph{ex} dimensions have the proper values. Note that there's already the \emph{parskip} glue between vertical steps.}% % \attr{everyvstep}{code}{nothing} Material inserted when a \com\step occurs in vertical mode. The insertion takes place after \attrib{vskip} (and doesn't switch to horizontal mode by itself). \attr{hskip}{skip}{0pt} The value of the horizontal glue inserted each time a \com\step occurs in horizontal mode. \attr{everyhstep}{code}{nothing} Material inserted when a \com\step occurs in horizontal mode, after \attrib{hskip} \attr{group}{true false}{false} If this is set to \val{true}, the content of the step (including the value of \verb"every(v/h)step") happens inside a group. \subsection{Style} \attr{font}{{font command}}{slide's font} The font used to typeset the step. This is actually just a placeholder for font commands, e.g. \com\it or \com\bfseries. If this attribute is used, it should be specified for all step types, or the slide or job should have its own \attrib{font} attribute, or the step should have \attrib{group} set to \val{true}. Otherwise, font will bleed to the rest of the slide. \attr{color}{{Named color or color expression}}{slide's foreground} The color of the step, overriding the slide's foreground color. \tosection{realcolors}{Colors} \attr{transition}{{named transition}}{none} \tosection{transitions}{Transitions} The animation used to display the step, as with \com\slide. Note that the \val{push}, \val{cover} and \val{uncover} transitions make more sense with slides, since they affect the entire slide and not the step only. \section{Attributes for the job}[job] \noindent This section describes attributes pertaining to the entire document. They are set with the \com\setparameter command with \param{job} as the parameter's name. \attr{author}{string}{nothing} The author's name. It is stored in a command called \com\Author, and used in the document's properties, unless \attrib{pdfauthor} is defined. \attr{pdfauthor}{string}{nothing} This is used in the document's properties instead of \attrib{author}. \attr{title}{string}{\string\jobname} The document's title. It is stored in a command called \com\Title, and used in the document's properties, unless \attrib{pdftitle} is defined. \attr{pdftitle}{string}{nothing} This is used in the document's properties instead of \attrib{title}. \attr{date}{string}{\arg{month}/\arg{day}/\arg{year}} The document's date, recorded in the macro \com\Date. \attr{background}{{named color or color expression}}{reader's default} This sets the color of the reader's background (if the reader allows \tosection{realcolors}{Colors} such a thing to be done). You can set it to the color of the slide's background, so that slides appear to have the screen's dimensions. \attr{font}{{font command}}{nothing} The default font for the job. This is actually just a placeholder for font commands, e.g. \com\it or \com\bfseries. It is wise to give a value to this attribute, so that fonts can be safely used in slides and steps. \attr{mode}{presentation handout}{presentation} Selects how the document should be displayed. In \val{handout}, only \tosection{handout}{Presentation and handout} those steps whose value for the \attrib{handout} attribute is \val{true} are displayed. The other ones nonetheless take space on the slide and can be turned on in the reader's layers panel. The \com\handoutonly, \com\presentationonly a,d \com\presentationorhandout commands are more radical yet, since they gobble the discarded material, which isn't typeset. \attr{fullscreen}{true false}{false} If this is turned to \val{true}, the document is opened in full screen, which will probably make the reader send a message for confirmation. \attr{autofullscreen}{true false}{false} If this is turned to \val{true}, the document is displayed in full screen before navigating to a destination (when a bookmark is clicked, for instance), so that the destination is properly reached. \attr{normal}{none outlines thumbs layers}{outlines} Selects what must be displayed in the reader's navigation panel when not in full screen: \val{outlines} is, well, outlines (or bookmarks), \val{thumbs} is thumbnails, and \val{layers} shows the layers panel, where the steps can be turned on and off; \val{none} folds the navigation panel. \attr{menutext}{text}{***} The text to be displayed at the top of a submenu in the \tosection{bookmarks}{Creating bookmarks} navigation pop-up menu, to represent the current bookmark \section{Areas} \noindent Material normally declared is typeset following \TeX's usual rules, building paragraphs in the slide's textblock. However, in \ltr you can put material anywhere, thanks to areas. Areas can also be used simply as decorations, since they're basically colored squares. \subsection{Using a grid} \defcom\showgrid[\arg{left},\arg{top}]\arg{increment}\oarg{named color or color expression}\oarg{line width}/ This displays a grid on top of the slides % \note{% Grids can also be used as decorations, with a little imagination.}% % (following the command) to ease the creation of a display. Lines are drawn at a distance of \arg{increment} from each other. The grid starts from the upper left corner by default, but the optional \arg{left} and \arg{top} set horizontal and vertical shifts respectively (\arg{top} being a vertical distance \ital{à la \TeX}, i.e. going downward). If no optional color is given, the grid is painted grey, and the default line width is .2pt. There can be as many such declarations as wanted, each grid being painted on top of the previous one. For instance: \example \showgrid[2cm,2cm]{1mm} \showgrid{1cm}[red][.4pt] \example/ \noindent displays a grid in millimeters in grey, starting at 2cm from both the upper and left border, and a grid in centimers on top of it in red, with a line width twice the previous one, starting from the upper left corner. Note that there should be no space before the last two optional arguments (if it was allowed there'd be risks of unwanted space gobbling). \defcom\hidegrids/ Hides all grids on following slides, as if \com\showgrid had never been called. \subsection{Adding material to areas}[areas] \defcom\position\arg{area}[\arg{left},\arg{top}]\arg{material}/ This puts \arg{material} inside \arg{area}. % \note{% If \emph{} or \emph{} are 0pt, they can be omitted. Not the brackets and comma, though.}% % However, things differ greatly whether the optional argument is present or not. In case it isn't, \arg{material} is put below previous material in \arg{area}, as if continuing a page. On the other hand, if the optional argument is present, then \arg{material} is typeset so that its left border is at a distance of \arg{left} from the left border of the \arg{area}'s textblock and its baseline at a distance of (\arg{top} + \arg{area}'s \attrib{topskip}) % \note{% The calculation includes \emph{} so the connection between freely positioned material and normally position material is preserved. When using it, this formula proves far more intuitive than it seems.} % from its upper border. Thus, if both \arg{left} and \arg{top} are 0pt, then \arg{material} is typeset normally. Material already in the area has no effect on this process, and \arg{material} will have no effect either on incoming material, which is why \verb"\position{area}{material}" and \verb"\position{area}[0pt,0pt]{material}" aren't the same thing at all. The \com\position obeys the flow of the presentation, and appears only when the \com\step where it belongs appears. In this example: \example \step \position{myarea}{One} \step \position{myarea}{Two} \step \position{myarea}{Three} \example/ \noindent `One', `Two' and `Three' will appear one after the other, and one above the other. On the other hand with: \example \step[off=B] \position{myarea}[12pt,12pt]{One} \step[B,off=C] \position{myarea}[12pt,12pt]{Two} \step[C] \position{myarea}[12pt,12pt]{Three} \example/ \noindent `One', `Two' and `Three' will admittedly appear one after the other, but also disappear when one appears and take the place of the previous one, since they share the same position. All areas are emptied at each new slide. Remember that to be painted on a given slide, an area must be in the list of areas that is the value of the \attrib{areas} attribute for this slide, or shouldn't appear in the slide's \attrib{areas*} attribute. By default, slides accept all areas. \defcom\setarea\arg{list of areas}/ To create an area, or to modify an existing one, this command is used with \arg{list of areas} being area names separated by space; thus attributes similar for several areas can be declared at once. The command then takes attributes and values like \com\setslide above. For instance the following code creates or modifies two areas, verb"badidea" and \verb"ugly": \example \setarea{badidea ugly} background = red foreground = green ... \par \example/ \subsection{Dimensions} \attr{width}{dimension}{slide's width} The area's width, i.e. the width of the painted zone. % \note{% As far as dimensions are concerned, areas are very similar to slides. See the \emph{Visual Doc} for an illustration of this claim.}% \attr{hshift}{dimension}{0pt} The distance between the area's left border and the slide's left border. \attr{hshift*}{dimension}{unspecified} The distance between the area's right border and the slide's right border. The \attrib{hshift*} attribute is always obeyed if present. If neither \attrib{width} nor \attrib{hshift} are specified, then \attrib{hshift} is set to \attrib{hshift*} and \attrib{width} is computed accordingly, which is convenient to center an area on a slide. If one of \attrib{width} or \attrib{hshift} is present but not the other, then the latter is computed with the given value and \attrib{hshift*}. If both are present, \attrib{width} is ignored and the previous rule applies. \attr{height}{dimension}{slide's height} The area's height. This defines the vertical dimension of the painted zone. \attr{vshift}{dimension}{0pt} The distance between the area's top and the slide's top. \attr{vshift*}{dimension}{unspecified} The distance between the area's bottom and the slide's bottom. It works like \attrib{hshift*} in the vertical dimension, and is consequently always obeyed. \attr{hsize}{dimension}{area's width} The line's length in the area. \attr{left}{dimension}{0pt} The area's left margin, i.e. the distance between its left border and the left border of its textblock. \attr{right}{dimension}{unspecified} The area's right margin, i.e. the distance between its right border and the right border of its textblock. Like the same attribute for slides, it is always obeyed, i.e. if specified \attrib{hsize} and/or \attrib{left} are set accordingly. For the rule governing those values are computed, see the discussion on the \attrib{right} attribute for slides, or on the \attrib{hshift*} attribute for areas just above, which works similarly. \attr{hpos}{ff fr rf rr}{fr} This controls the area's horizontal justification. The values mean: \val{ff} is flushleft/flushright (i.e. text justified on both sides), \val{fr} is flushleft/raggedright (commonly called raggedright), \val{rf} is raggedleft/flushright (called raggedleft), and \val{rr} is raggedleft/raggedright (i.e. text centered). \attr{vsize}{dimension}{area's height} The height of the area's textblock, not for page breaks, obviously, but for the \attrib{vpos} attribute below. \attr{top}{dimension}{0pt} The area's top margin, i.e. the distance between its upper border and the top of its textblock. \attr{bottom}{dimension}{unspecified} The area bottom margin, i.e. the distance between its textblock's bottom and its bottom border. It works like \attrib{right} in the vertical dimension. \attr{vpos}{top center bottom}{top} The vertical justification of the area's content in the textblock (defined as \attrib{vsize}). % \note{% Freely positioned material is unfolded (including its vertical displacement) at the top of normally positioned material. Hence its vertical justification might seem somewhat unpredictable unless \emph{} is set to \emph{top}, though it isn't by \TeX's standard. As a rule of thumb, take the top of the justified textblock as the vertical reference, and consider that freely positioned material is insensitive to vertical justification.}% % \attr{baselineskip}{{dimension or glue}}{current \com\baselineskip} The baseline distance for the area. \attr{topskip}{{dimension or glue}}{current \com\topskip} The distance between the baseline of the area's first box and the area's top. Unlike \TeX's \com\topskip, this distance is always respected, no matter the height of the box. \attr{parskip}{{dimension or glue}}{0pt} The distance between paragraphs in the areas, including between two normal \com\position. \attr{parindent}{dimension}{0pt} The width of the paragraph indent for the area. \subsection{Content} \attr{visible}{true false step}{true} If this attribute is set to \val{true}, then the area is visible on the slide even if it contains no material. With \val{false}, it is painted only on the slides where it is filled. In the latter case, using \val{step} means the area will follow the first step where the first \com\position command is issued. Empty material freely positioned may be useful to control the area, for instance: \example \step[on=start,off=stop]\position{mayarea}[0pt,0pt]{} \example/ \noindent This will make the area appear with \verb"start", probably its first real content, and disappear with \verb"stop", which probably also controls the disappearance of the last material in the area. Two remarks: the first \com\position means the first occurrence of the command in the source, not necessarily the first to be shown on screen; thus, to work properly, the previous example should be put at the very beginning of a slide. Second, in this example, it is important that the material be freely positioned, i.e. with \verb"[0pt,0pt]", so as to make the subsequent \com\position think (?) the area is still empty. \attr{everyposition}{code}{nothing} Code to be added before \arg{material} each time % \note{% All material is actually added in vertical mode with the \emph{\string\position} command.}% % \com\position\barg{area}\barg{material} is called. This material is added in vertical mode. \attr{everyfreeposition}{code}{nothing} Same as before, except it is used when \com\position is called with the optional argument for free position. \subsection{Style} \attr{background}{{named color or shade or color expression}}{none} The color of the area's background. If none is given, the area is transparent. \tosection{colors}{Colors, shades, and images} \attr{foreground}{{named color or color expression}}{black} The area's foreground color. \attr{image}{image}{none} An image inserted in the area's background, above the background color. The image is inserted at the area's upper left corner, and has the width and height it was declared with. Since this parameter is inherited, to cancel it give as \arg{image} any name that is not a declared image; no error message will ensue. \attr{font}{{font command}}{nothing} The font used to typeset material in the area. This is actually just a placeholder for font commands, e.g. \com\it or \com\bfseries. \attr{frame}{{attribute-value pairs}}{none} This sets the area's frame, if you want any. The value itself is a setting of attributes, each one being accessible in the main declaration as \tcode{frame_\arg{attribute}}. I.e. \example frame = "width = 1pt, color = blue" \example/ \noindent and \example frame_width = 1pt frame_color = blue \example/ \noindent are equivalent. \attr{frame_width}{dimension}{0pt} The frame's width. If positive, the frame is painted around the area. If negative, it is painted inside the area, with the the \arg{dimension}'s absolute value as its width. An area with no frame simply has a \attrib{frame_width} of 0pt. \attr{frame_color}{{named color or shade or color expression}}{area's \attrib{background}} The frame's color. \tosection{colors}{Colors, shades, and images} \attr{frame_corner}{miter round bevel}{miter} This is a \val{miter} corner:\kern4pt \pdfliteral {q 4 w 0 0 m 0 4 l 8 4 l S Q}\kern9pt, this is a \val{round} one:\kern4pt \pdfliteral {q 4 w 1 j 0 0 m 0 4 l 8 4 l S Q}\kern9pt, and this is a \val{bevel} one:\kern4pt \pdfliteral {q 4 w 2 j 0 0 m 0 4 l 8 4 l S Q}\kern9pt. \attr{frame_dash}{numbers}{none} The frame's dash pattern, meaning the frame is on (visible) for \ital{n1} points, then off (invisible) for \ital{n2} points, then on for \ital{n3} points, etc., where the \ital{n}'s are the \val{numbers}. This is cyclic, so that it starts again when \val{numbers} are exhausted. For instance a value of \verb"3 5 2" makes the frame visible for 3pt, then invisible for 5pt, then visible for 2pt, then invisible for 3pt, then... \section{Navigation} \noindent \ltr is made for fullscreen mode and navigation is no exception. Thus, bookmarks (and anchors in the next subsection) work properly in this mode only; when not in fullscreen, using a link leads to the page where the target appears, but not to the step in which it is embedded. Turning \attrib{autofullscreen} to \val{true} in the \param{job} parameters makes the reader go into fullscreen when clicking a link and thus navigation hits its target. \subsection{Creating bookmarks}[bookmarks] \noindent A presentation can be structured thanks to bookmarks (also called outlines), and these are accessible in the reader's outlines panel, or in the presentation via a pop-up menu. To create a bookmark, one uses the following command. \defcom\createbookmark\oarg{options}\arg{level}\oarg{anchor}\arg{text}/ This creates a bookmark with \arg{text} as the text displayed in the outline panel and the pop-up menu. Bookmark hierarchy is managed with \arg{level}, according to the following principle: bookmarks with larger \arg{level} are children to bookmarks with smaller one. Thus, \arg{level} must be a number, but it need not be an integer nor a positive number. For instance: % \note{% This means you don't need to redefine all your sections if you want to add intermediate ones; just give the latter any value in the interval where you want them to occur in the hierarchy.}% % \example \createbookmark{0}{Part} \createbookmark{.5}{Section} \slide[Slide] ... \createbookmark{1.5}{Step1} ... \createbookmark{1.5}{Step2} ... \endslide \example/ \noindent will create bookmarks with the following hierarchy: \example > Part > Section > Slide > Step1 > Step2 \example/ \noindent because by default slides are bookmarked and have bookmark level 1. If sections of widest scope are eventually needed in this example, one can create them using bookmarks with a negative \arg{level}. The \arg{options} are any combination of the following keywords, separated by commas: \val{bold}, \val{italic} and \val{bolditalic}, which specify how the bookmark is to be typeset in the outlines panel, and \val{open} and \val{closed}, which specify whether the bookmark displays its children by default or not. Finally, \val{nosubmenutext} applies to the pop-up menu displayed with \rcom\showbookmarks, as explained below. Any other material in \arg{options} is supposed to be a triplet of numbers ranging between 0 and 1, to denote the bookmark's color in an RGB model. For instance: \example \createbookmark[italic,open,1 0 0]{0}{Bookmark} \example/ \noindent creates a red bookmark in italic that displays its children when the document is opened in the reader. The \arg{anchor} is a reference so that one can go to the bookmarked place with \rcom\goto, and is equivalent to using \rcom\anchor (next subsection). Note that \arg{options} and \arg{level} are specified for a slide (if it \tosection{pdfslides}{PDF and navigation for slides} is bookmarked) the \attrib{bookmarkstyle} and \attrib{bookmarklevel} attributes. \defcom\showbookmarks\oarg{optional style}\arg{text}/ This creates an hbox containing \arg{text} (which can be anything, like real text, or a symbol, etc.); when clicked, a pop-up menu appears, which contains the bookmark hierarchy of the document. The optional style is either \val{flash} or \val{push}, which sets the little animation used when the link is clicked: it reverses its colors or seems to be pushed in the background. The keyword \val{none} can also be used to denote no animation. In the pop-up menu, the children of a bookmark are displayed as a sub-menu. Hence this bookmark isn't clickable anymore, because its only function is to show the submenu. That's why the first item of this sub-menu is clickable and refers to that parent bookmark. The text used by this item is the value of the \attrib{menutext} attribute in the \param{job} parameter, unless the bookmark has the \val{nosubmenutext} option. \subsection{Navigation commands} \defcom\anchor\arg{name}/ This creates an anchor called \arg{name}, which is a destination for the \rcom\goto command. In what follows, all commands create a clickable hbox containing \arg{text}, with animation specified by \arg{optional style}, as in \com\showbookmarks above. That's why I will only describe the action performed by the commands. \defcom\goto\oarg{optional style}\arg{name}\arg{text}/ Go to the destination anchored by \arg{name} (which can be the value of the \attrib{anchor} argument in a bookmark). \defcom\gotoA\oarg{optional style}\arg{name}\arg{text}/ This creates the first item of a bidirectional link called \arg{name}. Clicking \arg{text} goes where \com\gotoB with \arg{name} has been issued. \defcom\gotoB\oarg{optional style}\arg{name}\arg{text}/ This creates the second item of a bidirectional link called \arg{name}. Clicking \arg{text} goes where \com\gotoA with \arg{name} has been issued. There's no need for \com\gotoA to appear before \com\gotoB. Using these macros is just simpler than a pair of \com\anchor's with a pair of \com\goto's. \defcom\firstslide\oarg{optional style}\arg{text}/ Go to the presentation's first slide. \defcom\lastslide\oarg{optional style}\arg{text}/ Go to the presentation's last slide. \defcom\prevslide\oarg{optional style}\arg{text}/ Go to the presentation's previous slide. \defcom\nextslide\oarg{optional style}\arg{text}/ Go to the presentation's next slide. \defcom\prevstep\oarg{optional style}\arg{text}/ Go backward once. Equivalent to a right click. \defcom\nextstep\oarg{optional style}\arg{text}/ Go forward once. Equivalent to a left click. \defcom\showorhide\oarg{optional style}\arg{actions}\arg{text}/ This shows or hides the steps referred to in \arg{actions}, which is made of `\tcode{\arg{action}=\arg{step list}}' pairs separated by commas, where \arg{action} is \val{on}, \val{off} or \val{toggle}, and \arg{step list} is a list of step names separated by space. The action is to show, hide, or reverse the visibility of a set of steps. For instance: \example \showorhide{on=A B,off=C,toggle=D E F}{Button} \example/ \noindent will, when clicked, make the steps named \verb"A" and \verb"B" visible, hide step \verb"C", and reverse the visibility of \verb"D", \verb"E" and \verb"F". \section{Colors, shades, and images}[colors] \noindent Some attributes above take values denoted by the phrases \ital{named color or shade or color expression}, or \ital{named color or color expression}. Those are explained in this section. \subsection{Colors}[realcolors] \noindent A color can either be a \ital{named color} or a \ital{color expression}. The latter is the simpler. It is a \arg{color model} followed by as many \arg{numbers} as required, ranging from 0 to 1. A color model is one of the keywords \val{grey} (or \val{gray}), which takes one \arg{number} (0 is black, 1 is white), \val{rgb}, which takes three \arg{numbers} (red, green and blue), and is additive, and \val{cmyk}, which takes four numbers (cyan, magenta, yellow, black), and is substractive. Hence: \example \setparameter slide: background = "rgb 1 0 0" foreground = "cmyk 1 0 1 0" ... \par \example/ \noindent sets the slide's background color to red, and its foreground color to green. Which is not recommended. Color expressions aren't very handy, since you have to type them as many times as you need them. Which is why there exists the following command to declare a \ital{named color}: \defcom\newcolor\arg{name}\arg{color model}\oarg{opacity}\arg{values}/ After this declaration you can use \arg{name} to denote a color, % \note{% Unlike \emph{\string\newslide} or \emph{\string\newarea}, \emph{\string\newcolor} and \emph{\string\newshade} below take only one \emph{} (instead of a list).}% % which itself is somehow as a color expression, i.e. it has a \arg{color model} and as many \arg{values} as required. The optional \arg{opacity} is a number between 0 and 1, 0 meaning fully transparent and 1 fully opaque. If not present, it is set to 1. The following named colors are already defined (with full opacity): \val{black}, \val{white}, \val{red}, \val{green}, \val{blue}, \val{cyan}, \val{magenta}, \val{yellow}. I suppose you can see where they come from. So our example above could be more easily rewritten as: \example \setparameter slide: background = red foreground = green ... \par \example/ Finally, colors can be used simply with: \defcom\usecolor\arg{Named color or color expression}\arg{text}/ This typesets \arg{text} with the specified color, % \note{% Beware, the operation of the \emph{\string\usecolor} command isn't executed inside a group, as may be the case with colors in other packages.}% % overriding whatever is used as the current color wherever this command is issued (i.e. step, slide, area). \subsection{Shades} \noindent A \ital{shade} is a transition from one color to another. It can be used for backgrounds and frames only. It takes many parameters, so it is declared with the \yax syntax. \defcom\newshade\barg{name}/ The \arg{name} is what is used to refer to this shade where it can be used. \attr{model}{grey gray rgb cmyk}{grey} The shade's model for its colors. You can't create a shade with colors from different models. \attr{from}{values}{black} The shade's starting color. There must be as many numbers as required by the \attrib{model} parameter. If nothing is specified, black is supplied. \attr{to}{values}{white} The shade's ending color. There must be as many numbers as required by the \attrib{model} parameter. If nothing is specified, white is supplied. Neither \attrib{from} nor \attrib{to} can take named colors as arguments. \attr{angle}{angle}{90} The shade varies along an axis. % \note{% Shades' attributes may be more easily understood with the interactive examples in the \emph{Visual Doc}.}% % This axis starts in the upper left corner of the area to be painted and makes an angle of \arg{angle} degrees with the area's upper border. The \arg{angle} must range between 0 and 90: 0 means that the shade progresses horizontally and 90 that it moves verticaly. If \arg{angle} is between 0 and -90, its absolute value is taken as its value but the shade starts from the upper \ital{right} corner. The value of \arg{angle} actually refers to a shade painted in a square; if the area to be painted isn't a square, this imaginary square is scaled and the angle of the shade will follow the scaling. For instance, an angle of 45 makes the shade progress from the top left corner to the bottom right corner; if the area to be painted is a rectangle, the shade will still progress between these two corners, and the angle will be skewed. \attr{speed}{number}{1} The speed of the shade's progression: 1 means the shade takes its axis' full length to progress; a value between 0 and 1 makes it take more than this length (and thus it won't be fully painted in the area) whereas a value larger than 1 makes it take less than this length (for instance with \verb"speed = 2" it'll take half the axis' length). \attr{width}{dimension}{none} A shade normally adapts to the area it paints. However, if \attrib{width} is given, the shade will take the specified dimension; if \attrib{width} is larger than the area to be painted, the shade won't be seen in its entirety; if it is smaller, part of the area will be painted with the shade's \attrib{to} color. \attr{height}{dimension}{none} Same as width in the vertical dimension. \attr{fixed}{true false}{false} By default, a shade is painted from the area's upper left corner (or right corner if \attrib{angle} is negative). If \attrib{fixed} is set to \val{true}, then it is painted from the slide's upper left (or right) corner, although only the area displays it. Note that a fixed shade whose width and height are unspecified doesn't make much sense. \vskip\baselineskip To sum up: picture two areas painted with the same shade. If the shade has no width nor height and isn't fixed, they will both display the entire shade, and if they don't have the same dimensions the shade will have different shapes in them. If the shade has a width and a height, both areas will display exactly the same shade, although what is revealed of it depends on the areas' dimensions. Finally, if the shade is fixed, the areas will look like open windows on the same underlying shade. \subsection{Images}[images] \defcom\newimage\arg{name}[\arg{width},\arg{height}]\arg{file}/ This loads image file \arg{file}, % \note{% If only one dimension is used, the comma should nonetheless remain, with nothing left or right, in order to indicate which dimension is referred to. Specifying a \emph{} only is done for instance with:~\emph{[,5cm]}. Note that background images in slides and areas (as values to the \emph{image} attribute) aren't scaled to their container's dimensions.}% % setting its dimensions to \arg{width} and \arg{height}; if none are present, the image has its natural width; if only one dimension is given, the other ones is scaled accordingly. If both are given, deformations might ensue. The image can be used in the background of a slide or area by setting \arg{name} as the value for the \attrib{image} attribute, and anywhere else with the following command. \defcom\useimage\arg{name}/ This returns an hbox containing the image \arg{name}. The height and width of the box are the height and width of the image as declared with the previous command. \section{Drawing symbols} \noindent \ltr provides very basic but still useful drawing facilities aimed at creating symbols to whatever end, e.g. a button for navigation or a bullet before each step. \defcom\newsymbol\arg{command}\oarg{settings}\arg{drawing}/ This creates a symbol that is called with \arg{command} and designed with \arg{drawing}; the symbol is actually an hbox, and its reference point (i.e. the intersection of its left border with the baseline) is the origin of the coordinate system for \arg{drawing}; in turn, this hbox's width is the largest x-coordinate in \arg{drawing}, its height the largest y-coordinate, and its depth the smallest negative y-coordinate. Any part of \arg{drawing} on the left of the y-axis, i.e. with a negative x-coordinate, is ignored in the box's width and will overlap material on the box's left. In \arg{drawing} goes a set of simple statements separated by commas, a statement being an operator sometimes followed by arguments (separated by space), which either define paths or paint them. All coordinates are expressed in units, a unit being 1pt by default, which can be changed in \arg{settings}. At the beginning the current point is \Point00. Here are the operators (in the first two, `\verb"[+]"' means an optional \verb"+" character, without the brackets): \draw move [+] x y/ If \verb"+" is not present, this moves to \point, which becomes the current point; if there is a \verb"+", and the current point is \Point{x'}{y'}, then it moves to \Point{x'+x}{y'+y}, which becomes the current point. If there was a path being drawn, it is ended and stroked beforehand. \draw line [+] x y/ If \verb"+" is not present, this creates a line from the current point to \point, which becomes the current point; if there is a \verb"+", and the current point is \Point{x'}{y'}, then it creates a line between the current point and \Point{x'+x}{y'+y}, which becomes the current point. Note that the \attrib{line} operator is actually optional and any statement of the form `\verb"[+] x y"' is understood as `\verb"line [+] x y"'. \draw circle \arg{direction} \arg{radius}/ Despite its name, this actually creates a quarter-circle from the current point to a point depending on \arg{direction} and \arg{radius}, with the latter being a number and the former one of the keywords \val{ul}, \val{ur}, \val{lu}, \val{ru}, \val{dl}, \val{dr}, \val{ld} or \val{rd}, where each letter denotes \ital{left}, \ital{right}, \ital{up} or \ital{down}, these in turn being the quarter-circle's tangents' directions at the starting (for the first letter) and ending (for the second letter) points. For instance, `\verb"circle ur 7, circle rd 7"' creates a quarter-circle of radius 7 going up and then right, followed by a quarter-circle of the same radius going right and then down, which figure mathematicians tend to call a semi-circle, i.e.~% \pdfliteral {q .7 0 0 .7 0 0 cm 0 0 m 0 5.52 4.48 10 10 10 c 15.52 10 20 5.52 20 0 c S Q}\kern15pt. The current point after a (quarter-)\attrib{circle} is its ending point, i.e. \val{radius} units away left or right and below or above from the starting point. \draw close / This closes the path, i.e. appends a line from the current point to the path's starting point. \draw stroke / This strokes the current path. This operator is appended at the end of \arg{drawing} if there remains a path that hasn't been painted; thus it is useless as the very last command. \draw fill / This fills the current path, i.e. the path is closed and the area it delimits is colored. % \note{% Differences between \emph{fill} and \emph{paint} are visible when the line width, set with \emph{pen}, is large.}% % \draw paint / This is similar to fill, except the path is also stroked. \draw pen \arg{width}/ This sets the width of the stroking pen to \val{width}. \draw color \arg{named color or color expression}/ This changes the current color to the specified value. If several such \tosection{realcolors}{Colors} commands are issued, the painting operators above use the color most recently issued when they are called. If no color is specified, the symbol takes the foreground color of the place where it appears. \vskip\baselineskip The optional \arg{settings} to \com\newsymbol are comma-separated `\verb"attribute=value"' pairs; there can also be a single \arg{dimension} among them expressing the value of a unit in the coordinate system, which is 1pt by default. The attributes are \attrib{left}, \attrib{right}, \attrib{top}, \attrib{bottom} and \attrib{padding}, and the values are \arg{dimensions}. These attributes set the amount of padding on the left, right, top and bottom borders respectively, with \attrib{padding} setting them all at once. Padding is somteimes necessary because the drawing's box's (and clipping path's) dimensions are defined according to the abstract paths the drawing is made of, not according to the paths as they are painted, and a painted path has the width of the pen used to paint it. For instance, the simple drawing `\verb"line 0 10"' has no width, even though it might be painted with a 10-unit wide pen. If there's no padding, the symbol won't show anything. By default, padding is set to 1pt on all sides. As an example, here's how the alien has been drawn in the demonstration file called \tcode{LecturerDemo-KitschScienceFiction.pdf}: \example % Default unit. \newsymbol\alien[1.7em]{% pen .05, color cmyk .2 1 .4 0, % The alien's body 1 0, circle ul .5, circle ld .5, fill, % The left tentacle circle dl .2, circle lu .2, % The right tentacle move 1 0, circle dr .2, circle ru .2, % The legs move .16 0, + 0 -.3, % stroke is implicit in the next move move .49 0, + 0 -.3, move .82 0, + 0 -.3,stroke, % The eyes color cmyk 0 0 1 0, move .2 .25, + .2 0, move + .2 0, + .2 0 % stroke is implicitly added at the end } \example/ \defcom\symbolwidth\arg{command}/ \Defcom\symbolheight\arg{command}/ \Defcom\symboldepth\arg{command}/ When a symbol is defined, its dimensions can be queried with those macros, where \arg{command} is the symbol's command. \section{Transitions}[transitions] \noindent Transitions are basic animations played when a step (dis)appears on the slide or when one advances to the next slide. The \attrib{transition} attribute for slides and steps can take a \arg{named transition} as its value, and one declares a named transition with the following command: \defcom\newtransition\arg{name}/ This command takes several attributes, which are: \attr{type}{split blinds box wipe dissolve glitter fly push cover uncover fade}{none} (These values can also have an uppercase first letter.) This is the type of the % \note[2\baselineskip]{% The \emph{Visual Doc} has a slide illustrating those transitions.}% % animation being played. The predefined transitions already available in \ltr are those animations with the following parameters set to their default values. \attr{motion}{inward outward}{inward} (Only for transitions of type \val{split}, \val{box}, and \val{fly}.) The direction of motion, either from or to the center of the page. \attr{direction}{lr bt rl tb dx}{lr} (Only for moving transitions.) The direction of movement: left to right, bottom to top, right to left, top to bottom, and diagonal (top-left to bottom-right). \attr{dimension}{horizontal vertical}{horizontal} (Only for \val{split} and \val{blinds}.) Whether the splitting is horizontal or vertical. \attr{scale}{number}{1} (Only for \val{fly}.) The scale at which elements affected by the transition are drawn at the beginning of the transition (if its motion is \val{inward}) or at the end (if it is \val{outward}). \attr{duration}{number}{1} The length of the transition, in seconds. \section{Inserting PDF code} \noindent\ltr relies heavily on PDF code and unfortunately pdf\TeX's management of some PDF objects is far from optimal. Consequently, if you want to insert some PDF constructs things might go wrong. Hence the following macros, where arguments are always expanded immediately. \defcom\addtopageobject\arg{code}/ This adds \arg{code} to the Page object for the current page. \defcom\addtoeachpageobject\arg{code}/ This adds \arg{code} to the Page object for all pages. This command and the previous one fill the \com\pdfpageattr token list, which after each shipout is emptied of material added with \com\addtopageobject. \defcom\addtopageresources\arg{code}/ This adds \arg{code} to the Resources dictionary for all pages. This uses the \com\pdfpageresources token list. For the Properties, Shading and ExtGState resources, the following command should be used. \defcom\addproperties\arg{name}\arg{object number}/ Maps \arg{name} to \arg{object number} in the Properties dictionary of the current page's Resources. For instance, \example \addproperties{foo}{3} \example/ \noindent produces the following in the page's Resources: \example ... /Properties << ... /foo 3 0 R ... >> ... \example/ \defcom\addshading\arg{name}\arg{object number}/ Same as \com\addproperties, but for the Shading dictionary. And this is added to all pages' Resources, not just the current one. \defcom\addgstate\arg{name}\arg{object number}/ Same as \com\addshading, but for the ExtGState dictionary. \defcom\addOCG\arg{object number}/ Adds the Optional Content Group \arg{object number} to the document's catalog, with base state {\sc off}. It is also turned off when one arrives on the page where it's been added. \defcom\addvisibleOCG\arg{object number}/ Same as \com\addOCG, except base state is {\sc on}. \clearpage \section{Demonstrations}[demonstrations] \demo VisualDoc 4 The present documentation might appear as a dull list of attributes. That's why it is distributed with a Visual Documentation (\demofile), which isn't really a demonstration, in the sense that it is not supposed to be an imaginary presentation but a visual display of many features of \ltr. Thus commands and attributes can make sense at once. One should nevertheless keep in mind that this visual documentation doesn't show everything in \ltr, and that the reference documentation remains the present one. The source isn't terribly user-friendly (and requires Lua\TeX\ and non-free fonts to compile), but still interesting constructions are used and can be copied, in particular with \com\showorhide. \let\par\endgraf \vskip\baselineskip The visual documentation explains how to use \ltr; the following demonstrations show what it can do. Barring \verb"LecturerDemo-SquaresOfAs", they have been typeset with the default Computer Modern fonts, so the sources can be modified and compiled again to see how things work. To do so, one should use the plain \TeX\ format with either pdf\TeX\ or Lua\TeX. \demo Mondrian 3 \demofile is a simple presentation based on the work of one famous Dutch painter. It illustrates what you can do with areas, setting the main text in one square (although the text is not \com\position'ed but typed in as the slide's content, see below), the maths (synced with the main text) in another one, and footnotes, which are turned on and off with the \com\showorhide command, in a third square. The other squares are just decorations. The alignment of the squares is made easy by grouped attribute declarations with the \com\setarea command. For instance, the three squares on the left are declared as: \example \setarea{area1 area2 matharea} width = 3cm \example/ \noindent and the first two, which have the same height and color, are specified further again with: \example \setarea{area1 area2} height = 4.3cm background = white \example/ \noindent after which \verb"area1" doesn't need anything; another declaration sets \verb"area2"'s \attrib{vshift}, and still another one is used for \verb"matharea" to display its content. The slide's background is painted black so lines appear between the areas (which is also why the \val{white} color must be specified as some areas' \attrib{background}, otherwise they'd be transparent). The main text is set in the slide's textblock (i.e. not \com\position'ed), and a red area is painted below, which gives the impression that the text is set in an area, whereas it is simlpy asymmetrically shifted. \demo SquaresOfAs 3 \demofile was inspired by some Con\-\TeX t presentations, and uses only areas to typeset its material. Barring the last slide, there's nothing in the main textblock. On the first slide, the \attrib{visible} attribute of the areas is set to \val{step}, so areas appear with their content. The background of the reader is turned to white, so the slides seem to fill the entire screen. The entire presentation is built on a single length (\com\squarewidth) in which all dimensions are expressed, including font sizes (such cumbersome font sizes as \verb"1.83\squarewidth" are meant to make all letters appear at the same height). Thus the presentation is totally scalable. Like in the Mondrian presentation, attributes are declared mostly for all areas at once, so the design can be easily modified. The frames of the areas have negative width, so they are painted inside the areas and they don't have to be taken into account when computing positions. Actually, their contribution to the design resides in their rounded corner only, since they have the same \attrib{background} color as the areas. The presentation itself is a wandering among several guises of the letter \ital{a}, with several non-free TrueType fonts (requiring Lua\TeX), and thus you should change those to fonts you own and can manage if you want to compile the source. (If you think it is inhuman to make the part of the letters below the baseline disappear in the white background, just change the latter. Jovica Veljovi\char"0107's \ital{Esprit} will regain its spirit indeed.) \demo SimplePresentation 4 \demofile uses a very simple display, built on a millimetric grid, which can be displayed by uncommenting the first lines of the file. Some subtleties are included in the presentation's flow; for instance, the triangles at the left of each vertical step are already painted on the slide before the steps appear. This is done by creating two steps, one for the triangle with \attrib{visible} set to \val{true},and one for the step's content, a process which is automated by a simple code: \example \def\Step{% \step[visible=true]\quitvmode\llap{\stepsym\kern.2cm}% \step} \example/ \noindent where \com\stepsym is the symbol's command. Note the necessary \com\quitvmode: those steps are called in vertical mode and plain \TeX's \com\llap macro creates a box which should be inserted in horizontal mode to get things right. The \attrib{everyvstep} attribute could also have been used, but care should be taken to ensure that no loop occurs, by creating to kinds of step, the \attrib{everyvstep} of one executing the other. The horizontal and vertical lines are actually areas with no width but a frame indeed, created with: \example \string\setarea{vline hline} frame = "width = .15pt, color = black" \setarea{vline} hshift = 3cm width = 0pt \setarea{hline} vshift = 2cm height = 0pt \example/ When clicked, the circle (a symbol) with the slide number in the bottom right corner displays the bookmarks in a pop-up menu. And the maths in the blackboark are of course inserted with free \com\position's. The next presentation is an elaboration on this one. \demo BeamerCambridgeUS 2 \demofile is an imitation (not terribly faithful) of the Beamer package's \tcode{CambridgeUS} theme. It uses \attrib{everyslide} to typeset recurrent material, like the date or the slide's title. It also mimicks Beamer's display of inactive steps in transparent color. This is no feature in \ltr, though, and must be done by hand with overlapping elements; which means it's basically undoable for the main text. The presentation is also heavy on symbols designed with \com\newsymbol used as buttons, and uses bookmarks and anchors for navigation, including between the main text and appendices, thanks to \com\gotoA and \com\gotoB. The last slide displays scaled content, and finally, if the \attrib{mode} attribute is turned to \val{handout}, a handout is produced. (Which is true of all presentations, except in this case care has been taken so that the handout isn't just a presentation on a sheet of paper, although the differences are rather slight with the original presentation.) \demo ThePoodleLectures 4 \demofile (don't ask) is made of five slides each displaying a different presentation style, sometimes verging on the PowerPoint-ish. The point of this demonstration is that the code for each slide remains minimal: you don't need to write hundreds of lines of attribute specifications to set up a presentation. Areas are used for decoration and the slide's title, and no complex positioning is involved. The same steps are reused (with silly text, don't ask either) and illustrate the use of the \attrib{left} attribute for steps as an easy way to create list items. Most of the effort, though, is spent on symbol design, from simple square to music note to sea shell. (Note that this demonstration contains such declarations as `\verb"hshift hshift* = 2cm"' when \attrib{hshift*} is supposed to automatically set \attrib{hshift} if the latter isn't specified; but since the same areas are reused for all slides, \attrib{hshift} \emph{is} specified after the first slide.) \demo KitschScienceFiction 1 \demofile is a pathetic attempt at creating a video game with \TeX. Obviously there are better ways to do that. Nevertheless, the presentation illustrates many \ltr's features, including the use of \com\showorhide, free positions, transparent colors, shades, and a background image. The drawing of symbols is also used to an extent it wasn't designed for in the first place. The reader can pay a visit to the layers panel (which is displayed by default when not in full screen) to see how elements are organized on the screen. Once again an area (the green square) is painted below the slide's textblock, with similar colors, to give the impression of a screen, even though as far as \ltr is concerned the textblock and the area are totally unrelated, i.e. the text isn't the content of the area. The darker line that appears at the area's perimeter is produced by the area and its frame overlapping, an unwanted side effect with transparent colors, unavoidable but not so bad-looking here. \pagenumfalse \processbookmarks \bye