path: root/macros/latex/contrib/gb4e/gb4e-doc.tex

% -*- LaTeX -*-
%%%% Latex2e:
\documentclass[11pt,a4paper]{article}
\usepackage{gb4e}
%%%% LaTeX209:
%\documentstyle[a4,11pt,gb4e]{article}
%%
\def\bs{$\backslash$}
\frenchspacing\parskip1.2ex
\parindent0pt
\def\bit{\vskip.05\baselineskip\hspace*{1em}\hangindent4em\hangafter1}
\title{Preliminary documentation for {\tt gb\gbVersion.sty}\thanks{%
  Parts of ``Government-Binding style'' {\tt gb\gbVersion.sty} are
  loosely based on ideas and code by M.~Covington, M.~van der Goot,
  J.~Frampton and L.~Holt. In particular it automatically includes {\tt
    cgloss\gbVersion.sty}, a (heavily adapted) version of M.~Covington's
  \LaTeX-adaptation of M.~van der Goot's plain\TeX{} Midnight gloss
  macros.} and {\tt cgloss\gbVersion.sty}}
\author{Hans-Peter Kolb \\[2pt]
Craig Thiersch $<${\sf c\_thiersch@alum.mit.edu}$>$}
\date{}
\begin{document}
\maketitle
\tableofcontents
\vspace*{1cm}
\vfill
\subsection*{Important note:}
The file {\tt gb\gbVersion.sty}\footnote{%
  This version of {\tt gb{\em x}.sty}
  redesigns the entire series of {\tt \bs ex}
  commands. It also contains changes to the gloss-macros to make them
  work in footnotes etc. {\bf NB: The {\em {\tt e}xport\/} version does
  not provide a
    soft-landing system of command-compatibility with earlier
    versions}.

  NB: Make sure to get {\tt cgloss\gbVersion.sty} together with {\tt
    gb\gbVersion.sty}.

  This version of gb4e includes some \emph{minimal} bug-fixes and enhancements by 
  Alexis Dimitriadis, with emphasis on backward compatibility.
}
 allows \verb"_" (subscript) and
\verb"^" (superscript) to be used in ordinary text, which is handy,
but because it changes their definitions it must be loaded {\bf after}
any file that uses them in their \TeX\ meaning.
\pagebreak
\section{Linguistic examples in \LaTeX}
{\tt gb\gbVersion.sty} is a style option to be used
  with \LaTeX's major document styles. To make its commands available,
  add it to your document's preamble like this:
\bit (in LaTex2e:)~~~~~~\verb,\usepackage{gb4e},
\bit (in LaTex 2.09:)~~{\tt \bs documentstyle[\ldots gb\gbVersion]\{\ldots\}}


Its core is an environment for the formatting of
linguistic examples.

The format is simple:\\
(Batches of) examples are introduced by
\verb,\begin{exe}, which sets up the top level example environment.
Obviously, this environment has to be closed after the example(s) by
\verb,\end{exe},. You can create sub- and subsubexamples by
embedding  several {\tt xlist}-environments (up to three levels deep).

Here is an elaborate example:
\begin{verbatim}
\begin{exe}                   % sets up the top-level example environment
\ex\label{here} Here is one.  % example with running number
\ex[*]{Here another is.}      % judged ex. with running number
\ex Here are some with judgements. 
 \begin{xlist}                % first embedding (alphabetical numbering)
 \ex[]{A grammatical sentence am I.}
 \ex[*]{An ungrammatical sentence is you.}
 \ex[??]{A dubious sentence is she.}
 \ex                          % just the number
  \begin{xlist}               % second embedding (roman numbering)
  \ex[**]{Need one a second embedding?}
  \ex[\%]{sometime.}
  \end{xlist}                 % end second embedding
 \ex Dare to judge me! 
 \end{xlist}                  % end first embedding
\ex This concludes our demonstration.
\end{exe}                     % end example environment
\end{verbatim}
This produces:
\begin{exe}                   % sets up the top-level example environment
\ex\label{here} Here is one.              % example with running number
\ex[*]{Here another is.}      % judged ex. with running number
\ex Here are some with judgements. 
 \begin{xlist}                % first embedding (alphabetical numbering)
 \ex[]{A grammatical sentence am I.}
 \ex[*]{An ungrammatical sentence is you.}
 \ex[??]{A dubious sentence is she.}
 \ex                          % just the number
  \begin{xlist}              % second embedding (roman numbering)
  \ex[**]{Need one a second embedding?}
  \ex[\%]{sometime.}
  \end{xlist}                % end second embedding
 \ex Dare to judge me! 
 \end{xlist}                  % end first embedding
\ex This concludes our demonstration.
\end{exe}                     % end example environment

All example-list commands have an optional argument which allows you to
set the labelwidth to, e.g., the widest label to come (in the style of
\verb,\begin{bibliography},). So,
\verb,\begin{exe}[(234)], will set the labelwidth to the width
  of ``{\tt (234)}''---which is also the default. The other defaults
  are  ``{\tt m.}'' for {\tt xlist}, and ``{\tt iii.}'' for {\tt xlisti}.
The default labelwidth for the {\tt exe}-environment can also be changed
globally by issuing a \verb,\exewidth{<string>}, command in the
preamble of your document (i.e.\ between 
\verb'\documentclass' and \verb'\begin{document}').
 
\subsection{Examples with running numbers}
As just shown, every example with a running number
is introduced by \verb'\ex'.
Obviously, \verb,\ex, is {\em context-sensitive\/}: at the top
level the number produced is {\em arabic} and accumulative
throughout the document; in embedded {\tt xlist}-environments it is
{\em alphabetic\/} on the first level, {\em roman\/} on the second, and
{\em arabic\/} on the third, starting with $a.$, $i.$, and $1.$,
repectively. For total control over the shape
of your subexample-numbering there are some special forms listed
below:\footnote{%
Note that for all
{\tt \bs begin\{<env>\}} \ldots {\tt \bs end\{<env>\}} pairs the forms
{\tt \bs<env>} \ldots {\tt \bs end<env>} are also permissible in \LaTeX.
So if you like you can go on using {\tt\bs xlist} \ldots
{\tt\bs endxlist} for {\tt \bs begin\{xlist\}} \ldots {\tt \bs end\{xlist\}}
 etc., but \LaTeX-syntaxcheckers and utilities like AUC-\TeX\ won't
recognize them as necessarily paired and won't report unmatched
 expressions. (Have you ever tried {\tt <Ctrl>-C <Ctrl>-C}
 (= LaTeX-environment) or {\tt <Ctrl>-C <Ctrl>-F}
 (= LaTeX-close-environment) in EMACS' AUC-\TeX\  mode? You should---it
saves a lot of typing.)}
\begin{center}
\begin{tabular}{|l|l|}\hline
{\em Environment}& {\em Default numbering}\\ \hline\hline
\verb,\begin{exe}, \ldots \verb,\end{exe},& (1) arabic 
(Toplevel)\\ \hline\hline
\verb,\begin{xlist}, \ldots \verb,\end{xlist},& depends on level of
embedding\\ \hline
\verb,\begin{xlista}, \ldots \verb,\end{xlista},& a. alphabetical\\
\verb,\begin{xlisti}, \ldots \verb,\end{xlisti},& ii. roman\\
\verb,\begin{xlistn}, \ldots \verb,\end{xlistn},& 3. arabic\\
\verb,\begin{xlistI}, \ldots \verb,\end{xlistI},& IV. Roman\\
\verb,\begin{xlistA}, \ldots \verb,\end{xlistA},& E. Alphabetical\\ \hline
\end{tabular}
\end{center}
In all cases, \verb,\label,/\verb,\ref, commands will do The Right
Thing.

The syntax of \verb,\ex, is as follows:
\bit\verb'\ex' $\Longrightarrow$ a label with running number (e.g., if a
sublist of examples follows).
\bit\verb'\ex <example>'  $\Longrightarrow$ a numbered example.
\bit\verb'\ex[<judgement>]{<example>}' $\Longrightarrow$ a numbered example
  with judgement. 

The space reserved for judgements can be controlled by the command\break
\verb,\judgewidth{<string>},, which sets it to the width of
\verb,<string>, (Default: ``{\tt ??}''). It can be issued in the
preamble to change the
default globally, or within an {\tt exe}-environment for a
local change.

\paragraph*{In short:} Use \verb"\ex" for all numbered
examples; if they have no optional argument (judgement)
 they will be flush left;
if they have {\tt [ ] }'s then there will be a space reserved for
judgements. (NB: In this case you have to
indicate the scope of the example itself with \{\ldots\}'s.)


\subsection{Examples with other identifiers}
Sometimes it is necessary not to use running numbers but to specify
the identifier of an example manually as in:
\begin{quote}
\ldots let us now contemplate Chomsky (1981:264, ex.29f):
\begin{exe}
\exi{(29)} \al\lb{INFL} AGR]\lb{VP} V\ldots]
\exi{(30)}
 \begin{xlist}[(ii)]
   \exi{(i)} \be\lb{VP} V-AGR\ldots]
   \exi{(ii)} \be\lb{VP}\lb{VP} V-AGR\ldots] NP]
 \end{xlist}
\end{exe}
\end{quote}
For cases like this there is the command \verb'\exi{<identifier>}'
which works exactly like \verb'\ex':
\bit\verb'\exi{<identifier>}'  $\Longrightarrow$ the identifier as label
\bit\verb'\exi{<identifier>} <example>'  $\Longrightarrow$ the example
  labelled with identifier
\bit\verb'\exi{<identifier>}[<judgement>]{<example>}'
  $\Longrightarrow$ the judged example,\\ labelled with identifier.\\


So the example above is produced by:

\pagebreak[2]
\begin{verbatim}
\ldots let us now contemplate Chomsky (1981:264, ex.29f):
\begin{exe}
\exi{(29)} \al\lb{INFL} AGR]\lb{VP} V\ldots]
\exi{(30)}
 \begin{xlist}[(ii)]
   \exi{(i)} \be\lb{VP} V-AGR\ldots]
   \exi{(ii)} \be\lb{VP}\lb{VP} V-AGR\ldots] NP]
 \end{xlist}
\end{exe}
\end{verbatim}

\verb'\exi' can be used to deal with many labelling problems. The
three most commons ones are predefined:
\begin{itemize}
\item Crossreferences (\verb'\exr{<label>}'):
  \begin{itemize}
  \item[] 
\ldots a sentiment already expressed in (\ref{here})
on page \pageref{here}, repeated here:
\begin{exe}
\exr{here} Here is one.
\end{exe}
\begin{verbatim}
\ldots a sentiment already expressed in (\ref{here})
on page \pageref{here}, repeated here:
\begin{exe}
\exr{here} Here is one.
\end{exe}
\end{verbatim}
\end{itemize}
\item Crossreferences with primes (\verb'\exp{<label>}'):
\begin{itemize}\item[]
\ldots which contrasts sharply with
\begin{exe}
\exp{here}[??]{Here is two}
\end{exe}
\begin{verbatim}
\ldots which contrasts sharply with
\begin{exe}
\exp{here}[??]{Here is two.}
\end{exe}
\end{verbatim}
\end{itemize}
\item Unnumbered examples (\verb'\sn'):
\begin{itemize}\item[]
\ldots here we have an example
\begin{exe}
\sn[\%]{Colourless green ideas sleep furiously.}
\end{exe}
of a sentence too famous to be numbered\ldots
\begin{verbatim}
\ldots here we have an example
\begin{exe}
\sn[\%]{Colourless green ideas sleep furiously.}
\end{exe}
of a sentence too famous to be numbered\ldots
\end{verbatim}
\end{itemize}
\end{itemize}
Again, these commands work exactly as \verb'\ex' or
\verb'\exi{<identifier>}'. 

\pagebreak[2]
\section{Glosses}\label{gloss}
{\tt gb\gbVersion.sty} offers a set of commands for typesetting glosses based
on M.\ Covington's \LaTeX-adaptation of M.\ van der Goot's Midnight gloss
\TeX-macros.\footnote{They are defined in the file {\tt cgloss\gbVersion.sty}
which is automatically read by {\tt gb\gbVersion.sty}.}\\[5pt] 
A gloss basically contains two elements:
\bit \verb'\gll' (obligatory):
introduces the actual sentence/gloss pair;\footnote{%
There is also a three-line version of {\tt \bs gll}, {\tt \bs glll} for
special morphological/phonological information (not for the free
translation!).}
\bit \verb'\glt' or \verb'\trans' (optional):  introduces a free
translation. 

\pagebreak[2] 
So the following
\begin{verbatim}
\begin{exe}
\ex
\gll Wenn jemand in die W\"uste zieht ... \\
If someone in the desert draws and lives ... \\
\trans `if one retreats to the desert and ... '
\end{exe}
\end{verbatim}
produces:
\begin{exe}
\ex
\gll Wenn jemand in die W\"uste zieht und lebt dort von Heuschrecken
  oder sich im Wald verirrt hat und n\"ahrt sich von Wurzeln und
  Beeren, \ldots\\
If someone in the desert draws and lives there from grasshoppers or
self {in the} woods errored has and nourisches self from roots and
berries \ldots\\
\trans `if one retreats to the desert and lives there from
grasshoppers or gets lost in the woods and lives off of roots and berries'
\end{exe}

Since the macro counts words, to match one word with a
multi-word gloss or vice versa, you either have to put the words in
braces or use
hyphens. For example, German {\em zum} could be glossed as either 
\verb"{to the}" or \verb"to-the". And of course, if you have a word that is
not glossed, like WH-trace $e_i$ or a proper name, you have to tell the
gloss line that there's something there, e.g. with \{~\}.
\begin{exe}
\ex
\gll Den Fritz_1 habe ich \_\_{}_1 zum Essen eingeladen.\\
     the fred have I {} {to the} eating invited.\\
\glt I invited Fred for dinner.
\end{exe}
is produced by
\begin{verbatim}
\begin{exe}
\ex
\gll Den Fritz_1 habe ich \_\_{}_1 zum Essen eingeladen.\\
     the fred have I {} {to the} eating invited.\\
\glt I invited Fred for dinner.
\end{exe}
\end{verbatim}

Although it is possible to treat an optional judgement just as the
first word of the sentence with a null-translation as in (\ref{null}),
the standard way of using an optional argument with \verb'\ex' as in
(\ref{arg})  is simpler (and conceptually more consistent).
\begin{exe}
\ex\label{null}
\gll * Dit is een voorboeldje.\\
     {} This is an example.\\
\trans `Here's where the translation would be'

\ex[*]{\label{arg}
\gll Dit is een voorboeld.\\ This is an example.\\
\trans `and this would be the translation line'
}
\end{exe}
\pagebreak[2]
This output is produced by
\begin{verbatim}
\ex
\gll * Dit is een voorboeldje.\\
     {} This is an example.\\
\trans `Here's where the translation would be'
\end{verbatim}
and
\begin{verbatim}
\ex[*]{
\gll Dit is een voorboeld.\\
     This is an example.\\
\trans `and this would be the translation line'}
\end{verbatim}
respectively.


By default the glosses appear in
``Linguistic Inquiry style'' with all lines in \verb"\rm". To change a line
(e.g.\ to italics if required for a particular journal), just put
the appropriate lines in the preamble of your document, e.g.,
\verb"\let\eachwordone=\it".\footnote{Font commands that take an argument, such as {\tt \bs textit}, can only be used with versions of gb4e after 2009/12/28. Upgrade to the latest version or use argument-less font commands, such as {\tt \bs it}.}
 The same for 
\verb"\eachwordtwo" and \verb"\eachwordthree" (used by the three line
glosses introduced by \verb'\glll'). Note that it will
{\em not} work  
to put \verb"\it" before the line in your text, as the words are parsed
separately.
 For example,
\verb"\let\eachwordone=\it" yields
\begin{exe}
\let\eachwordone=\it
\ex[?]{
\gll Und hier k\"onnen wir sehen was f\"ur Unfug wird gemacht wenn er einen 
ganz langen Satz binnen kriegt\\
and hier can we see what for nonsense will-be made if he a very long
sentence inside gets.\\
\glt `and here's what happens to a looooong sentence'}
\end{exe}
and \verb"\let\eachwordtwo=\sf" gives 
\begin{exe}\let\eachwordtwo=\sf
\ex[*]{
\gll Cette phrase n'a pas une traduction.\\
This sentence {not has} nought a translation.\\}
\end{exe}
As you can see by these examples, you can also re-define the {\tt eachword}
variables in your file for individual examples by using the \verb"\let"
command within the \verb"\begin{exe}" environment, and then the style change is
local.

By default, the glosses will be single-spaced even in double-spaced
environments. If you---or rather the journal you're submitting
to---don't like that, just give the command \verb,\nosinglegloss, in the
preamble of your document. 

\section{Varia}
{\tt gb\gbVersion.sty} contains a few additional goodies (mostly
abbreviations for frequently used constructions) which will be
properly documented in a subsequent life. For now just some sample of
uses:
\begin{itemize}
\item X-bar styles: Per default \verb,\obar{X} \ibar{X} \iibar{X} \mbar{X},
  yields \obar{X} \ibar{X} \iibar{X} \mbar{X}. With \verb,\primebars,
  in the preamble, the outcome is \obar{X} X^{'} XP \mbar{X}.
\item Labelled bracketings:
\verb,\lb{NP}[1]\lb{D}[1] the]\lb{\ibar{N}},\break \verb,example]], yields 
\lb{NP}[1]\lb{D}[1] the]\lb{\ibar{N}} example]]. An analogous
right-bracket (\verb,\rb,) is also defined. 
\item Greek letters: the frequently used letters \al\be\ga\de\ and
  \th\  have abbreviations \verb,\al \be \ga \de \th, which also work
  outside mathmode.
\item Sub- \& superscripts (\verb,_, and \verb,^,) work outside mathmode, too.
\\
{\bf Note:} This feature is known to cause problems for a number of
other packages. It is retained for backward compatibility. In case of problems,
you can disable it by adding the command \verb|\noautomath| in your preamble 
immediately after loading the gb4e package. You can also re-enable it later with
the command \verb|\automath|. [Added 2009/12/28]

\end{itemize}
At the very end of the style-file a couple of special accents for
``exotic'' languages are defined.  Also, check out the \verb,\attop,-,
\verb,\atcenter,-macros (by Lex Holt) for aligning naughty
({\tt picture}-)examples to their numbers, as well as J.~Frampton's
movement-arrows: 
\begin{exe}
\ex\atcenter{
 \arrowalign{
  \fillright\pd&\link3&\fillleft{\vrule\hfil}\cr
  Did&\ &John&\ &t_{\mathrm{Agr}}&\ appear &t&\ to be likely &t&\ to win.\cr
  &&\fillright\pu&\link3&\centr{\vrule\spacer\pu}&\lf&\fillleft\vrule\cr}
            }
\end{exe}
\begin{verbatim}
\begin{exe}
\ex\atcenter{
 \arrowalign{\fillright\pd&\link3&\fillleft{\vrule\hfil}\cr
  Did&\ &John&\ &t_{\mathrm{Agr}}&\ appear &t&\ to be likely 
          &t&\ to win.\cr
  &&\fillright\pu&\link3&\centr{\vrule\spacer\pu}&\lf
          &\fillleft\vrule\cr}
            }
\end{exe}
\end{verbatim}


\end{document}