1%slatex-d.tex 2%SLaTeX Version 2 3%Documentation for SLaTeX 4%(c) Dorai Sitaram, 1991, 1994 5%dorai@cs.rice.edu 6 7\documentstyle[../../src/slatex]{article} 8 9\slatexdisable{enableslatex} 10 11\edef\atcatcodebeforepreamble{\the\catcode`@} 12\catcode`@11 13 14\inputifpossible{multicol.sty} 15 16%if Frank Mittelbach's multicol.sty is not 17%available, the index will simply waste some paper 18 19%latex wastes too much paper, so... 20 21\textheight 11in 22\textwidth 8.5in 23\oddsidemargin 1.25in 24\advance\textheight -2\oddsidemargin 25\advance\textwidth -2\oddsidemargin 26\advance\oddsidemargin -1in 27\evensidemargin\oddsidemargin 28\topmargin\oddsidemargin 29\advance\topmargin -\headheight 30\advance\topmargin -\headsep 31 32%latex's section headings are way too obnoxiously 33%large, so... 34 35\def\nolargefonts{\let\large\normalsize 36\let\Large\normalsize 37\let\LARGE\normalsize 38\let\huge\normalsize 39\let\Huge\normalsize} 40 41%mini headers for introducing paragraphs 42 43\def\re{\medbreak\parindent0pt% 44\aftergroup\smallskip\obeylines 45\llap{$\searrow$\enspace\enspace}} 46 47%a wide line 48 49\def\wideline{\centerline{\hrulefill}} 50 51%smart italics 52 53\def\italicsbegin{\begingroup\it} 54\def\italicsend{\endgroup\futurelet\next\italiccorrection} 55\def\italiccorrection{\ifx\next,\else\ifx\next.\else\/\fi\fi} 56\def\italicstoggle{\italicsbegin\let\italicstoggle\italicsend} 57\catcode`\_\active 58\def_{\ifmmode\sb\else\expandafter\italicstoggle\fi} 59 60%quote.tex, by Hunter Goatley 61 62{\catcode`\"\active 63% 64\gdef\begindoublequotes{\global\catcode`\"\active 65\global\let\dblqu@te=L} 66% 67\gdef"{\ifinner\else\ifvmode\let\dblqu@te=L\fi\fi 68\if L\dblqu@te``\global\let\dblqu@te=R\else 69\let\xxx=\spacefactor 70''\global\let\dblqu@te=L% 71\spacefactor\xxx 72\fi}} 73 74\def\enddoublequotes{\catcode`\"=12} 75 76%nicer \verb 77 78\begingroup\catcode`[1\catcode`]2\catcode`\{12\catcode`\}12% 79\gdef\@sverb#1[\if#1{\def\@tempa##1}[\leavevmode\null##1\endgroup]\else 80\def\@tempa##1#1[\leavevmode\null##1\endgroup]\fi\@tempa]% 81\endgroup 82 83%nicer \footnote 84 85\let\latexfootnote\footnote 86\def\footnote{\unskip\latexfootnote\bgroup\let\dummy=} 87 88%item 89 90\let\o\item 91 92%index environment that exploits multicol.sty if 93%available... 94 95\renewenvironment{theindex}% 96{\parindent0pt% 97\let\item\@idxitem 98\section*{Index}% 99\ifx\multicols\undefined\else 100\begin{multicols}{2}\fi}% 101{\ifx\multicols\undefined\else 102\end{multicols}\fi} 103 104\catcode`@\atcatcodebeforepreamble 105 106\begindoublequotes 107\makeindex 108 109%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 110 111\title{How to Use SLaTeX} 112 113\author{Dorai Sitaram\\ 114{\tt dorai@cs.rice.edu}\\ 115Department of Computer Science\\ 116Rice University\\ 117Houston, TX 77251--1892} 118 119\date{Gestated 1990\\ 120First public release, Mar. 1991\\ 121First major update, Dec. 1991\\ 122Current update, Jan. 1994} 123 124\begin{document} 125\maketitle 126\nolargefonts 127 128\section{Introduction} 129 130SLaTeX\index{introduction} is a Scheme program 131that allows you to write programs or program fragments 132"as is" in your TeX or LaTeX source. SLaTeX is 133particularly geared to the programming languages Scheme 134and other Lisps, e.g., Common Lisp. The formatting of 135the code includes assigning appropriate fonts to the 136various tokens in the code (keywords, variables, 137constants, data), at the same time retaining the proper 138indentation when going to the non-monospace 139(non-typewriter) fonts provided by TeX. SLaTeX comes 140with two databases that recognize the identifier 141conventions of Scheme and Common Lisp respectively. 142These can be modified by the user using easy TeX 143commands. In addition, the user can inform SLaTeX to 144typeset certain identifiers as specially suited LaTeX 145expressions (i.e., beyond just fonting them). All this 146is done without interfering with the identifier 147conventions of the language of the programming code at 148all. In sum, no change need be made to your 149(presumably running) program code in order to get a 150typeset version suited to the particular need: you can 151get a spectrum of styles ranging from _no_ fonting 152through basic default fonting to various 153"mathematical"-looking output for pedagogic or other 154reasons. 155 156\enableslatex 157Other packages~\cite{schemeweb,lisp2tex} for 158typesetting code fragments use a \verb{verbatim} 159environment where all the characters are in a 160\verb{monospace typewriter font}. This \verb{monospace} 161ensures that the indentation is not affected. However, 162the resulting output fails to distinguish between the 163various tokens used in the code, e.g., boldface for 164keywords like 165\scheme{define} and \scheme{lambda}, sans-serif for 166constants like \scheme{#t} and \scheme{42}, and italics 167for variables such as \scheme{x} and 168\scheme{y} in \scheme{(lambda (x y) (cons x (cons y 169'())))}. 170\slatexdisable{enableslatex} 171 172The program SLaTeX provides a convenient way of 173capturing the indentation information as well as 174assigning distinguishing fonts to code tokens without 175requiring the user to worry about fonting and spacing. 176It uses temporary files to store its typeset version of 177the user's code fragments and then calls TeX or LaTeX 178on the user's TeX files as well as these temporaries. 179 180The following section will introduce you to the basic 181use of SLaTeX with a small example. 182Section~\ref{slatex.sty} introduces the SLaTeX style 183files. Section~\ref{glossary} gives a complete 184description of all the SLaTeX control sequences. These 185include commands for manipulating output positioning, 186enhancing the database, changing the fonting defaults, 187adding special symbols, and selective disabling of 188SLaTeX. Section~\ref{preamble} desribes how to set up 189a preamble that reflects your typesetting taste. 190Section~\ref{ftp} contains information on obtaining and 191installing SLaTeX. 192 193\section{A quick illustration of using SLaTeX} 194\label{quick} 195\index{quick illustration} 196 197This section presents a short example of SLaTeX use. 198We first look at a LaTeX file using SLaTeX commands, 199and then give a plain TeX version of the same file. We 200will see that there are minor differences between the 201ways SLaTeX is used with plain TeX and LaTeX (but see 202\verb{\defslatexenvstyle} for a way to use the 203plain-TeX style with the LaTeX format, and conversely, 204the LaTeX style with the plain format). 205 206\subsection{For LaTeX users} 207\index{LaTeX} 208\index{scheme@\verb{\scheme}} 209\index{schemedisplay@\verb{schemedisplay}!in LaTeX} 210\index{in-text Scheme code} 211\index{displayed Scheme code} 212\index{slatex.sty@\verb{slatex.sty}} 213\index{slatex.sty@\verb{slatex.sty}!as document style} 214 215Consider the following LaTeX (_and_ SLaTeX) file 216\verb{quick.tex}: 217 218\wideline 219\begin{verbatim} 220% quick.tex 221\documentstyle[slatex]{article} 222%or: 223% \documentstyle{article} 224% \input slatex.sty 225 226In Scheme, the expression \scheme|(set! x 42)| returns 227an unspecified value, rather than \scheme'42'. 228However, one could get a \scheme{set!} of the latter 229style by: 230 231\begin{schemedisplay} 232(define-syntax setq 233 (syntax-rules () 234 [(setq x a) 235 (begin (set! x a) 236 x)])) 237\end{schemedisplay} 238 239\end{document} 240\end{verbatim} 241\wideline 242 243First, the SLaTeX definitions in the style file 244\verb{slatex.sty} are loaded into your LaTeX file --- 245this may be done either as a \verb{\documentstyle} 246option, or through an \verb{\input} command. 247 248\index{scheme@\verb{\scheme}!using grouped argument} 249 250In-text code is introduced by the SLaTeX control 251sequence \verb{\scheme} and is flanked by a pair of 252identical characters that are not alphabets or 253"\verb|{|". As a special convenient case, SLaTeX also 254allows the form \verb|\scheme{...}|. 255 256The SLaTeX control sequences for displayed code are the 257opening \verb|\begin{schemedisplay}| and the closing 258\verb|\end{schemedisplay}|. 259 260The file is now SLaTeX'd by running the command 261\verb{slatex} on it from the Unix or DOS command line: 262 263\begin{verbatim} 264slatex quick 265\end{verbatim} 266or 267\begin{verbatim} 268slatex quick.tex 269\end{verbatim} 270This calls a Scheme program \verb{slatex.scm} that 271typesets the Scheme code fragments in \verb{quick.tex} 272into temporary files. Thereafter, \verb{quick.tex} along with 273the temporary files are then passed to LaTeX. (For 274information on judiciously reusing temporary files, see 275\verb{\slatexseparateincludes}.) 276The resulting 277\verb{quick.dvi} file, when viewed or printed looks like: 278 279\enableslatex 280\wideline 281In Scheme, the expression \scheme|(set! x 42)| returns 282an unspecified value, rather than 283\scheme'42'. However, one could get a \scheme{set!} of 284the latter style by: 285 286\begin{schemedisplay} 287(define-syntax setq 288 (syntax-rules () 289 [(setq x a) 290 (begin (set! x a) 291 x)])) 292\end{schemedisplay} 293\wideline 294 295\index{recognizing new syntactic keywords automatically} 296 297Note that \scheme{setq}, although not normally a 298syntactic keyword in Scheme is nevertheless 299automatically recognized as such because of the context 300in which it occurs. No special treatment is needed to 301ensure that it will continue be treated as such in any 302subsequent Scheme code in the document. 303 304\slatexdisable{enableslatex} 305 306\subsection{For plain TeX users} 307\index{plain TeX} 308\index{scheme@\verb{\scheme}} 309\index{schemedisplay@\verb{schemedisplay}!in plain TeX} 310\index{in-text Scheme code} 311\index{displayed Scheme code} 312 313Plain TeX users invoke SLaTeX much the same way, but 314for only two exceptions. First, since TeX doesn't have 315\verb{\documentstyle}, the file \verb{slatex.sty} is 316introduced via an \verb{\input} statement before its 317commands can be used in the plain TeX source. 318 319\index{environments} 320 321Second, since plain TeX does not have LaTeX's 322\verb|\begin{|_env_\verb|}...\end{|_env_\verb|}| 323style of environments, any 324environment commands in SLaTeX are invoked with the 325opening \verb{\}_env_ and the closing \verb{\end}_env_. 326 327The plain TeX version of \verb{quick.tex} looks like: 328 329\wideline 330\begin{verbatim} 331% quick.tex 332\input slatex.sty 333 334In Scheme, the expression \scheme|(set! x 42)| returns 335an unspecified value, rather than \scheme'42'. 336However, one could get a \scheme{set!} of the latter 337style by: 338 339\schemedisplay 340(define-syntax setq 341 (syntax-rules () 342 [(setq x a) 343 (begin (set! x a) 344 x)])) 345\endschemedisplay 346 347\bye 348\end{verbatim} 349\wideline 350 351The file is now SLaTeX'd by invoking \verb{slatex} as 352before --- SLaTeX is clever enough to figure out 353whether the file it operates on should later be send to 354LaTeX or plain Tex. 355 356\section{The style files} 357\label{slatex.sty} 358\index{slatex.sty@\verb{slatex.sty}} 359 360In short, the LaTeX (or TeX) file that is given to 361SLaTeX undergoes some code-setting preprocessing and is 362then handed over to LaTeX (or TeX). The style file 363\verb{slatex.sty} defines the appropriate commands so 364that LaTeX (or TeX) can recognize the SLaTeX-specific 365directives and either process or ignore them. You may 366either \verb|\input| the file \verb{slatex.sty} as 367usual, or use it as the \verb|\documentstyle| option 368\verb{slatex}. 369 370\index{cltl.sty@\verb{cltl.sty}} 371\index{SLaTeX database!for Scheme} 372\index{SLaTeX database!for Common Lisp} 373\index{SLaTeX database!modifying} 374 375The default database of SLaTeX recognizes the keywords 376and constants of Scheme. The database can be modified 377with the commands \verb{\setkeyword}, 378\verb{\setconstant}, \verb{\setvariable}, 379\verb{\setspecialsymbol} and \verb{\unsetspecialsymbol} 380(q.v.). If you're using Common Lisp rather than 381Scheme, use \verb{cltl.sty} instead of 382\verb{slatex.sty}. 383\verb{cltl.sty} loads \verb{slatex.sty} and modifies 384the database to reflect Common Lisp. You may fashion 385your own \verb{.sty} files on the model of 386\verb{cltl.sty}. 387 388\section{SLaTeX's control sequences} 389\label{glossary} 390\index{SLaTeX control sequences} 391 392You've already seen the SLaTeX control sequence 393\verb|\scheme| and the environment 394\verb{schemedisplay}. These suffice for quite a few 395instances of handling code. However, you will 396occasionally require more control on the typesetting 397process, and the rest of this section describes the 398complete 399\footnote{At least that's what you're supposed 400to think...} list of SLaTeX control sequences shows you 401the ropes. 402 403{\re 404\verb{schemedisplay}} 405\index{schemedisplay@\verb{schemedisplay}} 406\index{displayed Scheme code} 407 408[In plain TeX: \verb{\schemedisplay} ... 409\verb{\endschemedisplay}; in LaTeX: 410\verb|\begin{schemedisplay}| ... 411\verb|\end{schemedisplay}|; but see \verb{\defslatexenvstyle}.] 412 413Typesets the enclosed code, which is typically several 414lines of code indented as you normally do in your 415Scheme files. E.g., 416 417\begin{verbatim} 418\begin{schemedisplay} 419(define compose ;this is also known as $B$ 420 (lambda (f g) 421 (lambda (x) 422 (apply f (g x))))) 423\end{schemedisplay} 424is the "compose" function. 425\end{verbatim} 426produces 427 428\enableslatex 429\begin{schemedisplay} 430(define compose ;this is also known as $B$ 431 (lambda (f g) 432 (lambda (x) 433 (apply f (g x))))) 434\end{schemedisplay} 435\slatexdisable{enableslatex} 436is the "compose" function. 437 438As with all LaTeX environment enders, if the line after 439\verb|\end{schemedisplay}| contains 440non-whitespace text, the paragraph continues. 441Otherwise --- i.e., when \verb|\end{schemedisplay}| is 442followed by at least one blank line --- a fresh 443paragraph is started. Similarly, in plain TeX, a fresh 444paragraph is started after a \verb{schemedisplay} only 445if 446\verb|\endschemedisplay| is followed by at least one 447blank line. 448 449\index{Scheme comments} 450 451Comments in Scheme are usually introduced by "\verb{;}" 452(semicolon). The rest of the line after a "\verb{;}" 453is set as a line in LaTeX LR mode. 454 455\index{TeX paragraphs amidst Scheme code} 456 457Separate _blocks_ of code can either be introduced in 458different \verb{schemedisplay} environments or put in a 459single \verb{schemedisplay} and separated by a line with 460a "\verb{;}" in the first column. This "\verb{;}" is 461not typeset and anything following it on the line is 462set in (La)TeX LR paragraph mode. Consecutive lines 463with "\verb{;}" in the first column are treated 464as input for a TeX paragraph, with words possibly 465moved around from line to line to ensure justification. 466When in paragraph mode, the first line that has _no_ 467leading "\verb{;}" signals a fresh block 468of Scheme code within the 469\verb{schemedisplay}. (The \verb{schemedisplay} may 470end, or commence, on either a paragraph or a Scheme 471code block.) 472 473E.g., 474 475\begin{verbatim} 476\begin{schemedisplay} 477(define even? ; testing evenness 478 (lambda (n) 479 (if (= n 0) #t (not (odd? (- n 1)))))) 480; The procedures {\it even?} above 481; and {\it odd?} below are mutually 482; recursive. 483(define odd? ; testing oddness 484 (lambda (n) 485 (if (= n 0) #f (not (even? (- n 1)))))) 486\end{schemedisplay} 487\end{verbatim} 488produces 489 490\enableslatex 491\begin{schemedisplay} 492(define even? ; testing evenness 493 (lambda (n) 494 (if (= n 0) #t (not (odd? (- n 1)))))) 495; The procedures {\it even?} above 496; and {\it odd?} below are mutually 497; recursive. 498(define odd? ; testing oddness 499 (lambda (n) 500 (if (= n 0) #f (not (even? (- n 1)))))) 501\end{schemedisplay} 502\slatexdisable{enableslatex} 503 504SLaTeX can recognize that blocks of code are separate 505if you have at least one empty line separating them. 506I.e., there is no need for empty "\verb{;}" lines. This 507convenience is to accommodate Scheme files where 508definitions are usually separated by one or more blank 509lines. 510 511\index{schemedisplay@\verb{schemedisplay}!allowing page 512breaks in} 513 514Intervening paragraphs, either with lines with a 515leading "\verb{;}", or with blank lines, are ideal 516spots for \verb{schemedisplay} to allow pagebreaks. In 517fact, the default setting for \verb{schemedisplay} also 518allows pagebreaks _within_ a Scheme block, but it is 519easy to disable this (see entry for 520\verb{\rightcodeskip}). 521 522The space surrounding displayed Scheme code can be 523modified by setting the _skip_s \verb{\abovecodeskip}, 524\verb{\belowcodeskip}, \verb{\leftcodeskip}, and 525\verb{\rightcodeskip} (q.v.). 526 527Note: see \verb{schemeregion}. 528 529{\re 530\verb{\scheme}} 531\index{scheme@\verb{\scheme}} 532\index{in-text Scheme code} 533 534Typesets its argument, which is enclosed in arbitrary 535but identical non-alphabetic and non-\verb|{| 536characters, as in-text code. Special case: 537\verb|\scheme{...}| is a convenience (provided the 538\verb|...| doesn't contain a 539\verb|}|). E.g., \verb+\scheme|(call/cc (lambda (x) x))|+ 540and \verb+\scheme{(call/cc (lambda (x) x))}+ both 541produce 542\enableslatex 543\scheme{(call/cc (lambda (x) x))}. 544\slatexdisable{enableslatex} 545\index{scheme@\verb{\scheme}!using grouped argument} 546 547\index{nesting SLaTeX control sequences} 548It _is_ permitted to intermix calls to 549\verb{schemedisplay} and 550\verb|\scheme|. Thus, 551 552\begin{verbatim} 553\begin{schemedisplay} 554(define factorial 555 (lambda (n) 556 (if (= n 0) ; \scheme{(zero? n)} also possible 557 1 (* n (factorial (- n 1)))))) ; or \scheme{... (sub1 1)} 558\end{schemedisplay} 559\end{verbatim} 560produces 561 562\enableslatex 563\begin{schemedisplay} 564(define factorial 565 (lambda (n) 566 (if (= n 0) ; \scheme{(zero? n)} also possible 567 1 568 (* n (factorial (- n 1)))))) ; or \scheme{... (sub1 1)} 569\end{schemedisplay} 570\slatexdisable{enableslatex} 571 572Note: see \verb{schemeregion}. 573 574{\re 575\verb{\schemeresult}} 576\index{schemeresult@\verb{\schemeresult}} 577 578Typesets its argument, which is enclosed in arbitrary 579but identical non-alphabetic and non-\verb|{| 580characters, as in-text Scheme "result" or data: i.e., 581keyword and variable fonts are disabled. Special 582convenient case (as for \verb|\scheme|): 583\verb|\schemeresult{...}|. E.g., 584\index{schemeresult@\verb{\schemeresult}!using grouped argument} 585 586\begin{verbatim} 587\scheme|((lambda () (cons 'lambda 'cons)))| yields 588\schemeresult|(lambda . cons)|. 589\end{verbatim} 590produces 591 592\enableslatex 593\scheme|((lambda () (cons 'lambda 'cons)))| yields 594\schemeresult|(lambda . cons)|. 595\slatexdisable{enableslatex} 596 597{\re 598\verb{schemebox}} 599\index{schemebox@\verb{schemebox}} 600\index{boxed Scheme code} 601 602[In plain TeX: \verb{\schemebox} ... 603\verb{\endschemebox}; in LaTeX: 604\verb|\begin{schemebox}| ... 605\verb|\end{schemebox}|; but see \verb{defslatexenvstyle}.] 606 607The \verb{schemebox} environment is similar to 608\verb{schemedisplay} except that the code is provided 609as a "box" (i.e., it is not "displayed" in the standard 610way). Indeed, when the appropriate skip parameters are 611set, \verb{schemedisplay} itself _may_ 612\footnote{Yes, _may_: Not all \verb{schemedisplay}s invoke 613\verb{schemebox}, and if you're curious why, 614see entry for \verb{\rightcodeskip}. It is a matter of 615whether pagebreaks within Scheme code are allowed or 616not.} use a 617\verb{schemebox} to create a box of code that is 618set off with all-round space as a display. 619 620Saving a \verb{schemebox} in an explicit box allows you 621to move your typeset code arbitrarily. 622 623Note: see \verb{schemeregion}. 624 625{\re 626\verb{\schemeinput}} 627\index{schemeinput@\verb{schemeinput}} 628\index{inputting Scheme files as is} 629 630This can be used to input Scheme files as typeset code. 631(Unlike LaTeX's \verb|\input|, \verb|\schemeinput|'s 632argument must always be grouped.) The Scheme file can 633be specified either by its full name, or without its 634extension, if the latter is \verb{.scm}, \verb{.ss} or 635\verb{.s}. E.g., 636 637\begin{verbatim} 638\schemeinput{evenodd.scm} % the .scm is optional! 639\end{verbatim} 640(where \verb{evenodd.scm} is the name of a Scheme file 641containing the code for 642\enableslatex 643\scheme{even?} and \scheme{odd?} above) produces the same 644effect as the 645\verb{schemedisplay} version. 646\slatexdisable{enableslatex} 647 648Note: see \verb{schemeregion}. 649 650{\re 651\verb{schemeregion}} 652\index{schemeregion@\verb{schemeregion}} 653\index{nesting SLaTeX control sequences} 654 655[In plain TeX: \verb{\schemeregion} ... 656\verb{\endschemeregion}; in LaTeX: 657\verb|\begin{schemeregion}| ... 658\verb|\end{schemeregion}|; but see \verb{defslatexenvstyle}.] 659 660Calls to \verb|\scheme|, \verb|\schemeresult|, 661\verb{schemedisplay}, \verb{schemebox} or 662\verb|schemeinput| can be nested in (a Scheme comment) 663of other calls. In LaTeX text, they can occur in 664bodies of environments or otherwise grouped. However, 665they cannot normally be passed as arguments to macros 666or included in bodies of macro definitions, even though 667these are complete calls and not parameterized with 668respect to macro arguments. To be able to do this, you 669should cordon off such a text with the 670\verb{schemeregion} environment. SLaTeX is fairly 671generous about where exactly you throw the cordon. 672 673E.g., you cannot have 674 675\begin{verbatim} 676... 677The code fragment 678$\underline{\hbox{\scheme{(call/cc I)}}}$ is ... 679... 680\end{verbatim} 681but you _can_ have 682 683\begin{verbatim} 684\begin{schemeregion} 685... 686The code fragment 687$\underline{\hbox{\scheme{(call/cc I)}}}$ is ... 688... 689\end{schemeregion} 690\end{verbatim} 691and this will produce 692 693\enableslatex 694\begin{schemeregion} 695... 696 697The code fragment 698$\underline{\hbox{\scheme{(call/cc I)}}}$ is ... 699 700... 701\end{schemeregion} 702\slatexdisable{enableslatex} 703 704Thus, the \verb{schemeregion} environment makes it 705possible to put SLaTeX-specific commands inside macro 706arguments or macro definitions without causing rupture. 707Normally, this can't be done since SLaTeX-specific 708commands correspond to \verb{comment}-like regions of 709LaTeX code once SLaTeX is done preprocessing your text. 710These \verb{comment} regions share the characteristic of 711LaTeX's \verb{verbatim} regions, which also can't appear 712in macro arguments or definitions. 713 714To solve this, you enclose the offending text in a 715\verb{schemeregion} environment. This "inlines" all 716the calls to SLaTeX in its body instead of commenting 717them and then invoking \verb|\input|, thus escaping 718the fate described above. They are no-ops as far as 719non-SLaTeX commands are concerned. However, while a 720\verb{schemeregion} allows its constituent SLaTeX 721commands to be included in macro arguments and bodies, 722it itself cannot be so included. Thus, your 723\verb{schemeregion} should be in a position that 724satisfies the property A: either directly at the 725"top-level" or in a LaTeX environment that satisfies A. 726Since this recursive rule might look weird, you may 727just stick to calling \verb{schemeregion} at the 728"top-level". Or, you may even wrap each of your LaTeX 729files in one huge \verb{schemeregion} if you so wish. 730This will cover any obscure "non-robust" use of the 731SLaTeX primitives --- however, SLaTeX will run slower. 732(The term "robust" is not necessarily used in the same 733sense as in LaTeX.) 734 735Note that SLaTeX commands are made robust only if they 736are surrounded textually (lexically) by a 737\verb{schemeregion}. A region marker doesn't have 738dynamic scope in the sense that LaTeX files loaded 739using \verb|\input| from within a 740\verb{schemeregion} will not inherit it. In summary, a 741\verb{schemeregion} makes "robust" all calls to 742\verb|\scheme|, \verb{schemedisplay}, \verb{schemebox} 743and 744\verb|\schemeinput| within it. 745 746{\re 747\verb{\setkeyword} 748\verb{\setconstant} 749\verb{\setvariable}} 750\index{setkeyword@\verb{\setkeyword}} 751\index{setconstant@\verb{\setconstant}} 752\index{setvariable@\verb{\setvariable}} 753\index{SLaTeX database!modifying} 754 755SLaTeX has a database containing information about 756which code tokens are to be treated as {\bf keywords}, 757which as {\sf constants}, and which as _variables_. 758However, there will always be instances where the user 759wants to add their own tokens to these categories, or 760perhaps even modify the categories as prescribed by 761SLaTeX. The control sequences that enable the user to 762do these are 763\verb|\setkeyword|, \verb|\setconstant|, and 764\verb|\setvariable|. Their arguments are entered as 765a (space-separated) list enclosed in braces 766(\verb|{}|): SLaTeX learns that these are henceforth 767to be typeset in the appropriate font. E.g., 768 769\enableslatex 770\begin{verbatim} 771\setconstant{infinity -infinity} 772\end{verbatim} 773tells SLaTeX that \scheme{infinity} and 774\scheme{-infinity} are to be typeset as constants. 775\slatexdisable{enableslatex} 776 777\index{recognizing new syntactic keywords automatically} 778 779The user need not use \verb|\setkeyword| specify such 780new keywords as are introduced by Scheme's and Common 781Lisp's syntactic definition facilities, viz., 782\enableslatex 783\scheme{define-syntax}/\scheme{syntax-rules}, 784\scheme{defmacro}, \scheme{extend-syntax}, 785\scheme{define-macro!}: SLaTeX automatically recognizes 786new macros defined using these facilities. 787\slatexdisable{enableslatex} 788 789{\re 790\verb{\setspecialsymbol} 791\verb{\unsetspecialsymbol}} 792\index{setspecialsymbol@\verb{\setspecialsymbol}} 793\index{unsetspecialsymbol@\verb{\unsetspecialsymbol}} 794\index{SLaTeX database!modifying} 795\index{recognizing special symbols} 796 797These commands are useful to generate 798"mathematical"-looking typeset versions of your code, 799over and beyond the fonting capabilities provided by 800default. For instance, although your code is 801restricted to using ascii identifiers that follow some 802convention, the corresponding typeset code could be 803more mnemonic and utilize the full suite of 804mathematical and other symbols provided by TeX. This 805of course should not require you to interfere with your 806code itself, which should run in its ascii 807representation. It is only the typeset version that 808has the new look. For instance, you might want all 809occurrences of \verb|lambda|, \verb|and|, 810\verb|equiv?|, 811\verb|below?|, \verb|above?|, \verb|a1| and \verb|a2| in 812your code to be typeset as $\lambda$, $\land$, $\equiv$, 813$\sqsubseteq$, $\sqsupseteq$, $a_1$ and $a_2$ respectively. 814To do this, you should \verb|\setspecialsymbol| the 815concerned identifier to the desired TeX expansion, viz., 816 817\enableslatex 818\begin{verbatim} 819\setspecialsymbol{lambda}{$\lambda$} 820\setspecialsymbol{and}{$\land$} 821\setspecialsymbol{equiv?}{$\equiv$} 822\setspecialsymbol{below?}{$\sqsubseteq$} 823\setspecialsymbol{above?}{$\sqsupseteq$} 824\setspecialsymbol{a1}{$a_1$} 825\setspecialsymbol{a2}{$a_2$} 826\end{verbatim} 827\slatexdisable{enableslatex} 828Now, typing 829 830\begin{verbatim} 831\begin{schemedisplay} 832(define equiv? 833 (lambda (a1 a2) 834 (and (below? a1 a2) (above? a1 a2)))) 835\end{schemedisplay} 836\end{verbatim} 837produces 838 839\enableslatex 840\begin{schemedisplay} 841(define equiv? 842 (lambda (a1 a2) 843 (and (below? a1 a2) (above? a1 a2)))) 844\end{schemedisplay} 845\slatexdisable{enableslatex} 846Note that with the above settings, \verb|lambda| and 847\verb|and| have lost their default keyword status, i.e., 848they will not be typed {\bf boldface}. To retrieve the 849original status of special symbols, you should use 850\verb|\unsetspecialsymbol|, e.g. 851 852\enableslatex 853\begin{verbatim} 854\unsetspecialsymbol{lambda and} 855\end{verbatim} 856Typing the same program after unsetting the special symbols 857as above produces, as expected: 858 859\begin{schemedisplay} 860(define equiv? 861 (lambda (a1 a2) 862 (and (below? a1 a2) (above? a1 a2)))) 863\end{schemedisplay} 864\slatexdisable{enableslatex} 865 866In effect, \verb|\setspecialsymbol| extends the 867basic "fonting" capability to arbitrary special 868typeset versions. 869 870{\re 871\verb{\schemecasesensitive}} 872\index{schemecasesensitive@\verb{\schemecasesensitive}} 873\index{case sensitivity} 874 875SLaTeX always typesets output that is of the same case 876as your input, regardless of the setting of the 877\verb|\schemecasesensitive| command. However, this command 878can be used to signal to SLaTeX that all case variations of 879an identifier are to be treated identically. E.g. typing 880\verb|\schemecasesensitive{false}| implies that while 881\verb|lambda| continues to be a keyword, so also are 882\verb|Lambda|, \verb|LAMBDA| and \verb|LaMbDa|. 883\verb|\schemecasesensitive{true}| reverts it back to 884the default mode where case is significant in 885determining the class of a token. 886 887Note that the status \verb|\schemecasesensitive| also 888affects the "special symbols" of the previous item. 889Thus, in the default case-_sensitive_ setting, only the 890case-significant symbol as mentioned in the call to 891\verb|\setspecialsymbol| will be replaced by the 892corresponding LaTeX expansion. In a case-_in_sensitive 893setting, all case variations of the special symbol will 894be replaced. 895 896{\re 897\verb{\abovecodeskip} 898\verb{\belowcodeskip} 899\verb{\leftcodeskip} 900\verb{\rightcodeskip}} 901\index{abovecodeskip@\verb{\abovecodeskip}} 902\index{belowcodeskip@\verb{\belowcodeskip}} 903\index{leftcodeskip@\verb{\leftcodeskip}} 904\index{rightcodeskip@\verb{\rightcodeskip}} 905\index{schemedisplay@\verb{schemedisplay}!adjusting display parameters} 906 907These are the parameters used by \verb{schemedisplay} for 908positioning the displayed code. The default values are 909 910\begin{verbatim} 911\abovecodeskip \medskipamount 912\belowcodeskip \medskipamount 913\leftcodeskip 0pt 914\rightcodeskip 0pt 915\end{verbatim} 916This produces a flushleft display. The defaults can be 917changed to get new display styles. E.g., the 918assignment 919 920\begin{verbatim} 921\leftcodeskip5em 922\end{verbatim} 923shifts the display from the left by a constant 5 ems. 924 925\index{schemedisplay@\verb{schemedisplay}!allowing page 926breaks in} 927\index{schemedisplay@\verb{schemedisplay}!disallowing 928page breaks in} 929 930In both the above cases, the \verb{schemedisplay} 931environment will be broken naturally across page 932boundaries at the right spot if the code is too long to 933fit a single page. In fact, automatic pagebreaks 934within the Scheme code are allowed if and only if 935\verb{\rightcodeskip} is 0pt (its default value). For 936all other values of \verb{\rightcodeskip}, each Scheme 937code block in a \verb{schemedisplay} is guaranteed to 938be on the same page. If you like your current left 939indentation, and you're not sure of what value to give 940\verb{\rightcodeskip}, but nevertheless don't want 941Scheme code broken across pages, you could set 942 943\begin{verbatim} 944\rightcodeskip=0.01pt %or 945\rightcodeskip=0pt plus 1fil 946\end{verbatim} 947 948The following explains why the above disable page 949breaks within the Scheme block. For example, suppose 950you'd set 951 952\begin{verbatim} 953\leftcodeskip=0pt plus 1fil 954\rightcodeskip=0pt plus 1fil 955\end{verbatim} 956This will get you a _centered_ display style. This is 957of course because the skip on each side of the code 958produces a spring~\cite{tex} that pushes the code to 959the center. But for this spring action to work nicely, 960the code must have been collected into an unbreakable 961box --- which is precisely what 962\verb{schemedisplay} does for each of its code blocks 963whenever it notices that the prevailing value of 964\verb{\rightcodeskip} is not the default zero. 965\footnote{0pt plus 1fil $\ne$ 0pt} 966 967It is this behind-the-scenes selective boxing that 968dictates whether a \verb{schemedisplay} block can or 969cannot be broken across a page boundary. And the 970value of \verb{\rightcodeskip} is used to govern this 971selection in a "reasonable" manner. 972 973{\re 974\verb{\keywordfont} 975\verb{\constantfont} 976\verb{\variablefont}} 977\index{keywordfont@\verb{\keywordfont}} 978\index{constantfont@\verb{\constantfont}} 979\index{variablefont@\verb{\variablefont}} 980\index{specifying SLaTeX's fonts} 981 982These decide the typefaces used for keywords, constants, 983and variables. The default definitions are: 984 985\begin{verbatim} 986\def\keywordfont#1{{\bf#1}} 987\def\constantfont#1{{\sf#1}} 988\def\variablefont#1{{\it#1\/}} 989\end{verbatim} 990 991This is close to the Little Lisper~\cite{ll} style. 992Redefine these control sequences for font changes. As 993an extreme case, defining all of them to 994\verb|{{\tt#1}}| typesets everything in monospace 995typewriter font, as, for instance, in SICP~\cite{sicp}. 996 997{\re 998\verb{\defschemedisplaytoken} 999\verb{\defschemetoken} 1000\verb{\defschemeresulttoken} 1001\verb{\defschemeinputtoken} 1002\verb{\defschemeregiontoken}} 1003\index{defschemedisplaytoken@\verb{\defschemedisplaytoken}} 1004\index{defschemetoken@\verb{\defschemetoken}} 1005\index{defschemeresulttoken@\verb{\defschemeresulttoken}} 1006\index{defschemeboxtoken@\verb{\defschemeboxtoken}} 1007\index{defschemeinputtoken@\verb{\defschemeinputtoken}} 1008\index{defining SLaTeX control sequences} 1009 1010These define the tokens used by SLaTeX to trigger 1011typesetting of in-text code, display code, box code, 1012and Scheme files. The default tokens are, as already 1013described, \verb{schemedisplay}, \verb|\scheme|, 1014\verb|\schemeresult|, \verb{schemebox}, 1015\verb|\schemeinput| and \verb{schemeregion} 1016respectively. If you want shorter or more mnemonic 1017tokens, the \verb|\defscheme*token| control sequences 1018prove useful. E.g., if you want \verb|\code| to be 1019your new control sequence for in-text code, use 1020\verb|\defschemetoken{code}|. All instances of 1021\verb|\code+...+| after this definition produce 1022in-text code, unless overridden by an 1023\verb|\undefschemetoken| command. 1024 1025One can have at any time any number of tokens for the 1026same activity. One consequence of this is that one can 1027have nested \verb{schemeregion}s, provided one has 1028different names for the nested call. Otherwise, the 1029\verb|\end| of an inner region will prematurely 1030terminate an outer region. 1031 1032{\re 1033\verb{\undefschemedisplaytoken} 1034\verb{\undefschemetoken} 1035\verb{\undefschemeresulttoken} 1036\verb{\undefschemeinputtoken} 1037\verb{\undefschemeregiontoken}} 1038\index{undefschemedisplaytoken@\verb{\undefschemedisplaytoken}} 1039\index{undefschemetoken@\verb{\undefschemetoken}} 1040\index{undefschemeresulttoken@\verb{\undefschemeresulttoken}} 1041\index{undefschemeboxtoken@\verb{\undefschemeboxtoken}} 1042\index{undefschemeinputtoken@\verb{\undefschemeinputtoken}} 1043\index{undefschemeregiontoken@\verb{\undefschemeregiontoken}} 1044\index{undefining SLaTeX control sequences} 1045 1046These _un_define the tokens used for triggering 1047typesetting in-text code, display code, box code, 1048Scheme files, and robust Scheme regions. Use these if 1049you want to use these tokens for other purposes and do 1050not want to unwittingly trip up the SLaTeX system. 1051 1052{\re 1053\verb{\defschememathescape} 1054\verb{\undefschememathescape}} 1055\index{defschememathescape@\verb{\defschememathescape}} 1056\index{undefschememathescape@\verb{\undefschememathescape}} 1057\index{TeX mathmode in SLaTeX} 1058\index{escape character for mathmode within Scheme} 1059 1060\verb|\defschememathescape{$}| defines the character 1061\verb|$| as a mathematical escape character to be used 1062within scheme code. (Any character other than 1063\verb|}| and whitespace may be chosen instead of 1064\verb|$|.) This allows one to use LaTeX-like 1065mathematical subformulas within Scheme code, e.g., 1066 1067\begin{verbatim} 1068\defschememathescape{$} 1069 1070\begin{schemedisplay} 1071(define $\equiv$ 1072 (lambda (a$_1$ a$_2$) 1073 ($\land$ ($\sqsubseteq$ a$_1$ a$_2$) 1074 ($\sqsupseteq$ a$_1$ a$_2$)))) 1075\end{schemedisplay} 1076\end{verbatim} 1077produces 1078 1079\enableslatex 1080\defschememathescape{$} 1081 1082\begin{schemedisplay} 1083(define $\equiv$ 1084 (lambda (a$_1$ a$_2$) 1085 ($\land$ ($\sqsubseteq$ a$_1$ a$_2$) 1086 ($\sqsupseteq$ a$_1$ a$_2$)))) 1087\end{schemedisplay} 1088\undefschememathescape{$} 1089\slatexdisable{enableslatex} 1090\verb|\undefschememathescape{$}| disables the 1091math-escape nature, if any, of \verb|$|. 1092 1093{\re 1094\verb{\slatexdisable}} 1095\index{slatexdisable@\verb{\slatexdisable}} 1096\index{disabling SLaTeX} 1097 1098The tokens for typesetting code, as also the token 1099\verb|\input| (which is sensitive to SLaTeX, since 1100the latter uses it to recursively process files within 1101files), can only be used as calls. If they occur in 1102the bodies of macro definitions, or their names are 1103used for defining other control sequences, SLaTeX will 1104not be able to process them. Sometimes, one wants to 1105use these tokens, say \verb|\input|, without having 1106SLaTeX try to process the inputted file. Or the name 1107\verb|\scheme| may be used in a verbatim environment, 1108and we don't want such an occurrence to trigger the 1109codesetting half of SLaTeX to look for code. 1110 1111Avoiding such uses altogether can be unduly 1112restrictive. 1113\footnote{Especially when one is writing a "How to ..." 1114manual like this where one both uses _and_ mentions the 1115control sequences!} One way out is to judiciously use 1116the \verb|\undefscheme*token| commands to temporarily 1117remove the SLaTeX-specificity of these names. Even 1118this can be painful. SLaTeX therefore provides the 1119commands \verb|\slatexdisable|. This takes one 1120argument word and makes the corresponding control 1121sequence out of it. Further, from this point in the 1122text, SLaTeX is disabled _until_ the manufactured 1123control sequence shows up. This mechanism makes it 1124possible to restrict SLaTeX to only appropriate 1125portions of the text. Note that the token 1126\verb|\slatexdisable| itself can appear in the text 1127succeeding its call. The only token that can restore 1128SLaTeX-sensitivity is the one created during the call 1129to \verb|\slatexdisable|. 1130 1131A typical example of the use of \verb|\slatexdisable| 1132is when you use the names \verb|\scheme| and 1133\verb|\begin{schemedisplay}| in a \verb{verbatim} 1134environment. E.g., 1135 1136{\medskip 1137\obeylines\parindent0pt 1138\verb|\slatexdisable{slatexenable}| 1139\verb|\begin{verbatim}| 1140\verb|slatex provides the command \scheme and the pair| 1141\verb|\begin{schemedisplay} and \end{schemedisplay} to typeset| 1142\verb|in-text and displayed Scheme code respectively.| 1143\verb|\end{verbatim}| 1144\verb|\slatexenable| 1145\medskip} 1146 1147produces the required 1148 1149\begin{verbatim} 1150slatex provides the command \scheme and the pair 1151\begin{schemedisplay} and \end{schemedisplay} to typeset 1152in-text and display Scheme code respectively. 1153\end{verbatim} 1154 1155{\re 1156\verb{\slatexignorecurrentfile}} 1157\index{slatexignorecurrentfile@\verb{\slatexignorecurrentfile}} 1158\index{disabling SLaTeX} 1159 1160This is a SLaTeX pragma included to improve efficiency. 1161If you're sure that the remaining portion of a certain 1162LaTeX (or TeX) file (including the files that would be 1163\verb|\input|ed by it) don't contain any SLaTeX 1164commands, then you may place this control sequence in 1165it at this point to signal SLaTeX that no preprocessing 1166is necessary for the rest of the file. 1167 1168{\re 1169\verb{\defslatexenvstyle}} 1170\index{defslatexenvstyle@\verb{\defslatexenvstyle}} 1171\index{plain TeX} 1172\index{LaTeX} 1173\index{environments} 1174 1175As section~\ref{quick} showed, the differences in SLaTeX 1176usage between plain TeX and LaTeX is simply a matter of 1177the difference in the "environment" styles of the two 1178formats. It is easy get the behavior of the one 1179format with the other. 1180 1181\begin{enumerate} 1182\o If you wish to use the plain-TeX style in LaTeX, 1183type 1184\begin{verbatim} 1185\defslatexenvstyle{tex} 1186\end{verbatim} 1187before first such use. 1188 1189\o Similarly, if you wish to use the LaTeX 1190\verb{\begin}/\verb{\end} style in plain TeX, use 1191\begin{verbatim} 1192\defslatexenvstyle{latex} 1193\end{verbatim} 1194_provided you have already defined \verb{\begin} and 1195\verb{\end} appropriately!_ 1196 1197Before doing this, you should keep in mind that 1198TeX already has an 1199\verb{\end} command --- which is used by TeX's 1200\verb{\bye} --- that ends the document. This function 1201should be saved under a different name, before 1202\verb{\end} can be redefined as an environment closer. 1203The following is one way to accomplish this: 1204\begin{verbatim} 1205\let\plaintexend\end 1206\outer\def\bye{\par\vfill\supereject\plaintexend} 1207\def\begin#1{\csname#1\endcsname} 1208\def\end#1{\csname end#1\endcsname} 1209\end{verbatim} 1210\end{enumerate} 1211 1212In either case, you can revert to the default style with 1213\verb|\defslatexenvstyle{latex}| and 1214\verb|\defslatexenvstyle{tex}| respectively. 1215 1216{\re 1217\verb{\slatexseparateincludes}} 1218\index{slatexseparateincludes@\verb{slatexseparateincludes}} 1219\index{reusing SLaTeX's temporary files} 1220 1221By default, the temporary files of SLaTeX use the name 1222of the topmost TeX file, i.e., the name stored under 1223\verb{\jobname}. In large LaTeX documents using 1224\verb{\include}, this may be unduly restrictive. 1225 1226To recapitulate, the \verb{slatex} command creates 1227temporary files to store typeset code and then passes 1228the baton on to TeX or LaTeX. If no significant change 1229has been made to the Scheme code (either in content or 1230in relative positioning) in the document, then 1231successive calls to (La)TeX could be made directly 1232using the old temporary files. This could be a time-saver, 1233since it avoids calling up the Scheme typesetter. 1234 1235However, in a large LaTeX document with 1236\verb{\include}s, these successive calls to LaTeX often 1237entail juggling the \verb{\include}s that are chosen. 1238In this case, even though the relative position of the 1239Scheme code is preserved within each \verb{include}d 1240file, the sequence perceived by the main file changes. 1241This spoils the invariance we needed if we'd wanted to 1242avoid calling SLaTeX unnecessarily. 1243 1244\index{reusing SLaTeX's temporary files!exploiting 1245LaTeX's \verb{\include}} 1246 1247To solve this, the SLaTeX command sequence 1248\verb{\slatexseparateincludes} --- which must be called 1249before the first occurrence of Scheme code in your 1250document --- 1251guarantees that each 1252\verb{\include}d file will generate its own pool of 1253temp files. Thus, if the SLaTeX 1254files are created once for each \verb{\include}, they 1255will be correctly loaded no matter what sequence of 1256\verb{\include}s is taken. 1257 1258{\re 1259\verb{\schemecodehook}} 1260\index{schemecodehook@\verb{\schemecodehook}} 1261\index{hook for \verb{schemedisplay} and 1262\verb{schemebox}} 1263 1264The user can define \verb{\schemecodehook} to be 1265anything. The hook will be evaluated inside each 1266subsequent call to \verb{schemedisplay} and 1267\verb{schemebox}. E.g., 1268 1269\begin{verbatim} 1270\let\schemecodehook\tiny 1271\end{verbatim} 1272converts your Scheme displays and boxes into {\tiny 1273small print}. 1274 1275The default value of the hook is \verb{\relax}, a 1276no-op. 1277 1278\section{Setting up a file that resets SLaTeX's 1279defaults} 1280\label{preamble} 1281\index{writing personal preamble} 1282\index{SLaTeX database!modifying} 1283 1284A sample style modification file for SLaTeX would 1285include redefinition of the names of the codesetting 1286control sequences, adjustment of the display 1287parameters, modification of the font assignments for 1288keywords/constants/variables/special symbols, and 1289addition of new keywords/constants/variables/special 1290symbols to SLaTeX's database. 1291 1292Let's assume you want 1293 1294\begin{itemize} 1295\o a centered display style with no vertical skips; 1296 1297\o the names \verb|\code|, \verb{schemefrag}, \verb{scmbox}, 1298\verb|\sinput| instead of \verb|\scheme|, 1299\verb{schemefrag}, \verb{schemebox} and 1300\verb|\schemeinput|; 1301 1302\o tokens to disregard case; 1303 1304\o the keywords to come out it \verb{typewriter}, the 1305constants in roman, and the variables in {\sl slant}; 1306 1307\o "\verb{und}" and "\verb{oder}" as keywords, 1308"\verb{true}" and "\verb{false}" as constants, 1309"\verb{define}" as a variable (overriding default as 1310keyword!), "\verb{F}" as a constant (\verb{f} will also 1311be a constant, due to case-insensitivity!); 1312 1313\o "\verb{top}" and "\verb{bottom}" to print as 1314$\top$ and $\bot$ respectively. 1315\end{itemize} 1316 1317This could be set up as 1318 1319\begin{verbatim} 1320\abovecodeskip 0pt 1321\belowcodeskip 0pt 1322\leftcodeskip 0pt plus 1fil 1323\rightcodeskip 0pt plus 1fil 1324 1325\undefschemetoken{scheme} 1326\undefschemeboxtoken{schemebox} 1327\undefschemedisplaytoken{schemedisplay} 1328\undefschemeinputtoken{schemeinput} 1329 1330\defschemetoken{code} 1331\defschemeboxtoken{scmbox} 1332\defschemedisplaytoken{schemegrag} 1333\defschemeinputtoken{sinput} 1334 1335\schemecasesensitive{false} 1336 1337\def\keywordfont#1{{\tt#1}} 1338\def\constantfont#1{{\rm#1}} 1339\def\variablefont#1{{\sl#1\/}} 1340 1341\setkeyword{und oder} 1342\setconstant{true false} 1343\setvariable{define} 1344\setconstant{F} 1345 1346\setspecialsymbol{top}{$\top$} 1347\setspecialsymbol{bottom}{$\bottom$} 1348\end{verbatim} 1349 1350This file can then be \verb|\input| in the preamble of 1351your LaTeX document. 1352 1353\section{How to obtain and install SLaTeX} 1354\label{ftp} 1355\index{obtaining and installing SLaTeX} 1356 1357\enableslatex 1358\leftcodeskip=0pt plus 1fil 1359\rightcodeskip=0pt plus 1fil 1360\slatexdisable{enableslatex} 1361 1362SLaTeX is available via anonymous ftp from 1363\verb{cs.rice.edu} (or \verb{titan.cs.rice.edu}). 1364Login as 1365\verb{anonymous}, give your userid as password, change 1366to the directory \verb{public/dorai}, convert to 1367\verb{bin} mode, and get the file 1368\verb{slatex}_NN_\verb{.tar.gz}, where _NN_ is some 1369number. Un\verb{gzip}ping and un\verb{tar}ring 1370produces a directory \verb{slatex}, containing the 1371SLaTeX files. (The file \verb{manifest} lists the 1372files in the distribution --- make sure that nothing is 1373missing.) 1374 1375To install SLaTeX on your system: 1376 1377\begin{enumerate} 1378\o First change directory (\verb{cd}) to \verb{slatex}, the 1379directory housing the SLaTeX files. 1380\footnote{Some of the SLaTeX files use DOS-style CR-LF 1381newlines. You may want to use an appropriate newline 1382modifier to the SLaTeX files to make the files comply 1383with your operating system's newline format.} 1384 1385\o Edit the file \verb{config.dat} as suggested by the 1386comments in the file itself. 1387 1388\o Invoke your Scheme or Common Lisp interpreter. 1389Load the file \verb{config.scm}, i.e., type 1390 1391\enableslatex 1392\begin{schemedisplay} 1393(load "config.scm") 1394\end{schemedisplay} 1395\slatexdisable{enableslatex} 1396at the Scheme (or Common Lisp) prompt. This will 1397configure SLaTeX for your Scheme dialect and operating 1398system, creating a Scheme file called 1399\verb{slatex.scm}. (If you informed \verb{config.dat} 1400that your Scheme dialect is Chez, the file 1401\verb{slatex.scm} is a compiled version rather than 1402Scheme source.) The configuration process also creates 1403a batch file \verb{slatex.bat} (on DOS) or a shell 1404script \verb{slatex} (on Unix), for convenient 1405invocation of SLaTeX from your operating system command 1406line. A Scheme/Common Lisp file \verb{callsla.scm} is 1407also created --- this lets you call SLaTeX from the 1408Scheme/Common Lisp prompt. 1409 1410\o Exit Scheme/Common Lisp. 1411\end{enumerate} 1412 1413To set up paths and modify shell script/batch file: 1414 1415\begin{enumerate} 1416\o Copy (or move, or link) \verb{slatex.scm} into a 1417suitable place, e.g., your \verb{bin} or \verb{lib} 1418directory, or the system \verb{bin} or \verb{lib}. 1419 1420\o Copy (or move, or link) \verb{slatex.sty} into a 1421suitable place, i.e., somewhere in your \verb{TEXINPUTS} 1422path. For installing on a multiuser system, place in 1423the directory containing the LaTeX files (on mine this 1424is \verb{/usr/local/lib/tex/macros}). 1425 1426 1427\o \enableslatex 1428Copy (or move, or link) the shell script 1429\verb{slatex} or the batch file \verb{slatex.bat} to a 1430suitable place in your \verb{PATH}, e.g., your {bin} or 1431the system {bin} directory. Note that 1432\verb{slatex}(\verb{.bat}) sets 1433\scheme{SLaTeX.*texinputs*}. If you're making the same 1434shell script (or batch file) available to multiple 1435users, you should change the line 1436\begin{schemedisplay} 1437(set! SLaTeX.*texinputs* "...") 1438\end{schemedisplay} 1439to 1440\begin{schemedisplay} 1441(set! SLaTeX.*texinputs* (getenv "TEXINPUTS")) 1442\end{schemedisplay} 1443or some other dialect-dependent way of obtaining the 1444\verb{TEXINPUTS} environment variable. 1445\slatexdisable{enableslatex} 1446 1447\o Run \verb{slatex} on \verb{slatex-d.tex} (this 1448file!) for documentation. (This also serves as a check 1449that SLaTeX does indeed work on your machine.) Refer 1450to \verb{slatex-d.dvi} when befuddled. 1451\end{enumerate} 1452 1453If your dialect did not allow a nice enough shell 1454script or batch file, the following provides an 1455alternate route to unlocking SLaTeX. 1456 1457\subsection{Other ways of invoking SLaTeX} 1458 1459The configuration process creates shell script/batch 1460file \verb{slatex}(\verb{.bat}) for a standard invoking 1461mechanism for SLaTeX. The shell script/batch file is 1462created to exploit the way your Scheme is called, e.g., 1463matters like whether it accepts \verb{echo}'d 1464s-expressions (e.g., Chez) , whether it loads command 1465line files (e.g., SCM) , and whether it always checks 1466for an "init" file (e.g., MIT C Scheme). 1467 1468\begin{enumerate} 1469\o If your Scheme doesn't fall into either of these 1470categories, you may have to write your own 1471shell script/batch file or devise some other mechanism. 1472 1473\o The shell script/batch file invokes 1474Scheme/Common Lisp. If, 1475however, you are already in Scheme/Common Lisp and 1476spend most of the time continuously at the 1477Scheme/Common Lisp prompt rather than the operating 1478system prompt, you may avoid some of the delays 1479inherent in the shell script/batch file. 1480\end{enumerate} 1481 1482\enableslatex 1483The file \verb{callsla.scm}, which contains just one 1484small procedure named \scheme{call-slatex}, and which 1485is created by the configuration process, provides a 1486simple calling mechanism from Scheme/Common Lisp, as 1487opposed to the operating system command line. You may 1488use it as an alternative to the 1489\verb{slatex}(\verb{.bat}) shell script/batch file. 1490The usage is as follows: load 1491\verb{callsla.scm} into Scheme/Common Lisp 1492 1493\begin{schemedisplay} 1494(load "callsla.scm") 1495\end{schemedisplay} 1496and type 1497 1498\setspecialsymbol{<tex-file>}{\va{$\langle$tex-file$\rangle$}} 1499\begin{schemedisplay} 1500(call-slatex <tex-file>) 1501\end{schemedisplay} 1502when you need to call SLaTeX on the (La)TeX file 1503\scheme{<tex-file>}. This invokes the SLaTeX preprocessor on 1504\scheme{<tex-file>}. If your Scheme has a 1505\scheme{system} procedure 1506that can call the operating system command line, 1507\scheme{call-slatex} will also send your file to TeX or 1508LaTeX. If your Scheme does not have such a procedure, 1509\scheme{call-slatex} will simply prod you to call TeX 1510or LaTeX 1511yourself. 1512\slatexdisable{enableslatex} 1513 1514The outline of the shell script/batch file or 1515\verb{callsla.scm} or of any strategy you devise for 1516using SLaTeX should include the following actions: 1517 1518\begin{enumerate} 1519\o Load the file \verb{slatex.scm} (created by the 1520configuration process) into Scheme/Common Lisp. 1521 1522\o \enableslatex 1523Set the variable \scheme{SLaTeX.*texinputs*} to the 1524path \verb{TEXINPUTS} or \verb{TEXINPUT} used by 1525TeX 1526\footnote{There is some variation on the name of 1527this environment variable. Unix TeX's prefer 1528\verb{TEXINPUTS} with an \verb{S}, while DOS (e.g., 1529Eberhard Mattes's emTeX) favors \verb{TEXINPUT} without 1530the \verb{S}.} 1531to look for 1532\slatexdisable{enableslatex} 1533\verb|\input| 1534files. 1535 1536 1537\o \enableslatex 1538Call the procedure 1539\scheme{SLaTeX.process-main-tex-file} on the \verb{.tex} 1540file to be processed. 1541\slatexdisable{enableslatex} 1542 1543\o Call either \verb{latex} or \verb{tex} on the \verb{.tex} file. 1544\end{enumerate} 1545 1546 1547\enableslatex 1548You may devise your own way of calling 1549\scheme{SLaTeX.process-main-tex-file}, provided your 1550method makes sure that \verb{slatex.scm} has been 1551loaded, \scheme{SLaTeX.*texinputs*} set appropriately 1552_before_ the call and \verb{latex}/\verb{tex} is called 1553_after_ the call. 1554 1555Note that if you prefer to stay in Scheme/Common Lisp 1556most of the time, it is a good idea to pre-load the 1557procedure \scheme{call-slatex}, perhaps through an 1558"init" file. \scheme{call-slatex} is just a 1559"one-liner" "call-by-need" hook to SLaTeX and does not 1560take up much resources. (Global name clashes between 1561your own code and SLaTeX code won't occur unless you 1562use variable names starting with "\scheme{SLaTeX.}") If 1563you made no calls to \scheme{call-slatex}, the bigger 1564file \verb{slatex.scm} is not loaded at all. If you 1565make several calls to \scheme{call-slatex}, 1566\verb{slatex.scm} is loaded only once, at the time of 1567the first call. 1568\slatexdisable{enableslatex} 1569 1570\subsection{Dialects SLaTeX runs on} 1571\index{dialects SLaTeX runs on} 1572 1573\enableslatex 1574SLaTeX is implemented in R4RS-compliant Scheme (macros 1575are not needed). The code uses the non-standard 1576procedures \scheme{delete-file}, 1577\scheme{file-exists?} and \scheme{force-output}, but 1578a Scheme without these procedures can also run SLaTeX 1579(the configuration defines the corresponding variables 1580to be dummy procedures, since they are not crucial). 1581The distribution comes with code to allow SLaTeX to run 1582also on Common Lisp. The files \verb{readme} and 1583\verb{install} contain all the information necessary to 1584configure SLaTeX for your system. 1585\slatexdisable{enableslatex} 1586 1587SLaTeX has been tested successfully in the following 1588dialects: 1589 1590\begin{itemize} 1591\o _On Unix:_ 1592Chez Scheme (R. Kent Dybvig), Ibuki Common 1593Lisp (1987), MIT C Scheme, Elk (Oliver Laumann), 1594Scheme-to-C (Joel Bartlett), Scm (Aubrey Jaffer) and 1595UMB Scheme (William Campbell); 1596 1597\o _On MS-DOS:_ 1598MIT C Scheme, Scm (Aubrey Jaffer), Austin Kyoto Common 1599Lisp (William Schelter's enhanced version of Taiichi 1600Yuasa and Masami Hagiya's KCL) and CLisp (Bruno Haible 1601and Michael Stoll). 1602\iffalse PCScheme/Geneva (Larry Bartholdi and 1603Marc Vuilleumier) \fi 1604\end{itemize} 1605 1606If your Scheme is not mentioned here but _is_ 1607R4RS-compliant, please send a note to the author at 1608\verb{dorai@cs.rice.edu} describing your Scheme's 1609procedures for deleting files, testing file existence, 1610and forcing output, if any, and the configuration file 1611will be enhanced to accommodate the new dialect. 1612 1613Bug reports are most welcome --- send to 1614\verb{dorai@cs.rice.edu}. 1615\index{bug reports} 1616 1617\begin{thebibliography}{9} 1618\bibitem{sicp} H. Abelson and G.J. Sussman with J. 1619Sussman. Structure and Interpretation of Computer 1620Programs. MIT Press, 1985. 1621 1622\bibitem{r4rs} W. Clinger and J. Rees, eds. 1623Revised$^4$ Report on the Algorithmic Language Scheme. 16241991. 1625 1626\bibitem{ll} D.P. Friedman and M. Felleisen. The 1627Little Lisper. Science Research Associates, 1989. 1628 1629\bibitem{tex} D.E. Knuth. The TeXbook. 1630Addison-Wesley, 1984. 1631 1632\bibitem{latex} L. Lamport. LaTeX User's Guide and 1633Reference Manual. Addison-Wesley, 1986. 1634 1635\bibitem{schemeweb} J. Ramsdell. SchemeWeb. Scheme 1636Repository, nexus.yorku.ca, maintained by O. Yigit. 1637 1638\bibitem{lisp2tex} C. Queinnec. LiSP2TeX. Scheme 1639Repository. 1640 1641\bibitem{cltl2} G.L. Steele Jr. Common Lisp: The 1642Language, 2nd ed. Digital Press, 1990. 1643\end{thebibliography} 1644 1645%input slatex-d.ind, the index, if available. 1646%slatex-d.ind is generated by running 1647% makeind(e)x slatex-d 1648%after running latex on slatex-d. The next call 1649% latex slatex-d 1650%will include slatex-d.ind 1651 1652\inputifpossible{slatex-d.ind} 1653 1654\end{document} 1655 1656\index{schemedisplay@\verb{schemedisplay}!with plain TeX} 1657\index{schemebox@\verb{schemebox}!with plain TeX} 1658\index{schemeregion@\verb{schemeregion}!with plain TeX} 1659