%%% ==================================================================== %%% @LaTeX-file{ %%% author-1 = "Jeremy Gibbons", %%% author-2 = "Alan Jeffrey", %%% version = "1.1", %%% date = "02 June 1992", %%% time = "15:06:36 BST", %%% filename = "stmaryrd.tex", %%% address-1 = "Department of Computer Science %%% University of Aukland %%% Private Bag %%% Aukland %%% New Zealand", %%% address-2 = "School of Cognitive and Computing Sciences %%% University of Sussex %%% Brighton BN1 9QH %%% UK", %%% telephone-1 = "+64 9 373 7599 x 5120", %%% telephone-2 = "+44 273 606755 x 3238", %%% FAX-1 = "+64 9 373 7453", %%% FAX-2 = "+44 273 678188", %%% checksum = "57063 696 2497 23237", %%% email-1 = "jeremy@cs.aukuni.ac.nz", %%% email-2 = "alanje@cogs.sussex.ac.uk", %%% codetable = "ISO/ASCII", %%% keywords = "metafont symbols math fonts LaTeX module", %%% supported = "yes", %%% abstract = "This is the documentation for module.sty and %%% the St Mary's Road symbol font.", %%% docstring = "This is the documentation for module.sty and %%% the St Mary's Road symbol font. The font %%% contains a number of mathematical %%% characters which are not present in the %%% standard TeX and AMS symbol fonts. %%% %%% Copyright 1992 Jeremy Gibbons and Alan Jeffrey. %%% %%% The checksum field above contains a CRC-16 %%% checksum as the first value, followed by the %%% equivalent of the standard UNIX wc (word %%% count) utility output of lines, words, and %%% characters. This is produced by Robert %%% Solovay's checksum utility.", %%% package = "St Mary's Road", %%% dependencies = "ltugboat.sty tugboat.com stmaryrd.sty %%% module.sty stmary*.tfm" %%% } %%% ==================================================================== %%% %%% 27 Jun 1991, v1.0: Finished v1.0 of the documentation. %%% %%% 2 Jun 1992, v1.1: added the headers and changed our addresses. % A keyboard check: % % @ # $ % ^ & * ~ at hash dollar percent caret ampersand asterisk tilde % : ; , . colon semicolon comma period % ? ! question-mark exclamation-mark % " ' ` double-quote apostrophe back-quote % ( ) { } [ ] parentheses braces square-brackets % - + = / \ minus plus equals forward-slash backslash % _ | < > underscore vertical-bar less-than greater-than % \documentstyle[stmaryrd]{ltugboat} \title{The St Mary's Road symbol package} \author{Jeremy Gibbons} %\address{Programming Research Group\\ % Oxford University\\ % 11 Keble Road\\ % Oxford OX1 3QD\\ % UK} %\netaddress{jg@prg.ox.ac.uk} \address{Department of Computer Science\\ University of Aukland\\ Private Bag\\ Aukland\\ New Zealand} \netaddress{jeremy@cs.aukuni.ac.nz} \author{Alan Jeffrey} %\address{Department of Computer Sciences\\ % Chalmers University\\ % S-412 96 G\"oteborg\\ % Sweden} %\netaddress{jeffrey@cs.chalmers.se} \address{School of Cognitive and Computing Sciences\\ University of Sussex\\ Falmer\\ Brighton BN1 4QR\\ UK} \netaddress{alanje@cogs.sussex.ac.uk} % The current version of ltugboat.sty uses (and doesn't define) % \tensl. \font\tensl cmsl10 % The symbols environment for laying out symbol declarations. \def\symbols#1{\hbox\bgroup\count0=#1\startcolumn} \def\endsymbols{\endcolumn\egroup} \def\startcolumn{\vtop\bgroup\count1=\count0\relax} \def\endcolumn{\egroup} \def\dosymbol#1{\hbox to .33\textwidth{\hbox to 2em{\hfil$#1$\hfil}{\tt\string#1}\hfil}% \advance\count1 by-1\relax \ifnum \count1=0\endcolumn\startcolumn\fi } % The \table macro from testfont.tex. \newcount\n \newcount\m \newcount\p \newdimen\dim \newif\ifskipping \def\oct#1{\hbox{\rm\'{}\kern-.2em\it#1\/\kern.05em}} % octal constant \def\hex#1{\hbox{\rm\H{}\tt#1}} % hexadecimal constant \def\setdigs#1"#2{\gdef\h{#2}% \h=hex prefix; \0\1=corresponding octal \m=\n \divide\m by 64 \xdef\0{\the\m}% \multiply\m by-64 \advance\m by\n \divide\m by 8 \xdef\1{\the\m}} \def\testrow{\setbox0=\hbox{\penalty 1\def\\{\char"\h}% \\0\\1\\2\\3\\4\\5\\6\\7\\8\\9\\A\\B\\C\\D\\E\\F% \global\p=\lastpenalty}} % \p=1 if none of the characters exist \def\oddline{\cr \noalign{\nointerlineskip} \multispan{19}\hrulefill& \setbox0=\hbox{\lower 2.3pt\hbox{\hex{\h x}}}\smash{\box0}\cr \noalign{\nointerlineskip}} \def\evenline{\loop\skippingfalse \ifnum\n<256 \m=\n \divide\m 16 \chardef\next=\m \expandafter\setdigs\meaning\next \testrow \ifnum\p=1 \skippingtrue \fi\fi \ifskipping \global\advance\n 16 \repeat \ifnum\n=256 \let\next=\endchart\else\let\next=\morechart\fi \next} \def\morechart{\cr\noalign{\hrule\penalty5000} \chartline \oddline \m=\1 \advance\m 1 \xdef\1{\the\m} \chartline \evenline} \def\chartline{&\oct{\0\1x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&} \def\chartstrut{\lower4.5pt\vbox to14pt{}} \def\table{$$\global\n=0 \halign to\hsize\bgroup \chartstrut##\tabskip0pt plus10pt& &\hfil##\hfil&\vrule##\cr \lower6.5pt\null &&&\oct0&&\oct1&&\oct2&&\oct3&&\oct4&&\oct5&&\oct6&&\oct7&\evenline} \def\endchart{\cr\noalign{\hrule} \raise11.5pt\null&&&\hex 8&&\hex 9&&\hex A&&\hex B& &\hex C&&\hex D&&\hex E&&\hex F&\cr\egroup$$\par} \def\:{\setbox0=\hbox{\char\n}% \ifdim\ht0>7.5pt\reposition \else\ifdim\dp0>2.5pt\reposition\fi\fi \box0\global\advance\n 1 } \def\reposition{\setbox0=\vbox{\kern2pt\box0}\dim=\dp0 \advance\dim 2pt \dp0=\dim} % A little hackette to make expand out to $\langle${\it foo}$\rangle$. \catcode`\<=\active \def<#1>{\leavevmode\hbox{$\langle$\rm\it#1\/$\rangle$}} \ifx\normalshape\undefined \def\stmaryrd{\stmaryten} \else \def\stmaryrd{\family{stmaryrd}\selectfont} \fi \begin{document} \maketitle \section{Introduction} This is a guide to the St Mary's Road symbol package for \LaTeX. It contains a number of new commands for use in math mode, and a new document style option {\tt module}, for modularizing large {\tt sty} files. The package is available as free software, the only restriction we make is that it should always be distributed as a package, not as individual files. The package consists of: \begin{itemize} \item {\tt README}: a short description. \item {\tt stmaryrd.tex}: this documentation. \item {\tt ltugboat.sty}: the {\tt sty} file this document uses. \item {\tt stmaryrd.sty}: loads the St Mary's Road symbol font. \item {\tt msam.sty}: loads the AMS symbol A font. \item {\tt msbm.sty}: loads the AMS symbol B font. \item {\tt module.sty}: provides commands for modularizing document style options. \item Various \MF\ files, which generate the St Mary's Road symbol font. \end{itemize} At its simplest, you can use the St~Mary's Road symbol font by saying \begin{verbatim} \documentstyle[stmaryrd]{article} \end{verbatim} This gives you the new symbols in Tables~\ref{Tab-op}, \ref{Tab-bin}, \ref{Tab-rel}, \ref{Tab-arrow} and~\ref{Tab-delim}. However, this defines over 100 new commands, and if you are using a \TeX\ implementation with limited memory, you might want to be more selective about which commands you use. In that case, you should read on, in order to find out about how modules work. \begin{table*} \begin{symbols}{3} \dosymbol\bigbox \dosymbol\bigcurlyvee \dosymbol\bigcurlywedge \dosymbol\biginterleave \dosymbol\bignplus \dosymbol\bigparallel \dosymbol\bigsqcap \dosymbol\bigtriangledown \dosymbol\bigtriangleup \end{symbols} \caption{New large operators} \label{Tab-op} \end{table*} \begin{table*} \begin{symbols}{19} \dosymbol\baro \dosymbol\bbslash \dosymbol\binampersand \dosymbol\bindnasrepma \dosymbol\boxast \dosymbol\boxbar \dosymbol\boxbox \dosymbol\boxbslash \dosymbol\boxcircle \dosymbol\boxdot \dosymbol\boxempty \dosymbol\boxslash \dosymbol\curlyveedownarrow \dosymbol\curlyveeuparrow \dosymbol\curlywedgedownarrow \dosymbol\curlywedgeuparrow \dosymbol\fatbslash \dosymbol\fatsemi \dosymbol\fatslash \dosymbol\interleave \dosymbol\leftslice \dosymbol\merge \dosymbol\minuso \dosymbol\moo \dosymbol\nplus \dosymbol\obar \dosymbol\oblong \dosymbol\obslash \dosymbol\ogreaterthan \dosymbol\olessthan \dosymbol\ovee \dosymbol\owedge \dosymbol\rightslice \dosymbol\sslash \dosymbol\talloblong \dosymbol\varbigcirc \dosymbol\varcurlyvee \dosymbol\varcurlywedge \dosymbol\varoast \dosymbol\varobar \dosymbol\varobslash \dosymbol\varocircle \dosymbol\varodot \dosymbol\varogreaterthan \dosymbol\varolessthan \dosymbol\varominus \dosymbol\varoplus \dosymbol\varoslash \dosymbol\varotimes \dosymbol\varovee \dosymbol\varowedge \dosymbol\vartimes \dosymbol\Ydown \dosymbol\Yleft \dosymbol\Yright \dosymbol\Yup \end{symbols} \caption{New binary operators} \label{Tab-bin} \end{table*} \begin{table*} \begin{symbols}{4} \dosymbol\inplus \dosymbol\niplus \dosymbol\ntrianglelefteqslant \dosymbol\ntrianglerighteqslant \dosymbol\subsetplus \dosymbol\subsetpluseq \dosymbol\supsetplus \dosymbol\supsetpluseq \dosymbol\trianglelefteqslant \dosymbol\trianglerighteqslant \end{symbols} \caption{New relations} \label{Tab-rel} \end{table*} \begin{table*} \begin{symbols}{7} \dosymbol\leftarrowtriangle \dosymbol\leftrightarroweq \dosymbol\leftrightarrowtriangle \dosymbol\lightning \dosymbol\Longmapsfrom \dosymbol\longmapsfrom \dosymbol\Longmapsto \dosymbol\Mapsfrom \dosymbol\mapsfrom \dosymbol\Mapsto \dosymbol\nnearrow \dosymbol\nnwarrow \dosymbol\rightarrowtriangle \dosymbol\shortdownarrow \dosymbol\shortleftarrow \dosymbol\shortrightarrow \dosymbol\shortuparrow \dosymbol\ssearrow \dosymbol\sswarrow \end{symbols} \caption{New arrows} \label{Tab-arrow} \end{table*} \begin{table*} \begin{symbols}{4} \dosymbol\Lbag \dosymbol\lbag \dosymbol\llbracket \dosymbol\llceil \dosymbol\llfloor \dosymbol\llparenthesis \dosymbol\Rbag \dosymbol\rbag \dosymbol\rrbracket \dosymbol\rrceil \dosymbol\rrfloor \dosymbol\rrparenthesis \end{symbols} \caption{New delimiters} \label{Tab-delim} \end{table*} \section{Modules} It is not uncommon for some document style options, particularly those loading new symbol fonts, to define hundreds of new commands, of which each user only wants a handful. This is not a problem on machines with memory to spare, but on a PC one has to be careful about these things. The solution adopted by the AMS, in their {\tt amsfonts} document style option, is to provide a new command \verb|\newsymbol|. For example, to use the symbol \verb|\lneq|, you say \begin{verbatim} \newsymbol\lneqq 2308 \end{verbatim} Unfortunately, this requires the user to look up the four-digit code for each symbol whenever they want to use it. The {\tt module} document style option is designed to get around this problem, by allowing the user to specify which new commands they want, without having to remember how they are defined. The main concept the user needs is that of a {\em tag\/} which is a request to a module saying `please give me this facility'. Usually these are just command names that the module will define---for example the module {\tt stmaryrd} has tags \verb|\varoplus|, \verb|\llbracket|, and so on. But there are other tags which control how the module behaves, for example the tag \verb|\heavycircles| means `please redefine $\oplus$, $\otimes$, etc.~to make them heavier.' To set the tag \verb|\foo|, you say \verb|\settag{\foo}|. To set \verb|\foo|, \verb|\baz| and \verb|\bar|, you say: \begin{verbatim} \begin{settags} \foo\baz\bar \end{settags} \end{verbatim} To unset the tag \verb|\foo|, you say \verb|\unsettag{\foo}|. To unset \verb|\foo|, \verb|\baz| and \verb|\bar|, you say: \begin{verbatim} \begin{unsettags} \foo\baz\bar \end{unsettags} \end{verbatim} You can then import a module. This can be done in various ways: \begin{itemize} \item By saying \verb|\import{fred}|, which only loads the commands whose tags you set. \item By saying \verb|\import*{fred}|, which loads in all the commands. \item In the same way as a \verb|\documentstyle| option, e.g.~\verb|\documentstyle[module,fred]{report}|. This is equivalent to \verb|\import*{fred}|. \end{itemize} For example, to load in the St Mary's Road symbol font, but only define \verb|\Lbag| and \verb|\Rbag|, you say: \begin{verbatim} \settag\Lbag \settag\Rbag \import{stmaryrd} \end{verbatim} The St Mary's Road package comes with three modules---{\tt stmaryrd}, which loads the St Mary's Road symbol font, {\tt msam}, which loads the AMS A font, and {\tt msbm}, which loads the AMS B font. \section{The {\tt stmaryrd} module} The St Mary's Road symbol font is designed to live with the AMS symbol fonts, and complement their focus on `concrete mathematics' by adding symbols for `abstract nonsense' such as domain theory ($\bigsqcap$), linear logic ($\binampersand$ and $\bindnasrepma$), process theory ($\llfloor$ and $\lightning$) and program calculation ($\moo$ and $\merge$). It also contains a number of circular characters (such as $\varotimes$, $\varoplus$, etc.)~which duplicate Knuth's. The only difference is that they have had digitization kludges added, so they are guaranteed to be symmetrical and circular. At low resolutions, Knuth's $\oplus$ tends to be rather egg-shaped. We have also made them the same weight as the other symbols. If you want \verb|\oplus| to produce $\varoplus$ and \verb|\varoplus| to produce $\oplus$, you should set the \verb|\heavycircles| tag. Note that \verb|\llbracket| and \verb|\rrbracket| are the only `growing' delimiters. For example: \[ \left\llbracket {\cal P} \right\rrbracket \quad \left\llbracket \bigbox {\cal P} \right\rrbracket \quad \left\llbracket \bigbox_{i\inplus I}^{a \varoplus b} P_i \right\rrbracket \quad \left\llbracket \begin{array}{c}a\\b\\c\end{array} \right\rrbracket \quad \left\llbracket \begin{array}{c}a\\b\\c\\d\\e\\f\end{array} \right\rrbracket \] Table~\ref{Tab-special} contains characters that are only used to build other ones. For example: \begin{itemize} \item \verb|$\arrownot\rightarrow$| is $\arrownot\rightarrow$. \item \verb|$\Arrownot\Rightarrow$| is $\Arrownot\Rightarrow$. \item \verb|$\longarrownot\longrightarrow$| is $\longarrownot\longrightarrow$. \item \verb|$\Longarrownot\Longrightarrow$| is $\Longarrownot\Longrightarrow$. \end{itemize} The characters \verb|\mapsfromchar|, \verb|\Mapstochar| and \verb|\Mapsfromchar| are used in defining \verb|\mapsfrom|, \verb|\Mapsto| and \verb|\Mapsfrom|. \begin{table*} \begin{symbols}{3} \dosymbol\Arrownot \dosymbol\arrownot \dosymbol\Longarrownot \dosymbol\longarrownot \dosymbol\Mapsfromchar \dosymbol\mapsfromchar \dosymbol\Mapstochar \end{symbols} \caption{Special symbols used for building other symbols} \label{Tab-special} \end{table*} \begin{table*} {\stmaryrd\table} \caption{The font layout for {\tt stmary10}} \end{table*} \section{Implementing a module} So, how does this magic with tags work? Well, a module {\tt fred} is just a {\tt sty} file like any other, but uses some extra commands defined in the {\tt module} document style option, including \verb|\settag| and \verb|\unsettag|. Each module {\tt fred} should include the command \verb|\settag\modulefredloaded|, to tell other modules (including itself, if {\tt fred} is loaded more than once) that it has been loaded. For example, a module can check to see if the {\tt module} document style option has been loaded by saying: \begin{verbatim} \@ifundefined{modulemoduleloaded} {\input module.sty}{} \end{verbatim} The most important new command a module-writer has is \verb|\iftest|, which tests to see if a is true or not. It has the syntax: \begin{verbatim} \iftest \then \fi \end{verbatim} or: \begin{verbatim} \iftest \then \else \fi \end{verbatim} meaning `if the test is true, do the true text, otherwise do the false text.' A is of the form: \begin{verbatim} \truetest \falsetest \tagisset \ortest{}{} \andtest{}{} \nottest{} \end{verbatim} For example, there is a special tag \verb|\everything|, which is set if the module was imported with \verb|\import*| or loaded as a document style option. So if we are defining a command \verb|\foo|, we would like to test if either \verb|\foo| or \verb|\everything| has been set. We can do this by saying \begin{verbatim} \iftest\ortest {\tagisset\foo}{\tagisset\everything} \then\def\foo{} \fi \end{verbatim} This is so common as to warrant its own syntactic sugar: \begin{verbatim} \ifdef\then\def\foo{}\fi \end{verbatim} This can also be used with \verb|\mathchardef|, \verb|\let|, or any other defining command. There are extra commands for defining new text characters (such as \verb|\varcopyright|) and delimiters (such as \verb|\llbracket|), since such definitions are so common: \begin{verbatim} \delimiterdef\foo"<7 digits> \textchardef\foo"<3 digits> \end{verbatim} Another common usage is \begin{verbatim} \iftest\tagisset\foo \then\settag\baz \fi \end{verbatim} meaning `If we are exporting \verb|\foo|, we should export \verb|\baz| as well.' This sort of dependency information is so common as to warrant its own syntactic sugar: \begin{verbatim} \dependent\foo\baz \end{verbatim} Note that since modules may well be loaded in more than once, care is needed to make sure the definitions stand up to being executed repeatedly. Unfortunately, this is not always the case---commands such as \verb|\newfam| or \verb|\font| should only be executed once. To get round this, the module {\tt fred} can look to see whether \verb|\modulefredloaded| is set. For example, you can say: \begin{verbatim} \iftest\tagisset\modulefredloaded \then\else \fi \end{verbatim} There is also a tag \verb|\newfontselection| which is set if Mittelbach and Sch\"opf's new font selection scheme is in force. \section{Implementing {\tt stmaryrd.sty}} As an example, we can look to see how the St Mary's Road module is implemented. To begin with, it looks to see if the {\tt module} document style is loaded, and inputs it if necessary: \begin{verbatim} \@ifundefined{modulemoduleloaded} {\input module.sty}{} \end{verbatim} Then it sets up the dependency information. For example, we need \verb|\Mapstochar| in order to build \verb|\Mapsto|. \begin{verbatim} \dependent\Mapsto\Mapstochar ... \dependent\Longmapsfrom\Mapsfromchar \end{verbatim} If the \verb|\heavycircles| tag is set, we need to define \verb|\varotimes|, \verb|\varoast|, etc. \begin{verbatim} \iftest\tagisset\heavycircles \then \settag\varotimes ... \settag\varbigcirc \fi \end{verbatim} Then we can do the real work of the module, which is to load the fonts in. We only do this the first time the module is loaded. \begin{verbatim} \iftest\tagisset\modulestmaryrdloaded \then\else \iftest\tagisset\newfontselection \then \else \fi \fi \end{verbatim} We can then define all those symbols, but first a quick cheat to make \verb|!| expand out to the hex digit for the St Mary's Road family. \begin{verbatim} \catcode`\!\active \edef!{\hexnumber@\stmaryrdfam} \end{verbatim} Then we have a huge number of definitions: \begin{verbatim} \ifdef\then\mathchardef\shortleftarrow "3!00\fi ... \ifdef\then\def\Longmapsfrom {\Longleftarrow\Mapsfromchar}\fi \end{verbatim} There's then a little hackette to swap the circular operators around if necessary. This works by keeping a tag \verb|\swappedcircles| which is set once we've swapped the circles round. So we swap the circles if \verb|\heavycircles| is set and \verb|\swappedcircles| is not. \begin{verbatim} \iftest\andtest {\tagisset\heavycircles} {\nottest{\tagisset\swappedcircles}} \then\else \def\@swap#1#2{\let\@tempa#1 \let#1#2\let#2\@tempa} \@swap\varotimes\otimes ... \@swap\varcopyright\copyright \settag\swappedcircles \fi \end{verbatim} Finally, the St Mary's Road module sets its own name. \begin{verbatim} \settag\modulestmaryrdloaded \end{verbatim} And that's it. \section{Implementing {\tt module.sty}} So the only question left is how the {\tt module} document style option is defined. The main problem is to implement \verb|\iftest| in a reasonably efficient manner, even though \TeX\ doesn't have primitives for `and' and `or' on booleans. The solution adopted here is to make a a command which expands out to either \verb|\iftrue| or \verb|\iffalse|. Note that \verb|\iftrue| and \verb|\iffalse| are not good tests, since they would fall foul of \TeX's \verb|\if...\fi| matching. \begin{verbatim} \def\truetest{\iftrue} \def\falsetest{\iffalse} \end{verbatim} The definition of `or': \begin{verbatim} \def\ortest#1{#1\expandafter\K@true \else\expandafter\@identity\fi} \def\@identity#1{#1} \def\K@true#1{\iftrue} \end{verbatim} The definition of `and': \begin{verbatim} \def\andtest#1#2{#1\@fi#2} \def\@fi{\fi} \end{verbatim} The definition of `not': \begin{verbatim} \def\nottest#1{#1\expandafter\falsetest \else\expandafter\truetest\fi} \end{verbatim} Then all that \verb|\iftest\then| has to do is expand out to . \begin{verbatim} \def\iftest#1\then{#1} \end{verbatim} However, in order to make sure that nested uses of \verb|\if...\fi| and \verb|\iftest...\then...\fi| work, we need to make \verb|\then| an \verb|\if|-like command. It doesn't matter which, since we're only using it to match against \verb|\fi| properly. \begin{verbatim} \let\then\true \end{verbatim} Then we can set a tag by making it the same as some magic value \verb|\magic@value|. \begin{verbatim} \def\tagisset#1{\ifx\magic@value#1} \def\settag#1{\let#1\magic@value} \def\unsettag#1{\let#1\unmagic@value} \end{verbatim} It doesn't matter which magic value we choose, so we let \verb|\magic@value| produce an error message. That way, if the user sets a tag, but none of the modules actually defines it, then they will get an error message if they try to use it. \begin{verbatim} \def\magic@value{\set@error} \def\set@error{} \def\unmagic@value{\unset@error} \def\unset@error{} \end{verbatim} The rest of the {\tt module} document style option is fairly routine. \section{Acknowledgements} We'd like to thank Dave Murphy for many thought-provoking comments, and Simon, Nigel and Stuart for making our life in St~Mary's Road livable. \makesignature \end{document}