Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % !TEX program = pdfLaTeX
3 %
4 %<*internal>
5 \iffalse
6 %</internal>
7 %<*readme>
8
9 The \textglos{} package provides a set of macros for in-line linguistic examples (as opposed to interlinear glossing, set apart from the main text). It prevents hyphenated examples from breaking across lines and consistently formats phonemic examples, orthographic examples, and more.
10
11 %</readme>
12 %<*internal>
13 \fi
14 \def\nameofplainTeX{plain}
15 \ifx\fmtname\nameofplainTeX\else
16 \expandafter\begingroup
17 \fi
18 %</internal>
19 % Copyright 2013 by Natalie Weber
20 %
21 % This work may be distributed and/or modified under the
22 % conditions of the LaTeX Project Public License, either version 1.3
23 % of this license or (at your option) any later version.
24 % The latest version of this license is in
25 %
26 % http://www.latex-project.org/lppl.txt
27 %
28 % and version 1.3 or later is part of all distributions of LaTeX
29 % version 2005/12/01 or later.
30 %
31 %<*internal>
32 \ifx\fmtname\nameofplainTeX
33 \expandafter\endbatchfile
34 \else
35 \expandafter\endgroup
36 \fi
37 %</internal>
38 %<*driver>
39 \ProvidesFile{textglos.dtx}%
40 %</driver>
41 %<package>\NeedsTeXFormat{LaTeX2e}[1996/10/24]%
42 %<package>\ProvidesPackage{textglos}%
43 %<*package>
44 [2012/06/27 v1.0 textglos package for inline linguistic glossing]%
45 %\AtBeginDocument{%
46 % \MakeShortVerb{\|}
47 % \DeleteShortVerb{"}}
48 %</package>
49 %
50 %<*driver>
51 % \begin{macrocode}
52 \documentclass[11pt]{ltxdoc}%
53 \usepackage{geometry}%
54 \usepackage[utf8x]{inputenc}%
55 \usepackage[T1]{fontenc}%
56 \usepackage{tipa}%
57 \usepackage{expex}% to typeset examples
58 \usepackage[longnamesfirst]{natbib}
59 \setcitestyle{authoryear,round,semicolon,aysep={},yysep={,},notesep={:}}%
60 \bibliographystyle{linquiry2}%
61 \usepackage{verbatim}%
62 \usepackage{url}%
63 \usepackage{textglos}%
64 \usepackage{sectsty}
65 \allsectionsfont{\sffamily\mdseries\upshape} % (See the fntguide.pdf for font help)
66 %\usepackage[nottoc,notlof,notlot]{tocbibind} % Put the bibliography in the ToC
67 %\usepackage[titles,subfigure]{tocloft} % Alter the style of the Table of Contents
68 %\renewcommand{\cftsecfont}{\rmfamily\mdseries\upshape}
69 %\renewcommand{\cftsecpagefont}{\rmfamily\mdseries\upshape} % No bold!
70 \usepackage{hyperref}%
71 \usepackage{xcolor}%
72 \definecolor{dark-red}{rgb}{0.4,0.15,0.15}
73 \definecolor{dark-blue}{rgb}{0.15,0.15,0.4}
74 \definecolor{medium-blue}{rgb}{0,0,0.5}
75 \hypersetup{%
76 colorlinks, linkcolor={dark-red},
77 citecolor={dark-blue}, urlcolor={medium-blue} }
78 \def\textglos{\textsf{textglos}}
79 \newcommand{\refp}[1]{(\protect\ref{#1})}%
80 %\EnableCrossrefs
81 \DisableCrossrefs
82 %\OnlyDescription
83 \CodelineIndex
84 %\PageIndex
85 \RecordChanges
86 \begin{document}%
87 \DocInput{textglos.dtx}%
88 \end{document}%
89 % \end{macrocode}
90 %</driver>
91 %
92 % \fi
93 %
94 %\CheckSum{129}
95 %
96 % \CharacterTable
97 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
98 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
99 % Digits \0\1\2\3\4\5\6\7\8\9
100 % Exclamation \! Double quote \" Hash (number) \#
101 % Dollar \$ Percent \% Ampersand \&
102 % Acute accent \' Left paren \( Right paren \)
103 % Asterisk \* Plus \+ Comma \,
104 % Minus \- Point \. Solidus \/
105 % Colon \: Semicolon \; Less than \<
106 % Equals \= Greater than \> Question mark \?
107 % Commercial at \@ Left bracket \[ Backslash \\
108 % Right bracket \] Circumflex \^ Underscore \_
109 % Grave accent \` Left brace \{ Vertical bar \|
110 % Right brace \} Tilde \~}
111 %
112 % \DoNotIndex{\@@getoptionalarg,\@@next,\@bracketcheck,\@currsize,\@firstoftwo}
113 % \DoNotIndex{\@secondoftwo,\@futurenonspacelet,\@getoptionalarg,\@optionaltemp}
114 % \DoNotIndex{\@gsingle,\@ifnextchar,\@ifpackageloaded,\@ifundefined,\@ne,\z@}
115 % \DoNotIndex{\@nexttoken,\@normalsize,\@optionalarg,\@optionalnext,\@gobble,\p@}
116 % \DoNotIndex{\@selfnt,\@stepone,\@steptwo,\@stepthree,\@stoken,\@undefined,\\}
117 % \DoNotIndex{\active,\addvspace,\advance,\afterassignment,\baselineskip}
118 % \DoNotIndex{\baselinestretch,\begingroup\bgroup,\box,\catcode,\copy,\csname}
119 % \DoNotIndex{\CurrentOption,\DeclareOption,\def,\detokenize,\egroup,\else,\empty}
120 % \DoNotIndex{\endcsname\endgraf\endgroup,PackageOptions,\eplain,\expandafter}
121 % \DoNotIndex{\expandonce,\fi,\fill,\finalhyphendemerits,\futurelet,\gdef,\global}
122 % \DoNotIndex{\gobble,\gobblespaces,\hbox,\hskip,\hspace,\ht,\hyphenpenalty}
123 % \DoNotIndex{\identity,\ifdim,\ifmmode,\ifnum,\ifx,\ifvoid,\ignorespacesafterend}
124 % \DoNotIndex{\ignorespaces,\itemindent,\itshape,\labelsep,\labelwidth,\lastbox}
125 % \DoNotIndex{\leavevmode,\leftskip,\let,\lineskip,\llap,\long,\MessageBreak}
126 % \DoNotIndex{\more,\name,\NAMEskip,\NAMEstyle,\newbox,\newcount,\newenvironment}
127 % \DoNotIndex{\newif,\newskip,\nobreak,\noexpand,\nolinebreak,\normalsize,\rm}
128 % \DoNotIndex{\PackageError,\PackageWarning,\par,\parfillskip,\parindent,\rlap}
129 % \DoNotIndex{\ProcessOptions,\providecommand,\quad,\raggedright,\relax,\rmfamily}
130 % \DoNotIndex{\rightskip,\scantokens,\scshape,\selectfont,\setbox,\sim,\space}
131 % \DoNotIndex{\strut,\textup,\the,\tlist@if@empty@nTF,\tolerance,\unhbox,\unskip}
132 % \DoNotIndex{\unvbox,\upshape,\vbox,\vskip,\vtop,\wd,\z@,\z@skip,\endgraf}
133 % \DoNotIndex{}
134 % \DoNotIndex{}
135 % \DoNotIndex{}
136 %
137 %
138 % \GetFileInfo{textglos.sty}
139 %
140 %\title{\textsf{textglos} package documentation\thanks{This document corresponds to \textsf{textglos}~\fileversion, dated~\filedate.}}
141 % \author{Natalie Weber\\\texttt{[email protected]}}
142 % \date{\filedate}
143 %
144 % \maketitle
145 %
146 %\changes{v1.0}{2012/06/27}{First documented version.}
147 %
148 % \begin{abstract}
149 % \noindent The \textglos{} package provides a set of macros for in-line linguistic examples (as opposed to interlinear glossing, set apart from the main text). It prevents hyphenated examples from breaking across lines and consistently formats phonemic examples, orthographic examples, and more.
150 % \end{abstract}
151 %
152 %
153 % \section{Introduction}\label{sec:intro}
154 %
155 %\DescribeMacro{\gl}
156 %\DescribeMacro{\xo}
157 %\DescribeMacro{\xt}
158 %\DescribeMacro{\xm}
159 %\DescribeMacro{\xv}
160 %\DescribeMacro{\xh}
161 %Linguists often need to use examples in the line of text like \xv[Language][gloss]{example} or \xh[proto-Language][reconstructed semantics]{reconstruction}. The following macros are provided:
162 %
163 %\ex\label{examples}\begin{tabular}[t]{ll}
164 % \textbf{This code} & \textbf{Prints}\\
165 % \verb+\gl{gloss}+ & `gloss'\\
166 % \verb+\xo{orthography}+ & $<$orthography$>$\\
167 % \verb+\xt{phonetic}+ & $[$phonetic$]$\\
168 % \verb+\xm{phonemic}+ & /phonemic/\\
169 % \verb+\xv{vernacular}+ & \textit{vernacular}\\
170 % \verb+\xh{reconstruction}+ & *reconstruction\\
171 %\end{tabular}\xe
172 %
173 %These macros are much more useful than simply typing each example by hand in a number of ways. First, you do not need to type the various opening and closing brackets or apostrophes (an easy place to introduce typos). Second, hyphens (for affixes) and equals signs (for clitics) never cause linebreaks and are always typset in an upright font. Third, the style of each macro is fully customizable using a template in the preamble of your document, and users can redefine the default macros, or define new macros of their own.
174 %
175 %\section{Basic usage}
176 %
177 %All of the macros also have two optional arguments. When just one optional argument is specified, it is printed as a gloss following the mandatory argument. The gloss uses |\gl| so it will be printed with single quote marks automatically\footnote{By default; see section~\refp{custom} for how to alter this behavior.}. When two optional arguments are specified, the first one will print as a prefix plus a non-breaking space\footnote{By default; see section~\refp{custom} for how to alter this behavior.} in front of the mandatory argument, and the second one will print as a gloss following the mandatory argument. Therefore, if you only want to print a prefix, you need to use empty brackets in place of the gloss.
178 %
179 %\ex\begin{tabular}[t]{ll}
180 % \textbf{This code} & \textbf{Prints}\\
181 % |\xv[Lang][gloss]{word}| & \xv[Lang][gloss]{word}\\
182 %|\xh[Lang][]{word}| & \xh[Lang][]{word}\\
183 %|\xo[gloss]{word}| & \xo[gloss]{word}\\
184 %\end{tabular}\xe
185 %
186 %\section{Typesetting features}
187 %
188 %The macros replace all hyphens with a non-breaking hyphen, so that morpheme breaks are not interpreted by \TeX{} as a place to break a line. You can suggest a hyphenation point by using |\-| in your example, as normal. Note that some of the macros prevent the normal line-breaking mechanism in \LaTeX{} while others do not; see section~\refp{custom} for details.
189 %
190 % The macros also replace all equals signs with a shorter version of the equals sign (for clitics), as long as the package \textsf{graphicx} exists on your system (otherwise a normal equals sign is used). The default math symbol is much longer than the hyphen, so that clitics look out of place next to affixes unless you use this shorter version.
191 %
192 %Finally, hyphens (for morpheme breaks) and equals signs (for clitics) will always be typed in upright text, even if the surrounding text is italicized, as it is for |\xv{}|\footnote{This will happen no matter what the surrounding font shape is. This may be undesirable behavior for, e.g.~smallcaps text.}. The macros use \LaTeX{}'s |\textup{}| command, which also take care of kerning when moving from italicized text to an upright punctuation mark and back. Notice that in the example in~\refp{bigex} typeset with |\textit|, the vertical edges of both the hyphen and the equals sign are slanted. (You may have to zoom in to see this.) The top and bottom bar of the equals sign are not aligned, and they are closer together than the upright version of the equals sign. The |\xv| versions are upright and squared off, and the clitic marker is shorter:
193 %
194 %\ex\label{bigex}\begin{tabular}[t]{lll}
195 % with \textbf{\texttt{\textbackslash textit}}: & & with \textbf{\texttt{\textbackslash xv}}:\\[.5\lineskip]
196 % \Huge \textit{hyphen-ated} & vs.\ & \Huge \xv{hyphen-ated}\\
197 % \Huge \textit{hyphen=ated} & vs.\ & \Huge \xv{hyphen=ated}\\
198 %\end{tabular}\xe
199 %
200 % The left column of the table is of course correct in normal italicized text, but a clitic marker should look like a clitic marker (and not like italicized punctuation) whether or not the surrounding text is italicized.
201 %
202 %\section{Customization}\label{custom}%
203 %
204 %\DescribeMacro{\lingprestyle}
205 %\DescribeMacro{\lingpoststyle}
206 %All prefixes and postfixes can be set to a fixed style. The default style is for the prefixes to be printed in the current font followed by a non-breaking space, and for the postfixes to be printed as a gloss following a normal space. Here is how they are defined in the package:
207 %
208 %\ex|\providecommand{\lingprestyle}[1]{#1~}|\newline
209 % |\providecommand{\lingpoststyle}[1]{ \gl{#1}}|\xe
210 %
211 %To change them, simply use |\renewcommand{\lingprestyle}[1]|\marg{\ldots|\#1|\ldots} in your preamble, and similarly for |\lingpoststyle|.
212 %
213 %\DescribeMacro{\lingexample}
214 %You can define (or redefine) in-text example macros with this command:
215 %
216 %\ex |\lingexample|\marg{name}\marg{template}%
217 %\xe
218 %
219 % The \meta{template} should be of the form \meta{text}X\meta{text}, where the X stands for the example itself. The \meta{text} on either side may not have an X in it. %The pre-defined macros are coded as in~(\ref{code}), which you can compare with the output in~(\ref{examples}).
220 %
221 %\begin{center}\noindent\textbf{\textsc{Caution:}} |\lingexample| does not check to see if macro names are pre-defined like |\newcommand| does! Make sure you choose macro names that are not already defined.\end{center}
222 %
223 %
224 %\ex~\label{code}\begin{tabular}[t]{l}
225 % |\lingexample{xo}{\ensuremath{<}X\ensuremath{>}}|\\
226 % |\lingexample{xt}{[X]}|\\
227 % |\lingexample{xm}{/X/}|\\
228 % |\lingexample{xv}{\itshape X}|\\
229 % |\lingexample{xh}{*X}|\\
230 %\end{tabular}\xe
231 %
232 %The only caution you must take is to never use \{ or \} in the \meta{text} on either side of the X within the \meta{template}. Use |\bgroup| and |\egroup| instead. So if you want your reconstructions to be italicized, you cannot use \verb+\lingexample{xh}{*\textit{X}}+. Instead use the following:
233 %
234 %\ex|\lingexample{xh}{*\bgroup\itshape X\egroup}|\newline
235 % \hbox{}\hspace{1em}or\newline
236 % |\lingexample{xh}{*\textit\bgroup X\egroup}|\xe
237 %
238 %You may want phonetic or phonemic examples to be typed in IPA. You can simply redefine |\xt| and |\xm| to use |\tipaencoding| (from the \textsf{tipa} package) by putting the following into your document preamble:
239 %
240 %\ex|\lingexample{xt}{\tipaencoding[X]}|\newline
241 % |\lingexample{xm}{\tipaencoding/X/}|\xe
242 %
243 %Of course you must have |\usepackage{tipa}| in your preamble to do this. This syntax means that both your example and the surrounding square brackets are typeset using \textsf{tipa}, which allows \textsf{tipa} to correctly handle the kerning between the brackets and the IPA symbols.
244 %
245 %By default, the macros do \emph{not} prevent the normal line-breaking mechanism in \LaTeX{}. This means that multiword examples like \xv{It was Colonel Mustard with the knife in the dining room}\footnote{Code: \texttt{\textbackslash xv\{It was Colonel Mustard with the knife in the dining room\}}} will break between words as normal. Unfortunately, if you work with a highly agglutinative language with long words (or long morphemes), then \LaTeX{} may try to hyphenate the words and break them across multiple lines. (It also may be undesirable to have transcriptions in \verb+\xt{}+ and \verb+\xm{}+ break across lines.) One solution would be to create a new \verb+\lingexample+ macro to be used with single-word examples which sets the example in an \verb+\hbox+. This example will not break across lines:
246 %
247 %\ex \verb+\lingexample{xvword}{\hbox\bgroup\itshape X\egroup}+\xe
248 %
249 %\iffalse
250 %\section{Changes}
251 %
252 % \StopEventually{\PrintChanges}
253 %\fi
254 %
255 %\section{The Code}
256 %
257 % \iffalse
258 % \begin{macrocode}
259 %<*package>
260 % \end{macrocode}
261 % \fi
262 %The package \textsf{graphicx} is required to create |\shorteq|.
263 % \begin{macrocode}
264 \IfFileExists{graphicx}{\RequirePackage{graphicx}}{}%
265 % \end{macrocode}
266 % This code originally Sven Siegmund's, created with help of XeTeX mailing list, to detect optional argument. See \url{http://xelatex.blogspot.com/2008/03/newcommand-with-optional-argument.html}. I use it constantly.
267 % \begin{macrocode}
268 \global\long\def\tlist@if@empty@nTF #1{%
269 \expandafter\ifx\expandafter\\\detokenize{#1}\\%
270 \expandafter\@firstoftwo%
271 \else%
272 \expandafter\@secondoftwo%
273 \fi%
274 }%
275 % \end{macrocode}
276 %\begin{macro}{\nbrpunct}
277 %Within a linguistic example we do not want \TeX to break the line at explicit hyphens (as these are generally morpheme breaks). We cannot use penalties, as they are only set for the paragraph as a whole, and the linguistic environment will be closed before the end of the paragraph. This solution uses e\TeX{} |scantokens| to make hyphens and equal signs active \emph{only within the linguistic environment} and |let| them to a non-breaking upright counterpart. It is courtesy Alan Munn on Ling-TeX and some comp.text.tex discussion.
278 %
279 %\begin{macro}{\shorteq}
280 %First we use the \textsf{graphicx} package to define an equals sign (for clitics) that is shorter than the default math sign. I find that 1.5 times the length of a hyphen (for affixes) looks good.
281 % \begin{macrocode}
282 \@ifpackageloaded{graphicx}{%
283 \newcommand{\shorteq}{%
284 \settowidth{\@tempdima}{-}% Width of hyphen
285 \resizebox{1.5\@tempdima}{\height}{=}%
286 }%
287 }{}%
288 % \end{macrocode}
289 %\end{macro}
290 %\begin{macro}{\nbrhyph,\nbreq}
291 % Then we define non-breaking punctuation.
292 % \begin{macrocode}
293 \def\nbrhyph{\textup{\hbox{-}}}%
294 \ifx\shorteq\relax
295 \def\nbreq{\textup{\hbox{=}}}%
296 \else
297 \def\nbreq{\textup{\hbox{\shorteq}}}%
298 \fi
299 % \end{macrocode}
300 %\end{macro}
301 %We define the macro |nbrpunct| which takes the linguistic example as its argument. This macro opens a group, makes punctuation marks active, and uses |scantokens| to |let| them to their nonbreaking counterparts, defined above. Then it closes the group.
302 % \begin{macrocode}
303 \def\nbrpunct#1{%
304 \bgroup
305 \catcode`\-=\active
306 \catcode`\==\active
307 % \hyphenchar\font=-1\relax % uncomment to disable automatic hyphenation
308 \scantokens{\let-\nbrhyph
309 \let=\nbreq#1\ignorespaces}
310 \egroup
311 }%
312 % \end{macrocode}
313 %\end{macro}
314 %\begin{macro}{\gl} The macro |\gl| is simply for glosses. It can be used on its own or in combination with an example, where it is hard-coded in.
315 % \begin{macrocode}
316 \providecommand*{\gl}[1]{`#1'}%
317 % \end{macrocode}
318 %\end{macro}
319 %\begin{macro}{\lingexample} The macro |\lingexample| takes two arguments (a user-defined name and template). First it calls |\@@lingsub|, which defines a macro based on the user-defined name called |\@@lingsub@|\meta{name}. This macro takes one argument and sandwiches it between the beginning part of the template and the last part of the template. This trick is from John Frampton's \textsf{expex} package.
320 %
321 %Second, it creates a new macro |\|\meta{name} that the author can use in the text either alone or with two optional arguments. We pass the \meta{name} along as the first parameter so that we can use it later.
322 % \begin{macrocode}
323 \def\lingexample#1#2{% #1 = name, #2 = template
324 \@lingsub(#1)#2\@nil % \@nil as delimiter
325 \expandafter\gdef\csname #1\endcsname{% \def\name
326 \@ifnextchar[{\@lingexample(#1)}{\@lingexample(#1)[]}%
327 }%
328 }%
329
330 \def\@lingsub(#1)#2X#3\@nil{%
331 \expandafter\gdef\csname @@lingsub@#1\endcsname##1{\nbrpunct{#2##1#3}}%
332 }%
333 % \end{macrocode}
334 %We use some trickery from the |natbib| package to switch around the optional arguments in the case that there is only one.
335 % \begin{macrocode}
336 \def\@lingexample(#1)[#2]{\@ifnextchar[%
337 {\@@lingexample(#1)[#2]}{\@@lingexample(#1)[][#2]}%
338 }%
339 % \end{macrocode}
340 %Finally, we check for math mode and use |\tlist@if@empty@nTF| to print the optional prefix \emph{only} in the case that it is non-empty, then the mandatory argument, using |\@@lingsub@|\meta{name} defined above to follow the desired template, and final the optional gloss \emph{only} in the case that it is non-empty. The macros |\lingprestyle| and |\lingpoststyle| are defined below.
341 % \begin{macrocode}
342 \def\@@lingexample(#1)[#2][#3]#4{%
343 \ifmmode
344 $\tlist@if@empty@nTF{#2}{}{#2~}%
345 {\csname @@lingsub@#1\endcsname{#4}}%
346 \tlist@if@empty@nTF{#3}{}{ \gl{#3}}$%
347 \else
348 \tlist@if@empty@nTF{#2}{}{\lingprestyle{{#2}}}%
349 {\csname @@lingsub@#1\endcsname{#4}}%
350 \tlist@if@empty@nTF{#3}{}{\lingpoststyle{{#3}}}%
351 \fi
352 }%
353 % \end{macrocode}
354 %\end{macro}
355 %\begin{macro}{\lingprestyle}
356 %\begin{macro}{\lingpoststyle}
357 % The optional prefix and optional postfix are printed with |\lingprestyle| and |\lingpoststyle| respectively.
358 % \begin{macrocode}
359 \providecommand{\lingprestyle}[1]{#1~}
360 \providecommand{\lingpoststyle}[1]{ \gl{#1}}
361 % \end{macrocode}
362 %\end{macro}
363 %\end{macro}
364 %\begin{macro}{\xo,\xt,\xm}
365 %\begin{macro}{\xv,\xh} The \textglos{} package pre-defines some in-text examples that will be useful to linguists.
366 % \begin{macrocode}
367 \lingexample{xo}{\ensuremath{<}X\ensuremath{>}}
368 \lingexample{xt}{[X]} % use \lingexample{xt}{\tipaencoding[X]}
369 % if you want IPA
370 \lingexample{xm}{/X/}
371 \lingexample{xv}{\itshape X}
372 \lingexample{xh}{*X} % use \lingexample{xh}{*\textit\bgroup X\egroup}
373 % if you want italicized
374 % \end{macrocode}
375 %\end{macro}
376 %\end{macro}
377 % \iffalse
378 % \begin{macrocode}
379 %</package>
380 % \end{macrocode}
381 % \fi
382 % \Finale
383 \endinput