path: root/Master/texmf-dist/source/latex/textglos/textglos.dtx

% \iffalse meta-comment
% !TEX program = pdfLaTeX
%
%<*internal>
\iffalse
%</internal>
%<*readme>

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.

%</readme>
%<*internal>
\fi
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
%</internal>
% Copyright 2013 by Natalie Weber
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%
%   http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
%<*internal>
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</internal>
%<*driver>
\ProvidesFile{textglos.dtx}%
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1996/10/24]%
%<package>\ProvidesPackage{textglos}%
%<*package>
    [2012/06/27 v1.0 textglos package for inline linguistic glossing]%
%\AtBeginDocument{%
%  \MakeShortVerb{\|}
%  \DeleteShortVerb{"}}
%</package>
%
%<*driver>
%    \begin{macrocode}
\documentclass[11pt]{ltxdoc}%
\usepackage{geometry}%
\usepackage[utf8x]{inputenc}%
\usepackage[T1]{fontenc}%
\usepackage{tipa}%
\usepackage{expex}% to typeset examples
\usepackage[longnamesfirst]{natbib}
\setcitestyle{authoryear,round,semicolon,aysep={},yysep={,},notesep={:}}%
\bibliographystyle{linquiry2}%
\usepackage{verbatim}%
\usepackage{url}%
\usepackage{textglos}%
\usepackage{sectsty}
\allsectionsfont{\sffamily\mdseries\upshape} % (See the fntguide.pdf for font help)
%\usepackage[nottoc,notlof,notlot]{tocbibind} % Put the bibliography in the ToC
%\usepackage[titles,subfigure]{tocloft} % Alter the style of the Table of Contents
%\renewcommand{\cftsecfont}{\rmfamily\mdseries\upshape}
%\renewcommand{\cftsecpagefont}{\rmfamily\mdseries\upshape} % No bold!
\usepackage{hyperref}%
\usepackage{xcolor}%
\definecolor{dark-red}{rgb}{0.4,0.15,0.15}
\definecolor{dark-blue}{rgb}{0.15,0.15,0.4}
\definecolor{medium-blue}{rgb}{0,0,0.5}
\hypersetup{%
    colorlinks, linkcolor={dark-red},
    citecolor={dark-blue}, urlcolor={medium-blue} }
\def\textglos{\textsf{textglos}}
\newcommand{\refp}[1]{(\protect\ref{#1})}%
%\EnableCrossrefs
\DisableCrossrefs
%\OnlyDescription
\CodelineIndex
%\PageIndex
\RecordChanges
\begin{document}%
  \DocInput{textglos.dtx}%
\end{document}%
%    \end{macrocode}
%</driver>
%
% \fi
%
%\CheckSum{129}
%
% \CharacterTable
% {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
%  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
%  Digits        \0\1\2\3\4\5\6\7\8\9
%  Exclamation   \!     Double quote  \"     Hash (number) \#
%  Dollar        \$     Percent       \%     Ampersand     \&
%  Acute accent  \'     Left paren    \(     Right paren   \)
%  Asterisk      \*     Plus          \+     Comma         \,
%  Minus         \-     Point         \.     Solidus       \/
%  Colon         \:     Semicolon     \;     Less than     \<
%  Equals        \=     Greater than  \>     Question mark \?
%  Commercial at \@     Left bracket  \[     Backslash     \\
%  Right bracket \]     Circumflex    \^     Underscore    \_
%  Grave accent  \`     Left brace    \{     Vertical bar  \|
%  Right brace   \}     Tilde         \~}
%
% \DoNotIndex{\@@getoptionalarg,\@@next,\@bracketcheck,\@currsize,\@firstoftwo}
% \DoNotIndex{\@secondoftwo,\@futurenonspacelet,\@getoptionalarg,\@optionaltemp}
% \DoNotIndex{\@gsingle,\@ifnextchar,\@ifpackageloaded,\@ifundefined,\@ne,\z@}
% \DoNotIndex{\@nexttoken,\@normalsize,\@optionalarg,\@optionalnext,\@gobble,\p@}
% \DoNotIndex{\@selfnt,\@stepone,\@steptwo,\@stepthree,\@stoken,\@undefined,\\}
% \DoNotIndex{\active,\addvspace,\advance,\afterassignment,\baselineskip}
% \DoNotIndex{\baselinestretch,\begingroup\bgroup,\box,\catcode,\copy,\csname}
% \DoNotIndex{\CurrentOption,\DeclareOption,\def,\detokenize,\egroup,\else,\empty}
% \DoNotIndex{\endcsname\endgraf\endgroup,PackageOptions,\eplain,\expandafter}
% \DoNotIndex{\expandonce,\fi,\fill,\finalhyphendemerits,\futurelet,\gdef,\global}
% \DoNotIndex{\gobble,\gobblespaces,\hbox,\hskip,\hspace,\ht,\hyphenpenalty}
% \DoNotIndex{\identity,\ifdim,\ifmmode,\ifnum,\ifx,\ifvoid,\ignorespacesafterend}
% \DoNotIndex{\ignorespaces,\itemindent,\itshape,\labelsep,\labelwidth,\lastbox}
% \DoNotIndex{\leavevmode,\leftskip,\let,\lineskip,\llap,\long,\MessageBreak}
% \DoNotIndex{\more,\name,\NAMEskip,\NAMEstyle,\newbox,\newcount,\newenvironment}
% \DoNotIndex{\newif,\newskip,\nobreak,\noexpand,\nolinebreak,\normalsize,\rm}
% \DoNotIndex{\PackageError,\PackageWarning,\par,\parfillskip,\parindent,\rlap}
% \DoNotIndex{\ProcessOptions,\providecommand,\quad,\raggedright,\relax,\rmfamily}
% \DoNotIndex{\rightskip,\scantokens,\scshape,\selectfont,\setbox,\sim,\space}
% \DoNotIndex{\strut,\textup,\the,\tlist@if@empty@nTF,\tolerance,\unhbox,\unskip}
% \DoNotIndex{\unvbox,\upshape,\vbox,\vskip,\vtop,\wd,\z@,\z@skip,\endgraf} 
% \DoNotIndex{} 
% \DoNotIndex{} 
% \DoNotIndex{} 
%
%
% \GetFileInfo{textglos.sty}
%
%\title{\textsf{textglos} package documentation\thanks{This document corresponds to \textsf{textglos}~\fileversion, dated~\filedate.}}
% \author{Natalie Weber\\\texttt{natalie.a.weber@gmail.com}}
% \date{\filedate}
%
% \maketitle
% 
%\changes{v1.0}{2012/06/27}{First documented version.}
%
% \begin{abstract}
% \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.
% \end{abstract}
%
%
% \section{Introduction}\label{sec:intro}
% 
%\DescribeMacro{\gl}
%\DescribeMacro{\xo}
%\DescribeMacro{\xt}
%\DescribeMacro{\xm}
%\DescribeMacro{\xv}
%\DescribeMacro{\xh}
%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:
%
%\ex\label{examples}\begin{tabular}[t]{ll}
% \textbf{This code} & \textbf{Prints}\\
% \verb+\gl{gloss}+        &                 `gloss'\\
% \verb+\xo{orthography}+  &                  $<$orthography$>$\\
% \verb+\xt{phonetic}+     &                  $[$phonetic$]$\\
% \verb+\xm{phonemic}+     &                  /phonemic/\\
% \verb+\xv{vernacular}+   &     \textit{vernacular}\\
% \verb+\xh{reconstruction}+ &   *reconstruction\\
%\end{tabular}\xe
%
%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.
%
%\section{Basic usage}
%
%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.
%
%\ex\begin{tabular}[t]{ll}
% \textbf{This code} & \textbf{Prints}\\
% |\xv[Lang][gloss]{word}| & \xv[Lang][gloss]{word}\\
%|\xh[Lang][]{word}| & \xh[Lang][]{word}\\
%|\xo[gloss]{word}| & \xo[gloss]{word}\\
%\end{tabular}\xe
%
%\section{Typesetting features}
%
%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. 
%
% 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.
%
%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:
%
%\ex\label{bigex}\begin{tabular}[t]{lll}
% with \textbf{\texttt{\textbackslash textit}}: & & with \textbf{\texttt{\textbackslash xv}}:\\[.5\lineskip]
% \Huge \textit{hyphen-ated} & vs.\  & \Huge \xv{hyphen-ated}\\
% \Huge \textit{hyphen=ated} & vs.\  & \Huge \xv{hyphen=ated}\\
%\end{tabular}\xe
%
% 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.
%
%\section{Customization}\label{custom}%
%
%\DescribeMacro{\lingprestyle}
%\DescribeMacro{\lingpoststyle}
%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:
%
%\ex|\providecommand{\lingprestyle}[1]{#1~}|\newline
%   |\providecommand{\lingpoststyle}[1]{ \gl{#1}}|\xe
%
%To change them, simply use |\renewcommand{\lingprestyle}[1]|\marg{\ldots|\#1|\ldots} in your preamble, and similarly for |\lingpoststyle|.
%
%\DescribeMacro{\lingexample}
%You can define (or redefine) in-text example macros with this command:
%
%\ex |\lingexample|\marg{name}\marg{template}%
%\xe
%
% 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}).
%
%\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}
%
%
%\ex~\label{code}\begin{tabular}[t]{l}
% |\lingexample{xo}{\ensuremath{<}X\ensuremath{>}}|\\
% |\lingexample{xt}{[X]}|\\
% |\lingexample{xm}{/X/}|\\
% |\lingexample{xv}{\itshape X}|\\
% |\lingexample{xh}{*X}|\\
%\end{tabular}\xe
%
%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:
%
%\ex|\lingexample{xh}{*\bgroup\itshape X\egroup}|\newline
% \hbox{}\hspace{1em}or\newline
% |\lingexample{xh}{*\textit\bgroup X\egroup}|\xe
%
%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:
%
%\ex|\lingexample{xt}{\tipaencoding[X]}|\newline
%   |\lingexample{xm}{\tipaencoding/X/}|\xe
%
%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.
%
%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:
%
%\ex \verb+\lingexample{xvword}{\hbox\bgroup\itshape X\egroup}+\xe
%
%\iffalse
%\section{Changes}
%
% \StopEventually{\PrintChanges}
%\fi
%
%\section{The Code}
%
% \iffalse
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
% \fi
%The package \textsf{graphicx} is required to create |\shorteq|.
%    \begin{macrocode}
\IfFileExists{graphicx}{\RequirePackage{graphicx}}{}%
%    \end{macrocode}
% 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. 
%    \begin{macrocode}
\global\long\def\tlist@if@empty@nTF #1{%
\expandafter\ifx\expandafter\\\detokenize{#1}\\%
\expandafter\@firstoftwo%
\else%
\expandafter\@secondoftwo%
\fi%
}%
%    \end{macrocode}
%\begin{macro}{\nbrpunct}
%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.
%
%\begin{macro}{\shorteq}
%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.
%    \begin{macrocode}
\@ifpackageloaded{graphicx}{%
  \newcommand{\shorteq}{%
    \settowidth{\@tempdima}{-}% Width of hyphen
    \resizebox{1.5\@tempdima}{\height}{=}%
  }%
}{}%
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\nbrhyph,\nbreq}
% Then we define non-breaking punctuation.
%    \begin{macrocode}
 \def\nbrhyph{\textup{\hbox{-}}}%
 \ifx\shorteq\relax
   \def\nbreq{\textup{\hbox{=}}}%
 \else
   \def\nbreq{\textup{\hbox{\shorteq}}}%
 \fi
%    \end{macrocode}
%\end{macro}
%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.
%    \begin{macrocode}
 \def\nbrpunct#1{%
   \bgroup
     \catcode`\-=\active
     \catcode`\==\active
%     \hyphenchar\font=-1\relax % uncomment to disable automatic hyphenation
     \scantokens{\let-\nbrhyph
         \let=\nbreq#1\ignorespaces}
   \egroup
 }%
%    \end{macrocode}
%\end{macro}
%\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.
%    \begin{macrocode}
\providecommand*{\gl}[1]{`#1'}%
%    \end{macrocode}
%\end{macro}
%\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. 
%
%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. 
%   \begin{macrocode}
\def\lingexample#1#2{% #1 = name, #2 = template
  \@lingsub(#1)#2\@nil % \@nil as delimiter 
  \expandafter\gdef\csname #1\endcsname{% \def\name
    \@ifnextchar[{\@lingexample(#1)}{\@lingexample(#1)[]}%
  }%
}%

\def\@lingsub(#1)#2X#3\@nil{%
  \expandafter\gdef\csname @@lingsub@#1\endcsname##1{\nbrpunct{#2##1#3}}%
}% 
%    \end{macrocode}
%We use some trickery from the |natbib| package to switch around the optional arguments in the case that there is only one.
%    \begin{macrocode}
\def\@lingexample(#1)[#2]{\@ifnextchar[% 
  {\@@lingexample(#1)[#2]}{\@@lingexample(#1)[][#2]}%
}%
%    \end{macrocode}
%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.
%    \begin{macrocode}
\def\@@lingexample(#1)[#2][#3]#4{% 
  \ifmmode
    $\tlist@if@empty@nTF{#2}{}{#2~}%
    {\csname @@lingsub@#1\endcsname{#4}}%
    \tlist@if@empty@nTF{#3}{}{ \gl{#3}}$%
  \else
    \tlist@if@empty@nTF{#2}{}{\lingprestyle{{#2}}}%
    {\csname @@lingsub@#1\endcsname{#4}}%
    \tlist@if@empty@nTF{#3}{}{\lingpoststyle{{#3}}}%
  \fi
}%
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\lingprestyle}
%\begin{macro}{\lingpoststyle}
% The optional prefix and optional postfix are printed with |\lingprestyle| and |\lingpoststyle| respectively.
%    \begin{macrocode}
\providecommand{\lingprestyle}[1]{#1~}
\providecommand{\lingpoststyle}[1]{ \gl{#1}}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\begin{macro}{\xo,\xt,\xm}
%\begin{macro}{\xv,\xh} The \textglos{} package pre-defines some in-text examples that will be useful to linguists.
%    \begin{macrocode}
\lingexample{xo}{\ensuremath{<}X\ensuremath{>}}
\lingexample{xt}{[X]} % use \lingexample{xt}{\tipaencoding[X]}
                      % if you want IPA
\lingexample{xm}{/X/}
\lingexample{xv}{\itshape X}
\lingexample{xh}{*X} % use \lingexample{xh}{*\textit\bgroup X\egroup}
                     % if you want italicized
%    \end{macrocode}
%\end{macro}
%\end{macro}
% \iffalse
%    \begin{macrocode}
%</package>
%    \end{macrocode}
% \fi
% \Finale
\endinput