%% BUILD THIS WITH LUALATEX (or XeLaTeX), not pdfLaTeX. %% %% Not a preference: section 9.3 documents that characters with a diacritic %% BELOW the letter -- Indic and Semitic transliteration, Latvian, Romanian %% -- are composed from two glyphs under pdfLaTeX, so the PDF's text layer %% records something other than what was written and a screen reader reads %% it wrongly. This manual contains exactly those characters, in the table %% that explains the problem. Built with pdfLaTeX it therefore exhibited %% the defect it warns about, which is not a good look for the manual of a %% package whose selling point is accessible output. %% %% fontspec keeps Latin Modern, so the result looks as it always did. \documentclass[11pt,a4paper]{article} \usepackage{iftex} \ifPDFTeX \PackageError{linguexx-doc}{Build this manual with lualatex or xelatex} {Under pdfLaTeX the transliteration examples in section 9.3 come out with a broken text layer -- which is the very thing that section documents. Run: lualatex linguexx-doc} \fi %% No fontspec and no lmodern here on purpose. Under LuaLaTeX the kernel %% already uses Latin Modern in TU encoding with every shape this manual %% needs; naming the families explicitly with \setmainfont loses the %% small-caps and bold-monospace shapes (the Leipzig table is entirely %% small caps), which shows up only as a font-shape warning in the log. \usepackage[margin=30mm]{geometry} \usepackage{microtype} \usepackage{xcolor} \usepackage{hologo} \usepackage{array} \usepackage{booktabs} \usepackage{longtable} \usepackage{enumitem} \usepackage{fancyvrb} \usepackage{amsmath} \usepackage{graphicx} \usepackage[normalem]{ulem} \usepackage[lazy,langsci]{linguexx} % This manual is written in linguex's reference convention -- its prose says % ``as in \ref{ex:x}'' and expects ``(1)'' -- while [langsci] selects % langsci-gb4e's bare one. One line asks for the other; see the subsection % ``What \ref prints'' in the [langsci] section. \ExParenRefs \usepackage[colorlinks,linkcolor=blue!50!black,urlcolor=blue!50!black]{hyperref} % --- documentation helpers -------------------------------------------------- \definecolor{codebg}{gray}{0.96} \newcommand{\cs}[1]{\texttt{\textbackslash #1}} \newcommand{\pkg}[2][]{\textsf{#2}} \newcommand{\opt}[1]{\texttt{#1}} \newcommand{\meta}[1]{\textrm{\itshape\textlangle#1\textrangle}} \newcommand{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}} \newcommand{\oarg}[1]{\texttt{[}\meta{#1}\texttt{]}} % a length/command name set as text, for the box-model diagram \newcommand{\lname}[1]{\text{\ttfamily\scriptsize\textbackslash #1}} \DefineVerbatimEnvironment{code}{Verbatim} {frame=leftline,framerule=1pt,rulecolor=\color{gray!40}, xleftmargin=8pt,fontsize=\small,samepage=true} \newcommand{\rendered}{\par\medskip\noindent\textcolor{gray!70}{\small renders as:}\par\nobreak\smallskip} \newcommand{\afterex}{\par\addvspace{\medskipamount}} \title{The \pkg{linguexx} package\\[4pt] \large Numbered examples, interlinear glosses and grammaticality judgments\\ for linguistics} \author{Gerhard Schaden\\\texttt{gerhard.schaden@univ-lille.fr}} \date{Version 1.3.1 --- \today} \begin{document} \maketitle \begin{abstract} \noindent \pkg{linguexx} typesets the standard apparatus of linguistic writing: numbered examples with lettered sub-examples, grammaticality judgments that hang in the margin, interlinear morpheme-by-morpheme glosses with any number of tiers, cross-references that follow the numbering automatically, and examples inside footnotes. Its input syntax is deliberately terse --- \cs{ex.}\ starts an example, a blank line ends it --- so that data does not disappear under markup. That syntax comes from Wolfgang Sternefeld's \pkg{linguex}, which this package owes almost everything to, and which it is designed to replace. With one exception, any document that compiles under \pkg{linguex} should also compile under \pkg{linguexx} – and given one switch, it should look the same. \pkg{linguexx} is a reimplementation from the ground up, undertaken for two reasons. The first is to repair the structural weaknesses of the original. The second is to bring the glossing closer to the level of John Frampton's \pkg{expex}: glosses may now have any number of tiers, each with its own font, rather than the two or three that \pkg{cgloss4e} allowed. A further new feature is that the package tags the whole example apparatus, from numbered examples to interlinear glosses, for a PDF/UA-2-conformant result (checked with \texttt{veraPDF}). The package's only dependencies are \pkg{tikz} and \pkg{xspace}, plus the \pkg{expl3} layer, part of the \LaTeX{} kernel since 2020, and it works identically under \hologo{pdfLaTeX}, \hologo{XeLaTeX} and \hologo{LuaLaTeX}. This manual is self-contained and assumes no acquaintance with \pkg{linguex} or any other example package. \end{abstract} \tableofcontents % =========================================================================== \section{A quick tour \& recommended usage}\label{sec:tour} % =========================================================================== This section illustrates the recommended use for a total novice in linguistic glossing. If you already know \pkg{linguex}, you can do what you are used to do. Load the package, with the recommended option \texttt{phantomalign} (see Section~\ref{sec:phantomalign}): \begin{code} \usepackage[phantomalign]{linguexx} \end{code} \noindent An example is introduced by \cs{ex.}\ --- note the period, which is part of the command name --- and ended by a \cs{z.}, or alternatively, a blank line: \begin{code} \ex. Colourless green ideas sleep furiously. \z. \end{code} \rendered \ex. Colourless green ideas sleep furiously. \z. \afterex Numbering is automatic and runs through the document. Sub-examples are introduced by \cs{a.}, and continued by \cs{b.}, \cs{c.}\ and so on: \begin{code} \ex. \a. Ich habe geschlafen. \b. Ich bin geschlafen. \z. \end{code} \rendered \ex. \a. Ich habe geschlafen. \b. Ich bin geschlafen. \z. \afterex A grammaticality judgment typed at the start of an example is recognized automatically and set in the margin, so that the example texts stay aligned: \begin{code} \ex. \a. Ich habe geschlafen. \b. *Ich habe gestorben. \z. \end{code} \rendered \ex. \a. Ich habe geschlafen. \b. *Ich habe gestorben. \z. \afterex Interlinear glosses are written with \cs{gll} (two tiers), with the free translation on a \cs{glt} line. The tiers are aligned word by word, and category labels are set in small capitals with \cs{lpzg}: \begin{code} \ex. \gll Ich schlief. \\ I sleep.\lpzg{pst} \\ \glt `I slept.' \z. \end{code} \rendered \ex. \gll Ich schlief. \\ I sleep.\lpzg{pst} \\ \glt `I slept.' \z. \afterex To refer to an example, label it and use \cs{ref}, exactly as with any other \LaTeX{} counter; the parentheses come for free. \cs{Next} and \cs{Last} refer to the next and the previous example without a label: \begin{code} \ex.\label{ex:sleep} Ich habe geschlafen. \z. As \ref{ex:sleep} shows, ... The contrast in \Next is sharper: \ex. *Ich habe gestorben. \z. \end{code} \rendered \ex.\label{ex:sleep} Ich habe geschlafen. \z. As \ref{ex:sleep} shows, \dots{} The contrast in \Next is sharper: \ex. *Ich habe gestorben. \z. \afterex This concludes the presentation of the essential syntax for the most elementary needs. The rest of this manual fills in the details: more nesting levels, more gloss tiers, arbitrary judgment marks, reference ranges, examples in footnotes, source attributions, and the layout parameters. % =========================================================================== \section{Origins, acknowledgments, and relation to other packages} \label{sec:origins} % =========================================================================== \paragraph{\pkg{linguex} (Wolfgang Sternefeld).} This package started from a set of patches I made to \pkg{linguex} over the years. As a consequence, the input language of \pkg{linguexx} \emph{is} the input language of \pkg{linguex}, deliberately and almost exhaustively: \cs{ex.}, \cs{a.}--\cs{f.}, \cs{z.}, termination by blank line, custom labels in brackets, automatic roman numbering in footnotes, the \cs{Next}/\cs{Last} family, \cs{exg.}\ and its relatives, and the layout parameters down to their names. Existing \pkg{linguex} documents compile essentially unchanged; the default geometry is a little tighter than \pkg{linguex}'s, and the option \opt{legacy} reproduces the original spacing exactly (section~\ref{sec:layout}). What has been replaced is the machinery underneath. \pkg{linguex} tracks sub-example depth in a global counter that drifts out of step whenever an example is malformed, and the damage then propagates to the numbering of every later example; it recognizes judgments with a hand-written tokenizer that manipulates category codes; and it scans an example body up to the next \cs{par}, so that an example may not end a \pkg{beamer} frame. In \pkg{linguexx} the depth is held in the grouping structure itself, so drift is not merely unlikely but impossible; judgments are recognized by token inspection with no catcode trickery, and any mark whatever may be used (section~\ref{sec:judgments}); and the body is collected by a scanner that stops at a blank line, at \cs{z.}, or at a structural boundary such as \cs{end}\marg{frame}. Two facilities of \pkg{linguex} were dropped as more trouble than they are worth: examples embedded inside sub-examples, and the index variants \cs{exi.}/\cs{ai.}. \paragraph{\pkg{cgloss4e} (Hans-Peter Kolb and Craig Thiersch).} The glossing commands \cs{gll}, \cs{glll} and \cs{glt} come from here, by way of \pkg{linguex}. The engine behind them is new, and the vertical space that \pkg{cgloss4e} inserted around a gloss is gone by construction. \paragraph{\pkg{expex} (John Frampton).} \pkg{expex} is the most capable glossing package in the field, and on that one axis \pkg{linguex} was simply outclassed: two or three tiers against an arbitrary number. \cs{gl}\ \dots\ \cs{endgl} (section~\ref{sec:glosses}) closes that gap --- any number of tiers, each with its own font command. It does not close every gap: \pkg{expex} retains finer control over the vertical layout of individual tiers, and its keyval interface exposes more parameters than the eight lengths of section~\ref{sec:layout}. If the glossing is the hard part of your document, \pkg{expex} may still be the better instrument. \paragraph{\pkg{leipzig} (Natalie Weber).} The table of Leipzig glossing abbreviations behind \cs{lpzg} (section~\ref{sec:leipzig}) follows Natalie Weber's \pkg{leipzig}, to which it owes both the list and the idea of treating the abbreviations as a resource the document can be asked about. \paragraph{\pkg{gb4e}.} Not an ancestor of the implementation, but its environment syntax is accepted: \texttt{exe}, \texttt{xlist} and the bracketed judgment form of \cs{ex} work as they do there (section~\ref{sec:envs}). It is worth knowing that \pkg{gb4e} makes \texttt{\_} and \texttt{\^{}} active in text mode, which is a frequent source of clashes with other packages; \pkg{linguexx} changes no category codes. \paragraph{One of them, not both.} \pkg{linguexx} replaces these packages rather than accompanying them, and a document must load only one. \pkg{linguex}, \pkg{expex}, \pkg{gb4e} and \pkg{langsci-gb4e} all define \cs{ex} --- as does this one, and all of them with \cs{def}, so whichever file is read second wins and nothing says so. The result compiles: the examples go on numbering, and what breaks is a detail in the middle of the document. \pkg{linguexx} therefore stops with an error naming the other package, whichever order they were loaded in. The environment and \cs{ea} syntaxes are available here as the options \opt{gb4e} and \opt{langsci} (sections~\ref{sec:envs} and~\ref{sec:langsci}), which is what a document that wants them should use. One case cannot be caught this way: \pkg{expex} is plain \TeX{} and may be read with \cs{input}, which leaves no record of a package having been loaded. There the package warns that \cs{ex} is no longer its own and leaves the document alone. \paragraph{Parenthesis-free references.} The \cs{pref}/\cs{pNext} family follows a construction of Alan Munn's. \paragraph{Contributors} This package has been coded and documented via generative AI (Claude), under the instruction and supervision of Gerhard Schaden. % =========================================================================== \section{Examples}\label{sec:examples} % =========================================================================== \subsection{Starting and ending an example} \cs{ex.}\ starts a numbered example. Three things end it: \begin{enumerate}[itemsep=2pt] \item a \textbf{blank line} (or an explicit \cs{par}) --- the only thing that ended an example in \pkg{linguex}; \item \textbf{\cs{z.}} (section~\ref{sec:z}), which ends it at the point where it stands; \item a \textbf{structural boundary}: the end of the enclosing environment or group. An example may therefore run directly into \cs{end}\marg{frame} or the closing brace of a group, with no blank line at all. \end{enumerate} \noindent Environments \emph{inside} an example do not end it: a \texttt{tabular}, a \texttt{tikzpicture} or a math display is passed through untouched. \subsection{Sub-examples} \cs{a.}\ opens a level of sub-examples; \cs{b.}\ through \cs{f.}\ add further items at the level currently open. The letters printed come from a counter, not from the command name, so \cs{b.}\ prints ``b.'' only because it happens to be the second item --- the commands are interchangeable and purely mnemonic. A second \cs{a.}\ opens a deeper level, numbered in roman: \begin{code} \ex. \a. First. \b. Second. \a. First of the deeper level. \b. Second of the deeper level. \c. Back at the letter level? No -- see below. \end{code} \rendered \ex. \a. First. \b. Second. \a. First of the deeper level. \b. Second of the deeper level. \c. Back at the letter level? No -- see below. \afterex The last \cs{c.}\ comes out as item~iii: the continuation commands stay at the level currently open. Two sub-levels are the maximum; a third \cs{a.}\ raises an error. To \emph{leave} a level, use \cs{z.}. \subsection{Returning to a higher level: \cs{z.}}\label{sec:z} \cs{z.}\ pops exactly one level, counting the surrounding prose as the outermost level. From the roman level it returns to the letters, so that a following \cs{b.}\ continues there; from the letter level --- or in an example with no sub-examples open --- it ends the example, and what follows is ordinary prose. Consecutive \cs{z.}'s therefore pop successively out of the example: \begin{code} \ex. \a. First \b. Second \a. Second a \b. Second b \z. \b. Third \z. Ordinary text again. \end{code} \rendered \ex. \a. First \b. Second \a. Second a \b. Second b \z. \b. Third \z. Ordinary text again. \afterex The first \cs{z.}\ leaves the roman level, so \cs{b.}\ yields item~c; the second leaves the example. Text on the same line as an example-ending \cs{z.}\ --- like ``Ordinary text again''\ above --- is a \emph{continuation}: it is set flush left under the example, without a paragraph indent. To start a genuinely new paragraph instead, indented as the class prescribes, leave a blank line after \cs{z.}: \begin{code} \ex. An example. \z. A new, ordinarily indented paragraph. \end{code} \rendered \ex. An example. \z. A new, ordinarily indented paragraph. \afterex \subsection{Custom labels}\label{sec:customlabels} An optional argument replaces the number, without advancing the counter --- useful for repeating an earlier example, or for primed variants: \begin{code} \ex.[(7$'$)] A repeated or modified example. \end{code} \rendered \ex.[(7$'$)] A repeated or modified example. \afterex \noindent A \cs{ref} to the example being repeated is the usual argument: \cs{ex.}\texttt{[\textbackslash ref\{ex:hund\}]} gives the repetition the number the original carries, whatever that turns out to be. \cs{exg.}\ takes the same argument, with one difference in how it is written, described where it is documented (section~\ref{sec:exgabbrev}). A custom label belongs to a whole example, and to nothing smaller: \cs{ex.}\ and \cs{exg.}\ take one, the sub-example commands \cs{a.}--\cs{f.}\ and \cs{ag.}--\cs{fg.}\ do not. A bracket after one of those is ordinary text, and the letter or roman numeral remains the label --- which is what a sub-level is for: its items are identified by their place in it. \subsection{An environment interface}\label{sec:envs} Everything above can equally be written with conventional environments, whose syntax is that of \pkg{gb4e}. They are enabled by a package option: \cs{usepackage[gb4e]\{linguexx\}} loads \emph{only} this syntax --- the dot commands are then not defined, which keeps documents and error messages clean, and as a side benefit leaves the kernel accent commands \cs{b}, \cs{c}, \cs{d} untouched, so no \pkg{hyperref} workaround is needed. The default (equivalently, the option \opt{lazy}) loads only the dot syntax of the preceding sections. The two may be combined, \opt{[lazy,gb4e]}, for a document that deliberately mixes them --- this manual does --- and then the two forms drive the same engine, sharing one counter, one label system and all layout parameters. A third syntax option, \opt{langsci}, adds the \cs{ea} \dots\ \cs{z} front-end on top of these; it has a section to itself (\ref{sec:langsci}). These options choose the input \emph{syntax}; a further, orthogonal option \opt{legacy} chooses the \emph{geometry} of the original \pkg{linguex} and may be added to the first two (section~\ref{sec:layout}). \texttt{exe} is a \emph{batch}: every \cs{ex} inside it --- written \emph{without} the period --- is a new top-level example. \texttt{xlist} embeds a sub-level, nestable once more for the romans; its items are made by \cs{ex} (or by plain \cs{item}). A judgment is given in the \pkg{gb4e} manner as an optional argument, \cs{ex}\oarg{judgment}\marg{text}, where the judgment may be \emph{any} mark, not only the auto-detected four --- or typed directly after a plain \cs{ex}, as everywhere else: \begin{code} \begin{exe} \ex\label{here} Here is one. \ex[*]{Here another is.} \ex Here are some with judgements. \begin{xlist} \ex[]{A grammatical sentence am I.} \ex[??]{A dubious sentence is she.} \end{xlist} \end{exe} \end{code} \rendered \begin{exe} \ex\label{gbdoc} Here is one. \ex[*]{Here another is.} \ex Here are some with judgements. \begin{xlist} \ex[]{A grammatical sentence am I.} \ex[??]{A dubious sentence is she.} \end{xlist} \end{exe} \afterex Two differences follow from the syntax itself: the environments end at their \cs{end} and nothing else, so blank lines inside them are ordinary paragraph breaks; and \cs{z.}\ does not end a batch, since an environment names its own end. An \texttt{xlist} may also sit inside a dot-command example, and \cs{a.}\ works inside \texttt{exe}. Use whichever form suits the document --- or the editor. Mixing the two syntaxes brings one rule with it, and it is the rule of the \texttt{xlist} environment rather than of the dot syntax: \emph{inside a batch, \cs{ex} continues at the level currently open}. So once an \cs{a.}\ has opened a sub-level, a following \cs{ex} is the next \emph{sub}-example, not the next top-level one. \cs{z.}\ is what closes the sub-level again --- the one job it does have inside \texttt{exe}: \begin{code} \begin{exe} \ex One. \a. A sub-example. \z. \ex Two, back at the top level. \end{exe} \end{code} \rendered \begin{exe} \ex One. \a. A sub-example. \z. \ex Two, back at the top level. \end{exe} \afterex Without the \cs{z.}, ``Two'' would come out as sub-example~b. Nothing warns about it, because that is what \cs{ex} means at the letter level: the same thing \cs{item} means inside an \texttt{xlist}. A \cs{z.}\ at the \emph{top} level of a batch, where there is no sub-level left to close, is a package error naming \cs{end\{exe\}} --- ending the batch is the environment's own job. \subsection{The \pkg{langsci-gb4e} interface: \cs{ea} \dots\ \cs{z}} \label{sec:langsci} \pkg{langsci-gb4e}, Language Science Press's fork of \pkg{gb4e}, writes what the environments of the preceding section write, without the environments. \cs{ea} opens an example; inside one, it opens the next level down; and \cs{z} closes whatever the matching \cs{ea} opened. The depth is never spelt out --- it is read off the nesting. The option is \cs{usepackage[langsci]\{linguexx\}}, and it implies \opt{gb4e}, so \texttt{exe}, \texttt{xlist} and \cs{ex} come with it. \begin{code} \ea LAONE the first example. \z \ea LATWO the head of a nest. \ea LASUBA the first sub-example. \ex[*]{LASUBB judged through the bracket.} \ea LAROMAN the roman level. \z \ex LASUBC back at the letters. \z \ex LATHREE a second top-level example. \z \end{code} \rendered \ea LAONE the first example. \z \ea LATWO the head of a nest. \ea LASUBA the first sub-example. \ex[*]{LASUBB judged through the bracket.} \ea LAROMAN the roman level. \z \ex LASUBC back at the letters. \z \ex LATHREE a second top-level example. \z \afterex Two things in that example are worth naming. \cs{ex} inside an \cs{ea} block continues at the level currently open, exactly as it does inside \texttt{exe} --- so the \cs{ex} after the inner \cs{z} is a second \emph{top-level} example, and the one before it a further letter. And the bracket judgment of \cs{ex}\oarg{judgment}\marg{text} is available at every level, \cs{ea} included: in \pkg{langsci-gb4e} \cs{ea} expands to \cs{begin\{exe\}}\cs{ex}, so anything \cs{ex} accepts, \cs{ea} accepts. \cs{eal} \dots\ \cs{zl} is the second pair: an example whose body is a sub-list, i.e.\ a number with no text of its own and the letters underneath it. \begin{code} \eal \ex LALISTA under a head with no text of its own. \ex LALISTB the second letter. \zl \end{code} \rendered \eal \ex LALISTA under a head with no text of its own. \ex LALISTB the second letter. \zl \afterex \cs{eal} is top-level only, as it is in \pkg{langsci-gb4e}; written inside an example it is a package error rather than a guess at what a nested one ought to mean. Where you want a nested list, write \cs{ea} and open the level below it with a second \cs{ea}, as in the first example above. The option also brings \pkg{langsci-gb4e}'s deeper gloss stacks, \cs{gllll} through \cs{gllllllll} --- four to eight tiers. They are wrappers over the same engine as \cs{gll}, and section~\ref{sec:anygl} describes \cs{gl} \dots\ \cs{endgl}, which takes any number of tiers and is available whatever options are in force. \subsubsection*{One syntax per example} The dot syntax and the \cs{ea} front-end may be mixed in one document --- that is what \opt{[lazy,langsci]} is for, and the next paragraph is about little else --- but not \emph{within one example}. An \cs{a.}\ inside an \cs{ea} example, and an \cs{ea} inside an \cs{ex.}\ example or an \texttt{exe} batch, are package errors naming both syntaxes. The reason is that \cs{ea} and \cs{a.}\ do different amounts of work. \cs{ea} opens the level, its list \emph{and} its first item in one command; \cs{a.}\ opens a level that \cs{z.}\ closes. Mixed, the closers no longer match the openers: a \cs{z.}\ inside an \cs{ea} example would close one of the three things \cs{ea} opened and leave the example half-open, and a \cs{z} after an \cs{a.}\ would close the letter level and leave the letters live for the rest of the document. Both of those typeset without complaint --- the first drops the following text into the wrong list, the second silently demotes the next example to a sub-example --- so the rule exists to turn a page that is quietly wrong into a message at the line that asked for it. The mixing described in section~\ref{sec:envs} is untouched: \cs{a.}\ inside \texttt{exe}, and an \texttt{xlist} inside a dot-command example, work exactly as they did. Those two agree about what \cs{z.}\ means, which is precisely what \cs{ea} does not. A footnote is a new stream, not part of the example it hangs on, so a footnote on an example written one way may hold examples written the other. One mistake this syntax makes possible and the other two do not is forgetting the closer: an \cs{ex.}\ example ends at a blank line and an \texttt{exe} batch at its \cs{end}, but an \cs{ea} example ends at a \cs{z} and at nothing else. An \cs{ea} left open is reported by name, with the line it stood on, and the example is closed so that the rest of the document still typesets --- everything after the missing \cs{z} will have been set inside it. A missing \emph{inner} \cs{z} has the same effect and the same message: the outer \cs{z} closes the inner level, and the example itself is what stays open. \subsubsection*{Moving a document across, one example at a time} That is what the option is for. Load \opt{[lazy,langsci]} and both syntaxes are live at once: \begin{code} \usepackage[lazy,langsci]{linguexx} \end{code} \noindent Both drive the same engine, so they share one counter, one label system, one set of anchors and all layout parameters. Converting an example therefore renumbers nothing, moves no cross-reference and shifts nothing on the page: a converted example and its unconverted neighbour set their sub-examples at the same indents. The unit of conversion is the whole example, which is also the unit that carries a number and that a \cs{ref} points at. One deliberate difference from \pkg{langsci-gb4e} follows from this. There, \cs{ea} sets its examples ragged right; here it does not, because in a half-converted document that would reflow every converted example against the ones still to come, and a page diff could then no longer tell a mistake from a conversion. \cs{ExRaggedRight} asks for \pkg{langsci-gb4e}'s behaviour; \cs{eanoraggedright} and \cs{ealnoraggedright} exist for source compatibility and set justified whatever that switch says. Finally, \opt{langsci} cannot be combined with \opt{legacy}: \opt{legacy} reproduces \pkg{linguex}'s geometry to the value and \pkg{langsci-gb4e} has its own, and a document asking for both has asked for two answers to every length in the package. The combination is a package error rather than a silent choice between them. \subsubsection*{The rest of \pkg{langsci-gb4e}} The option carries the rest of the package's surface too, so that a preamble and a document body being ported need no editing. The criterion is what \pkg{langsci-gb4e} \emph{does}, which is what a real source relies on; the list below is accordingly generous. Two names are not provided --- see \emph{What this package does not provide} below. Everything here is available under \opt{langsci} and nowhere else. \begin{center} \small \begin{longtable}{@{}>{\ttfamily\raggedright}p{0.34\linewidth} p{0.60\linewidth}@{}} \toprule \normalfont what & what it does\\ \midrule \endhead \multicolumn{2}{@{}l}{\normalfont\itshape sub-level numbering}\\ \textbackslash begin\{xlista\} & letters, \texttt{a.}\\ \textbackslash begin\{xlisti\} & lower roman, \texttt{i.}\\ \textbackslash begin\{xlistn\} & arabic, \texttt{1.}\\ \textbackslash begin\{xlistA\} & upper alph, \texttt{A.}\\ \textbackslash begin\{xlistI\} & upper roman, \texttt{I.}\\ \addlinespace \multicolumn{2}{@{}l}{\normalfont\itshape items}\\ \textbackslash exi\marg{label} & an item with the label given, stepping no counter\\ \textbackslash exr\marg{key} & an item labelled with another example's number\\ \textbackslash exp\marg{key} & the same, primed\\ \textbackslash sn & an unnumbered item\\ \addlinespace \multicolumn{2}{@{}l}{\normalfont\itshape the rest of the front-end}\\ \textbackslash eas \dots\ \textbackslash zs & an example boxed so it will not break across a page\\ \textbackslash eafirst, \textbackslash zlast,\linebreak \textbackslash zllast & the same, without the space above or below\\ \addlinespace \multicolumn{2}{@{}l}{\normalfont\itshape boxes and references}\\ \textbackslash jambox\oarg{width}\marg{text} & line \meta{text} up \meta{width} from the right margin\\ \textbackslash jambox*\marg{text} & the same, and set \textbackslash jamwidth\ to its width\\ \textbackslash attop\marg{box},\linebreak \textbackslash atcenter\marg{box} & align a box by its top, or on its centre\\ \textbackslash xbox\marg{width}\marg{text},\linebreak \textbackslash nobreakbox\marg{text} & unbreakable boxes\\ \textbackslash xref\marg{key},\linebreak \textbackslash xxref\marg{key}\marg{key} & a reference, and a range in one pair of parentheses\\ \addlinespace \multicolumn{2}{@{}l}{\normalfont\itshape lengths and fonts}\\ \textbackslash exewidth\marg{sample} & reserve a label box as wide as \meta{sample}\\ \textbackslash twodigitexamples \dots & \texttt{(23)}, \texttt{(234)}, \texttt{(2345)}\\ \textbackslash gblabelsep\marg{len} & the gap between label box and text\\ \textbackslash exfont, \textbackslash exnrfont & the example body, and its number\\ \textbackslash glossfont, \textbackslash transfont & the gloss tiers, and the free translation\\ \textbackslash fnexfont \dots & the same four inside a footnote\\ \textbackslash examplesroman,\linebreak \textbackslash examplesitalics & the object tier upright or italic\\ \textbackslash gltoffset, \textbackslash nogltOffset & the space above the free translation\\ \textbackslash singlegloss,\linebreak \textbackslash nosinglegloss & set the gloss single-spaced, or not\\ \bottomrule \end{longtable} \end{center} \noindent The four package options come too: \opt{nojambox}, \opt{manualexewidth}, \opt{lowerpenalty} and \opt{nocgloss}. The first three do what they do in \pkg{langsci-gb4e} --- suppress \cs{jambox}, stop the label box from widening by itself once the numbers reach three digits, and let examples break across a page. \opt{nocgloss} is accepted and reports that it has no effect; see below. \subsubsection*{Where this differs from \pkg{langsci-gb4e}, and why} Six things are not copies, and each is worth knowing before a page is compared against one set with the original. \begin{itemize}[leftmargin=*] \item \cs{exp} keeps \emph{both} meanings. It is the \LaTeX\ kernel's math operator as well as \pkg{langsci-gb4e}'s item command, and here the mode decides between them: inside math it is the operator, outside it is the item. A document may use both freely. \item \cs{exp}'s prime and \cs{atcenter} are written in \emph{text mode}. \pkg{langsci-gb4e} writes them \verb|$'$| and \verb|$\vcenter{...}$|, and math here would put a \texttt{Formula} element in the structure tree, which costs a document its PDF/UA-2 conformance (section~\ref{sec:tagging}). \cs{atcenter} therefore centres on \cs{ExAtCenterAxis}, half the x-height, rather than on the math axis, which is only readable from inside math mode; against a real \cs{vcenter} at 10pt the box sits 0.38\,pt lower. \item \cs{eas} boxes its example in a \texttt{minipage} and not in a \texttt{tabular}, so that the example's prose is not wrapped in a \texttt{Table} element --- a screen reader would announce it as a table, and PDF/UA does not allow it. A footnote inside one reaches the minipage-footnote numbering noted in section~\ref{sec:notes}. \item \cs{examplesroman} and \cs{examplesitalics} set the object tier and not the example font. Setting the object tier is what they are wanted for in a glossed example, and it is what they do here; the example font is \cs{exfont}'s to set. \item \cs{subexsep} and \cs{judgewidth} warn instead of acting. The first sets a label separation for the sub-levels alone, and this package has one \cs{Exlabelsep} for every level (section~\ref{sec:layout}); the second sets the width of a reserved judgment column, and here a judgment hangs into the label gutter and reserves nothing --- which is exactly why marked and unmarked examples align (section~\ref{sec:jdgspace}). \item \opt{nocgloss} is accepted and reports. In \pkg{langsci-gb4e} it stops a bundled copy of \pkg{cgloss} from being read so that another package can own \cs{gll}; here there is no bundled copy to withhold, and the glossing is what \cs{exg.}, \cs{altg}, \cs{GlossTierLang}, \cs{lpzg} and the tagged word-bundle structure are all built on. Switching it off would leave each of those needing an answer, and they have more than one; the question is recorded in \texttt{doc/DEFERRED-DECISIONS.md} rather than guessed at. \end{itemize} \noindent And one difference already noted above: \cs{ea} does not set its examples ragged right unless \cs{ExRaggedRight} asks for it. \subsubsection*{What this package does \emph{not} provide} \texttt{xlistabr} and \texttt{qlist} are not provided. They are not silently absent either: both names are defined here, and defined to stop at the line that uses them with a message naming what to write instead --- \texttt{xlist} for the first, an ordinary \LaTeX\ list for the second. An error at the line that has to change is friendlier than a surprise further down the page. \subsubsection*{What \cs{ref} prints}\label{sec:langsciref} \pkg{linguex} puts the parentheses in the number: \cs{theExNo} \emph{is} ``(1)'', so \cs{ref} gives ``(1)'' and prose says ``as in \cs{ref}\marg{key}''. \pkg{langsci-gb4e} puts them in the example's label instead and leaves the counter bare, so \cs{ref} there gives ``1'' and prose says ``(\cs{ref}\marg{key})'' or \cs{xref}\marg{key}. Both conventions are in use, and a document carried from the second to the first prints ``((1))'' on every cross-reference. So the convention follows the syntax: under \opt{langsci}, \cs{ref} is bare, at every level and on the footnote series --- \texttt{1}, \texttt{2a}, \texttt{2b-i}, \texttt{i} --- exactly as \pkg{langsci-gb4e} sets them. Without the option nothing changes: \cs{ref} parenthesises as it always has. What does \emph{not} follow the convention is everything this package prints itself. The example's own number, \cs{Next} and its family, \cs{xref}, \cs{xxref}, \cs{exr}, \cs{exp}, \cs{refrange} and \cs{Refrange} spell the parentheses out, so they print the same characters either way; only a plain \cs{ref}, and the \cs{cref} that follows it, change. A \opt{langsci} document whose prose already writes ``as in \cs{ref}\marg{key}'' asks for the other convention in one line: \begin{code} \ExParenRefs % \ref prints (1), as without the option \ExBareRefs % \ref prints 1, as langsci-gb4e does \end{code} \noindent Either may be given in the preamble or in the middle of the document; each takes effect from the point it stands at, and the example labels are unaffected by both. \subsection{Examples in footnotes} Inside a footnote, examples are numbered independently, in roman numerals, on their own counter; the running-text numbering is not disturbed, and references made inside the footnote resolve against the footnote's series. Nothing special needs to be done: write \cs{ex.}\ as usual.\footnote{Like so: \ex. First footnote example. \ex. *Second one, with a judgment. and \Last\ refers to the second of these, not to a text example.} % =========================================================================== \section{Grammaticality judgments}\label{sec:judgments} % =========================================================================== This section deals with the typesetting; marks are also given \emph{spoken forms} for accessible PDFs, so that a screen reader announces a judgment by its meaning rather than by its glyph (section~\ref{sec:jdgspoken}). That is one of the tagging features drawn together in section~\ref{sec:tagging}. \subsection{Automatic marks} The characters \texttt{*} and \texttt{?} and the commands \cs{\#} and \cs{\%}, in any combination, are recognized automatically when they open an example or sub-example. They are set in the margin, hanging to the left of the example text, so that judged and unjudged examples align: \begin{code} \ex. \a. Ich habe geschlafen. \b. ??Ich habe geschlaft. \c. *Ich bin geschlafen. \d. \#Ich schlafte. \end{code} \rendered \ex. \a. Ich habe geschlafen. \b. ??Ich habe geschlaft. \c. *Ich bin geschlafen. \d. \#Ich schlafte. \afterex The mark must come first in the item, \emph{before the example text}. A \cs{label} or a \cs{sublabel} may precede it: they make no ink, so the mark is still the first thing on the line and is still hung in the margin. \begin{code} \ex. \label{ex:invasione}*?La sola invasione romana della Tracia \end{code} \rendered \ex. \label{ex:invasione}*?La sola invasione romana della Tracia \afterex Anything that does print --- a \cs{textbf}, an opening bracket, a footnote mark --- ends the recognition, and a mark behind it stays in the text where it was typed. Use \cs{jdg} (section~\ref{sec:jdgmanual}) for those, and for marks outside the four characters below. The conventional readings are the usual ones (\texttt{*} ungrammatical, \texttt{?} degraded, \texttt{\#} semantically or pragmatically deviant, \texttt{\%} varying across speakers), but the package attaches no meaning to them: it only places them. \subsection{Space for judgments}\label{sec:jdgspace} A hanging mark takes no horizontal space, so it can never push the example text out of alignment --- but it can, if long enough, run into the example \emph{label} to its left. The room available is the clear space inside the label box plus the label gap, i.e. \[ \meta{labelwidth} - \hbox{width of the printed label} + \cs{Exlabelsep}. \] At the main level the number box (\cs{Exlabelwidth}, \texttt{2.6em}) leaves ample room. At the sub-levels the default widths (\cs{SubExlabelwidth}~\texttt{1.6em}, \cs{SubSubExlabelwidth}~\texttt{1.9em}) are chosen so that \textbf{two marks built from \texttt{?} and \texttt{*}} (\texttt{??}, \texttt{?*}, \dots) fit clear of the letter. Note that \cs{\#} and \cs{\%} are nearly twice as wide as \texttt{?} in most fonts, so they count roughly double. If you use \textbf{three marks} (or wide marks) on sub-examples \textbf{as a routine matter}, widen the boxes: \begin{code} \setlength{\SubExlabelwidth}{2.4em} \setlength{\SubSubExlabelwidth}{2.5em} \end{code} \noindent which carries \texttt{?*\#} comfortably. (An occasional long mark that grazes the letter is harmless; only alignment is guaranteed, and that unconditionally.) \subsection{Arbitrary marks: \cs{jdg}}\label{sec:jdgmanual} For any other mark, \cs{jdg}\marg{mark} hangs an arbitrary symbol into the margin, at any position, not only at the start of an example: \begin{code} \ex. \jdg{\dag}A mark of one's own choosing. \ex. \jdg{$\to$}Or an arrow, or anything else. \end{code} \rendered \ex. \jdg{\dag}A mark of one's own choosing. \ex. \jdg{$\to$}Or an arrow, or anything else. \afterex Because the mark occupies no horizontal space, alignment is preserved whatever its width. To give a recurrent mark a name of its own, use \cs{DeclareJudgment}\marg{command}\marg{mark}: \begin{code} \DeclareJudgment{\dubious}{\dag\dag} \ex. \dubious A doubly daggered example. \end{code} \rendered {\DeclareJudgment{\dubious}{\dag\dag}% \ex. \dubious A doubly daggered example. } \afterex The distance between mark and text is the length \cs{JdgSep} (default \texttt{0.15em}). % =========================================================================== \section{Interlinear glosses}\label{sec:glosses} % =========================================================================== \subsection{Two and three tiers} \cs{gll} takes an object line and a gloss line, each ended by \verb|\\|; \cs{glll} takes three lines. \cs{glt} introduces the free translation, which is set as an ordinary line, not aligned: \begin{code} \ex. \gll Der Hund hat geschlafen \\ the dog has slept \\ \glt `The dog slept.' \end{code} \rendered \ex. \gll Der Hund hat geschlafen \\ the dog has slept \\ \glt `The dog slept.' \afterex Words are separated by spaces, and \emph{braced material counts as one word}. This is how one object-language word is glossed by several English words, or the reverse: \begin{code} \ex. \gll Das {kleine Kind} schläft \\ the {little child} sleeps \\ \glt `The little child sleeps.' \end{code} \rendered \ex. \gll Das {kleine Kind} schläft \\ the {little child} sleeps \\ \glt `The little child sleeps.' \afterex If the tiers are of unequal length, the missing cells are simply left empty --- no error. A gloss too long for the line wraps between columns, never inside one. \subsection{Gloss abbreviations: \cs{lpzg}}\label{sec:leipzig} Category labels in a gloss are written in small capitals by convention (\textsc{sg}, \textsc{pst}, \textsc{nom}). \cs{lpzg}\marg{label} is a convenience for exactly this: it sets its argument in small capitals, so \cs{lpzg}\marg{sg} is a shorter, meaning-bearing spelling of \cs{textsc}\marg{sg}. A whole compound label goes in one call, written the Leipzig way --- a leading person number flush against the number, then further categories separated by periods: \begin{code} \gll Der Hund bellte.\\ the dog bark.\lpzg{3sg.pst}\\ \glt `The dog barked.' \end{code} \rendered \gll Der Hund bellte.\\ the dog bark.\lpzg{3sg.pst}\\ \glt `The dog barked.' \afterex \noindent \cs{lpzg}\marg{3sg.pst} simply sets \textsc{3sg.pst}. Its argument is a label you would otherwise have typed by hand; there is no fixed vocabulary as far as \emph{typesetting} is concerned. What \cs{lpzg} adds over \cs{textsc} appears only in a tagged PDF, where it records the spoken expansion of the label (``third person singular past'') for a screen reader; that behaviour, and the list of abbreviations it knows, are described in section~\ref{sec:leipzigtag}. \cs{lpzg} is self-contained and does not require, or interact with, the \pkg{leipzig} package. It may also stand in a section title: \pkg{hyperref} is told what one means in a PDF string, so the bookmark carries the label as written (\texttt{3sg.pst}) instead of the warning and the dropped command a title command it does not know about would earn. \paragraph{Modified labels.} A label, or a piece of one, may be marked up inside the call --- to pick the cell of a paradigm the surrounding discussion is about: \begin{code} \gll On-i star-e vladik-e su se posvadjal-i.\\ those-\lpzg{\textbf{m}.pl} old-\lpzg{f.pl} bishop-\lpzg{f.pl} are \lpzg{refl} argued-\lpzg{\textbf{m}.pl}\\ \glt `Those old bishops argued.' \end{code} \rendered \gll On-i star-e vladik-e su se posvadjal-i.\\ those-\lpzg{\textbf{m}.pl} old-\lpzg{f.pl} bishop-\lpzg{f.pl} are \lpzg{refl} argued-\lpzg{\textbf{m}.pl}\\ \glt `Those old bishops argued.' \afterex \noindent The modifier \emph{adds} to the small capitals: what it marks comes out bold \emph{and} small, and the rest of the label is unaffected. That is not automatic. Latin Modern has no bold small capitals in any encoding --- there is no bold companion to \texttt{lmromancaps} --- and plain \texttt{\textbackslash textsc\{\textbackslash textbf\{m\}\}} in such a font loses the shape and keeps the weight, silently: the label comes out as a bold lowercase ``m'', which is the one thing a category label must not look like. \cs{lpzg} therefore asks the font, for each piece of the label separately, whether its small capitals are real. Where they are --- pdf\LaTeX's default \pkg{cmr} has them, and so does any \textsc{OpenType} face carrying \texttt{smcp} in its bold weight --- nothing changes and the label is set with \cs{textsc} as before. Where they are not, the capitals are made: the letters are set as capitals at \cs{LpzgCapsScale} (default \texttt{0.75}) of the current size, in the font the modifier asked for, so the boldface survives and the height matches the real small capitals beside it. Under active tagging the made capitals carry an \texttt{/ActualText} of the letters as written, so a screen reader and copy-and-paste still get \texttt{m.pl}; in an untagged document they extract as capitals, as made small capitals always do. \cs{textbf}, \cs{textit}, \cs{textsl}, \cs{textup}, \cs{textmd}, \cs{textrm}, \cs{textsf}, \cs{texttt}, \cs{textnormal} and \cs{emph} are recognised inside a label; other commands are left to themselves and their argument stays in whatever small capitals surround it. The markup is invisible to everything else \cs{lpzg} does: the label is read through it, so \texttt{\textbackslash lpzg\{\textbackslash textbf\{m\}.pl\}} expands, records and lists exactly as \cs{lpzg}\marg{m.pl} does. \paragraph{Labels beyond ASCII.} A key may be any text --- \cs{SetLeipzig}\marg{fém}\marg{féminin} for a paper written in French, say --- and it may be spelt either way its language allows, as the character (\texttt{fém}) or as an accent command (\texttt{f\textbackslash'em}). Both are the same key: keys are compared in one normal form, so a label written one way finds a declaration written the other, and \cs{lpzglist} lists one entry rather than two. That normal form is a byte string, which is why the lists set the key through the same step that reads it back: what you typed is what is printed, on all three engines. \subsection{The list of abbreviations used: \cs{lpzglist}} \label{sec:lpzglist} A paper that glosses its examples owes the reader a list of the abbreviations it uses. \cs{lpzglist} prints one, and prints exactly the abbreviations the document actually uses: every label passed to \cs{lpzg} is recorded, and a compound label is recorded piece by piece, so one \cs{lpzg}\marg{3sg.pst} contributes three entries --- \textsc{3}, \textsc{sg} and \textsc{pst} --- and nothing else. Each entry is set as the abbreviation followed by its full form: \begin{code} \lpzglist \end{code} \rendered \lpzglist \afterex \noindent --- which, here, is the list of everything this manual glosses with \cs{lpzg}, collected from its own examples. The record survives in the \texttt{.aux} file, so the list may stand where such a list belongs --- in the front matter, before the examples it reports on. Like a table of contents it is then one run behind: \pkg{linguexx} asks for a rerun when the list is out of date. A list at the \emph{end} of a document is complete on the first run. Abbreviations that appear outside \cs{lpzg} --- in running text, in a figure, in a table --- are unknown to the recorder. Register them with \cs{lpzgadd}\marg{labels}, a comma list: \begin{code} \lpzgadd{erg,abs} \end{code} \noindent An abbreviation for which no expansion is known (a project-specific label neither in the built-in table of section~\ref{sec:leipzigtag} nor declared with \cs{SetLeipzig}) cannot be explained in the list, and is left out of it with a warning naming it. Either declare it, or ask for \opt{unexplained=keep} to have it listed with an empty explanation. \subsubsection*{Customisation} \cs{lpzglist} takes optional key--value settings for one list; \cs{lpzglistsetup}\marg{keys} sets them for all of them: \medskip \noindent \begin{tabular}{@{}>{\ttfamily}l p{0.68\linewidth}@{}} \toprule \normalfont key & \normalfont effect \\ \midrule style & \texttt{list} (the default): a two-column list of entries. \texttt{inline}: one paragraph, entries separated by \texttt{sep}. \\ sort & \texttt{true} (the default): alphabetically, the person numbers first. \texttt{false}: in order of first use. \\ include & \texttt{used} (the default) or \texttt{all}, which prints the whole built-in table --- a ready-made reference list. \\ ignore & Comma list of labels to leave out. \\ add & Comma list of labels to include in this list only (unlike \cs{lpzgadd}, which registers a label for every list). \\ unexplained & \texttt{omit} (the default) or \texttt{keep}; see above. \\ title & A heading for the list; none by default. \\ titlestyle & The one-argument command that sets the heading, by default \cs{lpzglisttitle} (\cs{section*} where that exists). \\ sep & Separator of the \texttt{inline} style, by default a semicolon. \\ itemsep & Vertical space between entries of the \texttt{list} style, \texttt{0pt} by default. \\ format & The entry itself, \texttt{\#1} the abbreviation and \texttt{\#2} its full form. \\ \bottomrule \end{tabular} \medskip \noindent So a list headed like a section, with the abbreviations set in bold roman rather than the small capitals of \cs{lpzg}: \begin{code} \lpzglist[title=Abbreviations, format={\item[\textbf{#1}] #2}] \end{code} \noindent \texttt{format} is the one-shot form of \cs{lpzglistentry}, which the \texttt{list} style calls with an \cs{item} and the \texttt{inline} style without one; redefine it with \cs{renewcommand} to change every list at once. The label column of the \texttt{list} style is as wide as the widest abbreviation in it. \subsection{Checking the abbreviations: \cs{lpzgcheck}} \label{sec:lpzgcheck} A mistyped abbreviation is invisible: \cs{lpzg}\marg{pres} for \cs{lpzg}\marg{prs} simply sets \textsc{pres} in small capitals and says nothing. \cs{lpzgcheck} turns that into a warning at the end of the document, whether or not the document builds a list: \begin{code} \lpzgcheck{unknown=true, % on by default unused=true, % off by default ignore={proj,adhoc}} \end{code} \noindent \texttt{unknown} reports every abbreviation used with no known expansion --- not in the Leipzig table and not declared with \cs{SetLeipzig}. It is \emph{on by default}, since such a key is nearly always a typo or a forgotten declaration. Abbreviations you mean to leave unexplained go in \texttt{ignore}. \texttt{unused} reports the reverse: an abbreviation declared with \cs{SetLeipzig} and never used, which is what a stale declaration looks like. It is \emph{off} by default, because keeping a standing set of declarations in a shared preamble and using only some of them in any one paper is a perfectly reasonable way to work. Only your own declarations are considered; the built-in table is not. The two are independent of \cs{lpzglist}: it reports the keys it cannot explain in a list it builds, whereas these check the document. A key that a list has already reported is not reported twice. \subsection{Any number of tiers: \cs{gl} \dots\ \cs{endgl}}\label{sec:anygl} Heavily annotated data --- transliteration, segmentation, gloss, category line --- needs more than three tiers. \cs{gl} takes any number of lines, each ended by \verb|\\|, up to \cs{endgl}: \begin{code} \GlossTierFont{4}{\textit}% \ex. \gl Der Hund schläft \\ der Hund schlaf-t \\ \lpzg{def.nom.sg.m} dog sleep-\lpzg{3sg} \\ D N V \\ \endgl \glt `The dog sleeps.' \end{code} \rendered {\GlossTierFont{4}{\textit}% \ex. \gl Der Hund schläft \\ der Hund schlaf-t \\ \lpzg{def.nom.sg.m} dog sleep-\lpzg{3sg} \\ D N V \\ \endgl \glt `The dog sleeps.' } \afterex All the conventions of \cs{gll} carry over: spaces separate words, braces group them, unequal tiers get empty cells, long examples wrap between columns. \cs{gll} and \cs{glll} are in fact abbreviations of this one engine. \subsection{Fonts and spacing} Each tier is set with a one-argument command, declared by \cs{GlossTierFont}\marg{n}\marg{command}. Tiers~1--3 have traditional names of their own --- \cs{eachwordone}, \cs{eachwordtwo}, \cs{eachwordthree} --- which may be redefined instead; all default to \cs{textnormal}, so glosses inherit the surrounding font (under \pkg{beamer}, they come out sans-serif, as they should). To set the gloss line in small capitals throughout: \begin{code} \renewcommand{\eachwordtwo}[1]{\textsc{#1}} \end{code} \noindent The space between columns is the macro \cs{GlossSep}, a glue specification (default \texttt{.5em plus .3em minus .1em}), changed with \cs{renewcommand}. \subsection{Aligning past brackets and judgment marks}\label{sec:phantomalign} When an object word opens with a bracket, a parenthesis or a judgment mark, the gloss word below it normally lines up with that mark, not with the word it introduces. Thus \begin{code} \ex. \gll Ich bin []\\ I am a idiot\\ \end{code} \noindent{}renders as: \ex. \gll Ich bin []\\ I am a idiot\\ \z. \noindent Here the gloss word \texttt{a} sits flush under the \texttt{[}, far to the left of \texttt{ein}. Switching on \emph{phantom alignment} makes the gloss word skip the leading run of marks, so its first real glyph sits under the object word's first real glyph (\texttt{a} under \texttt{ein}): \begin{code} {\GlossPhantomAlign \ex. \gll Ich bin []\\ I am a idiot\\ } \end{code} \rendered {\GlossPhantomAlign \ex. \gll Ich bin []\\ I am a idiot\\} \noindent The padding is an invisible box the width of the leading marks \emph{set in the object-line font}, so alignment holds even when the gloss tier is set at a different size (a \cs{footnotesize} gloss still lines up under the full-size bracket). It ships no ink and no marked content, so tagging is unaffected. Any number of leading marks are skipped together; the marks that count are, by default, the judgment marks \verb|* ? \# \%| and the openers \texttt{(\,[\,<}. Change the set with \cs{GlossPhantomChars}\marg{marks}, e.g.\ \cs{GlossPhantomChars}\texttt{\{[(\}} to react to square and round brackets only. A translation usually keeps the delimiters of what it translates, and such a gloss word is padded only by the \emph{difference}. In \begin{code} {\GlossPhantomAlign \ex. \gll della sua morte (\`e questa)\\ of.the his death (is this.one)\\ } \end{code} \rendered {\GlossPhantomAlign \ex. \gll della sua morte (\`e questa)\\ of.the his death (is this.one)\\} \noindent the gloss carries a parenthesis of its own, so its first real glyph already sits where it belongs and nothing is added: the two parentheses stay flush. Were the tier set at a smaller size its parenthesis would be narrower than the object's, and the pad would be exactly that difference --- enough to put the real glyphs under one another, and no more. Should the gloss open with \emph{more} mark than the object word does, aligning the real glyphs would mean pulling the gloss to the \emph{left} of its column, into the space belonging to the word before it; that is not done. The gloss keeps the column and its extra mark hangs out on the left. The argument is a list without separators: \emph{one token is one mark}, so a character and a command count alike and neither commas nor spaces are needed between them. That is how \verb|\#| and \verb|\%| are in the default set at all --- a bare \texttt{\#} is a macro parameter character and a bare \texttt{\%} opens a comment, so neither can be typed in an example in the first place, and the escaped forms are the only ones that exist. It is also how you add a mark of your own: \begin{code} \GlossPhantomChars{*?([<\#\%\dag} \end{code} \noindent leaves the default set alone and adds \cs{dag} to it. A command that is not in the set is not a mark: it stays in the word, where you typed it. There is one restriction on what may be a mark, and it is worth stating as a rule: \emph{math-mode code typed directly into the example cannot be a delimiter; a command that contains math can.} A Quine corner written \verb|$\ulcorner{}$| in the object word cannot be declared, however you spell the declaration. The same corner given a name --- \cs{qq}, defined as \verb|\ensuremath{\ulcorner}| --- can be, and from then on behaves like every other mark in the set. The reason is \emph{one token is one mark} read the other way round. The scan looks at the first \emph{token} of the word, and in \verb|($\ulcorner{}$machin| that token is the \texttt{\$}, which is not a mark; the scan stops there, before it has so much as seen \cs{ulcorner}. So putting \cs{ulcorner} in the set changes nothing, and says nothing --- the gloss simply goes on being padded as though the corner were part of the word. \verb|\ensuremath{\ulcorner}| written out in the example fails identically, its first token being \cs{ensuremath}. Nor is declaring the \texttt{\$} itself a way round it: the scan would then peel the dollar and the corner off and stop at the empty group between them, leaving a leading run with its math unbalanced --- \texttt{! Extra \}, or forgotten \$}, at the end of the example. A name is the only thing here with a single token to offer: \begin{code} \newcommand{\qq}{\ensuremath{\ulcorner}} \GlossPhantomChars{*?([<\#\%\qq} \ex. \gll AAA (\qq{}machin BBB\\ aaa \qq{}thingy bbb\\ \end{code} \noindent The empty group after \cs{qq} does two jobs. It keeps the control word off the letters that follow it without using a \emph{space} --- a space there would end the word, and \cs{gll} would build two columns out of the one --- and the scan stops at a brace group, so the leading run comes out as exactly \verb|(\qq| and no more. Without the declaration that example still lines up, as it happens: the corner is then simply part of the word, in the object line and in the gloss alike, and the parenthesis alone accounts for the difference between them. Declaring it earns its keep when the gloss does \emph{not} carry the corner --- then \texttt{thingy} sits under \texttt{machin}, where undeclared it would sit under the corner. The feature is \emph{off by default} --- only because turning it on shifts the horizontal position of glosses under bracketed material, and existing documents should keep the layout they were written for. For new documents it is \emph{recommended}: it is what makes an interlinear gloss line up the way a reader expects, and it costs nothing under tagging. Enable it document-wide with the package option \opt{phantomalign} or with \cs{GlossPhantomAlign}; \cs{GlossPhantomAlignOff} turns it back off, so it can be scoped to a single example inside a group. It applies to the space-separated words of \cs{gll}/\cs{glll}/\cs{gl}, and it is also what makes a judgment mark hang to the left of a stack instead of displacing the alternative it marks --- in \cs{altn} (section~\ref{sec:altn}), and in \cs{altg} on the tier that carries the object language (section~\ref{sec:altg}). For anything the automatic scan cannot see --- a bracket wrapped in a macro (the scanner reads the control word, not the \texttt{[}), or a target you want to choose by hand --- there is a manual escape hatch: \cs{GlossPhantom}\marg{material} typesets an invisible box the width of \meta{material}, \emph{set in the object-line font}. Put it at the front of a gloss word to push that word past \meta{material}: \begin{code} \ex. \gll Das ist \textbf{[}ein Reh\\ This is \GlossPhantom{\textbf{[}}a deer\\ \end{code} \rendered \ex. \gll Das ist \textbf{[}ein Reh\\ This is \GlossPhantom{\textbf{[}}a deer\\ \noindent Give it whatever the object word opens with (here \cs{textbf}\texttt{\{[\}}, so the phantom is a \emph{bold} bracket and the widths match). Unlike a bare \cs{phantom}\marg{material}, which would be set in the gloss font, \cs{GlossPhantom} borrows the object font, so it aligns at any gloss-tier size. One caveat: because it reproduces the width of the leading material \emph{alone}, alignment is exact only when that material does not kern with the letter that follows it in the object word. Brackets, parentheses and judgment marks do not kern with letters, so in practice this never bites; a leading slash or the like might land a fraction off. \subsection{The language of a tier (tagged PDFs)}\label{sec:glosslang} The object line of a gloss is usually in a different language from the document. In a tagged PDF that difference can be recorded so that a screen reader pronounces each tier with its own phonetics rather than reading, say, German words as though they were English. Declare the language of a tier with \cs{GlossTierLang}\marg{tier}\marg{code}, where \meta{code} is a language tag such as \texttt{de} or \texttt{fr}: \begin{code} \GlossTierLang{1}{de} \ex. \gll Der Hund bellte.\\ the dog barked.\\ \glt `The dog barked.' \end{code} \noindent Each word of tier~1 is then wrapped, in the structure tree, in a span carrying that language; the other tiers are unaffected. \cs{GlossTierLang} obeys the usual scope rule. Given in the preamble or in the document body between examples, it sets a \emph{document-wide default} for that tier. Given \emph{inside} an example, before the gloss, it overrides that tier for that one example only and reverts afterwards, so a document that glosses several object languages needs only a local \cs{GlossTierLang} in the odd example that departs from the default: \begin{code} \GlossTierLang{1}{de} % default: object line is German ... \ex. \GlossTierLang{1}{fr} % this example only \gll Le chien aboya.\\ the dog bark.\lpzg{pst}\\ \glt `The dog barked.' \end{code} \noindent As with the rest of the tagging support this is inert unless tagging is active (section~\ref{sec:tagging}): it changes nothing in the printed gloss and nothing in an untagged document. A tier with no declared language behaves exactly as before. The free translation is a tier of its own kind, and usually in a third language: neither the object language nor, in a paper written in one language and glossing into another, the language of the document. \cs{GlossTransLang}\marg{code} marks it, and under tagging the translation is wrapped in a span carrying \texttt{/Lang}: \begin{code} \GlossTierLang{1}{de} % object line is German \GlossTransLang{en} % free translations are English \end{code} \noindent This is worth setting explicitly even in a document that already declares its language to \cs{DocumentMetadata}: \pkg{babel}'s \cs{foreignlanguage} does \emph{not} reach the structure tree, so without \cs{GlossTransLang} a translation in another language carries no \texttt{/Lang} of its own and is read out with the document's phonetics. The translation can also be styled, with the declaration \cs{GlossTransStyle} --- many venues want it italic, or a size smaller: \begin{code} \renewcommand\GlossTransStyle{\itshape} \end{code} \noindent It applies only to the translation, not to the gloss tiers above it, and reverts at the end of the example. Both hooks are empty by default, so a document that sets neither is unaffected in its output and in its tagging alike. \subsection{Abbreviations: \cs{exg.}\ and \cs{ag.}}\label{sec:exgabbrev} \cs{exg.}\ abbreviates \cs{ex.}\ \cs{gll}, and \cs{ag.}\ through \cs{fg.}\ abbreviate \cs{a.}\ \cs{gll} and so on, for glossed sub-examples. Judgments still work in front of the gloss: \begin{code} \exg. *Das Beispiel funktionieren \\ the example work.INF \\ \glt (intended: `The example works.') \end{code} \rendered \exg. *Das Beispiel funktionieren \\ the example work.INF \\ \glt (intended: `The example works.') \afterex \noindent So does the custom label of section~\ref{sec:customlabels}, which is what repeats a glossed example under the number it had: \begin{code} \exg.[\ref{ex:hund}] Der Hund bellte. \\ the dog bark.PST \\ \end{code} \noindent With one difference from \cs{ex.}: the bracket must follow \cs{exg.}\ immediately. A bracket that a \emph{space} separates from it is the first word of the object line --- \texttt{[} is one of the openers \cs{GlossPhantomChars} lists, and phantom alignment (section \ref{sec:phantomalign}) exists to hang it in the gutter --- so \cs{exg.}~\texttt{[DP der Hund] bellte.} glosses a bracketed constituent and takes a number of its own. \cs{ex.}\ has no object line for a bracket to open and follows the \LaTeX\ convention of skipping the space. % =========================================================================== \section{Cross-references}\label{sec:refs} % =========================================================================== \subsection{Labels} Examples and sub-examples are ordinary \LaTeX{} counters: \cs{label} them and \cs{ref} them. The reference prints with parentheses, and a sub-example reference includes its letter: \begin{code} \ex.\label{ex:main} \a.\label{ex:a} Erste. \b.\label{ex:b} Zweite. See \ref{ex:main}, and in particular \ref{ex:b}. \end{code} \rendered \ex.\label{ex:main} \a.\label{ex:a} Erste. \b.\label{ex:b} Zweite. See \ref{ex:main}, and in particular \ref{ex:b}. \afterex \subsection{References without parentheses} In running text one often wants ``example 3\,b'' rather than ``example (3\,b)''. Every reference command has a \texttt{p}-prefixed twin that omits the parentheses: \cs{pref}, \cs{pNext}, \cs{pLast}, \cs{pNNext}, \cs{pLLast}, \cs{pTextNext}. \begin{code} \ref{ex:b} with parentheses, \pref{ex:b} without. \end{code} \rendered \ref{ex:b} with parentheses, \pref{ex:b} without. \afterex \subsection{Relative references} To refer to a neighbouring example without labelling it: \begin{center} \begin{tabular}{@{}>{\ttfamily}l l@{}} \toprule \normalfont Command & \normalfont Refers to \\ \midrule \textbackslash Next & the next example \\ \textbackslash NNext & the one after that \\ \textbackslash Last & the previous example \\ \textbackslash LLast & the one before that \\ \textbackslash TextNext & the next example in the running text (for use inside footnotes) \\ \bottomrule \end{tabular} \end{center} \noindent Inside a footnote these refer to the footnote's own series, which is nearly always what is meant; \cs{TextNext} escapes to the main series. Each of them, and each \texttt{p}-twin, takes an optional sub-example part: \cs{Last}\oarg{letter} refers to that letter of the example \cs{Last} resolves to and prints it inside the parentheses, ``(3b)''. The separator is \cs{firstrefdash}, the same hook \cs{ref} uses for a \cs{sublabel}, so the two spell an example alike --- ``(3b)'' by default and ``(3-b)'' under \opt{legacy}. Nothing verifies that the letter exists; it is text you supply, as it is in \pkg{linguex}. \paragraph{Clickable references.} With \pkg{hyperref} loaded, each of these --- and each \texttt{p}-twin --- prints as a link to the example it names, exactly as the \cs{ref} it abbreviates does. No label is needed: every example gets a destination whether or not anyone asks for one, from \pkg{hyperref} where it makes them and from \pkg{linguexx} where it does not. \pkg{beamer} is the case where it does not --- it switches \pkg{hyperref}'s implicit anchors off and runs its own navigation --- and the links work there too. On a frame with overlays the link lands on the slide where the example \emph{appears}: an example after a \cs{pause}, or inside \cs{uncover} or \cs{only}, is anchored where the reader can see it rather than where \TeX{} first ran it. A reference that names an example the document does not have --- \cs{LLast} before the second example, \cs{Next} after the last one --- prints its number as it always did and is deliberately \emph{not} linked. A link to a destination that does not exist is not an error; the reader would simply be taken somewhere plausible and wrong. Instead every such reference is named, with its input line, in one warning at the end of the run: \begin{code} Package linguexx Warning: No example carries the number a relative (linguexx) reference asks for: 0 (line 12), 9 (line 40). \end{code} \noindent A number that \emph{two} examples carry is withheld in the same way and reported in its own words. That happens when the example counter is reset --- with \cs{setcounter}, or by \opt{legacy}'s per-chapter reset in a class that has chapters --- because the anchor \pkg{hyperref} attaches to an example is built from the counter alone, so the two examples claim one anchor and \pkg{hyperref} keeps only the first. A \cs{ref} to the second has always led to the first for the same reason; what the links promise is that they add no second wrong jump to a document that has that one. Which examples exist is read from the \texttt{.aux}, so the links are a run behind: a document whose examples have just moved is asked to rerun rather than told that its references dangle. The optional part is printed but not aimed at --- \cs{Last}\oarg{b} links to the example, not to its letter b --- because that letter is text you typed and need not name a sub-example that exists. Pass \opt{norelreflinks} to the package to print the numbers without links, as \pkg{linguex} does. \paragraph{The space after the command.} These are control words, so \TeX{}'s tokenizer discards the space that follows one before any package can see it. Written plainly, \verb|\Last shows| would therefore set as ``(1)shows''. Each of them ends in \cs{xspace} --- as \pkg{linguex}'s references do --- which puts the space back before a word and leaves it out before punctuation, so \verb|\Last shows| and \verb|\Last, but| both come out right and neither needs guarding. The \verb|\Last\ | and \verb|\Last{}| that documents written against the older behaviour contain stay correct too: \cs{xspace} recognises both and adds nothing. These commands are part of the \pkg{linguex} compatibility surface and are kept for it, but they are worth using sparingly. What they resolve to depends on where they stand, so inserting an example between a reference and its target silently changes what the reference means --- and nothing in the document records that anything was meant at all. Being clickable makes a reference that has drifted easier to notice, since it now lands on the wrong example rather than merely naming it, but no less likely. In a document you expect to revise, prefer \cs{label} with \cs{ref} or, better, \pkg{cleveref}'s \cs{cref} (below): a label survives being moved, and a label that has lost its target is an error rather than a wrong number. \subsection{Ranges} \cs{refrange}\marg{first}\marg{last} sets a compact range over sub-examples, printing ``(3a--c)'' rather than ``(3a)--(3c)''. The sub-examples must be labelled with \cs{sublabel} instead of \cs{label} (this records the label in the \texttt{.aux} file; \cs{sublabel} also does everything \cs{label} does, so \cs{ref} keeps working). It works at either sub-level, recording the letter at the letter level and the numeral at the roman one, so a range over sub-sub-examples closes with a numeral: ``(3b-i--iii)''. On a main-level example it records nothing, and the range closes with a full reference instead: \begin{code} \ex. \a.\sublabel{r:a} Erste. \b. Zweite. \c.\sublabel{r:c} Dritte. The examples in \refrange{r:a}{r:c} all show ... \end{code} \rendered \ex. \a.\sublabel{r:a} Erste. \b. Zweite. \c.\sublabel{r:c} Dritte. The examples in \refrange{r:a}{r:c} all show \dots \afterex \paragraph{\pkg{cleveref}.} If \pkg{cleveref} is loaded, \cs{cref} works on examples and sub-examples. It prints the number alone --- ``(1)'', ``(1a)'' --- rather than putting a word in front of it, since that is how examples are referred to in running prose; what it adds over \cs{ref} is its handling of several references at once, \cs{cref}\texttt{\{a,b\}} giving ``(1) and (2)''. Should you want a word after all, say so in the preamble and it is left alone: \begin{code} \crefname{ExNo}{example}{examples} \end{code} \noindent The counters are \texttt{ExNo}, \texttt{SubExNo}, \texttt{SubSubExNo} and \texttt{FnExNo}. \cs{crefrange} works too, but it is not a replacement for \cs{refrange}: over the first and last sub-example of an example it prints ``(3a) to (3c)'', where \cs{refrange} prints ``(3a--c)''. \pkg{cleveref} has no way to compress a range whose members share a prefix, which is the compact form a linguistics text wants, so \cs{refrange} and \cs{sublabel} are still the way to get it --- and a label may carry both, since \cs{sublabel} does everything \cs{label} does. \cs{prefrange} is the parenthesis-free variant; \cs{Refrange} sets a range over two whole examples, as (10)--(12). The range dash is the macro \cs{rangedash} (default an en-dash). The dash between number and letter is \cs{firstrefdash} --- empty by default, so ``(3a)'', but \texttt{-} under \opt{legacy} --- and between letter and roman numeral \cs{secondrefdash} (\texttt{-} in both modes); see section~\ref{sec:layout}. % =========================================================================== \section{Further apparatus}\label{sec:extras} % =========================================================================== \pkg{linguexx} contains three constructs that were not part of its ancestor \pkg{linguex}: \cs{altn}, \cs{altg}, and \cs{exsource}. \subsection{Stacked alternatives: \cs{altn}}\label{sec:altn} A set of interchangeable constituents is conventionally stacked inside a curly brace. \cs{altn} takes any number of brace groups and stacks them: \begin{code} \ex. \altn{\sout{This girl in the red coat}}{She}{Mary} will put a picture of \altn{Bill}{him} on your desk. \end{code} \rendered \ex. \altn{\sout{This girl in the red coat}}{She}{Mary} will put a picture of \altn{Bill}{him} on your desk. \afterex The alternatives are collected as long as brace groups follow one another immediately; the first non-brace token ends the list. Strike-through (\cs{sout}) is available for an excluded alternative if your document loads \pkg{ulem} --- the package does not load it for you. An optional argument sets the alignment: \opt{[c]} (default), \opt{[l]}, \opt{[r]}. \paragraph{A guaranteed-available fallback.} \cs{altn} was chosen because nothing in a current \TeX\ Live distribution defines it (unlike the shorter \cs{alt}, which \pkg{beamer} and several other packages already claim). If some other package you load ever does define \cs{altn} first, \pkg{linguexx} detects this, leaves that command alone, notes it in the log, and falls back: \textbf{write \cs{lxAltn}} instead. Otherwise \cs{altn} and \cs{lxAltn} are the same command. \paragraph{Judgment marks in a stack.} Alternatives that differ only in their acceptability are the ordinary case for a stack, and the mark that says so should not push the word it judges out of line: \begin{code} \ex. La secrétaire de Jean et collaboratrice de Paul \altn[l]{est}{*sont} à la gare. \end{code} \noindent Left-aligned and taken literally, that stacks \texttt{est} above \texttt{*sont}, which puts \texttt{est} under the star and \texttt{sont} a star-width to its right --- so the one pair of words the reader is asked to compare is the one pair that does not line up. With \cs{GlossPhantomAlign} in force (or the package option \opt{phantomalign}; section~\ref{sec:phantomalign}) the mark is set in a narrow column of its own, hanging to the left of the alternatives and flush against them, and the words line up: \rendered {\GlossPhantomAlign \ex. La secrétaire de Jean et collaboratrice de Paul \altn[l]{est}{*sont} à la gare. \par} \afterex \noindent The mark stays \emph{inside} the braces, because it judges its own alternative and not the stack. The marks that count are those of \cs{GlossPhantomChars}, and where several rows carry marks of different widths the column takes the widest, so every mark sits flush against the words. Nothing is inserted between a mark and the word it marks: that distance is the font's own, exactly what you get by typing \texttt{*sont} in running text, and alignment does not change it. What moves is the \emph{other} rows, which come right to meet the marked one --- so an aligned stack is no wider than the same stack unaligned. A stack that carries a mark also tucks \cs{AltJdgTuck} (default \texttt{0.2em}) closer to its opening brace. The room is there: a brace's arm curls \emph{away} from the content between its tips, so at the height of any row its ink sits well inside the box, and the mark moves into that hollow without touching it. The effect is to undo part of what the hanging costs: at 10pt on a one-star stack the opening brace sits 7.7pt from the unmarked rows instead of 9.7pt, while the mark keeps 2.3pt of air. The default is chosen so that the air holds at every size --- 2.3pt from 10pt to 20pt --- which a deeper tuck does not, since the brace's pen grows with the font and \cs{AltBraceAmplitude} does not. Only the opening gap changes, so the closing brace rides along with the stack and the distance from the preceding word is untouched; and only a stack that actually carries a mark tucks. Set \cs{AltJdgTuck} to \texttt{0pt} for the untucked layout, or deeper than the default to trade the mark's air for words that stay where an unjudged stack puts them. Like the other brace lengths, it is not clamped: a large enough value pulls the stack straight through the brace, and \TeX{} has no opinion about overlapping ink, so nothing would otherwise say so. Past \cs{AltBraceWidth}${}+{}$\cs{AltBraceSep} the package therefore writes one warning to the log, naming the value and the threshold, and \emph{uses the value anyway} --- a setting that silently did something other than what it was set to would be worse than one that obeys. The warning is reported once per document, and only for a stack that actually carries a mark. A stack in which no alternative carries a mark is set exactly as it would be with the option off, so turning the option on never moves a stack that has nothing to align. For a light word-level alternation inside a glossed line a slash (\texttt{gehe/laufe}) is often enough; when each alternative needs a gloss of its own, use \cs{altg} (section~\ref{sec:altg}). \cs{altn} is set in text mode: the alternatives are the rows of a \pkg{tabular}, braced on both sides with drawn braces, so no mathematics is involved (the package needs \pkg{tikz}, not \pkg{amsmath}). The brace is drawn as a filled outline rather than a stroke, because a typographic brace does not have one width everywhere: like the \texttt{\{} of a maths font it carries its weight in the spine and tapers at the two ends and at the tip. The braces are tunable through seven macros, redefined with \cs{renewcommand}. Three govern the drawn shape of the bracket itself: \cs{AltBraceWidth} (default \texttt{0.9ex}) is the horizontal box reserved for one brace glyph --- the vertical spine of the \texttt{\{}/\texttt{\}} is drawn close to the edge of this box that faces the stack, so widening \cs{AltBraceWidth} leaves more room on the far side for the curl to bulge into; \cs{AltBraceAmplitude} (\texttt{4pt}) is how far the small pointed tip at mid-height projects sideways from that spine, so a larger value draws a more pronounced curl and a smaller one flattens the bracket toward a plain vertical stroke; and \cs{AltBracePen} (\texttt{0.11em}) is the weight of the spine --- the figure is Computer Modern's own, whose brace stem measures \texttt{1.20pt} at 11\,pt, so the default puts the brace at the colour of the type around it. The other four govern placement, not shape: \cs{AltBraceSep} (\texttt{0.15em}, the gap between brace and stack), \cs{AltBraceOuterSep} (\texttt{0.35em}, the gap between the brace and whatever precedes or follows it --- wider than \cs{AltBraceSep} because the drawn curl bulges outward past its own box only on that side, by about \texttt{1.1pt} at 11\,pt), \cs{AltBraceRaise} (\texttt{0pt}, a vertical nudge), and \cs{AltJdgTuck} (\texttt{0.2em}, how far a stack carrying a hanging judgment tucks toward its opening brace --- see above). \cs{altg} (section~\ref{sec:altg}) draws its braces with the same \cs{AltBraceWidth}, \cs{AltBraceAmplitude} and \cs{AltBracePen}, so changing any of them here reshapes both commands' brackets together. Because the alternatives are ordinary text rather than a formula, they are read sensibly in a tagged PDF. Under active tagging \cs{altn} wraps the stack in a span carrying a spoken form of the list --- ``This girl in the red coat, She, or Mary'' --- built from the alternatives themselves, with any formatting (such as the \cs{sout} above) stripped for speech. The printed output is unchanged, and an untagged document is unaffected (section~\ref{sec:tagging}). \subsection{Glossed alternatives: \cs{altg}}\label{sec:altg} Where \cs{altn} stacks bare constituents, \cs{altg} stacks a paradigm in which each alternative carries its own gloss. Inside an interlinear gloss it is written \emph{twice} --- once in the object line with the object words, once in the gloss line with their glosses: \begin{code} \exg. Die \altg{Frau}{Socke}{Maus}{Tonne} ist hier.\\ The.\lpzg{sg} \altg{woman.\lpzg{sg}}{sock.\lpzg{sg}}% {mouse.\lpzg{sg}}{ton.\lpzg{sg}} is.\lpzg{prs} here.\\ \end{code} \rendered \exg. Die \altg{Frau}{Socke}{Maus}{Tonne} ist hier.\\ The.\lpzg{sg} \altg{woman.\lpzg{sg}}{sock.\lpzg{sg}}% {mouse.\lpzg{sg}}{ton.\lpzg{sg}} is.\lpzg{prs} here.\\ \afterex The two calls occupy the two tiers of one gloss column and assemble a single paradigm: object stack on the left, gloss stack to its right (offset by \cs{AltgColSep}), braced on \emph{both} sides. The block is centred on the midline between the object tier and the gloss tier: with four alternatives, rows two and three ride the object and gloss lines and the outer rows protrude symmetrically, with the surrounding lines keeping clear. The example number stays on the object baseline, where \cs{exg.} puts it. Four rules of use. The two calls must list the same number of alternatives --- the package stops with an error otherwise. They must also fall in the \emph{same} gloss column, one in the object tier and one in the gloss tier: a column carrying a stack in only one of its tiers cannot be paired up, and is likewise an error. (This is why a three-tier \cs{glll} cannot take a stack in its third tier either. Alternatives spread over three tiers are not supported.) No spaces may separate the brace groups: a space both ends the collection and splits the gloss into separate columns; break long calls across source lines with \texttt{\%}, as above. And the alternatives are paired by position --- the $n$-th gloss glosses the $n$-th object word. Outside a gloss, a single \cs{altg} sets one both-braced stack on the current baseline --- \cs{altn} with a closing brace, in effect. \paragraph{Punctuation after a paradigm.} A paradigm is one block spanning both tiers, and its closing brace is drawn by the gloss call --- half a line lower and a gloss column further right than the object call. A sentence-final period, though, is written where a period is written: right after the object \cs{altg} that ends the object line. Punctuation glued to the object call (no space between) therefore travels with the paradigm and is set after the closing brace, level with the middle of it --- the sentence it ends is the paradigm's, not the first alternative's: \rendered \exg. On-i su se \altg{posvadjal-i}{*posvadjal-e}.\\ they are \lpzg{refl} \altg{argued.\lpzg{m.pl}}{argued.\lpzg{f.pl}}\\ \afterex \noindent Typeset where it stands it would land immediately after the object stack --- inside the braces, in the gutter between the two columns, reading as a period on the first alternative. It keeps \cs{AltBraceSep} from the brace, the clearance the brace keeps from the stack on its other side: the tip points straight at the punctuation at this height, and a period flush against it reads as part of the brace. Anything separated from the call by a space is a gloss column of its own and needs none of this. \paragraph{Judgment marks: the object tier only.} With \cs{GlossPhantomAlign} in force (or the package option \opt{phantomalign}; section~\ref{sec:phantomalign}), a judgment mark on an object alternative hangs to the left of the stack instead of pushing the word it marks out of line, exactly as in \cs{altn} (section~\ref{sec:altn}): \rendered {\GlossPhantomAlign \exg. Die \altg{Frau}{*Socke}{Maus} ist hier.\\ The.\lpzg{sg} \altg{woman.\lpzg{sg}}{sock.\lpzg{sg}}% {mouse.\lpzg{sg}} is.\lpzg{prs} here.\\ \par} \afterex \noindent The gloss stack follows the widened object stack of its own accord, so the paradigm stays a two-column block. The \emph{gloss} tier is deliberately left out: a judgment is a claim about the object language, and a gloss is a translation of that language rather than something that is itself grammatical or not, so a mark typed in a gloss alternative stays where you put it. If you want a mark to govern a whole paradigm rather than one alternative, put it on the example with \cs{jdg}. Because each stack already competes for both tiers, \cs{lpzg} inside it prints as plain small caps, without the abbreviation span of section~\ref{sec:tagging}; the expansions are not lost --- they reappear in the spoken forms. Under active tagging each call is wrapped in a span carrying a spoken \texttt{/Alt} of its own list --- ``Frau, Socke, Maus, or Tonne'' for the object call, ``woman.singular, sock.singular, mouse.singular, or ton.singular'' for the gloss call --- with simple \cs{lpzg} keys expanded from the Leipzig table; compound keys (\texttt{3sg.pst}) and unknown keys are spoken as printed. Like \cs{altn}, none of this is mathematics, so the alternatives remain ordinary tagged text. Two settings of its own, redefined with \cs{renewcommand}: \cs{AltgColSep} (default \texttt{1.2em}), the gap between the object and gloss stacks, and \cs{AltgTransFont} (default \cs{normalfont}), the font of the gloss stack. The braces are drawn with the \cs{altn} tunables (\cs{AltBraceWidth}, \cs{AltBraceAmplitude}, \cs{AltBracePen}, \cs{AltBraceSep}, \cs{AltBraceOuterSep}). If some other package owns \cs{altg}, the package leaves it alone and only \cs{lxAltg} is available, as with \cs{altn}/\cs{lxAltn}. \subsection{Source attributions: \cs{exsource}} \cs{exsource} sets an attribution flush right at the end of an example, dropping it onto a line of its own if it does not fit: \begin{code} \ex. This girl in the red coat will put a picture of Bill on your desk. \exsource{(Perlmutter 1971: 76)} \end{code} \rendered \ex. This girl in the red coat will put a picture of Bill on your desk. \exsource{(Perlmutter 1971: 76)} \afterex It works in every part of a multipart example, and after a gloss. The font is the hook \cs{ExSourceFont} (default \cs{normalfont}\cs{footnotesize}); the argument may contain a \cs{cite}. \subsection{A free translation beside the gloss: \cs{GlossTransSide}}\label{sec:transside} By default \cs{glt} sets the free translation under the interlinear grid. \cs{GlossTransSide} puts it in a column beside the grid instead, which on a slide buys the thing there is least of: \begin{code} {\GlossTransSide \ex. \gll il mio libro\\ the my book\\ \glt `my book, and a translation with room of its own' } \end{code} \rendered \begingroup {\GlossTransSide \ex. \gll il mio libro\\ the my book\\ \glt `my book, and a translation with room of its own' } \endgroup \afterex It is a declaration and it respects grouping, like \cs{ExAnnotFit} and \cs{ExRaggedRight}; \cs{GlossTransBelow} turns it off again. \cs{glt} itself is unchanged --- it still takes no argument, and no document that does not ask for the side position is affected in any way. The declaration has to come \emph{before} the example, and that is not a style preference. By the time \cs{glt} is reached the grid is already a finished paragraph contributed to the enclosing list, and there is nothing left to set beside it; the decision has to be made while the grid is still being built. The share of the measure the grid gets is \cs{GlossTransRatio} (default \texttt{.6}), and the gap between the two columns is \cs{GlossTransSep} (default \texttt{2em}). Both are ordinary parameters, settable for one example or for the whole document. \cs{GlossTransRightSkip} (default \texttt{0pt plus 2em}) is a little stretch at the right of the translation's column: a narrow measure hands \TeX\ lines it cannot break any shorter, and a fully justified column then overflows rather than ending short. All three defaults follow \pkg{expex}, so that one example set with either package comes out in much the same proportions. The gloss is what is being read closely, and it gets the room. Two restrictions, each a package error rather than a silent reinterpretation: \begin{itemize}[leftmargin=*] \item \textbf{Top-level examples only.} Below the top level the measure has already been reduced twice, so both columns come out narrow and the grid starts wrapping between columns; and a split taken from the indented measure would put every sibling's translation at a different place. The restriction is cheap to lift if a document turns up wanting it --- \texttt{doc/EXPEX-GAPS.md} records what such a design would have to answer. \item \textbf{No \cs{exannot} on the same gloss.} Its column is measured from \cs{columnwidth}, which says nothing once the grid has been narrowed to half of it. \end{itemize} If there is no room --- a narrow measure, a \texttt{twocolumn} paper --- the translation goes underneath after all and the log says so. The threshold is \cs{GlossTransMinWidth} (default \texttt{6em}), measured on the translation's column. A side-by-side gloss is one unbreakable block: the two columns are boxes, and a box does not break across a page. A tall one therefore wants a page with room for it, and says so as an overfull \verb|\vbox| if it does not get one. \goodbreak Where it earns its keep is a gloss that already runs to several lines. This is \pkg{expex}'s own illustration of the same feature, from §12.2 of its manual (printed p.~52), reproduced here so that the two can be compared on one example: \begin{code} {\GlossTransSide \renewcommand\GlossTransRatio{.69} % this gloss wants the room \newcommand\gc[1]{\textsc{#1}} \ex. \gll Homâo sa čô pô tha ñu nao ngă hmua. Ñu djă gă, ñu djă čŏng ñu, laih gui rêo ñu. Todang bboi rôk jolan ñu nao hma, ñu bbôh sa droi mră dŏ bboi gah, a, hruh ñu.\\ \gc{exist} one \gc{clf} person old \gc{3s} go do field \gc{3s} hold machete \gc{3s} hold hoe \gc{3s} and carry.on.back back.basket \gc{3s} while at along trail \gc{3s} go field \gc{3s} see one \gc{clf} peacock stay at \gc{drct} -- nest \gc{3s}\\ \glt `There was an old person who went to work in the field. He took along his machete, he took along his hoe, and he carried his basket on his back. While he was on his way to the farm, he saw a peacock beside its nest.' } \end{code} \rendered \begingroup \GlossTransSide \renewcommand\GlossTransRatio{.69} \newcommand\gc[1]{\textsc{#1}} \ex. \gll Homâo sa čô pô tha ñu nao ngă hmua. Ñu djă gă, ñu djă čŏng ñu, laih gui rêo ñu. Todang bboi rôk jolan ñu nao hma, ñu bbôh sa droi mră dŏ bboi gah, a, hruh ñu.\\ \gc{exist} one \gc{clf} person old \gc{3s} go do field \gc{3s} hold machete \gc{3s} hold hoe \gc{3s} and carry.on.back back.basket \gc{3s} while at along trail \gc{3s} go field \gc{3s} see one \gc{clf} peacock stay at \gc{drct} -- nest \gc{3s}\\ \glt `There was an old person who went to work in the field. He took along his machete, he took along his hoe, and he carried his basket on his back. While he was on his way to the farm, he saw a peacock beside its nest.' \endgroup \afterex \cs{GlossTransRatio} is raised to \texttt{.69} here, which is what the parameter is for. A gloss of nine words to a row wants width more than running prose does, so the \texttt{.6} default leaves this one cramped, while too generous a share leaves the translation's last line a single word. There is no formula: try two or three values and look at the result. That is a fair description of the whole feature --- it is a typesetting decision, and the parameter is there so that one example can make it differently from the rest of the document. \paragraph{When the side position actually saves space.} Less often than one would think, and it is worth being plain about. Narrowing the measure makes \emph{both} columns taller, so the arrangement pays only when one of them would have been much shorter than the other --- the short one then costs nothing, because it hides inside the tall one's height. Measured on this package's own examples: \begin{center}\small \begin{tabular}{@{}lrrl@{}} \toprule translation & underneath & beside & \\ \midrule one line & 71.1pt & 57.6pt & saves a line \\ three lines & 84.7pt & 94.1pt & costs most of one \\ \bottomrule \end{tabular} \end{center} \noindent (Measured on a two-tier gloss of three words in a 25\,mm-margin \pkg{article}; the point is the direction, not the millimetre.) \noindent So: reach for it when the translation is short beside a gloss of some height, which is the common case in a slide, and leave it alone when the translation is the longer of the two. The Jarai example above is worth setting this way not because it saves height --- it saves about four points, a quarter of a line --- but because the translation stays \emph{beside} the gloss it belongs to instead of arriving after eight lines of it. \cs{gc} is a local shorthand for this example only: \pkg{expex} writes \verb|\\{exist}| for it, which is not available here because \verb|\\| separates the gloss tiers. In a linguexx document the Leipzig abbreviations would be \cs{lpzg}\marg{clf} and so on, which sets the small caps \emph{and} gives a screen reader the expansion to speak (section~\ref{sec:leipzig}); they are left plain here only to keep the example the one \pkg{expex} prints, since three of its glosses are not Leipzig abbreviations at all. A long gloss in a narrowed column may of course wrap between columns, as one in a full-width measure would; the side position makes that more likely rather than less. If it happens, the vertical space the arrangement was supposed to buy is what pays for it, and \cs{GlossTransBelow} for that example is the answer. \subsection{Structural labels: \cs{exannot}}\label{sec:exannot} \cs{exsource} puts its argument at the right margin, which is where a source belongs. A label \emph{about} an example --- the category of a constituent, the reading intended, the language --- belongs beside the example instead, and beside several examples it has to form a column, or the eye cannot use it. \cs{exannot} does that: \begin{code} \setlength{\ExAnnotColumn}{9cm} \ex. \a. que Pierre est fatigu\'e\exannot{[CP]} \b. Pierre est fatigu\'e\exannot{[TP]} \z. \end{code} \rendered \begingroup \setlength{\ExAnnotColumn}{9cm} \ex. \a. que Pierre est fatigu\'e\exannot{[CP]} \b. Pierre est fatigu\'e\exannot{[TP]} \z. \endgroup \afterex \cs{ExAnnotColumn} is where the column is, measured from the \emph{left} edge of the text block --- so ``9cm'' means what it says on the page, and does not move when the example does. The default is \texttt{.75}\cs{columnwidth}. \cs{ExAnnotSep} (default \texttt{1em}) is the least gap between an example and the column; give it no stretch or shrink. The font is \cs{ExAnnotFont}, \cs{normalfont} by default. The column holds across nesting levels, because it is measured from the text block and not from the indented line; and it holds however long the examples are, because an example that would come within \cs{ExAnnotSep} of the column takes its annotation onto the next line rather than pushing the column right: \rendered \begingroup \setlength{\ExAnnotColumn}{9cm} \ex. \a. a short one\exannot{[CP]} \b. one long enough that its annotation has to go somewhere else\exannot{[TP]} \a. and one a level deeper\exannot{[DP]} \z. \endgroup \afterex \cs{exannot} closes the example's paragraph, as it must in order to hold the last line to the column, so it comes last in its example. In a gloss, write it at the end of the \emph{object} line --- with a space in front of it or glued to the last word, whichever reads better. It is set level with the object tier, at the same column as everywhere else --- not under the free translation, and not as a column of the grid: \begin{code} \ex. \gll que Pierre est fatigu\'e \exannot{[CP]}\\ that Pierre is tired\\ \glt `that Pierre is tired' \end{code} \rendered \begingroup \setlength{\ExAnnotColumn}{9cm} \ex. \gll que Pierre est fatigu\'e \exannot{[CP]}\\ that Pierre is tired\\ \glt `that Pierre is tired' \endgroup \afterex On any other tier it is an error, and so is one in the middle of a line: a gloss is a translation, so a label on a gloss tier has nothing to align with, and one between two object words has nowhere to go. \paragraph{What a screen reader says.} ``\texttt{[CP]}'' is an abbreviation a reader cannot expand and a synthesiser will not usefully spell. Give \cs{exannot} a spoken form and, under tagging, the annotation reaches the structure tree as a \texttt{Span} carrying \texttt{/Alt}: the page still shows \texttt{[CP]}, copy-and-paste still yields \texttt{[CP]}, and the reader hears the phrase. Either per annotation, or once for a label used throughout: \begin{code} \SetAnnotSpoken{[CP]}{complementizer phrase} \ex. que Pierre est fatigu\'e\exannot{[CP]} % from the table \ex. Pierre est fatigu\'e\exannot[tense phrase]{[TP]} % just this one \end{code} \noindent This is the same arrangement as \cs{DeclareJudgment}\texttt{[spoken=]} and \cs{SetJudgmentSpoken} (\S\ref{sec:judgments} if you have met those already). An annotation with no spoken form gets no \texttt{Span} at all: an \texttt{/Alt} that repeats the text it replaces is noise in the tree. \texttt{/Alt} is used rather than \texttt{/E} or \texttt{/ActualText} because it is the one of the three that leaves both the printed label and the text layer alone; \texttt{doc/TAGGING-NOTES.md} sets out the comparison for anyone auditing a document's structure. \paragraph{Letting the examples choose the column: \cs{ExAnnotFit}.} \cs{ExAnnotColumn} is a number you have to find, and the number that looks right depends on the examples underneath it. \cs{ExAnnotFit} finds it instead. Each annotated example records where its text ended, and the column of an example --- one \cs{ex.} and everything under it --- is put \cs{ExAnnotSep} past the longest of them: \begin{code} \ExAnnotFit \ex. \a. que Pierre est fatigu\'e depuis mardi\exannot{[CP]} \b. Pierre est fatigu\'e\exannot{[TP]} \z. \ex. \a. short\exannot{[DP]} \b. brief\exannot{[VP]} \z. \end{code} \rendered \begingroup \ExAnnotFit \ex. \a. que Pierre est fatigu\'e depuis mardi\exannot{[CP]} \b. Pierre est fatigu\'e\exannot{[TP]} \z. \ex. \a. short\exannot{[DP]} \b. brief\exannot{[VP]} \z. \endgroup \afterex The unit is the \emph{example}, not the document: the second block above gets a column of its own, because its examples are shorter. Footnote examples are their own examples in this sense too. The widest \emph{annotation} of a block counts as well, and the column is never narrower than it. That is what keeps a long label in line with its neighbours instead of letting it step out to the left on its own: \rendered \begingroup \ExAnnotFit \ex. \a. que Pierre est fatigu\'e\exannot{[CP]} \b. Pierre est fatigu\'e\exannot{[an annotation wider than that column]} \c. Pierre dort\exannot{[TP]} \z. \endgroup \afterex When the two pull against each other --- a label so wide that the column has to move left of where some example's text ends --- the column wins and that one annotation goes onto the next line. It is the column that has to hold; a line is only a line. This costs an \texttt{.aux} round trip, so a fresh document's first run sets \cs{ExAnnotColumn} and says \begin{quote}\small\ttfamily Package linguexx Warning: Annotation columns\\ are not settled. Rerun to get\\ \textbackslash ExAnnotFit right \end{quote} \noindent The second run is right, and silent. If the warning comes back on a later run, something is still moving: the one way that happens is an example whose own text breaks across lines, where the annotation is part of what the paragraph breaker is fitting. Set \cs{ExAnnotColumn} for that block and turn the fitting off inside it (\cs{ExAnnotNoFit}); both are ordinary switches and respect \TeX\ grouping. Nothing is recorded and no round trip happens unless \cs{ExAnnotFit} is asked for. \paragraph{And \cs{jambox}.} Under \opt{langsci} this package also provides Alexis Dimitriadis's \cs{jambox} (\S\ref{sec:langsci}), which answers a neighbouring question: it lines material up a fixed distance from the \emph{right} margin, and for a note that belongs near the margin it is the more direct instrument of the two. \cs{exannot} is aimed at the other case --- a column set close to the examples, where what has to be held is the column's position rather than its distance from the margin --- and the two are built differently because of it. \cs{jambox} is provided exactly as \pkg{langsci-gb4e} has it; use whichever suits the note you are writing. % =========================================================================== \section{Example and glossing layout}\label{sec:layout} % =========================================================================== The geometry is uniform across levels: each level reserves a label box of fixed width, followed by the shared gap \cs{Exlabelsep}; the text margin of a level is its label width plus \cs{Exlabelsep}, measured from the margin of the level above (figure~\ref{fig:boxmodel}). Judgments hang to the left of the text margin and take no space. \begin{figure}[htbp] \centering {\setlength{\fboxsep}{2.2pt}\setlength{\arraycolsep}{2pt}% \renewcommand{\arraystretch}{1.5}% \resizebox{\linewidth}{!}{% $\begin{array}[t]{@{}l|l|l|l|l@{}} \multicolumn{5}{@{}c@{}}{\lname{Extopsep}\ \updownarrow\ 0.66\,\lname{baselineskip}}\\[1.2ex] \underbrace{\lname{Exindent}}_{\text{\scriptsize0pt}} & \fbox{\lname{Exlabelwidth}}\underbrace{\lname{Exlabelsep}}_{\text{\scriptsize.6em}} & \text{\footnotesize main text}\ldots & & \\[2.6ex] & & \fbox{\lname{SubExlabelwidth}}\underbrace{\lname{Exlabelsep}}_{\text{\scriptsize.6em}} & \text{\footnotesize sub text}\ldots & \\[2.6ex] & & & \fbox{\lname{SubSubExlabelwidth}}\underbrace{\lname{Exlabelsep}}_{\text{\scriptsize.6em}} & \text{\footnotesize roman text}\ldots \\[1.2ex] \multicolumn{5}{@{}c@{}}{\lname{Extopsep}\ \updownarrow\ 0.66\,\lname{baselineskip}} \end{array}$}} \caption{The default box model. On each line, reading left to right: an optional \cs{Exindent} (0\,pt), the label box, then the shared gap \cs{Exlabelsep}; the text of a level begins one label box plus one \cs{Exlabelsep} to the right of the level above, so the boxes cascade down the page. Each box is named for the length that fixes its width (\cs{Exlabelwidth} 2.6\,em, \cs{SubExlabelwidth} 1.6\,em, \cs{SubSubExlabelwidth} 1.6\,em) and holds the number, the letter and the roman label respectively; the vertical rules mark the three text margins. \cs{Extopsep} is the space left above and below. Under \opt{legacy} the sub-levels are driven instead by two leftmargins, \cs{SubExleftmargin} and \cs{SubSubExleftmargin}, as in \pkg{linguex}.} \label{fig:boxmodel} \end{figure} \noindent Every parameter is an ordinary length, set with \cs{setlength} anywhere in the document: \begingroup \renewcommand{\arraystretch}{1.25} \setlength{\LTpre}{\medskipamount}\setlength{\LTpost}{\medskipamount} \begin{longtable}{@{}>{\ttfamily}l l p{0.44\linewidth}@{}} \toprule \normalfont Length & Default & Role \\ \midrule \endhead \midrule \multicolumn{3}{r@{}}{\normalfont\footnotesize\itshape continued on the next page} \\ \endfoot \bottomrule \endlastfoot \textbackslash Extopsep & \texttt{.66\textbackslash baselineskip} & Vertical space before and after an example. \\ \textbackslash Exredux & \texttt{-.66\textbackslash baselineskip} & Correction inserted between \emph{consecutive} examples, so the gap is not doubled. Keep it at $-\cs{Extopsep}$ for an even rhythm. \\ \textbackslash Exlabelwidth & \texttt{2.6em} & Width of the number box --- room for ``(199)''. Widen it for four-digit numbering. \\ \textbackslash Exlabelsep & \texttt{.6em} & Gap between any label box and its text. \\ \textbackslash SubExlabelwidth & \texttt{1.6em} & Width of the letter box (``a.''). Deliberately wider than the letter: the surplus is where a hanging judgment goes (section~\ref{sec:jdgspace}). \\ \textbackslash SubSubExlabelwidth & \texttt{1.6em} & Width of the roman box, sized for the widest label up to ``vi.'' (``iii.''), which is the same width as the widest letter; equal to \cs{SubExlabelwidth}, so the two sub-levels share one box width. \\ \textbackslash JdgSep & \texttt{0.15em} & Gap between a hanging judgment and the text. \\ \textbackslash ExAnnotColumn & \texttt{.75\textbackslash columnwidth} & Where \cs{exannot}'s column is, measured from the \emph{left} edge of the text block, so it does not move with the nesting level (section~\ref{sec:exannot}). \\ \textbackslash GlossTransSep & \texttt{2em} & Gap between the gloss and a side translation (section~\ref{sec:transside}); \cs{GlossTransRatio} (\texttt{.6}, a factor) is the share of the measure the gloss gets, \cs{GlossTransMinWidth} (\texttt{6em}) the width below which the side position is abandoned, and \cs{GlossTransRightSkip} (\texttt{0pt plus 2em}) the stretch at the right of the translation's column. \\ \textbackslash ExAnnotSep & \texttt{1em} & Least gap between an example and that column. Give it no stretch or shrink: it is what makes an example that comes within it take its annotation onto the next line rather than crowd in. \\ & & Under \cs{ExAnnotFit} the same length is the distance the fitted column keeps past the longest example of its block. \\ \end{longtable} \endgroup \noindent A few further knobs are macros, not lengths, and are changed with \cs{renewcommand}: \cs{GlossSep} (glue between gloss columns), \cs{ExAnnotFont} (default \cs{normalfont}) and the three reference dashes. \cs{rangedash} (default \texttt{-\/-}) separates the two ends of a range; \cs{firstrefdash} sits between an example number and a sub-example letter in a reference such as ``(3a)'', and \cs{secondrefdash} between the letter and a roman numeral in ``(3a-i)''. Their defaults differ by mode: in the default scheme \cs{firstrefdash} is \emph{empty} (giving ``(3a)'') and \cs{secondrefdash} is \texttt{-}; under \opt{legacy} both are \texttt{-}, so the same reference prints ``(3-a)'' and ``(3-a-i)'', as \pkg{linguex} does. The sub-label delimiters \cs{SubExLBr}/\cs{SubExRBr} and \cs{SubSubExLBr}/\cs{SubSubExRBr} bracket the letter and roman labels themselves; they are \texttt{\{\}}/\texttt{\{.\}} in both modes for the letter (``a.''), while the roman is bare ``i.'' by default but parenthesised ``(i)'' under \opt{legacy}. The number of a top-level example is bracketed by \cs{ExLBr}/\cs{ExRBr}, and a footnote example's by \cs{FnExLBr}/\cs{FnExRBr}. These are \pkg{linguex}'s names and \pkg{linguex}'s meaning: \verb|\renewcommand{\ExLBr}{[}| together with \verb|\renewcommand{\ExRBr}{]}| prints ``[1]'' in the label and in every reference to it, and the footnote series keeps its parentheses until its own pair is moved as well. The package reads all four through \cs{theExLBr} and its relatives, which add the parenthesis suppression that \cs{ExBareRefs} asks for (section~\ref{sec:refs}); redefine one of \emph{those} and you replace the switch along with the character. The counters are \texttt{ExNo}, \texttt{SubExNo}, \texttt{SubSubExNo} and \texttt{FnExNo} (footnotes). To change the style of the numbering, redefine \cs{theExNo} and its relatives in the usual \LaTeX{} way. \paragraph{The default scheme and \opt{legacy}.} The values in the table are the \emph{default} scheme. The option \opt{legacy} selects instead the exact geometry and conventions of \pkg{linguex}: the number box is sized per example from the width of its digits rather than fixed at \cs{Exlabelwidth}; the sub-levels are positioned by two leftmargins, \cs{SubExleftmargin} (\texttt{2em}) and \cs{SubSubExleftmargin} (\texttt{2.4em}), rather than by a label width plus \cs{Exlabelsep}; roman sub-sub-labels print as ``(i)''; \cs{firstrefdash} is \texttt{-}; and, in a book-class document, \texttt{ExNo} resets at each \cs{chapter}. \opt{legacy} is orthogonal to the choice of input syntax: combine it freely, as in \opt{[legacy,gb4e]}. Both parameter sets exist in either mode --- \cs{SubExleftmargin} always equals \cs{SubExlabelwidth}${}+{}$\cs{Exlabelsep} --- so a document can be nudged from one scheme toward the other one length at a time. \cs{resetExdefaults} restores every layout parameter to the values of the mode in force; it is what the package runs for you as it loads. Because the defaults are applied at load time, not \cs{AtBeginDocument} as in \pkg{linguex}, a \cs{setlength} in your preamble simply wins --- there is no need to hook it into \cs{resetExdefaults} to keep it from being overwritten. The two font-relative lengths, \cs{Extopsep} and \cs{Exredux}, are the exception: they are finalised at \cs{begin\{document\}} so that they follow the body font, unless you have already given either an explicit value. % =========================================================================== \section{PDF tagging and accessibility}\label{sec:tagging} % =========================================================================== \pkg{linguexx} is aware of the \LaTeX{} project's PDF tagging code. If the document begins with a \cs{DocumentMetadata} line that turns tagging on, for example, on a current \TeX{} distribution, \begin{code} \DocumentMetadata{lang=en,tagging=on} \end{code} \noindent then examples are written into the PDF's structure tree as genuine, accessible objects rather than as loose ink. Without such a line nothing below applies: the printed output is identical and the package behaves exactly as in the rest of this manual. The exact spelling of that line may depend on your version of \LaTeX{}. The \texttt{tagging=on} key is the recommended form from the \LaTeX{} release of November~2025 onward. On distributions between roughly 2023 and 2025 the tagging code lives behind the experimental \texttt{testphase} key instead; the portable choice there, which also works on current \TeX{}, is \begin{code} \DocumentMetadata{lang=en,testphase={phase-III}} \end{code} \noindent Both enable the same comprehensive tagging as far as \pkg{linguexx} is concerned.\footnote{Avoid the older habit of naming individual modules (\texttt{testphase=\{tagpdf,\dots\}}): those names have been reorganised and can now load only part of the machinery.} The structure tree of all structures provided by \pkg{linguexx} is valid, including the case of an example inside a footnote. Each example is a list item with its number as the label and its content as the body; the letter and roman sub-levels are nested lists inside it, so assistive technology can walk into and out of the hierarchy. Those lists are marked as \emph{ordered}, matching their numbering. Grammaticality marks are given a spoken form, so a screen reader announces ``ungrammatical'' rather than ``asterisk'' (section~\ref{sec:jdgspoken}). In an interlinear gloss each column --- an object word together with its aligned gloss(es) --- is grouped as one structure element, so the gloss is read and navigated word bundle by word bundle, in the object-then-gloss order, rather than as one undifferentiated run of text. The object language of a tier can be recorded (section~\ref{sec:glosslang}), so it is pronounced with its own phonetics; and category abbreviations written with \cs{lpzg} carry their expansion (section~\ref{sec:leipzigtag}), so a reader hears ``past'' rather than ``pee-ess-tee''.\footnote{This also means that tagging is only useful for English at the current time.} Stacked alternatives (\cs{altn}) are set in text mode rather than as a formula, and carry a spoken form of the list (section~\ref{sec:extras}), so they are read as ``A, B, or C'' rather than as a run of braces and glyphs. A document built with the accessibility preamble above validates as PDF/UA-2: veraPDF reports it conformant, with every rule and check passing and no exceptions. Conformance is a document-level property, not only a matter of the examples --- it also needs a document title and a few other pieces of metadata --- so the package ships a short checklist (\texttt{PDFUA-CHECKLIST}) giving the preamble that supplies them. What a validator cannot certify is that the result is \emph{pleasant} to listen to; that still wants testing with a real screen reader. A caution on stability. Tagging in \LaTeX{} requires a recent \LaTeX{}. \pkg{linguexx}'s support is written to degrade quietly --- if the tagging machinery is absent or turned off, the relevant code does nothing --- but it should be regarded as provisional and may need a touch-up as the tagging project matures. The \opt{legacy} option is orthogonal to all of this; tagging support targets the default mode. \subsection{Spoken forms for tagged PDFs}\label{sec:jdgspoken} A judgment mark is a symbol whose meaning a screen reader cannot guess: read literally, \texttt{*} is ``asterisk''. When the document is compiled with the PDF tagging code active (a \cs{DocumentMetadata} line enabling the tagging \texttt{testphase}), \pkg{linguexx} wraps each mark in a structure element carrying an \emph{alternate text} so it is announced by its meaning instead. The built-in marks have the following defaults: \begin{center} \begin{tabular}{@{}ll@{}} \toprule mark & spoken as \\ \midrule \texttt{*} & ungrammatical \\ \texttt{?} & questionable \\ \texttt{??} & highly questionable \\ \texttt{?*} & extremely degraded \\ \texttt{\#} & infelicitous \\ \texttt{\%} & grammatical for some speakers \\ \bottomrule \end{tabular} \end{center} \noindent This affects only the tagged PDF's accessibility layer; the printed output is unchanged, and nothing happens on an engine or in a document without active tagging. To set the spoken form of a mark, give \cs{DeclareJudgment} its optional \texttt{spoken} key --- which both names the mark and registers its spoken form, so a leading scanned mark is announced the same way --- \begin{code} \DeclareJudgment[spoken={marginal, some speakers}]{\pcent}{\%} \end{code} \noindent or, for a mark you do not need to name, \cs{SetJudgmentSpoken}\- \marg{mark}\marg{phrase}. An explicit \cs{jdg} may also carry a one-off spoken form as an optional argument: \begin{code} \jdg[contradictory]{*} \end{code} \subsection{Stacked alternatives, and the word between them} \label{sec:altspoken} A stack set by \cs{altn} or \cs{altg} is a vertical arrangement on the page, and a screen reader cannot see that the rows are alternatives rather than lines. Under active tagging \pkg{linguexx} therefore gives the stack an alternate text that says so in words: \cs{altn}\marg{aa}\marg{bb} is announced ``aa or bb'', and three alternatives become ``aa, bb, or~cc''. That word is English, and so is the punctuation convention around it --- English puts a comma before the final connector and most other languages do not. \cs{SetAltSpoken}\marg{word} replaces the connector: \begin{code} \SetAltSpoken{ou} % "aa ou bb", "aa, bb ou cc" \SetAltSpoken{oder} % "aa oder bb", "aa, bb oder cc" \end{code} \noindent Write the word bare, without spaces: the spacing around it is the package's business, so \verb|\SetAltSpoken{ou}| and \verb|\SetAltSpoken{ ou }| are the same setting. Dropping the comma before the connector is part of the same change, because that is what these languages do. To keep it --- the English convention, and the package's default --- use the starred form. An optional argument replaces the punctuation itself: \begin{code} \SetAltSpoken*{or} % "aa, bb, or cc" <- the default, spelled out \SetAltSpoken{y}[;] % "aa; bb y cc" \SetAltSpoken{} % "aa bb" <- no connector at all \end{code} \noindent The setting respects grouping, like the \pkg{xlist} variants and unlike \cs{SetLeipzig}, so one example may be spoken in another language without disturbing the rest of the document: \begin{code} {\SetAltSpoken{ou} \ex. \altn{aa}{bb} } \end{code} \noindent It applies to \cs{altg} as well as \cs{altn}, and as with everything in this section it changes nothing on the page and nothing at all in a document compiled without active tagging. \subsection{Gloss abbreviations and their expansions} \label{sec:leipzigtag} Under active tagging, \cs{lpzg}\marg{label} does more than set small capitals (section~\ref{sec:leipzig}): it records the label's \emph{expansion} as the PDF ``expansion text'' (the \texttt{/E} entry of an abbreviation), so a screen reader announces ``singular'' while the page still shows \textsc{sg} and copy-and-paste still yields \texttt{sg}. This is the correct mechanism for an abbreviation --- distinct from an \emph{alternate text}, and unlike \texttt{/ActualText} it leaves the copied text alone. A compound label is parsed for the expansion: it is split on periods, a leading \texttt{1}, \texttt{2} or \texttt{3} is taken as the person, and each piece is expanded and joined into one phrase, so \cs{lpzg}\marg{3sg.pst} reads ``third person singular past''. A piece not in the table below passes through verbatim; a label with nothing recognisable in it gets no expansion, and no warning, so project-specific labels are safe. Extend or override the table with \cs{SetLeipzig}\marg{label}\marg{expansion}: \begin{code} \SetLeipzig{obv}{obviative} \end{code} \noindent The built-in table is the standard Leipzig Glossing Rules list; the meaning column is what a screen reader speaks. \begin{center} \small \begin{longtable}{@{}llll@{}} \toprule label & meaning & label & meaning \\ %\midrule \endfirsthead \toprule label & meaning & label & meaning \\ \midrule \endhead \bottomrule \textsc{1} & first person & \textsc{indf} & indefinite \\ \textsc{2} & second person & \textsc{inf} & infinitive \\ \textsc{3} & third person & \textsc{ins} & instrumental \\ \textsc{a} & agent & \textsc{intr} & intransitive \\ \textsc{abl} & ablative & \textsc{ipfv} & imperfective \\ \textsc{abs} & absolutive & \textsc{irr} & irrealis \\ \textsc{acc} & accusative & \textsc{loc} & locative \\ \textsc{adj} & adjective & \textsc{m} & masculine \\ \textsc{adv} & adverbial & \textsc{n} & neuter \\ \textsc{agr} & agreement & \textsc{neg} & negative \\ \textsc{all} & allative & \textsc{nmlz} & nominalizer \\ \textsc{antip} & antipassive & \textsc{nom} & nominative \\ \textsc{appl} & applicative & \textsc{obj} & object \\ \textsc{art} & article & \textsc{obl} & oblique \\ \textsc{aux} & auxiliary & \textsc{p} & patient \\ \textsc{ben} & benefactive & \textsc{pass} & passive \\ \textsc{caus} & causative & \textsc{pfv} & perfective \\ \textsc{clf} & classifier & \textsc{pl} & plural \\ \textsc{com} & comitative & \textsc{poss} & possessive \\ \textsc{comp} & complementizer & \textsc{pred} & predicative \\ \textsc{compl} & completive & \textsc{prf} & perfect \\ \textsc{cond} & conditional & \textsc{prog} & progressive \\ \textsc{cop} & copula & \textsc{proh} & prohibitive \\ \textsc{cvb} & converb & \textsc{prox} & proximal \\ \textsc{dat} & dative & \textsc{prs} & present \\ \textsc{decl} & declarative & \textsc{pst} & past \\ \textsc{def} & definite & \textsc{ptcp} & participle \\ \textsc{dem} & demonstrative & \textsc{purp} & purposive \\ \textsc{det} & determiner & \textsc{q} & question particle \\ \textsc{dist} & distal & \textsc{quot} & quotative \\ \textsc{distr} & distributive & \textsc{recp} & reciprocal \\ \textsc{du} & dual & \textsc{refl} & reflexive \\ \textsc{dur} & durative & \textsc{rel} & relative \\ \textsc{erg} & ergative & \textsc{res} & resultative \\ \textsc{excl} & exclusive & \textsc{s} & argument of intransitive verb \\ \textsc{f} & feminine & \textsc{sbj} & subject \\ \textsc{foc} & focus & \textsc{sbjv} & subjunctive \\ \textsc{fut} & future & \textsc{sg} & singular \\ \textsc{gen} & genitive & \textsc{top} & topic \\ \textsc{imp} & imperative & \textsc{tr} & transitive \\ \textsc{incl} & inclusive & \textsc{voc} & vocative \\ \textsc{ind} & indicative & & \\ \bottomrule \end{longtable} \end{center} \subsection{Transliteration and the engine you compile with} \label{sec:translitengine} One trap is worth knowing about, because nothing warns you and the page looks perfect. Under pdf\LaTeX{}, characters whose diacritic sits \emph{below} the letter are not single glyphs: \TeX{} composes them by placing a period-like glyph under the base letter. The result prints correctly, but the PDF's text layer records the two pieces, so what copy-paste and a screen reader receive is not what you wrote: \begin{center} \begin{tabular}{@{}lll@{}} \toprule you write & pdf\LaTeX{} extracts & Xe\LaTeX/Lua\LaTeX{} extract \\ \midrule \texttt{kṛṣṇaḥ} (Indic) & \texttt{kr.s.n.ah.} & \texttt{kṛṣṇaḥ} \\ \texttt{ḍāṇṭaḥ} (Indic) & \texttt{d . ān.t.ah.} & \texttt{ḍāṇṭaḥ} \\ \texttt{ģimeņu} (Latvian) & \texttt{gimen ,u} & \texttt{ģimeņu} \\ \bottomrule \end{tabular} \end{center} \noindent This manual is itself built with Lua\LaTeX{}, for exactly this reason: it contains those characters in the table above, and under pdf\LaTeX{} it would exhibit the defect it is describing --- copying the first column out of the PDF would give you the second. Built as it is, the first and third columns copy out as written. This affects dot-below (Indic and Semitic transliteration: \texttt{ḍ ṇ ṭ ṣ ḥ ṛ ṃ}) and comma-below (Latvian \texttt{ģ ķ ļ ņ}, and the same command produces Romanian \texttt{ș ț}). Two things make it easy to miss. Tagging does \emph{not} repair it --- the mapping is supplied per glyph, and here there are two glyphs where you meant one --- so it is present in a fully tagged \opt{ua-2} document as much as in a plain one. And veraPDF \emph{passes} such a file on all three profiles: the structure tree is valid, so the only authoritative check for PDF/UA gives it a clean bill while the text a screen reader reads is wrong. If your data uses those scripts, compile with Xe\LaTeX{} or Lua\LaTeX{}, where the characters stay single glyphs and extract correctly. For those languages this is an accessibility requirement, not a preference. Accents \emph{above} the letter --- the whole European Latin repertoire, \texttt{ä é č ő ł ø þ} and the rest --- are unaffected and extract correctly under all three engines. % =========================================================================== \subsection{What this does not yet claim}\label{sec:tagginglimits} The structure this package writes is validated, and validation is not the same as knowing that a document reads well. It is worth being explicit about the distance between the two. \paragraph{No screen reader has been in the room.} veraPDF can say that a file conforms to PDF/UA-2. It cannot say that a reader using JAWS, NVDA, VoiceOver or Orca gets a good account of an interlinear gloss. Nothing here has been tried with one. The structural decisions are argued rather than observed --- above all the decision to read a gloss word bundle by word bundle, so that an object word and its gloss are heard together, instead of the whole object line and then the whole gloss line. That is the choice this package would defend, but it is a choice, and only a user can settle it. Treat this part of the package as a well-formed proof of concept: correct by every check that can be automated, and not yet confirmed by the only check that counts. \paragraph{The spoken forms are English.} Three things carry words rather than markup, and all three are written in English: \begin{itemize}[leftmargin=*] \item the judgment phrases --- ``ungrammatical'', ``questionable'' and the rest (section~\ref{sec:jdgspoken}); \item the Leipzig expansions --- ``singular'', ``accusative'' and some two hundred others (section~\ref{sec:leipzig}); \item the word \cs{altn} puts between stacked alternatives when it builds their spoken form: ``A, B, or C''. \end{itemize} \noindent The first two can be replaced entry by entry, with \cs{SetJudgmentSpoken} and \cs{SetLeipzig}, and the third with \cs{SetAltSpoken} (section~\ref{sec:altspoken}). So setting \verb|lang=fr| in \cs{DocumentMetadata} is not enough to make a French document read properly. The tree would then declare French while its \texttt{/Alt} and \texttt{/E} strings remained English words, and a French voice would pronounce them as French. Nor is there a way to mark them as English in passing: the \texttt{Span} that carries an \texttt{/Alt} does not also carry a \texttt{/Lang}, so the phrase is announced in whatever language surrounds it. Calling that a translation job would be too quick, because for the gloss abbreviations it is not clear what should be translated. The printed label is already free: \cs{lpzg} small-caps whatever you type and never consults the table, and keys are compared with their accents normalised, so \verb|\lpzg{fém}| prints \textsc{fém} today, and \verb|\SetLeipzig{f\'em}{féminin}| gives it an expansion although it spells the key the other way. A French document can be glossed in French, entry by entry, right now. What is undecided is what the package should \emph{ship}: whether the Leipzig abbreviations stay in place in every document --- they are English-derived but serve as an interchange standard well beyond English --- with only the spoken expansions translated, or whether a language should have its own labels as well. The first keeps a glossed example legible to any reader of the field, and costs the link between the label and the word spoken for it. The second is more coherent inside one document, and gives up that portability. This manual does not answer the question, and the package does not answer it by default; \texttt{doc/DEFERRED-DECISIONS.md} records what would settle it. \paragraph{The kernel's tagging is still provisional.} These features sit on the \LaTeX\ Project's tagging code at \texttt{phase-III}, whose interfaces are declared provisional by the project itself. Where this package leans on an internal it does so behind a guard that degrades to no tagging rather than to a broken document, but the arrangement will want revisiting as that work moves out of testphase. \paragraph{What is checked, and how often.} One accessible configuration is validated with veraPDF on every run of the test suite, and the worked accessible document shipped in \texttt{examples/} before a release. The number of combinations a document can present --- syntax option, gloss shape, beamer, footnotes, a language per tier --- is much larger than the set under validation. Support for \texttt{/E} and \texttt{/Alt} also varies between readers; a reader that ignores \texttt{/E} will simply say ``sg''. If you use this with a screen reader, reports of what it actually sounds like are very welcome. That is the missing evidence, and no amount of validation substitutes for it. % =========================================================================== \section{Notes and limitations}\label{sec:notes} % =========================================================================== \begin{itemize}[itemsep=4pt] \item \textbf{Two sub-levels.} A third \cs{a.}\ is an error. Deeper hierarchies are almost always better expressed as separate examples. \item \textbf{The period is part of the command.} \cs{ex.}, \cs{a.}, \cs{z.}\ --- not \cs{ex}, \cs{a}, \cs{z}. This is what allows the syntax to be so light. \item \textbf{\cs{z.}\ at brace depth 0.} \cs{z.}\ is recognized in the body of an example, not inside a brace group within it. \item \textbf{\cs{verb} in an example body.} It cannot work in the dot syntax. A dot-syntax body is \emph{collected} before it is typeset --- that is exactly what lets a blank line end it and \cs{z.}\ pop a level --- and by then its tokens have long since been read, with the catcodes in force where the \cs{ex.}\ stood. \cs{verb} has to change those catcodes \emph{while} reading, so it finds nothing left to protect and fails, usually as ``Missing \$ inserted''. The same goes for \texttt{verbatim}, \pkg{listings} and \pkg{fancyvrb}'s environments, and for anything else that reads its own argument specially. This is inherent to a blank-line-delimited body rather than a defect to be fixed someday --- \pkg{linguex} grabs its bodies at \cs{par} and has it too. The environment syntax does \emph{not} collect, so there \cs{verb} works normally, including inside an \cs{a.}\ or an \texttt{xlist} written within the batch: \begin{code} \begin{exe} \ex A body with \verb|x_y| in it. \end{exe} \end{code} The one exception is the braced judgment form \cs{ex}\oarg{judgment}\marg{text}, whose body is a macro argument and is therefore read before it is used, exactly like a collected one. So: for verbatim material in an example, use \texttt{exe} with an unbraced \cs{ex}. \item \textbf{Examples in a \texttt{minipage} footnote.} They are numbered on the main series, not on the footnote series: \cs{footnote} inside a \texttt{minipage} is a different command from the ordinary one, and only the ordinary one is hooked. Whether such examples ought to share the footnote series, keep the main one, or get a series per minipage is a question none of \pkg{linguex}, \pkg{gb4e} and \pkg{langsci-gb4e} settles either: all three number such examples on the main series too, so a document arriving from any of them keeps the numbers it had. Nothing is claimed here and nothing is patched; if the numbering matters in your document, put the examples outside the minipage. \item \textbf{\pkg{ulem} is not loaded.} For struck-through alternatives (\cs{sout} inside \cs{altn}), load \pkg{ulem} yourself; the usual choice is \cs{usepackage[normalem]\{ulem\}}, which keeps \cs{emph} italic. \item \textbf{The accents \cs{b}, \cs{c}, \cs{d} keep working.} These are accent commands as well as sub-example letters, and both meanings are available everywhere, including in the same example: each letter dispatches on what follows it, so a period gives the sub-example command and anything else the accent. \cs{c}\marg{c} and a literal ``\c c'' --- which \pkg{inputenc} turns into exactly that pair of tokens under pdf\LaTeX{} --- both work in running text, in a section title and inside an example body. The same holds under \pkg{hyperref}, in either load order. \item \textbf{Shorthand names another package owns.} The glossed shorthands \cs{ag.}--\cs{fg.}\ are claimed at \cs{begin\{document\}} and only if the name is still free. \pkg{babel}'s French option defines \cs{fg}, the closing guillemet of \cs{og}\,\dots\,\cs{fg}, so in a French document \cs{fg.}\ is simply not available and the guillemet keeps its meaning; write \cs{f.}\ followed by \cs{gll} instead. The same applies to any name you have defined yourself --- \cs{eg} is a common one --- and the fact is recorded in the \texttt{.log}. \item \textbf{Footnote examples.} End an example inside a footnote with a blank line or \cs{z.}\ rather than letting it run into the footnote's own end. \item \textbf{Glosses and alternatives do not combine.} See section~\ref{sec:extras}. \item \textbf{Where \pkg{expex} still does more.} Tier \emph{count} and tier \emph{fonts} are unrestricted here, but the vertical layout of a gloss is not individually adjustable per tier, and there is no keyval interface. See section~\ref{sec:origins}. \end{itemize} \clearpage % =========================================================================== \section{For front-end authors}\label{sec:api} % =========================================================================== Nothing in this section is needed to write a document. It is for someone building a \emph{package} on top of \pkg{linguexx}: a third input syntax, or a geometry to sit beside \opt{legacy}. The two syntaxes this package ships --- the dot commands and the \texttt{exe}/\texttt{xlist} environments --- are thin. Between them they are a few dozen lines; everything underneath, the numbering, the label boxes, the judgment machinery, the glossing and the PDF tagging, is shared and knows nothing about which syntax called it. That seam is exposed under documented names, so a further syntax can be built without touching internals and without a fork. The names below are the contract. Everything else in \texttt{linguexx.sty} --- anything spelled \cs{lx@\dots} or \cs{\_\_lx\_\dots} --- is private and may change in any release. Public names are \pkg{expl3} functions, so a front-end calls them under \cs{ExplSyntaxOn}; they exist whatever combination of \opt{lazy}, \opt{gb4e} and \opt{legacy} the document asked for. The contract runs the other way too. A release may \emph{add} public names, and does not otherwise touch them: an existing \cs{lx\_\dots} loses its meaning or its name only in a major version, and only after the changelog has announced it as deprecated in a release before that. A front-end pinned to a major version therefore keeps compiling. \subsection{Protocol A: building a syntax} \begingroup \renewcommand{\arraystretch}{1.2} \setlength{\tabcolsep}{4pt} \setlength{\LTpre}{\medskipamount}\setlength{\LTpost}{\medskipamount} \begin{longtable}{@{}>{\ttfamily\raggedright\arraybackslash}p{0.34\linewidth} p{0.57\linewidth}@{}} \toprule \normalfont Function & \normalfont Effect \\ \midrule \endhead \midrule \multicolumn{2}{r@{}}{\normalfont\footnotesize\itshape continued on the next page} \\ \endfoot \bottomrule \endlastfoot \multicolumn{2}{@{}l}{\itshape Lifecycle} \\ \textbackslash lx\_example\_begin: & Open an example: reset the sub-level depth and counters, and save the cross-referencing state. \\ \textbackslash lx\_example\_end: & Close it: every sub-level still open, then the main list, then the paragraph bookkeeping. \\ \multicolumn{2}{@{}l}{\itshape The body} \\ \textbackslash lx\_body\_collect:N \meta{function} & Collect the example body under this package's terminator rules --- a blank line, \cs{z.}, or an unmatched \cs{end} --- and hand it to \meta{function}, which must take one argument and be \cs{long}. Optional: a syntax whose body is delimited some other way simply does not call it. \\ \multicolumn{2}{@{}l}{\itshape Items} \\ \textbackslash lx\_item\_main: & Step the counter, open the main list, and make the item. For an example that brings its own list. \\ \textbackslash lx\_item\_main:n \marg{label} & The same with a label of your choosing, and no counter step. \\ \textbackslash lx\_item\_next: & Step the counter and make the item \emph{without} opening a list: the next example in a batch. \\ \textbackslash lx\_item\_core: & Step the counter of whatever level is open and set its label; emit nothing. \\ \textbackslash lx\_item\_emit: & Emit the item for the current label, and hang any judgment collected since the last scan. \\ \textbackslash lx\_item\_judged:n \marg{mark} & Core, mark and item in one move, at the current level. \\ \multicolumn{2}{@{}l}{\itshape Sub-levels} \\ \textbackslash lx\_sub\_push: & Open a new, deeper level and give it its first item. Two levels maximum. \\ \textbackslash lx\_sub\_next: & The next item at the level now open. \\ \textbackslash lx\_subenv\_begin: & Open a deeper level \emph{without} an item, for a level bounded by an environment: the environment's own group undoes the depth advance at its \cs{end}. \\ \multicolumn{2}{@{}l}{\itshape Judgments} \\ \textbackslash lx\_judgment\_scan: & Peek for judgment marks in the input, then emit the item. This is where the \texttt{lx\_item\_} commands end. \\ \textbackslash lx\_judgment\_scan:n \marg{code} & Peek for marks, then run \meta{code}. \\ \textbackslash lx\_judgment\_set:n \marg{mark} & Set the mark explicitly, for a syntax that takes it as an argument. Any mark is allowed, not only the scanned set. \\ \multicolumn{2}{@{}l}{\itshape Lists} \\ \textbackslash lx\_list\_main\_open: & Open the main example list by hand, for the batch shape. \\ \textbackslash lx\_label\_guess: & Stand in the label the \emph{next} item will print. Required before opening a list that has no item yet. \\ \textbackslash lx\_list\_open:n \marg{decl} \newline \textbackslash lx\_list\_close: & The list funnel (see invariant~4). \\ \textbackslash lx\_ol\_class:n \marg{class} & The \texttt{/ListNumbering} attribute class for the list about to open. \\ \multicolumn{2}{@{}l}{\itshape Tagging} \\ \textbackslash lx\_tag\_if\_active:TF & Whether tagging is switched on \emph{and} the kernel has the commands for it. The one guard. \\ \textbackslash lx\_tag\_span:nn \marg{keyvals} \marg{content} & Set \meta{content} inside a tagged \texttt{Span}. Without active tagging the content is set bare, so untagged output is unaffected. \\ \textbackslash lx\_tag\_span\_open:n \newline \textbackslash lx\_tag\_span\_close: & The outer half alone, for content that carries marked content of its own. \\ \textbackslash lx\_tag\_span\_begin:n \newline \textbackslash lx\_tag\_span\_end: & The inner half as well, for leaf content. \\ \end{longtable} \endgroup \subsection{A worked front-end} The whole of a dot-syntax-shaped front-end. It collects a body the way \cs{ex.}\ does, and gives it one item: \begin{code} \ExplSyntaxOn \NewDocumentCommand \pex { } { \lx_body_collect:N \__fe_run:n } \cs_new_protected:Npn \__fe_run:n #1 { \lx_example_begin: \lx_item_main: #1 \lx_example_end: } \NewDocumentCommand \pa { } { \lx_sub_push: } \NewDocumentCommand \pb { } { \lx_sub_next: } \ExplSyntaxOff \end{code} \noindent That is enough for \verb|\pex|, \verb|\pa| and \verb|\pb| to number, to nest, to take judgments typed into the text, to be cross-referenced, to carry glosses, and to tag themselves. The batch shape --- one list holding several examples, as \texttt{exe} does --- is the same parts in a different order: \cs{lx\_example\_begin:}, then \cs{lx\_label\_guess:} and \cs{lx\_list\_main\_open:} to open the list, then \cs{lx\_item\_next:} per example, then \cs{lx\_example\_end:}. A fuller version of both, exercising every function in the table, is \texttt{tests/frontend.tex} in the distribution. It is a regression case: it is written against the public names only, so it stops compiling if one of them goes away, and \texttt{veraPDF} is run on what it produces. Glossing is deliberately outside Protocol A, and its absence from the table is not an invitation to rebuild it: the interlinear tagging --- the column spans, the object-language \texttt{/Lang}, the abbreviation \texttt{/E} --- is what makes a gloss PDF/UA-valid, and reassembling it from the raw span helpers is work nobody should repeat. A front-end that wants a gloss syntax of its own should translate it onto the user-level engine, \cs{gl}\ \dots\ \cs{endgl} (section~\ref{sec:glosses}), which takes any number of tiers and styles them per tier through \cs{GlossTierFont} and \cs{GlossTierLang}; the tagging travels with it. A gloss protocol of the same standing as Protocol~A is possible later, once there are real front-ends to shape what it should expose. \subsection{The four invariants}\label{sec:apirules} These are not style advice but constraints the engine relies on. Each can be broken without any error being raised, and the output then looks plausible, which is what makes them worth stating. \begin{enumerate}[itemsep=4pt] \item \textbf{The label is fixed before the list opens.} Under \opt{legacy} the width of the label box is measured from the label itself, so a list opened first is sized from whatever the previous example left behind. This renders identically in the default mode, which is what makes it easy to write and hard to see: use \cs{lx\_item\_core:} before \cs{lx\_list\_main\_open:}, never after. \item \textbf{The grouping structure is the depth stack.} \cs{lx\_sub\_push:} advances the depth inside the group it opens for the new level, so leaving that group pops it and \cs{lx\_example\_end:} can close whatever is left. Never advance or reset the depth yourself. \pkg{linguex} tracked it in a global counter, and the drift that followed --- an example that quietly starts one level deep because an earlier one ended badly --- is the thing this design makes impossible. \item \textbf{No extra group around a whole example.} It is tempting to wrap the lifecycle in \cs{begingroup}\dots\cs{endgroup} for safety. Do not: the tagged-PDF ``block'' code accounts for text units across the example, and an enclosing group desynchronises that accounting for an example inside a footnote. What the group would have protected is restored explicitly by \cs{lx\_example\_end:}. \item \textbf{Every list goes through the funnel.} Use \cs{lx\_list\_open:n} and \cs{lx\_list\_close:}, not \cs{list} or \texttt{\{list\}} directly. The funnel uses the environment form, which is the interface the tagging code supports --- part of its state restoration is keyed to hooks that command-form \cs{list} never fires --- and it is where the \texttt{/ListNumbering} attribute is attached. A list opened around it loses both. \end{enumerate} \subsection{Protocol B: a geometry mode} A mode is a defaults table and three geometry hooks, and nothing else: \opt{legacy} differs from the default in exactly those four macros. \begin{code} \ExplSyntaxOn \lx_mode_new:nn {name} { defaults = \myDefaults, main = \myMain, sub = \mySub, subsub = \mySubSub } \lx_mode_select:n {name} \ExplSyntaxOff \end{code} \noindent The values are macro \emph{names}, not bodies, so that you may define them with plain \cs{newcommand} in ordinary catcodes --- a defaults table contains glue whose spaces matter (\texttt{.5em plus .3em}), and those would be stripped from a body written as an argument under \cs{ExplSyntaxOn}. Anything else is refused with an error. The interface is keyval because a mode may later have more than four things to set: new keys may appear in a future release, which is exactly what the arity-encoded form this replaced could not do without changing its own name. \texttt{defaults} is required, and is what \cs{resetExdefaults} calls. It must set every length of \emph{both} parameter sets described in section~\ref{sec:layout}, since the document may switch modes afterwards. The three hooks are optional --- one omitted does nothing, and the level keeps the list parameters it was handed. They run inside the list declaration of their level and may set \cs{labelwidth}, \cs{labelsep}, \cs{leftmargin} and \cs{topsep}; \texttt{main} runs after the label is fixed, so it may measure it (which is what \opt{legacy} does). A hook that wants its level tagged with a numbering style calls \cs{lx\_ol\_class:n}. \cs{lx\_mode\_select:n} assigns locally, so a mode selected inside a group is undone at the end of it; the mode in force is readable in \cs{l\_lx\_mode\_tl}. \clearpage % =========================================================================== \section{Command reference}\label{sec:reference} % =========================================================================== \begingroup \renewcommand{\arraystretch}{1.2} \setlength{\tabcolsep}{4pt} \setlength{\LTpre}{\medskipamount}\setlength{\LTpost}{\medskipamount} \begin{longtable}{@{}>{\ttfamily\raggedright\arraybackslash}p{0.31\linewidth} p{0.60\linewidth}@{}} \toprule \normalfont Command & \normalfont Effect \\ \midrule \endhead \midrule \multicolumn{2}{r@{}}{\normalfont\footnotesize\itshape continued on the next page} \\ \endfoot \bottomrule \endlastfoot \multicolumn{2}{@{}l}{\itshape Examples} \\ \textbackslash ex. & Start a numbered example; a blank line ends it. \cs{ex.}\oarg{label} uses a custom label without advancing the counter. \\ \textbackslash a. & Open a level of sub-examples (letters, then roman). \\ \textbackslash b. -- \textbackslash f. & Next item at the level currently open. \\ \textbackslash z. & Leave one level; from the letter level or an example without sub-examples, end it. \\ exe, xlist & \pkg{gb4e}-compatible batch and sub-level environments (package option \opt{gb4e}); items via \cs{ex}, \cs{ex}\oarg{judgment}\marg{text}, or plain \cs{item}. \\ \textbackslash exg. & \cs{ex.}\ followed by \cs{gll}. \cs{exg.}\oarg{label} takes a custom label too, written against the command: a bracket after a space is the object line's first word. \\ \textbackslash ag. -- \textbackslash fg. & \cs{a.}--\cs{f.}\ followed by \cs{gll}. \\ \addlinespace \multicolumn{2}{@{}l}{\itshape Judgments} \\ \textbackslash jdg\marg{mark} & Hang an arbitrary mark in the margin. \\ \textbackslash DeclareJudgment\allowbreak\marg{cmd}\marg{mark} & Give a mark a name. \\ \addlinespace \multicolumn{2}{@{}l}{\itshape Glosses} \\ \textbackslash gll, \textbackslash glll & Two-, three-tier gloss; lines end in \verb|\\|. \\ \textbackslash gl \dots\ \textbackslash endgl & Gloss with any number of tiers. \\ \textbackslash glt & Free-translation line. (\cs{gln} is a synonym.) \\ \textbackslash GlossTierFont\allowbreak\marg{n}\marg{cmd} & Font command for tier \meta{n}. \\ \textbackslash GlossTierLang\allowbreak\marg{n}\marg{code} & Language of tier \meta{n} for tagged PDFs (section~\ref{sec:glosslang}). \\ \textbackslash GlossTransStyle & Declaration applied to the free translation after \cs{glt}; empty by default. \\ \textbackslash GlossTransLang\marg{code} & Language of the free translation for tagged PDFs (section~\ref{sec:glosslang}). \\ \textbackslash GlossTransSide & Set the free translation in a column \emph{beside} the gloss rather than under it (section~\ref{sec:transside}); \cs{GlossTransBelow} restores the default. A declaration, and it must come before the example. Top-level examples only, and not on a gloss carrying an \cs{exannot}. \\ \textbackslash GlossTransRatio & Share of the measure the gloss gets beside a side translation (\texttt{.6}, a factor, not a length). \\ \textbackslash GlossTransSep & Gap between the two columns (\texttt{2em}). \\ \textbackslash GlossTransRightSkip & Stretch at the right of the translation's column (\texttt{0pt plus 2em}); without it a narrow column overflows rather than ending short. \\ \textbackslash GlossTransMinWidth & Below this the side position is abandoned and the translation set underneath, with a warning (\texttt{6em}). \\ \textbackslash lpzg\marg{abbr} & Gloss abbreviation in small caps, with spoken expansion when tagged (section~\ref{sec:leipzig}). \\ \textbackslash SetLeipzig\allowbreak\marg{abbr}\marg{expansion} & Add or override a Leipzig abbreviation expansion. \\ \textbackslash lpzglist\oarg{keys} & List of the abbreviations the document uses, each with its full form (section~\ref{sec:lpzglist}). Keys: \opt{style}, \opt{sort}, \opt{include}, \opt{ignore}, \opt{add}, \opt{unexplained}, \opt{title}, \opt{titlestyle}, \opt{sep}, \opt{itemsep}, \opt{format}. \\ \textbackslash lpzglistsetup\marg{keys} & The same keys, for every list. \\ \textbackslash lpzgcheck\marg{keys} & Consistency checks on the abbreviations: \opt{unknown} (on by default), \opt{unused}, \opt{ignore} (section~\ref{sec:lpzgcheck}). \\ \textbackslash ag. \dots\ \textbackslash fg. & Glossed sub-example: \cs{a.}\,\dots\,\cs{f.} followed by \cs{gll}. A shorthand whose name another package already owns is left to it (section~\ref{sec:notes}). \\ \textbackslash lpzgadd\marg{abbrs} & Register abbreviations used outside \cs{lpzg} so that they reach the list. \\ \textbackslash lpzglistentry\allowbreak\marg{abbr}\marg{full form} & One entry of the list; redefine to restyle every list. \\ \textbackslash eachwordone/two/three & Font commands for tiers 1--3. \\ \textbackslash GlossSep & Glue between gloss columns. \\ \textbackslash GlossPhantomAlign & Align gloss words past leading brackets, parentheses and judgment marks (\emph{recommended}; section~\ref{sec:phantomalign}). Also the package option \opt{phantomalign}; \cs{GlossPhantomAlignOff} reverts. \\ \textbackslash GlossPhantomChars\allowbreak\marg{marks} & Leading marks that alignment skips; one token is one mark, characters and commands alike (default \texttt{*?([<} plus \textbackslash\# \textbackslash\%). \\ \textbackslash GlossPhantom\allowbreak\marg{material} & Manual override: pad a gloss word by an invisible box the width of \meta{material}, in the object font. \\ \addlinespace \multicolumn{2}{@{}l}{\itshape References} \\ \textbackslash label, \textbackslash ref & As usual; references print in parentheses. \\ \textbackslash sublabel\marg{key} & Label a sub-example for use in a range. \\ \textbackslash Next, \textbackslash NNext, \textbackslash Last, \textbackslash LLast & Relative references; \oarg{letter} adds a sub-example part, as (3b). Clickable under \pkg{hyperref}. \\ \textbackslash TextNext & Next example of the running text (from a footnote). \\ \textbackslash pref, \textbackslash pNext, \dots & Parenthesis-free twins of all of the above. \\ \textbackslash refrange\marg{a}\marg{b} & Compact range, as (3a--c). \\ \textbackslash prefrange, \textbackslash Refrange & Without parentheses; over whole examples. \\ \addlinespace \multicolumn{2}{@{}l}{\itshape Further apparatus} \\ \textbackslash altn\marg{$\dots$}\marg{$\dots$} & Stacked alternatives; \oarg{c/l/r} alignment. Fallback: \cs{lxAltn}. \\ \textbackslash altg\marg{alt}\marg{alt}$\dots$ & Glossed alternatives: written in both lines of \textbackslash exg. (objects, then glosses); both-braced, centred. Also \cs{lxAltg}. \\ \textbackslash SetAltSpoken\marg{word} & The word spoken between stacked alternatives, for \cs{altn} and \cs{altg} alike: \cs{SetAltSpoken}\marg{ou} gives ``aa, bb ou cc''. The starred form keeps the comma before the connector, which is English usage and the default; an optional \oarg{punct} replaces the punctuation. Respects grouping (section~\ref{sec:altspoken}). \\ \textbackslash exsource\marg{text} & Flush-right attribution. \\ \textbackslash exannot\oarg{spoken}\marg{text} & Structural label, set in a column at \cs{ExAnnotColumn}; on the object line in a gloss. \cs{SetAnnotSpoken}\marg{text}\marg{phrase} registers a spoken form for a label used throughout (section~\ref{sec:exannot}). \\ \textbackslash ExAnnotFit & Measure that column from the examples instead: one column per example, past the longest of them. Costs an \texttt{.aux} round trip; \cs{ExAnnotNoFit} turns it off again. \\ \textbackslash ExAnnotColumn & Where the column is, from the \emph{left} edge of the text block (\texttt{.75\textbackslash columnwidth}). \\ \textbackslash ExAnnotSep & Least gap between an example and that column (\texttt{1em}); give it no stretch or shrink. \\ \textbackslash ExAnnotFont & Font of the annotation (\cs{normalfont}). \\ \addlinespace \multicolumn{2}{@{}l}{\itshape Layout and options} \\ \opt{lazy}, \opt{gb4e} & Package options: dot syntax (default), \pkg{gb4e} environment syntax; combinable. \\ \opt{phantomalign} & Package option: aligns words in glosses with the word in the object line, not a bracket or judgment mark; combinable.\\ \opt{legacy} & Package option: the geometry and dash conventions of \pkg{linguex}; orthogonal to the syntax options. \\ \opt{norelreflinks} & Package option: print \textbackslash Next and \textbackslash Last without the \pkg{hyperref} link. \\ \textbackslash resetExdefaults & Restore all layout lengths to the current mode's defaults. \\ \textbackslash firstrefdash & Number--letter dash in ``(3a)''; empty by default, \texttt{-} under \opt{legacy}. \\ \textbackslash secondrefdash & Letter--roman dash in ``(3a-i)''; \texttt{-} in both modes. \\ \textbackslash rangedash & Dash in a whole-example range. \\ \end{longtable} \endgroup \vfill \noindent\small \pkg{linguexx} owes its input syntax to Wolfgang Sternefeld's \pkg{linguex}, its glossing commands to the \pkg{cgloss4e} of Hans-Peter Kolb and Craig Thiersch, the ambition of its gloss engine to John Frampton's \pkg{expex}, and its parenthesis-free references to a construction of Alan Munn's. The implementation is its own. \end{document} %%% Local Variables: %%% mode: LaTeX %%% TeX-master: t %%% End: