% gloss.doc  --- version 1.0 (26 November 1990)
% This is the documentation for gloss.tex.
% To read this file, process it with (plain) TeX: tex gloss.doc
% (To do that, you need both gloss.tex and manmac.tex. The latter has
% the macros for typesetting the TeXbook, as explained in appendix E.
% It comes free with the standard distribution of TeX.)
%
% NOTE: Processing this file with TeX will create empty files
%       index.tex and answers.tex in your directory. And if you
%	have a file pages.tex in your directory, TeX will probably
%	get very confused.
%	The manmac format will try to load a font called cmman; if
%	TeX complains that it cannot find that font you can savely
%	ignore that, since the font is not actually used.
%
% This file: copyright (c) 1990  Marcel van der Goot.
%	You may redistribute this file and printed versions of it.
%
% original: csvax.cs.caltech.edu [131.215.131.131] in pub/tex
%           (use anonymous ftp). Also in various archives.
%
% Marcel van der Goot
% marcel@cs.caltech.edu
%   Caltech 256--80
%   Pasadena, CA 91125
%   (818) 356--4603

% ------ definitions for manual pages:
% The documentation is typeset using Knuth's ``manmac'' macros, with a
% few additional things defined here. You are free to use or adapt these
% extra definitions.

\input manmac % the macros used for typesetting The TeXbook (appendix E)
\catcode`^=7 % manmac makes ^ active for creating an index
	% we don't make an index, and we need ^ to be non-active

{\catcode`\^^M=12 \endlinechar=-1 % 12 = other
\long\gdef\manpagehead#1^^M#2^^M#3^^M^^M% tex-file, description, version
   {\egroup % matches \bgroup in \manpage
    \par\vfill\eject
    \edef\rhead{\manualname: #1\unskip}%
    \setbox1=\hbox{\titlefont #1\quad}%
    \setbox3=\vtop{\advance\hsize by-\wd1 \parindent=0pt \raggedright
		   #2\par
		   #3\par
		   \cnotice
		  }%
    \line{\box1\box3}%
    \bigskip\bigskip\bigskip\noindent
   }%
} % restore \catcode`\^^M

\outer\def\manpage
   {\bgroup\catcode`\^^M=12
    \manpagehead
   }

\hsize=6.5in\vsize=8.9in % default plain TeX values
\pagewidth=\hsize \pageheight=\vsize

\def\cnotice{Copyright \copyright\ 1991 Marcel R. van der Goot}
\def\manualname{Midnight Macros}

% LaTeX logo, from latex.tex (except for the capital `A': manmac
% doesn't have a real smallcaps font)
\def\LaTeX{{\rm L\kern-.36em\raise.3ex\hbox{\sc A}\kern-.15em
    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}

\tenpoint

% (end of extra definitions)

% -------------------- gloss.doc:

\input gloss % change this to refer to gloss.tex on your system

\pageno=5 % follows quire.doc

\manpage gloss.tex
Macros for vertically aligning words in consecutive sentences.
Version: 1.0 (26 November 1990) (doc: 10 November 1990)

To gloss means to insert explanations or translations of words
between the lines of a text. For ease of reading, one generally
wants the explained word and the explanation to line up, as in
\gloss Dit is een Nederlands voorbeeld.
This is a Dutch example.
\begindisplay
\box\gline
\enddisplay
The macros defined in gloss.tex make it convenient to typeset
such glossed sentences. To use the macros, you first have to
|\input gloss|\footnote*{We have made no attempt to \LaTeX ify gloss.tex,
but you can use the macros in \LaTeX\ just as in plain \TeX.}.
The main macro for typesetting glossed sentences
is |\gloss|. It should be followed by the two sentences, each
terminated by a \<return>. The previous example was typeset with
\begintt
\gloss Dit is een Nederlands voorbeeld.
This is a Dutch example.
\endtt
But instead of printing the glossed sentence, |\gloss| puts the
whole construction in an hbox, called |\gline|. To actually insert
that box in your text, you use |\box\gline| or |\unhbox\gline|.
The text is put in a box to make it easier to handle. For instance,
it makes it easy to put extra indentation or an example number
in front of the sentence. (The baseline of the hbox is the baseline
of the second line in the box.) The difference between |\box\gline|
and |\unhbox\gline| is that the latter allows line breaks in the
glossed sentence. That is obviously only useful if the glossed
sentence is quite long; we will see an example later on.

The |\gloss| macro splits each sentence into words, and then aligns
the words. In this context, a word is a sequence of characters separated
by spaces. The number of spaces between words is irrelevant, so that
you can line up the words in your input as well. Using
\begintt
\gloss Dit  is een Nederlands voorbeeld.
       This is a   Dutch      example.
\endtt
gives exactly the same output as the input given before. However,
you should not insert extra \<return> symbols. The sentences
can have a different number of words.
Sometimes one of the two sentences has a word without equivalent
in the other sentence. In such cases you can insert an empty word
with |{}|. You can also combine several words into a single word,
by using grouping. The following example illustrates both.
\begintt
\gloss Dit is een voorbeeldje     in het Nederlands.
       This is a {little example} in {}  Dutch.
\endtt
gives
\gloss Dit is een voorbeeldje     in het Nederlands.
       This is a {little example} in {}  Dutch.
\begindisplay
\box\gline
\enddisplay
Without the grouping ``example'' would have been lined up
with ``{\it in\/}.''

By default the first sentence of a glossed pair is set in italic font
(|\it|), the second in roman font (|\rm|). You can change this by,
for instance, setting |\let\eachwordone=\rm|, which will set
each word in the first sentence in roman font. The font of the second
sentence is governed by |\eachwordtwo|. This use of the |\eachword|
macros is an instance of a more general mechanism that is explained
later. You can insert font changes in the middle
of a sentence, but they only apply to the next word.
\begintt
\gloss Dit  is een Nederlands voorbeeld.
       This is a   \sl Dutch      example.
\endtt
will set ``Dutch'' in slanted font, but ``example'' in the default
font. The |\gloss| macro considers |\sl Dutch| to be a single word,
and sets this word in an hbox so that the effect of the font change
is limited. |\sl| is not considered a word by itself, because
spaces following a macro are always skipped.

{
\let\eachwordone=\rm
\def\sixstrut{\vrule height5pt depth1.5pt width0pt }
\def\eachwordtwo{\let\strut=\sixstrut\sixrm}
\baselineskip=22.5pt
\setbox0=\hbox{ }\advance\rightskip by-\wd0
\let\s=\string

\gloss You may want to gloss more than a single sentence, maybe
       {} verb verb {} verb  {}   {}   {} {}    noun
\gloss a whole paragraph.
       {} {}   noun
\gloss It would however be quite inconvenient if you had to
       {} verb {}     verb
\gloss follow |\s\gloss| by a whole paragraph on a single line (by
       verb    macro     {} {} {}   noun      {} {} {}    noun
\gloss terminating each line with a {|\%|-sign}), followed by a line
       verb        {}   noun  {} {} noun             verb  {} {} noun
\gloss containing all the glosses. Especially if there are a lot of
       verb {} {}         noun      {}        {} {}   verb {} noun
\gloss unglossed (empty) words, it would be hard to get the sentences
       verb?       {}     noun   {} verb verb {} {} verb {} noun
\gloss lined up properly. Fortunately, a paragraph like the current
       verb {} {}          {}         {} noun
\gloss one can be set quite easily. |\s\gloss| puts the created sentence
       noun verb verb verb {} {}      macro    verb {} verb noun
\gloss  in |\s\gline|, and |\s\gline| is emptied by using |\s\box| or
       {} box        {}   box   verb verb    {} verb
\gloss  |\s\unhbox|. But if you don't empty |\s\gline|, the next
       {}          {}  {} {} verb   verb     box
\gloss usage of |\s\gloss| will append the new sentence to the older
       noun  {}  macro  verb verb    {}   {} noun
\gloss one. Hence, this paragraph was typeset with
       noun {}    {}   noun     verb  verb
\unhbox\gline

}
\beginlines
|\gloss You may want to gloss more than a single sentence, maybe|
\nobreak
|       {} verb verb {} verb  {}   {}   {} {}    noun|
|\gloss a whole paragraph.|
\nobreak
|       {} {}   noun|
\quad\vdots\ {\sevenrm(10 more)}\smallskip
|\gloss one. Hence, this paragraph was typeset with|
\nobreak
|       noun {}    {}   noun     verb  verb|
\nobreak\smallskip\nobreak
|\unhbox\gline|
\endlines
Of course, a few more things, like the fonts, had to be changed. We
discuss that next. Also notice that it takes \TeX\ quite some time
to typeset such a paragraph.

\medskip
\def\word{{\rm\<word>}}
\danger Each word from the first line following |\gloss| is set in
an hbox as follows
\begintt
\hbox{\eachwordone\strut|word|]}
\endtt
The macro |\eachwordone| is by default |\let| equal to |\it|, but
can be redefined. The previous paragraph was made with
\begintt
\let\eachwordone=\rm
\def\sixstrut{\vrule height5pt depth1.5pt width0pt }
\def\eachwordtwo{\let\strut=\sixstrut\sixrm}
\endtt
(If |\strut| were not redefined, there would be too much space between
the first and the second line.) Furthermore, to obtain a larger separation
between the pairs of lines, the |\baselineskip| was set to 22.5 pt
(|\baselineskip| governs the spacing between the glossed pairs, the
spacing within the pair is governed by the |\strut|s.) Since a word
does not contain spaces, and each word is followed by a space,
the |\eachword| macros can easily be made to take the word (and the
|\strut|) as argument. For instance, the following definition will
underline every word in the first line.
\begintt
\def\eachwordone#1|]{\rm\underbar{#1}|]}
\endtt
The space following the word does not disappear at a line break, because
it is hidden within an hbox. To hide this extra space between the last
word and the right margin, the final thing needed to typeset the
previous paragraph was
\begintt
\setbox0=\hbox{|]}\advance\rightskip by-\wd0
\endtt
This is not perfect, because the size of the space depends on the font:
there is a {\sixrm verb} sticking out slightly.

\danger The word boxes are paired together in a single vbox, and
|\gline| consists of a sequence of these vboxes. The vboxes are separated
by some glue, equal to |\glossglue|. Without this glue no line breaks
would be possible, nor would the spaces between the words be stretchable.
|gloss.tex| says |\glossglue=0pt plus2pt minus1pt|. The stretch and
shrink components are only relevant if |\unhbox\gline| is used.

Sometimes you would rather not have extra space following a word,
for instance when parts of a word are glossed separately: In
\gloss Dit is een voorbeeld- je in het Nederlands.
This is an example (``little'') in {} Dutch.
\begindisplay
\box\gline
\enddisplay
it is preferable to have no space following ``{\it voorbeeld-}'' if it
is not necessary. This can easily be achieved with a macro like
\begintt
\def\+#1|]{#1}
\endtt
which is inserted just before the word that should not have a space:
|\+voorbeeld- je|.
It can also be done by making the hyphen gobble up the space, as in
\begintt
\let\hyphen=-
\catcode`-=\active
\def-#1|]{\hyphen#1}
\endtt
However, this does not work if there is a word with a hyphen in the
middle. To handle that situation, a more sophisticated definition
of |-| can check what the next character is, using
|\futurelet|. We will not do that here, as it has little to do with
glossed sentences.

\bye