Doc/spec-macros.tex

   1 % -*- Mode: LaTeX; Package: CLIM-USER -*-
   2
   3 %%
   4 %%  MACROS for CLIM Specs
   5 %%
   6
   7 \newskip  \normalparskip
   8 \normalparskip = 0pc
   9
  10 \def\removedepth{\ifdim \prevdepth>-1000pt \vskip -\prevdepth\fi}
  11 \def\Vskip #1!{\endgraf
  12                \removedepth
  13                \ifdim \lastskip<#1 \ifdim \lastskip>0pc
  14                \removelastskip\fi
  15                \vskip#1\fi}
  16
  17 %%
  18 %% Basic macros
  19 %%
  20
  21 \def\curly#1{$\{${\it #1\/}$\}$}
  22 \def\star#1{#1{\rm *}}
  23 \def\form{\curly{form}}
  24 \def\place{\curly{place}}
  25 \def\paren#1{\rm({\it #1\/})}
  26 \def\brac#1{\rm[{\it #1\/}]}
  27 \def\ttbrac#1{\tt[{\it #1\/}]}
  28 \def\plus#1{$\hbox{#1}^+$}
  29 \def\placeplus{ $\{${\it place}$\}^+$}
  30 \def\lparen{{\rm (}}
  31 \def\rparen{{\rm )}}
  32
  33 \def\optional{{\tt\&optional\ }}
  34 \def\rest{{\tt\&rest\ }}
  35 \def\key{{\tt\&key\ }}
  36 \def\allow{{\tt\&allow-other-keys\ }}
  37 \def\body{{\tt\&body\ }}
  38
  39 \def\arg#1{{\it #1}}
  40
  41 %% When you supply a default value for optional or keyword arguments,
  42 %% use this idiom:  \key (filled \cl{t})
  43 %% \newcommand {\cl} [1] {{\tt #1}}
  44
  45 %% This allows hyphenation of CL symbols at the hyphens that exist in
  46 %% the symbol name, but noplace else, e.g., \cl{standard\-region\-union}.
  47 %% The reason we don't use this is that the backslashes in the symbol
  48 %% names make Tags Search next to useless.
  49 %% \def\cl#1{{\def\-{\discretionary{-}{}{-}}\tt #1}}
  50
  51 %% Spiffier version that hyphenates only at hyphens, but makes hyphens
  52 %% be active characters, so we don't break Tags Search.  Thanks to
  53 %% Stephen Gildea for providing this.
  54 {\catcode`\-=\active
  55 \gdef\cl{\bgroup
  56   \catcode`\-=\active \def-{{\tt \char`\-}\penalty\exhyphenpenalty}%
  57   \@cl}}
  58 \def\@cl#1{\tt#1\egroup}
  59
  60 %% Use \concept when you are introducing a term for the first time, and
  61 %% want it in the index.  Use \term after that.
  62 \newcommand {\concept} [1] {{\sl #1}\index{#1}}
  63 \newcommand {\term} [1] {{\sl #1}}
  64
  65 %%
  66 %% Miscellaneous
  67 %%
  68
  69 \long\def\comment #1 {}
  70
  71 \long\def\keepout #1 {}
  72
  73 \long\def\Issue #1 #2 {{\bf Major issue: } {\sl #2 ---~#1}}
  74 \long\def\issue #1 #2 {{\bf Minor issue: } {\sl #2 ---~#1}}
  75
  76 %%
  77 %% Definition types
  78 %%
  79
  80 \def\outdent#1{\noindent\hbox to 0pc{\hskip -1.5pc #1\hss}\ignorespaces}
  81
  82 \newcommand {\Dodocf} [3] {\outdent{$\Rightarrow$}{\tt #1 {\it #2} \hfill\mbox{\brac{\it #3\/}}}
  83                            \index{{\tt #1} #3}
  84                            \Vskip\normalparskip!}
  85 \newcommand {\Dodocv} [2] {\outdent{$\Rightarrow$}{\tt #1 \hfill\mbox{\brac{\it #2\/}}}
  86                            \index{{\tt #1} #2}
  87                            \Vskip\normalparskip!}
  88
  89 %% Use these when you want to leave some vertical whitespace afterwards
  90 \def\Defmacro #1 #2 {\Dodocf {#1} {#2} {Macro}}
  91 \def\Defun #1 #2 {\Dodocf {#1} {#2} {Function}}
  92 \def\Defgeneric #1 #2 {\Dodocf {#1} {#2} {Generic~Function}}
  93 \def\Defmethod #1 #2 {\Dodocf {#1} {#2} {Method}}
  94 \def\Defaftermethod #1 #2 {\Dodocf {#1} {#2} {:After~Method}}
  95 \def\Defaroundmethod #1 #2 {\Dodocf {#1} {#2} {:Around~Method}}
  96 \def\Defvar #1 {\Dodocv {#1} {Variable}}
  97 \def\Defconst #1 {\Dodocv {#1} {Constant}}
  98 \def\Defprotoclass #1 {\Dodocv {#1} {Protocol~Class}}
  99 \def\Defpredicate #1 #2 {\Dodocf {#1} {#2} {Protocol~Predicate}}
 100 \def\Defclass #1 {\Dodocv {#1} {Class}}
 101 \def\Definitarg #1 {\Dodocv {#1} {Initarg}}
 102 \def\Deftype #1 {\Dodocv {#1} {Type}}
 103 \def\Defoption #1 {\Dodocv {#1} {Option}}
 104 \def\Defptype #1 #2 {\Dodocf {#1} {#2} {Presentation~Type}}
 105 \def\DefptypeAbbrev #1 #2 {\Dodocf {#1} {#2} {Presentation~Type~Abbreviation}}
 106 \def\Defcondition #1 {\Dodocv {#1} {Condition}}
 107 \def\Deferror #1 {\Dodocv {#1} {Error Condition}}
 108 \def\Defrestart #1 {\Dodocv {#1} {Restart}}
 109
 110 \newcommand {\dodocf} [3] {\outdent{$\Rightarrow$}{\tt #1 {\it #2} \hfill\mbox{\brac{\it #3\/}}}
 111                            \index{{\tt #1} #3}
 112                            \linebreak}
 113 \newcommand {\dodocv} [2] {\outdent{$\Rightarrow$}{\tt #1 \hfill\mbox{\brac{\it #2\/}}}
 114                            \index{{\tt #1} #2}
 115                            \linebreak}
 116
 117 %% Use these when you don't want to leave any vertical whitespace afterwards
 118 \def\defmacro #1 #2 {\dodocf {#1} {#2} {Macro}}
 119 \def\defun #1 #2 {\dodocf {#1} {#2} {Function}}
 120 \def\defgeneric #1 #2 {\dodocf {#1} {#2} {Generic~Function}}
 121 \def\defmethod #1 #2 {\dodocf {#1} {#2} {Method}}
 122 \def\defvar #1 {\dodocv {#1} {Variable}}
 123 \def\defconst #1 {\dodocv {#1} {Constant}}
 124 \def\defprotoclass #1 {\dodocv {#1} {Protocol~Class}}
 125 \def\defpredicate #1 #2 {\dodocf {#1} {#2} {Protocol~Predicate}}
 126 \def\defclass #1 {\dodocv {#1} {Class}}
 127 \def\definitarg #1 {\dodocv {#1} {Initarg}}
 128 \def\defoption #1 {\dodocv {#1} {Option}}
 129
 130 \def\Defcommandtable #1 {\Dodocv {#1} {Command~Table}}
 131 \def\Defframe #1 {\Dodocv {#1} {Application~Frame}}
 132
 133 \def\Defgadget #1 {\Dodocv {#1} {Abstract~Gadget}}
 134 \def\defgadget #1 {\dodocv {#1} {Abstract~Gadget}}
 135
 136 \def\Defspane #1 {\Dodocv {#1} {Service~Pane}}
 137 \def\defspane #1 {\dodocv {#1} {Service~Pane}}
 138 \def\Deflpane #1 {\Dodocv {#1} {Layout~Pane}}
 139 \def\deflpane #1 {\dodocv {#1} {Layout~Pane}}
 140
 141 \def\Callback #1 #2 {\Dodocf {#1} {#2} {Callback~Generic~Function}}
 142 \def\callback #1 #2 {\dodocf {#1} {#2} {Callback~Generic~Function}}
 143
 144 %%
 145 %% Canned phrases.
 146 %%
 147
 148 \def\IfYouWantClass #1 #2 #3 {If you want to create a new class that behaves
 149 like #1 #2, it should be a subclass of \cl{#3}.  All instantiable subclasses of
 150 \cl{#3} must obey the #2 protocol.\ }
 151
 152 \def\AbstractClass{This class is an abstract class, intended only to be
 153 subclassed, not instantiated.\ }
 154
 155 \def\Mutable{Members of this class are mutable.\ }
 156
 157 \def\Immutable{Members of this class are immutable.\ }
 158
 159 \def\UncapturedInputs{This function does not capture any of its mutable inputs.\ }
 160
 161 \def\MayCaptureInputs{This function is permitted to capture its mutable inputs; the
 162 consequences of modifying those objects are unspecified.\ }
 163
 164 \def\FreshOutputs{This function returns fresh objects that may be modified.\ }
 165
 166 \def\ReadOnly{This function returns objects that reveal CLIM's internal state;
 167 do not modify those objects.\ }
 168
 169 \def\ReadWrite{This function returns objects that reveal CLIM's internal state;
 170 these objects may be modified.\ }
 171
 172 \def\NotInRelease2{{\sl This is not fully supported in Release 2.\ }}