Debian Codegraph @

texmf-dist/source/latex/dvgloss/dvgloss.dtx

raw
1 % \iffalse
2 %<package>\NeedsTeXFormat{LaTeX2e}
3 %<package>\ProvidesPackage{dvgloss}[2012/08/06 v0.1 Flexible glossing commands]
4 %<*driver>
5 \documentclass{article}
6 \usepackage{doc}
7 \usepackage{dvgloss}
8 \usepackage{expex}
9 \usepackage{sverb}
10 \EnableCrossrefs
11 \RecordChanges
12 \aboveglskip=-3pt
13 \begin{document}
14 \DocInput{dvgloss.dtx}
15 \end{document}
16 %</driver>
17 % \fi
18 % \title{The \textsf{dvgloss} package}
19 % \author{Dan Bridges Velleman}
20 % \maketitle
21 %\tableofcontents
22 %\section{What it does}
23 %This is a package that lets you set interlinear linguistic examples like
24 %the one below:
25 %\begin{demo}[w]{A linguistic example}
26 %\gl{{K'a tee} ka-r-il ri achih ri jun keej xaa maa pwaq
27 % k-u-kisii-j.}
28 % {{suddenly} {\sc inc-a}3s-see the man the one horse
29 % just {\sc exclam} money {\sc inc-a}3s-shit-{\sc ss}}
30 %\ft{Suddenly, the man saw a horse that was just shitting money.}
31 %\lb{Mondloch 1981}
32 %\end{demo}
33 %
34 %Some characters have been set up as shortcuts for
35 %various useful things within an example --- inserting a line break
36 %(using {\tt /})
37 %putting subscripts on brackets (\emph{e.g.}~\verb+]Contr+ in the example
38 %below), etcetera.
39 %
40 %\begin{demo}[w]{Using a shortcut}
41 %\gl{No [ morir\'e ]Contr / {sino que} [ vivir\'e ]Contr}
42 % {not will.die but will.live}
43 %\ft{You will not die, but will live.}
44 %\end{demo}
45 %What makes this package different from others that exist so far (and in
46 % particular from
47 %{\sf expex}, which offers a similar set of shortcuts) is that these
48 %shortcuts are \emph{customizable}. You can declare new characters as shortcuts,
49 %change the meanings of existing shortcuts, and so on. For instance, if the
50 %slash hadn't already been set up as a newline character, you could make it
51 %one like this:
52 %\begin{verbatim}
53 %\makeglshortcut / {\par}
54 %\end{verbatim}
55 %If you wanted to repurpose it --- let's say you've been using it to mark
56 %prosodic boundaries, but you decide you want those to show up as the IPA
57 %double-pipe character as in the example below ---
58 %you could do that too.
59 %
60 %\begin{demo}[w]{Redefining a shortcut}
61 %\begingroup
62 %\makeglshortcut / {\unskip\quad$\|$\quad}
63 %\gl{No [ morir\'e ]Contr / {sino que} [ vivir\'e ]Contr}
64 % {not will.die rather will.live}
65 %\ft{You will not die, but will live.}
66 %\endgroup
67 %\end{demo}
68 %
69 %Finally, for one-off situations where you don't want to define a new shortcut,
70 %there is an ``escape character'' which lets you issue any command you want from
71 %within an argument of \verb+\gl+. Suppose you redefine {\tt /} to generate the
72 %double-pipe character, but then you run into a tricky formatting situation
73 %where you really need to force a line break. Just say \verb+!{\par}+ --- or,
74 %for that matter, \verb+!{\par\vspace{\jot}\mbox{}\qquad}+, if that's what
75 %floats your boat --- and you'll get what you want. (The default escape character
76 %is {\tt !}, but if you're a Khoisanist or otherwise need to start words with
77 %a bang, you can redefine it to something else.)
78 %\section{What it doesn't do}
79 %\begin{itemize}
80 %\item It doesn't handle example numbering. There are plenty of other packages
81 % that do, so I doubt I'll bother to reinvent that particular wheel any time
82 % soon.
83 %\item It doesn't do three-line glosses, or anything bigger. This is a dumb
84 % limit and could easily be removed --- but I probably won't get around to it
85 % unless someone else asks, because two-line glosses are all I ever use.
86 %\item Shortcuts or escaped commands can take arguments, and can (if you arrange
87 % it right) take scope over more than one word of interlinear gloss; but there
88 % are limits --- in particular, scope-taking commands can't be \emph{nested}.
89 % This is a limit that could in principle be removed, but it would take some work.
90 %\end{itemize}
91 % So for instance, as an example of that last limit: you can define a pair of shortcut characters that will
92 % cause a box to be drawn around any number of intervening words, as in the example below; but
93 % you will not be able to use those shortcuts to produce nested boxes.
94 %
95 %\begin{demo}[w]{A scope-taking shortcut}
96 %\gl{Los * frase-s nominal-es * est\'a-n en * caja-s. * No s\'e porqu\'e.}
97 % {the phrase-pl nominal-pl are-3pl in box-pl not know.1sg why}
98 %\ft{The noun phrases are in boxes. I don't know why.}
99 %\end{demo}
100 %
101 %\section{How to use it}
102 %\subsection{The basics}
103 % \begin{macro}{\gl}
104 %\begin{macro}{\ft}
105 % The \verb+\gl+ macro takes two arguments. It treats each argument as a list of
106 % (space-delimited) items, and aligns the items from the first argument atop the
107 % items from the second.
108 %
109 % The \verb+\ft+ macro is for putting a \emph{free translation} after an
110 % interlinear gloss. It takes a single argument.
111 %
112 %\begin{demo}[w]{A generic example}
113 %\gl{dolorem ipsum quia dolor sit amet}
114 % {pain.acc.sg itself.acc.sg because
115 % because pain.nom.sg be.3sg.subj love.3sg}
116 %\ft{``loves pain itself because it is pain''}
117 %\end{demo}
118 %
119 %\end{macro}
120 % \end{macro}
121 %\begin{macro}{\lb}
122 % The \verb+\lb+ macro gives you a ``label'' --- a bit of text set on the same line
123 % as what came before (if there's room) but pushed right to the end of the line.
124 % You can use this, among other things, for citations.
125 %
126 %\begin{demo}[w]{An example with a label}
127 %\gl{dolorem ipsum quia dolor sit amet}
128 % {pain.acc.sg itself.acc.sg because pain.nom.sg be.3sg.subj love.3sg}
129 %\ft{loves pain itself just for being pain}
130 %\lb{Cicero}
131 %\end{demo}
132 % If there isn't room for the label on one line, a line break will be added.
133 %
134 %\begin{demo}[w]{An example with a long label}
135 %\gl{dolorem ipsum quia dolor sit amet}
136 % {pain.acc.sg itself.acc.sg because pain.nom.sg be.3sg.subj love.3sg}
137 %\ft{loves pain itself just for being pain}
138 %\lb{Cicero, \emph{de Finibus Bonorum et Malorum}}
139 %\end{demo}
140 %\end{macro}
141 %
142 %\subsection{Grouping}
143 %You can use curly braces to group multiple words together; \verb+\gl+ will
144 % then treat them like a single word.
145 %
146 %\begin{demo}{Grouping two words together}
147 %\gl{Edormi crapulam}
148 % {{sleep off} hangover}
149 %\ft{``Sleep off that hangover.''}
150 %\lb{Cicero, Philippic 2 30}
151 %\end{demo}
152 %
153 %The \verb+\gl+ macro ignores spaces in all the same places that \LaTeX\ normally
154 %ignores spaces --- for instance after a control sequence. To make sure that
155 %a space after a control sequence will be recognized, wrap the control sequence
156 %in curly braces, as in the first two words below.
157 %
158 %\begin{demo}{Spaces ignored after control sequences}
159 %\gl{{\aa} {n\aa} Bl\aa-\aa s-en}
160 % {to reach blue-ridge-def}
161 %\ft{to reach Bl\aa\aa sen}
162 %\end{demo}
163
164 %\subsection{Prebuilt shortcuts}
165 % For a shortcut character to do anything at all, (i) it must be in the first
166 % argument of \verb+\gl+, and (ii) it must be at the beginning of a word.
167 %
168 % If the shortcut character has non-space characters after it, they will be
169 % treated as an argument. The right-bracket shortcut which we saw back in
170 % \S1 is an example of this: if you type \verb+]Contr+, then \verb+Contr+ is
171 % treated as the shortcut's argument --- which in this case means it's typeset
172 % as a subscript.
173 %
174 % \begin{itemize}
175 % \item[\tt /] Insert a line break. The argument, if present, specifies an
176 % amount of extra vertical space to be added afterward.
177 % \item[{$\tt [$}] Insert a left bracket in the top line, with nothing aligned
178 % with it below. The argument, if present, specifies a label to be set as a
179 % subscript to the left bracket.
180 % \item[{$\tt ]$}] As above, but insert a right bracket.
181 % \item[\tt * *] Everything between the two asterisks is set with a
182 % \verb+\framebox+ around it. If an argument is present after the second
183 % asterisk, it's set as a label on top of the \verb+\framebox+.
184 % \end{itemize}
185 %
186 %\subsection{New shortcuts}
187 %\begin{macro}{\makeglshortcut}
188 %To define a new shortcut along the lines of \verb+/+ and \verb+[+, use the command
189 %\verb+\makeglshortcut+. It takes two arguments --- the first is the character you
190 %want to turn into a shortcut, the second is the macro code that will be executed when
191 %that character is encountered. If the shortcut character is encountered with other,
192 %non-space characters after it, those will be passed to the macro code you supply as
193 %an argument --- so you can capture those characters as \verb+#1+.
194 % (If you try to do something with \verb+#1+ but the user hasn't supplied an argument,
195 % then \verb+#1+will be empty. You might want to test for this --- as in the example
196 % below --- if this is an issue. If the user does supply an argument, but you don't
197 % do anything with it, then that's not a problem --- the argument will be silently
198 % discarded.)
199 %\end{macro}
200 %We've already seen an example of a shortcut definition that doesn't use an argument.
201 %\begin{verbatim}
202 %\makeglshortcut / {\par}
203 %\end{verbatim}
204 %Here's an example of one which does.
205 %\begin{verbatim}
206 %\makeglshortcut / {\par\ifx#1\empty\else\vskip#1\fi}
207 %\end{verbatim}
208 %
209 %Shortcuts have to be single characters. \verb+\makeglshortcut{somethingverylong}{code}+ will
210 %not do what you want.
211 %\begin{macro}{\makeglsurround}
212 %To define a new shortcut along the lines of \verb+*+ --- a set of delimiters which can surround
213 % multiple
214 %words of glossed text and ``take scope'' over them --- use the command \verb+\makeglsurround+.
215 %It takes three arguments: the left-hand delimiter, the right-hand delimiter, and the code
216 %that will be executed when they're encountered. The two delimiters can be the same --- as
217 %with \verb+*+, above --- but they don't have to be.
218 %
219 %If there are extra non-space characters after the left-hand delimiter, they are passed in as
220 %argument \verb+#1+. The characters between the two delimiters are passed in as argument
221 %\verb+#2+. Extra non-space characters after the right-hand delimiter are passed in as argument
222 %\verb+#3+. You'll almost certainly want to do something with \verb+#2+, but ignoring \verb+#1+
223 %and \verb+#3+ is completely fine.
224 %\end{macro}
225 %As an example, here's how the asterisk shortcut was defined:
226 %\begin{verbatim}
227 %\makeglsurround ** {%
228 % \rlap{\raisebox{1.5em}{\footnotesize\sf#3}}%
229 % \fbox{\noglstrut#2\unskip}\glspace}
230 %\end{verbatim}
231 %
232 %\subsection{The escape character}
233 %Spacing and line-beaking commands, among others, need to be ``escaped'' if you want to use
234 %them inside of \verb+\gl+. (See \S4 for an explanation of why this is. For now, just
235 %trust me.) The escape character by default is \verb+!+, and it's best to enclose whatever
236 %comes after it in curly braces. So you could use \verb+!{\par)}+ to insert a new line if
237 %you'd already redefined \verb+/+, or \verb+!{\qquad}+ to insert some extra horizontal space.
238 %
239 %\macro{\glescape}
240 %If you want to change the escape character, redefine \verb+\glescape+. Like shortcuts,
241 %the escape has to be a single character. \verb+\def\glescape{averylongescape}+ will not
242 %do what you want.
243 %\section{What's going on}
244 %
245 % Internally, there is a command called \verb+\glossword+ which is responsible for stacking
246 % two words on top of one another. The arguments you give to the \verb+\gl+ command are
247 % converted into a series of \verb+\glossword+s, like so:
248 % \begin{verbatim}
249 % \gl{a b c d}{1 2 3 4}
250 % ===>
251 % \glossword{a}{1}
252 % \glossword{b}{2}
253 % \glossword{c}{3}
254 % \glossword{d}{4}
255 % \end{verbatim}
256 %
257 % Normally, command sequences that appear inside of \verb+\gl+ will be wrapped up inside a
258 % \verb+\glossword+. Sometimes this is what you want.
259 % \begin{verbatim}
260 % \gl{a b \bf c d}{1 2 3 4}
261 % ===>
262 % \glossword{a}{1}
263 % \glossword{b}{2}
264 % \glossword{\bf c}{3}
265 % \glossword{d}{4}
266 % \end{verbatim}
267 % But sometimes it is really not at all what you want.
268 % \begin{verbatim}
269 % \gl{a b \par c d}{1 2 3 4}
270 % ===>
271 % \glossword{a}{1}
272 % \glossword{b}{2}
273 % \glossword{\par c}{3}
274 % \glossword{d}{4}
275 % \end{verbatim}
276 %
277 % So we need a way to get a command like \verb+\par+ to show up \emph{outside} of
278 % a \verb+\glossword+. That's what the escape character is for.
279 % \begin{verbatim}
280 % \gl{a b !{\par} c d}{1 2 3 4}
281 % ===>
282 % \glossword{a}{1}
283 % \glossword{b}{2}
284 % \par
285 % \glossword{c}{3}
286 % \glossword{d}{4}
287 % \end{verbatim}
288 %
289 % The expansion of a shortcut character also ends up outside of any \verb+\glossword+s.
290 % \begin{verbatim}
291 % \gl{a b / c d}{1 2 3 4}
292 % ===>
293 % \glossword{a}{1}
294 % \glossword{b}{2}
295 % \par
296 % \glossword{c}{3}
297 % \glossword{d}{4}
298 % \end{verbatim}
299 %
300 % \StopEventually{}
301 %\section{Code}
302 % To begin with we set up temporary token list registers, and some spacing and formatting parameters.
303 % \begin{macrocode}
304 \newtoks\ta\newtoks\tb
305 \newdimen\glhangindent\glhangindent=2em
306 \newdimen\betweenglskip\betweenglskip=1\jot
307 \newdimen\withinglskip\withinglskip=0pt
308 \newdimen\aboveglftskip\aboveglftskip=2\jot
309 \newdimen\aboveglskip\aboveglftskip=2\jot
310 \newdimen\glstrutheight\newdimen\glstrutdepth
311 \def\glspace{\penalty0\hspace{1ex plus 2em minus 2pt}}
312 \def\everygla{\itshape}
313 \def\everyglb{}
314 % \end{macrocode}
315 % We also specify an escape character.
316 % \begin{macrocode}
317 \def\glescape{!}
318 % \end{macrocode}
319 %
320 %\begin{macro}{\addtokens}
321 %\begin{macro}{\popoff}
322 % Here's some helper macros for wrangling lists in which the items are separated
323 % by spaces.
324 % \begin{macrocode}
325 \long\def\addtokens#1\to#2{\ta={#1}\tb=\expandafter{#2}\edef#2{\the\tb\the\ta}}
326 \def\pop#1\to#2{\expandafter\popoff#1\to#2\remainderin#1}
327 \long\def\popoff#1 #2\to#3\remainderin#4{#3={#1}\def#4{#2}}
328 % \end{macrocode}
329 %\end{macro}
330 %\end{macro}
331 %\begin{macro}{\split}
332 %\begin{macro}{\istchar}
333 %\begin{macro}{\restchars}
334 % Here's one
335 % for splitting off a single token from a longer string. If you
336 % execute \verb+\split{Lorem}+, then the \verb+L+ is stored in
337 % \verb+\istchar+ and the rest of the word --- \verb+orem+ --- is stored in
338 % \verb+\restchars+.
339 % \begin{macrocode}
340 \long\def\split#1{\expandafter\ssplit#1\xyzzy}
341 \long\def\ssplit#1#2\xyzzy{\gdef\istchar{#1}\gdef\restchars{#2}}
342 % \end{macrocode}
343 %\end{macro}
344 %\end{macro}
345 %\end{macro}
346 %
347 %\begin{macro}{\ifnotin}
348 % There's one truly devious helper macro here: a really tricky way of testing
349 % whether one serious of tokens occurs
350 % within another. This is cribbed from the doc package, which credits Michael
351 % Spivak with the original invention.
352 % \begin{macrocode}
353 \def\ifnotin#1#2{%
354 \def\@ifnotin##1#1##2##3\zyzzy{\ifx\ifnotfound##2}%
355 \expandafter\@ifnotin#2#1\notfound\zyzzy}
356 % \end{macrocode}
357 %\end{macro}
358 %\begin{macro}{\ifspecial}
359 %\begin{macro}{\checkspecial}
360 %\begin{macro}{\makespecial}
361 % We need this bit of deviousness because we're going to keep a list of characters that have been
362 % declared as special shortcuts. \verb+\makespecial+ adds something to the list;
363 % \verb+\checkspecial+ checks whether it's on the list (using \verb+\ifnotin+) and stores the answer in
364 % \verb+\ifspecial+.
365 % \begin{macrocode}
366 \newif\ifspecial
367 \def\dvglspecials{}
368 \def\checkspecial#1{%
369 \ifnotin#1{\dvglspecials}\specialfalse\else\specialtrue\fi}
370 \def\makespecial#1{%
371 \xdef\dvglspecials{\dvglspecials#1}}
372 % \end{macrocode}
373 %\end{macro}
374 %\end{macro}
375 %\end{macro}
376 %
377 %\subsection{Glossing}
378 %\begin{macro}{\glossword}
379 % First we define the basic formatting macro: it stacks a word and its gloss
380 % atop one another.
381 % \begin{macrocode}
382 \def\glossword#1#2{%
383 \mbox{\vtop{\halign{##\hfil\cr\everygla#1\strut\cr\everyglb#2\strut\cr}}}%
384 \glstrut\glspace}
385 % \end{macrocode}
386 %\end{macro}
387 %\begin{macro}{\zipper}
388 % Now we have the rearranging macro.
389 % To use a functional programming analogy:
390 % \verb+\zipper\a\and\b\to\c+ basically means \verb+c = zipWith(glossword) a b+.
391 % In other words, if \verb+\a+ is a list macro containing the tokens \verb+1 2 3+
392 % and \verb+\b+ is a list macro containing the tokens \verb+4 5 6+, and we execute
393 % \verb+\zipper\a\and\b\to\c+, then \verb+\c+ will end up containing
394 % \verb+\glossword{1}{4}\glossword{2}{5}\glossword{3}{6}+.
395 %
396 % In fact, though, \verb+\zipper+ is not quite \verb+zipWith+. It also catches
397 % ``special'' or escaped tokens in its first argument and adds them to the output
398 % \emph{without} pairing them off or wrapping them in a \verb+\glossword+.
399 % \begin{macrocode}
400 \def\zipper#1\and#2\to#3{%
401 % \end{macrocode}
402 % If there's any items left on list \#1, pull one off (storing it in
403 % \verb+\ta+) and split off its first token so we can peek and see if it's an
404 % escape character or a special character.
405 % \begin{macrocode}
406 \ifx\empty#1\else%
407 \pop#1\to\ta%
408 \def\istchar{}\def\restchar{}%
409 \edef\temp{\the\ta}\split\temp%
410 % \end{macrocode}
411 % If that first token is an escape character, we pass the rest of the item through
412 % to the output.
413 % \begin{macrocode}
414 \ifx\istchar\glescape\expandafter\addtokens\restchars\to#3%
415 % \end{macrocode}
416 % If that first token is a special character, we convert it into a control sequence
417 % and make the remaining characters in the item into its argument.
418 % \begin{macrocode}
419 \else%
420 \expandafter\checkspecial\istchar\ifspecial%
421 \expandafter\addtokens\csname gl\istchar\endcsname\to#3%
422 \expandafter\addtokens\expandafter<\restchars>\to#3%
423 % \end{macrocode}
424 % If neither of those two conditions hold, then we're just building a normal
425 % glossword. That means we should also pull an item off of list \#2, storing it
426 % in \verb+\tb+.
427 % \begin{macrocode}
428 \else
429 \ifx\empty#2\else%
430 \pop#2\to\tb%
431 % \end{macrocode}
432 % Finally, we wrap the contents of \verb+\ta+ and \verb+\tb+ in a
433 % \verb+\glossword+ command and pass it to the output.
434 % Here we need to be careful: we want to expand \verb+\the\ta+ and \verb+\the\tb+
435 % \emph{once} --- to \emph{get} their contents. But having gotten their contents,
436 % we don't want to do any further expansion.\footnote{Why not? Because trying to
437 % expand an unexpandable macro here would be messy and unpleasant.}
438 % \begin{macrocode}
439 \edef\temp{\noexpand\glossword{\the\ta}{\the\tb}}%
440 \expandafter\addtokens\temp\to#3%
441 \fi%
442 \fi%
443 \fi%
444 \zipper#1\and#2\to#3%
445 \fi%
446 }
447 % \end{macrocode}
448 %\end{macro}
449 %\begin{macro}{\gl}
450 % Based on \verb+\zipper+, we can define a user-friendly gloss command: take
451 % two arguments, \verb+\zipper+ them together, call \verb+\fixglstrut+ (see below)
452 % to make sure everything is spaced real nice, and
453 % send everything off to be typeset.
454 % \begin{macrocode}
455 \long\def\gl#1#2{%
456 \begingroup%
457 \def\x{#1 }\def\y{#2 }\def\z{}%
458 \zipper\x\and\y\to\z%
459 \fixglstrut%
460 \ifvmode\vskip\aboveglskip\fi\z%
461 \endgroup%
462 }
463 % \end{macrocode}
464 %\end{macro}
465 %\begin{macro}{\fixglstrut}
466 %\begin{macro}{\noglstrut}
467 % The \verb+\fixglstrut+ command is issued in \verb+\gl+ right before we begin
468 % typesetting. It sets \verb+\glstrut+ to be as tall as a normal glossbox at
469 % the current font size \emph{plus} the current value of \verb+\betweenglskip+.
470 % Sometimes we'll also want to be able to suppress \verb+\glstrut+ temporarily
471 % as a way of preventing the \verb+\betweenglskip+ space from being inserted.
472 % \verb+\noglstrut+ does that. (It's temporary because \verb+\fixglstrut+ will
473 % be called again at the beginning of the next gloss and things will go back to
474 % normal. If you issue \verb+\noglstrut+ within a group, it's of course even
475 % temporary-er than that.)
476 % \begin{macrocode}
477 \def\fixglstrut{%
478 \def\glstrut{}%
479 \setbox0=\hbox{\glossword{}{}}%
480 \glstrutheight=\ht0%
481 \glstrutdepth=\dp0%
482 \advance\glstrutdepth by \betweenglskip%
483 \global\edef\glstrut{\vrule height\glstrutheight width0pt depth\glstrutdepth}}
484
485 \def\noglstrut{\def\glstrut{}}
486 % \end{macrocode}
487 %\end{macro}
488 %\end{macro}
489 %\begin{macro}{\ft}
490 % Usually after an interlinear gloss there's a line of ``free translation.''
491 % This is a user-facing command for setting that free translation line --- or,
492 % really, for setting \emph{anything} that needs to come on a new line right after
493 % an interlinear gloss. The only time this matters is when \verb+betweenglskip+
494 % and \verb+belowglskip+ are different sizes.
495 % \begin{macrocode}
496 \def\ft#1{\nobreak\par\nobreak\vskip-\betweenglskip\vskip\aboveglftskip #1}
497 % \end{macrocode}
498 %\end{macro}
499 %\begin{macro}{\lb}
500 % Here's a labeling macro, swiped from the \TeX book.
501 % \begin{macrocode}
502 \def\lb#1{{\unskip\nobreak\hfil\penalty0\hskip2em\mbox{}\nobreak\hfill\mbox{#1}}}
503 % \end{macrocode}
504 %\end{macro}
505 %\subsection{Declaring shortcuts}
506 % We have a macro \verb+\makespecial+ which will tell the parser ``treat
507 % this character as special.''
508 %
509 % But that alone won't get us anywhere interesting. We also need to \emph{define}
510 % the macro that will be executed when the special character in question is
511 % encountered. And it would be nice if we could wrap both steps --- calling
512 % \verb+\makespecial+ and defining the macro --- in a user-friendly package.
513 % That's what this last section does.
514 %
515 % Suppose we want to declare {\tt /} as a shortcut character which inserts
516 % a line break. Step one is simple:
517 % \begin{center}
518 % \verb+\makespecial{/}+
519 % \end{center}
520 % Now let's consider how the parser will respond after we've done this.
521 % Suppose we then execute this command:
522 % \begin{center}
523 % \verb+\gl{a b * c}{1 2 3}+
524 % \end{center}
525 % The output which is sent to be typeset will look like this
526 % \begin{center}
527 % \verb+\glossword{a}{1}+\\
528 % \verb+\glossword{b}{2}+\\
529 % \verb+ \gl/<>+\\
530 % \verb+\glossword{c}{3}+\\
531 % \end{center}
532 % where \verb+\gl/+ is a control sequence --- one which could not normally be
533 % input directly. And if we execute the command
534 % \begin{center}
535 % \verb+\gl{a b /argument c}{1 2 3}+
536 % \end{center}
537 % The output which is sent to be typeset will look like this:
538 % \begin{center}
539 % \verb+\glossword{a}{1}+\\
540 % \verb+\glossword{b}{2}+\\
541 % \verb+ \gl/<argument>+\\
542 % \verb+\glossword{c}{3}+\\
543 % \end{center}
544 %
545 % Step two, then, is to define a macro that will do something useful in those
546 % contexts. If the slash were a normal character, this would be easy:
547 % \begin{center}
548 % \verb+\def\gl/<#1>{\par\ifx#1\empty\else\vskip{#1}\fi}+
549 % \end{center}
550 % But since the slash isn't a normal character, we need to do it this way instead:
551 % \begin{center}
552 % \verb+\expandafter\def\csname gl/\endcsname<#1>{\par\ifx#1\empty\else\vskip{#1}\fi}+
553 % \end{center}
554 % \begin{macro}{\makeglshortcut}
555 % Well, that's just what \verb+\makeglshortcut+ does: carries out Step One and
556 % Step Two for an arbitrary character and arbitrary macro code.
557 % \begin{macrocode}
558 \long\def\makeglshortcut#1#2{%
559 \makespecial{#1}%
560 \expandafter\gdef\csname gl#1\endcsname<##1>{#2}}
561 % \end{macrocode}
562 % \end{macro}
563 % \begin{macro}{/}
564 % Here are a few examples of \verb+\makeglshortcut+ in action. To make the slash
565 % into a newline character, like we did in our example, the user-friendly way to
566 % do it is this:
567 % \begin{macrocode}
568 \makeglshortcut/{\par\ifx#1\empty\else\vskip{#1}\fi}
569 % \end{macrocode}
570 % \end{macro}
571 % \begin{macro}{[ ]}
572 % We declare that square brackets in the input will give square brackets in the output --- but with
573 % nice spacing, and an optional argument set as a subscript.
574 % \begin{macrocode}
575 \makeglshortcut[{[$_\textrm{\footnotesize#1}$\thinspace}
576 \makeglshortcut]{\unskip\thinspace]$_\textrm{\footnotesize#1}$\glspace}
577 % \end{macrocode}
578 % \end{macro}
579 %
580 % This is where it gets a little hairy. We also want to be able to set up
581 % shortcut characters that turn into the left- and right-hand sides of a
582 % \emph{delimited macro}. For instance, suppose we want to be able to use
583 % asterisks as shortcuts, such that everything in between
584 % two asterisks is put into a \verb+\framebox+. Well, step one is as easy
585 % as it was before.
586 %\begin{center}
587 %\verb+\makespecial{*}+
588 %\end{center}
589 % And if the asterisk were a normal character, step two would also be
590 % reasonably easy.
591 %\begin{center}
592 %\verb+\def\gl*<#1>#2\gl*<#3>{\framebox{#2}}+
593 %\end{center}
594 % \begin{macro}{makeglsurround}
595 % But as before, because the asterisk is not a normal
596 % character, we need to invoke \verb+\csname+. And this time, it's ugly:
597 % \begin{macrocode}
598 \long\def\makeglsurround#1#2#3{%
599 \xdef\dvglspecials{\dvglspecials#1#2}%
600 \ta=\expandafter{\csname gl#1\endcsname}%
601 \tb=\expandafter{\csname gl#2\endcsname}%
602 \expandafter\expandafter\expandafter\gdef%
603 \expandafter\expandafter\the\ta%
604 \expandafter<\expandafter##\expandafter1\expandafter>%
605 \expandafter##\expandafter2\the\tb<##3>{#3}}
606 % \end{macrocode}
607 % \end{macro}
608 %\begin{macro}{* *}
609 % Luckily, the user is protected from that ugliness. Here's a slightly more complicated
610 % version of that \verb+\framebox+-making macro, with elegant spacing and an optional
611 % argument set as a label on top of the frame. Note the use of \verb+\noglstrut+
612 % here to prevent extra space from ending up \emph{inside} the frame.
613
614 % \begin{macrocode}
615 \makeglsurround ** {%
616 \rlap{\raisebox{1.5em}{\footnotesize\sf#3}}%
617 \fbox{\noglstrut#2\unskip}\glspace}
618 % \end{macrocode}
619 % \end{macro}
620 % \Finale