summaryrefslogtreecommitdiff
path: root/macros/generic/lecturer/doc/lecturer-doc.tex
blob: 7165c27f3a17f87814751d637c54d7180db8db97 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
% 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{<font>} 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{<left>} or \emph{<top>} 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{<topskip>} 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{<vpos>} 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{<name>} (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{<height>} 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