diff options
Diffstat (limited to 'macros/latex/contrib/covington')
| -rw-r--r-- | macros/latex/contrib/covington/README | 16 | ||||
| -rw-r--r-- | macros/latex/contrib/covington/covington.pdf | bin | 520384 -> 533391 bytes | |||
| -rw-r--r-- | macros/latex/contrib/covington/covington.sty | 723 | ||||
| -rw-r--r-- | macros/latex/contrib/covington/covington.tex | 770 |
4 files changed, 971 insertions, 538 deletions
diff --git a/macros/latex/contrib/covington/README b/macros/latex/contrib/covington/README index 4d1636aa59..4587e8f7b4 100644 --- a/macros/latex/contrib/covington/README +++ b/macros/latex/contrib/covington/README @@ -31,6 +31,22 @@ The package consists of the following files: == CHANGES == +* Version 2.10 (2023-06-02) + - Use LaTeX's own keyval mechanism rather than xkeyval. + - Introduce a better interface to customize the appearance of examples. Now everything can + be easily adjusted globally and locally via key-val options. This entails the following changes: + * Allow to globally set example options via the new macro \setexampleoptions. + * Add way to customize example and subexample number format. + * Add new example options: fs, fsno, fspreamble, fspostamble, leftmargin, addnumbersep, + addsubnumbersep, numberformat, subnumberformat, and fnnumberformat. + - Add new gloss options: fspreamble, fspostamble, fstl, and enquotetl. + This allows for full customization of glosses via options, both locally and globally. + - Package options now all have a key-value format as well. + - Introduce new package choice-option fnexamplecounter that supersedes the two boolean, + mutually exclusive options ownfncounter and ownfncounter* (which are still supported + for backwards compatibility reasons). + - Major documentation revisions. + * Version 2.9 (2023-05-26): - Add postamble and postamble* options to example and subexamples environment. - Add \expreamble, \subexpreamble, \expostamble and \subexpostamble macros. diff --git a/macros/latex/contrib/covington/covington.pdf b/macros/latex/contrib/covington/covington.pdf Binary files differindex a802c03ff1..d76ea95e7d 100644 --- a/macros/latex/contrib/covington/covington.pdf +++ b/macros/latex/contrib/covington/covington.pdf diff --git a/macros/latex/contrib/covington/covington.sty b/macros/latex/contrib/covington/covington.sty index 5218249db1..06792446c4 100644 --- a/macros/latex/contrib/covington/covington.sty +++ b/macros/latex/contrib/covington/covington.sty @@ -42,10 +42,15 @@ %%% Metadata %%% -\def\filedate{2023/05/26} -\def\fileversion{2.9} +\def\filedate{2023/06/02} +\def\fileversion{2.10} \def\filename{covington.sty} +% Macro to issue warnings +\newcommand\cov@warning[1]{% + \PackageWarning{covington}{#1}% +} + % Force redefinition of environments? \newif\ifforceredef\forceredeffalse % Tweak text layout? @@ -59,43 +64,61 @@ % Reset separate counter in footnote \newif\ifresetownfnexcounter\resetownfnexcounterfalse -\@ifundefined{ProvidesPackage}{% -\typeout{* covington.sty -- Macros for Linguistics, \fileversion\ \filedate *} -}{% \ProvidesPackage{covington} [\filedate\space v\fileversion\space Macros for Linguistics] -\DeclareOption{force}{\forceredeftrue} -\DeclareOption{keeplayout}{\tweaklayoutfalse} -\DeclareOption{noglossbreaks}{\noglossbreakstrue} -\DeclareOption{owncounter}{\ownexcountertrue} -\DeclareOption{ownfncounter}{\ownfnexcountertrue} -\DeclareOption{ownfncounter*}{\ownfnexcountertrue\resetownfnexcountertrue} -\ProcessOptions + +\DeclareKeys[covington] +{ + % 1. force=<true|false> + force.if = forceredef, + % 2. keeplayout=<true|false> + keeplayout.ifnot = tweaklayout, + % 3. noglossbreaks=<true|false> + noglossbreaks.if = noglossbreaks, + % 4. owncounter=<true|false> + owncounter.if = ownexcounter, + % 5. fnexamplecounter=<main|own|own-reset> + fnexamplecounter.choice:, + % a. main + fnexamplecounter / main.code:n = { \ownfnexcounterfalse\resetownfnexcounterfalse }, + % b. own + fnexamplecounter / own.code:n = { \ownfnexcountertrue\resetownfnexcounterfalse }, + % c. own-reset + fnexamplecounter / own-reset.code:n = { \ownfnexcountertrue\resetownfnexcountertrue }, + fnexamplecounter.default:n = { main }, + % DEPRECATED OPTONS + % force=<true|false> + ownfncounter.code:n = + { \ownfnexcountertrue + \resetownfnexcounterfalse + \cov@warning{Option 'ownfncounter' is deprecated!\MessageBreak + Please use fnexamplecounter=own instead.} + }, + % force=<true|false> + ownfncounter*.code = + { \ownfnexcountertrue + \resetownfnexcountertrue + \cov@warning{Option 'ownfncounter*' is deprecated!\MessageBreak + Please use fnexamplecounter=own-reset instead.} + } } +% Process package options +\ProcessKeyOptions[covington] + % % Required packages % -\RequirePackage{xkeyval} \RequirePackage{iftex} -% Macro to issue warnings -\newcommand\cov@warning[1]{% - \@ifundefined{PackageWarning}{% - \typeout{* covington warning : #1 *} - }{% - \PackageWarning{covington}{#1}% - } -} - %%% %%% Preferences about how text is laid out %%% % New 2018-08-24: Option to opt-out these layout tweaks \iftweaklayout -\setlength{\textfloatsep}{0.7in} -\raggedbottom + \setlength{\textfloatsep}{0.7in} + \raggedbottom \fi %%% @@ -172,6 +195,8 @@ \newcommand*\@@exampleno{\ifownexcounter\thecovex\else\theequation\fi} \newcommand*\exampleno{\@ifstar{\@@exampleno}{\@exampleno}} +\let\fnexfmt\roman + \newif\ifcov@infootnote\cov@infootnotefalse \ifownfnexcounter % Check whether we are in a footnote @@ -182,7 +207,7 @@ \else \newcounter{covfnex} \fi - \renewcommand{\thecovfnex}{\roman{covfnex}} + \renewcommand{\thecovfnex}{\fnexfmt{covfnex}} \fi %%% @@ -190,8 +215,8 @@ %%% % Font setting possibility for example sentences -\newcommand*\covexamplefs{} -\newcommand*\covexamplenofs{\normalfont} +\newcommand*\covexamplefs{\normalfont\upshape} +\newcommand*\covexamplenofs{\normalfont\upshape} % example is an environment for displaying a single numbered % example, preceded by its number. Example of use: @@ -219,20 +244,106 @@ % with packages/classes that roll their own example environment % (such as beamer). +% Helper function for numbering templates +\newif\ifcov@have@exno\cov@have@exnofalse + +\def\cov@parse@number@loop#1{% + \ifx\relax#1\else% + \cov@parse@number@loop@body{#1}\expandafter\cov@parse@number@loop% + \fi% +} + +\newcommand\cov@parse@number@loop@body[1]{% + \ifcov@have@exno% + \let\cov@@tmpfmtright\cov@tmpfmtright% + \edef\cov@tmpfmtright{\cov@@tmpfmtright#1}% + \else% + \ifx 1#1% + \cov@have@exnotrue% + \let\cov@tmpfmt\arabic% + \else% + \ifx i#1% + \cov@have@exnotrue% + \let\cov@tmpfmt\roman% + \else% + \ifx I#1% + \cov@have@exnotrue% + \let\cov@tmpfmt\Roman% + \else% + \ifx a#1% + \cov@have@exnotrue% + \let\cov@tmpfmt\alph% + \else% + \ifx A#1% + \cov@have@exnotrue% + \let\cov@tmpfmt\Alph% + \else% + \let\cov@@tmpfmtleft\cov@tmpfmtleft% + \edef\cov@tmpfmtleft{\cov@@tmpfmtleft#1}% + \fi% + \fi% + \fi% + \fi% + \fi% + \fi% +}% + +\newcommand\cov@parse@number@template[3]{% + \cov@have@exnofalse% + \let\cov@tmpfmt\roman% + \def\cov@tmpfmtleft{}% + \def\cov@tmpfmtright{}% + \cov@parse@number@loop#1\relax% + \expandafter\let\csname#2\endcsname\cov@tmpfmt% + \expandafter\let\csname cov@tmpfmtleft#3\endcsname\cov@tmpfmtleft% + \expandafter\let\csname cov@tmpfmtright#3\endcsname\cov@tmpfmtright% + \ifcov@have@exno% + \expandafter\renewcommand\csname#3\endcsname[1]{% + \csname cov@tmpfmtleft#3\endcsname##1\csname cov@tmpfmtright#3\endcsname}% + \else% + \expandafter\renewcommand\csname#3\endcsname[1]{% + \csname cov@tmpfmtleft#3\endcsname\csname cov@tmpfmtright#3\endcsname}% + \fi% +} + +\newif\if@cov@expst@star\@cov@expst@starfalse + % 2022-08-20 (v. 2.8): optional preceding example text -\define@key{cov@ex}{preamble}{\def\cov@xp{#1}} \newcommand*\expreamblefs{\normalfont} \newcommand\expreamble[1]{\bgroup\expreamblefs#1\egroup\par} -\newif\if@cov@expst@star\@cov@expst@starfalse -\define@key{cov@ex}{postamble}{\def\cov@xpst{#1}\@cov@expst@starfalse} -\define@key{cov@ex}{postamble*}{\def\cov@xpst{#1}\@cov@expst@startrue} % 2023.05.26 (v. 2.9): optional trailung subexample text \newcommand*\expostamblefs{\normalfont} \newcommand*\expostamble[1]{\bgroup\expostamblefs#1\egroup} +\DeclareKeys[covexpl] +{ + % font settings + fs.store = \covexamplefs, + % font settings of the ex. number + fsno.store = \covexamplenofs, + % preamble + preamble.store = \cov@xp, + % postamble + postamble.code = { \def\cov@xpst{#1}\@cov@expst@starfalse }, + % postamble* (no space) + postamble*.code = { \def\cov@xpst{#1}\@cov@expst@startrue }, + % preamble font settings + fspreamble.store = \expreamblefs, + % postamble font settings + fspostamble.store = \expostamblefs, + % leftmargin + leftmargin.code = { \setlength{\exampleind}{#1} }, + % addnumbersep + addnumbersep.code = { \setlength{\examplenumbersep}{#1} }, + % numberformat={template} + numberformat.code = { \cov@parse@number@template{#1}{exfmt}{covexnumber} }, + % fnnumberformat={template} + fnumberformat.code = { \cov@parse@number@template{#1}{fnexfmt}{covexnumberfn} } +} + \newenvironment{covexample}[1][]{% - \ifx#1\empty\else\setkeys{cov@ex}{#1}\fi% + \ifx#1\empty\else\SetKeys[covexpl]{#1}\fi% \begin{covexamples} \item\@ifundefined{cov@xp}{}{\expreamble{\cov@xp}}% insert preamble if given }{% @@ -289,39 +400,43 @@ \newcommand*\covexnumber[1]{(#1)} \newcommand*\covexnumberfn[1]{\covexnumber{#1}} -\newenvironment{covexamples}% % define "example" environment -{% -\begin{list}% -{% - \covexamplenofs% font - \ifcov@infootnote - \covexnumberfn{\thecovfnex}% - \else - \covexnumber{\@@exampleno}% - \fi -}% -{% - \addtolength{\labelwidth}{\examplenumbersep}% - \addtolength{\leftmargin}{\examplenumbersep}% - \addtolength{\leftmargin}{\exampleind}% - \ifcov@infootnote - \setcounter{covexsave}{\arabic{covfnex}}% - \usecounter{covfnex}% - \setcounter{covfnex}{\arabic{covexsave}}% - \else - \ifownexcounter - \setcounter{covexsave}{\arabic{covex}}% - \usecounter{covex}% % sets it to zero, unwantedly - \setcounter{covex}{\arabic{covexsave}}% % restores previous value +\let\exfmt\arabic + +\newenvironment{covexamples}[1][]{% % define "examples" environment + \ifx#1\empty\else\SetKeys[covexpl]{#1}\fi% + \begin{list}% + {% + \covexamplenofs% font + \ifcov@infootnote + \covexnumberfn{\thecovfnex}% \else - \setcounter{covexsave}{\arabic{equation}}% - \usecounter{equation}% % sets it to zero, unwantedly - \setcounter{equation}{\arabic{covexsave}}% % restores previous value + \covexnumber{\@@exampleno}% \fi - \fi - \setlength{\listparindent}{0pt}% - \def\makelabel##1{##1\hfil}% % put labels flushleft in space available -}% + }% + {% + \addtolength{\labelwidth}{\examplenumbersep}% + \addtolength{\leftmargin}{\examplenumbersep}% + \addtolength{\leftmargin}{\exampleind}% + \ifcov@infootnote + \setcounter{covexsave}{\arabic{covfnex}}% + \usecounter{covfnex}% + \setcounter{covfnex}{\arabic{covexsave}}% + \else + \ifownexcounter + \renewcommand{\thecovex}{\exfmt{covex}}% + \setcounter{covexsave}{\arabic{covex}}% + \usecounter{covex}% % sets it to zero, unwantedly + \setcounter{covex}{\arabic{covexsave}}% % restores previous value + \else + \renewcommand{\theequation}{\exfmt{equation}}% + \setcounter{covexsave}{\arabic{equation}}% + \usecounter{equation}% % sets it to zero, unwantedly + \setcounter{equation}{\arabic{covexsave}}% % restores previous value + \fi + \fi + \setlength{\listparindent}{0pt}% + \def\makelabel##1{##1\hfil}% % put labels flushleft in space available + }% \raggedright% text is flushleft, not justified \covexamplefs% }% @@ -356,29 +471,63 @@ % \item This is the second subexample. % \end{subexamples} -\newlength\subexamplenumbersep -\setlength\subexamplenumbersep{0pt} - -\newcommand*\covsubexnumber[1]{(#1)} - % 2019-06-21 (v. 2.3): optional preceding subexample text -\define@key{cov@subex}{preamble}{\def\cov@sxp{#1}} \newcommand*\subexpreamblefs{\normalfont} \newcommand\subexpreamble[1]{\bgroup\subexpreamblefs#1\egroup\par} % 2023.05.26 (v. 2.9): optional trailung subexample text -\define@key{cov@subex}{postamble}{\def\cov@sxpst{#1}} \newcommand*\subexpostamblefs{\normalfont} -\newcommand*\subexpostamble[1]{\bgroup\expostamblefs#1\egroup} +\newcommand*\subexpostamble[1]{\bgroup\subexpostamblefs#1\egroup} + +\DeclareKeys[covsubexpl] +{ + % font settings + fs.store = \covexamplefs, + % font settings + fsno.store = \covexamplenofs, + % preamble text + preamble.store = \cov@sxp, + % postamble text + postamble.store = \cov@sxpst, + % preamble font settings + fspreamble.store = \subexpreamblefs, + % postamble font settings + fspostamble.store = \subexpostamblefs, + % preamble font settings (alias) + fssubpreamble.store = \subexpreamblefs, + % postamble font settings (alias) + fssubpostamble.store = \subexpostamblefs, + % leftmargin + leftmargin.code = { \setlength{\exampleind}{#1} }, + % addnumbersep + addnumbersep.code = { \setlength{\examplenumbersep}{#1} }, + % addnumbersep + addsubnumbersep.code = { \setlength{\subexamplenumbersep}{#1} }, + % numberformat={template} + numberformat.code = { \cov@parse@number@template{#1}{exfmt}{covexnumber} }, + % fnnumberformat={template} + fnumberformat.code = { \cov@parse@number@template{#1}{fnexfmt}{covexnumberfn} }, + % subnumberformat={template} + subnumberformat.code = { \cov@parse@number@template{#1}{subexfmt}{covsubexnumber} } +} + +\newlength\subexamplenumbersep +\setlength\subexamplenumbersep{0pt} + +\newcommand*\covsubexnumber[1]{(#1)} + +\let\subexfmt\alph \newenvironment{covsubexamples}[1][]% % define "subexamples" environment {% - \ifx#1\empty\else\setkeys{cov@subex}{#1}\fi% + \let\cov@xp\relax% + \let\cov@xpst\relax% + \ifx#1\empty\else\SetKeys[covsubexpl]{#1}\fi% \begin{covexample}% - \@ifundefined{cov@sxp}{}{\subexpreamblefs\cov@sxp}% insert preamble if given + \@ifundefined{cov@sxp}{}{\bgroup\subexpreamblefs\cov@sxp\egroup}% insert preamble if given \begin{enumerate} \addtolength{\labelsep}{\subexamplenumbersep}% - \renewcommand\theenumi{\alph{enumi}} + \renewcommand\theenumi{\subexfmt{enumi}} \renewcommand\labelenumi{\covexamplenofs\covsubexnumber{\theenumi}} \renewcommand\p@enumi{\@@exampleno\,}% \setlength{\listparindent}{0pt}% @@ -395,17 +544,58 @@ \@ifundefined{subexamples}{% \newenvironment{subexamples}[1][]{\begin{covsubexamples}[#1]}{\end{covsubexamples}} }{% -\ifforceredef - \renewenvironment{subexamples}[1][]{\begin{covsubexamples}[#1]}{\end{covsubexamples}} - \cov@warning{The subexamples environment was already defined. Redefining it.} -\else - \cov@warning{The subexamples environment was already defined.^^J - Covington does not touch it.^^J - Use covsubexamples if you want to access covington's^^J - version, or use the force package option.} -\fi + \ifforceredef + \renewenvironment{subexamples}[1][]{\begin{covsubexamples}[#1]}{\end{covsubexamples}} + \cov@warning{The subexamples environment was already defined. Redefining it.} + \else + \cov@warning{The subexamples environment was already defined.^^J + Covington does not touch it.^^J + Use covsubexamples if you want to access covington's^^J + version, or use the force package option.} + \fi +} + +\DeclareKeys[gcovexamples] +{ + % font settings + fs.store = \covexamplefs, + % font settings + fsno.store = \covexamplenofs, + % preamble + preamble.store = \cov@xp, + % postamble + postamble.code = { \def\cov@xpst{#1}\@cov@expst@starfalse }, + % postamble* (no space) + postamble*.code = { \def\cov@xpst{#1}\@cov@expst@startrue }, + % preamble text + subpreamble.store = \cov@sxp, + % postamble text + subpostamble.store = \cov@sxpst, + % preamble font settings + fspreamble.store = \expreamblefs, + % postamble font settings + fspostamble.store = \expostamblefs, + % preamble font settings + fssubpreamble.store = \subexpreamblefs, + % postamble font settings + fssubpostamble.store = \subexpostamblefs, + % leftmargin + leftmargin.code = { \setlength{\exampleind}{#1} }, + % addnumbersep + addnumbersep.code = { \setlength{\examplenumbersep}{#1} }, + % addsubnumbersep + addsubnumbersep.code = { \setlength{\subexamplenumbersep}{#1} }, + % numberformat={template} + numberformat.code = { \cov@parse@number@template{#1}{exfmt}{covexnumber} }, + % fnnumberformat={template} + fnumberformat.code = { \cov@parse@number@template{#1}{fnexfmt}{covexnumberfn} }, + % subnumberformat={template} + subnumberformat.code = { \cov@parse@number@template{#1}{subexfmt}{covsubexnumber} } } +% General setting option +\newcommand*\setexampleoptions[1]{\SetKeys[gcovexamples]{#1}} + %%% @@ -468,17 +658,26 @@ % Try to prevent page breaks in glosses if noglossbreaks option is set \def\cov@nopagebreak{} \ifnoglossbreaks -\def\cov@nopagebreak{\let\reserved@e\vadjust\let\reserved@f\nobreak} + \def\cov@nopagebreak{\let\reserved@e\vadjust\let\reserved@f\nobreak} \fi +\def\cov@emphasized{\normalfont\itshape}% +\def\cov@normalfont{\normalfont\upshape}% + +\def\cov@fsglpreamble@global{\cov@normalfont} +\def\cov@fsglpostamble@global{\cov@normalfont} +\def\cov@fstl@global{\cov@normalfont} + % 2019-05-07: optional preceding gloss text (non-interlinearized) -\newcommand*\glosslinepreamble[1]{#1} -\def\cov@glp{} -\newcommand*\glosspreamble[1]{\def\cov@glp{#1}} +\def\fsglpreamble{\cov@fsglpreamble@global} +\newcommand*\glosslinepreamble[1]{\bgroup\fsglpreamble{}#1\egroup} +\def\cov@gl@preamble@text{} +\newcommand*\glosspreamble[1]{\def\cov@gl@preamble@text{#1}} % 2021-09-01: optional trailing gloss text (non-interlinearized) -\newcommand*\glosslinepostamble[1]{#1} -\def\cov@glpst{} +\def\fsglpostamble{\cov@fsglpostamble@global} +\newcommand*\glosslinepostamble[1]{\bgroup\fsglpostamble{}#1\egroup} +\def\cov@gl@postamble@text{} \def\gll{% % Introduces 2-line text-and-gloss. \begin{flushleft} @@ -539,8 +738,8 @@ \def\glend{% \end{flushleft}% - \def\cov@glp{}% - \def\cov@glpst{}% + \def\cov@gl@preamble@text{}% + \def\cov@gl@postamble@text{}% } % Ends the gloss environment. % The following TeX code is adapted, with permission, from: @@ -563,19 +762,14 @@ \glossglue = 5pt plus 2pt minus 1pt % allow stretch/shrink between words \newif\ifnotdone -% Add semantic markup (with latex 2.09 backwards support) -\@ifundefined{selectfont}{% - \def\cov@emphasized{\it}% - \def\cov@normalfont{\rm}% -}{% - \def\cov@emphasized{\normalfont\itshape}% - \def\cov@normalfont{\normalfont\upshape}% -} - % Font settings for gloss lines -\newcommand*\glosslineone{\cov@emphasized} -\newcommand*\glosslinetwo{\cov@normalfont} -\newcommand*\glosslinethree{\cov@normalfont} +\newcommand*\glosslineone@global{\cov@emphasized} +\newcommand*\glosslinetwo@global{\cov@normalfont} +\newcommand*\glosslinethree@global{\cov@normalfont} + +\let\glosslineone\glosslineone@global +\let\glosslinetwo\glosslinetwo@global +\let\glosslinethree\glosslinethree@global \def\eachwordone{\glosslineone} \def\eachwordtwo{\glosslinetwo} @@ -615,7 +809,10 @@ \gdef\twosent#1^^M#2^^M% #1 = first line, #2 = second line {\getwords(\lineone,\eachwordone)#1 ^^M% \getwords(\linetwo,\eachwordtwo)#2 ^^M% - \ifx\cov@glp\empty\else\glosslinepreamble{\cov@glp}\cov@nopagebreak\newline\fi% + \ifx\cov@gl@preamble@text\empty% + \else% + \glosslinepreamble{\cov@gl@preamble@text}\cov@nopagebreak\newline% + \fi% \loop\lastword{\eachwordone}{\lineone}{\wordone}% \lastword{\eachwordtwo}{\linetwo}{\wordtwo}% \global\setbox\gline=\hbox{\unhbox\gline @@ -636,7 +833,10 @@ {\getwords(\lineone,\eachwordone)#1 ^^M% \getwords(\linetwo,\eachwordtwo)#2 ^^M% \getwords(\linethree,\eachwordthree)#3 ^^M% - \ifx\cov@glp\empty\else\glosslinepreamble{\cov@glp}\cov@nopagebreak\newline\fi% + \ifx\cov@gl@preamble@text\empty% + \else% + \glosslinepreamble{\cov@gl@preamble@text}\cov@nopagebreak\newline% + \fi% \loop\lastword{\eachwordone}{\lineone}{\wordone}% \lastword{\eachwordtwo}{\linetwo}{\wordtwo}% \lastword{\eachwordthree}{\linethree}{\wordthree}% @@ -677,7 +877,10 @@ \gdef\xtwosent#1\xgle#2\xgle% #1 = first line, #2 = second line {\xgetwords(\lineone,\eachwordone)#1 \xgle% \xgetwords(\linetwo,\eachwordtwo)#2 \xgle% - \ifx\cov@glp\empty\else\glosslinepreamble{\cov@glp}\cov@nopagebreak\newline\fi% + \ifx\cov@gl@preamble@text\empty% + \else% + \glosslinepreamble{\cov@gl@preamble@text}\cov@nopagebreak\newline% + \fi% \loop\lastword{\eachwordone}{\lineone}{\wordone}% \lastword{\eachwordtwo}{\linetwo}{\wordtwo}% \global\setbox\gline=\hbox{\unhbox\gline% @@ -698,7 +901,10 @@ {\xgetwords(\lineone,\eachwordone)#1 \xgle% \xgetwords(\linetwo,\eachwordtwo)#2 \xgle% \xgetwords(\linethree,\eachwordthree)#3 \xgle% - \ifx\cov@glp\empty\else\glosslinepreamble{\cov@glp}\cov@nopagebreak\newline\fi% + \ifx\cov@gl@preamble@text\empty% + \else% + \glosslinepreamble{\cov@gl@preamble@text}\cov@nopagebreak\newline% + \fi% \loop\lastword{\eachwordone}{\lineone}{\wordone}% \lastword{\eachwordtwo}{\linetwo}{\wordtwo}% \lastword{\eachwordthree}{\linethree}{\wordthree}% @@ -718,8 +924,10 @@ \egroup % matches \bgroup in \gloss } -% V. 2.0: enquotable translation line -\newcommand*\glosslinetrans[1]{\covenquote{#1}} +% V. 2.0: enquotable translation line +\newif\ifcov@enquote@tl\cov@enquote@tltrue +\def\cov@fstl{\cov@fstl@global} +\newcommand*\glosslinetrans[1]{\bgroup\cov@fstl\ifcov@enquote@tl\covenquote{#1}\else#1\fi\egroup} \newcommand*\glot[1]{% \def\tempx{#1}% \ifx\tempx\empty\gln @@ -730,151 +938,202 @@ % % Key-val options for the macros % -% 1. ex=<true|false> -\newif\ifgexample\gexamplefalse -\newif\ifggexample\ggexamplefalse -\define@boolkey+{covington}{ex}[true]{% - \ifKV@covington@ex - \gexampletrue - \else - \gexamplefalse - \fi -}{% - \cov@warning{unknown env value '#1' in gloss macro}% -} -\define@boolkey+{gcovington}{ex}[true]{% - \ifKV@gcovington@ex - \ggexampletrue - \else - \ggexamplefalse - \fi -}{% - \cov@warning{unknown env value '#1' in setglossoptions}% -} -\newif\ifgtright\gtrightfalse -\newif\ifggtright\ggtrightfalse -% -% 2. tlb=<true|false> -\define@boolkey+{covington}{tlr}[true]{% - \ifKV@covington@tlr - \gtrighttrue - \else - \gtrightfalse - \fi -}{% - \cov@warning{unknown tlr value '#1' in gloss macro}% +\newif\ifcov@ex@gloss\cov@ex@glossfalse +\newif\ifcov@ex@gloss@global\cov@ex@gloss@globalfalse +\newif\ifcov@tlr\cov@tlrfalse +\newif\ifcov@tlr@global\cov@tlr@globalfalse +\newif\ifcov@enquote@tl@global\cov@enquote@tl@globaltrue +\def\cov@gl@preamble@global{} +\def\cov@gl@postamble@global{} + +\DeclareKeys[covgloss] +{ + % 1. ex=<true|false> + ex.if = cov@ex@gloss, + % 2. tlr=<true|false> + tlr.if = cov@tlr, + % 3. font settings for gloss line i, ii, iii + fsi.store = \lglosslineone, + fsii.store = \lglosslinetwo, + fsiii.store = \lglosslinethree, + % 4. Gloss preamble text + preamble.code = { \edef\cov@gl@preamble{#1} }, + % 5. Gloss postamble text + postamble.store = \cov@gl@postamble, + % 6. Gloss preamble font settings + fspreamble.store = \cov@fsglpreamble@local, + % 7. Gloss postamble font settings + fspostamble.store = \cov@fsglpostamble@local, + % 8. Enquote translation line + enquotetl.if = cov@enquote@tl, + % 9. translation line font settings + fstl.store = \cov@fstl@local } -\define@boolkey+{gcovington}{tlr}[true]{% - \ifKV@gcovington@tlr - \ggtrighttrue - \else - \ggtrightfalse - \fi -}{% - \cov@warning{unknown tlr value '#1' in setglossoptions}% + +\DeclareKeys[gcovgloss] +{ + % 1. ex=<true|false> + ex.if = cov@ex@gloss@global, + % 2. tlr=<true|false> + tlr.if = cov@tlr@global, + % 3. font settings for gloss line i, ii, iii + fsi.code = { \global\def\glosslineone@global{#1} }, + fsii.code = { \global\def\glosslinetwo@global{#1} }, + fsiii.code = { \global\def\glosslinethree@global{#1} }, + % 4. Gloss preamble text + preamble.code = { \global\def\cov@gl@preamble@global{#1} }, + % 5. Gloss postamble text + postamble.code = { \global\def\cov@gl@postamble@global{#1} }, + % 6. Gloss preamble font settings + fspreamble.code = { \global\def\cov@fsglpreamble@global{#1} }, + % 7. Gloss postamble font settings + fspostamble.code = { \global\def\cov@fsglpostamble@global{#1} }, + % 8. Enquote translation line + enquotetl.if = cov@enquote@tl@global, + % 9. translation line font settings + fstl.code = { \global\def\cov@fstl@global{#1} } } -% -% 3. font settings for gloss line i, ii, iii -\define@key{covington}{fsi}{\def\lglosslineone{#1}} -\define@key{covington}{fsii}{\def\lglosslinetwo{#1}} -\define@key{covington}{fsiii}{\def\lglosslinethree{#1}} -\define@key{gcovington}{fsi}{\def\glosslineone{#1}} -\define@key{gcovington}{fsii}{\def\glosslinetwo{#1}} -\define@key{gcovington}{fsiii}{\def\glosslinethree{#1}} -% -% 4. Gloss preamble text -\def\cov@gglp{} -\define@key{covington}{preamble}{\def\cov@lglp{#1}} -\define@key{gcovington}{preamble}{\def\cov@gglp{#1}} -% -% 5. Gloss postamble text -\def\cov@gglpst{} -\define@key{covington}{postamble}{\def\cov@lglpst{#1}} -\define@key{gcovington}{postamble}{\def\cov@gglpst{#1}} + + +\let\cov@fsglpreamble@local\relax% +\let\cov@fsglpostamble@local\relax% +\let\cov@fstl@local\relax% + % % General setting option -\newcommand*\setglossoptions[1]{\setkeys{gcovington}{#1}} +\newcommand*\setglossoptions[1]{\SetKeys[gcovgloss]{#1}} % % 1. \digloss[<opts>]{<line 1>}{<line 2>}{<translation>} \newcommand*\digloss[4][\empty]{% - \ifggexample - \setkeys{covington}{ex=true} + \let\lglosslineone\relax% + \let\lglosslinetwo\relax% + \let\lglosslinethree\relax% + \let\glosslineone\glosslineone@global% + \let\glosslinetwo\glosslinetwo@global% + \let\glosslinethree\glosslinethree@global% + \ifcov@ex@gloss@global + \SetKeys[covgloss]{ex=true} + \else + \SetKeys[covgloss]{ex=false} + \fi% + \ifcov@tlr@global + \SetKeys[covgloss]{tlr=true} \else - \setkeys{covington}{ex=false} + \SetKeys[covgloss]{tlr=false} \fi% - \ifggtright - \setkeys{covington}{tlr=true} + \ifcov@enquote@tl@global + \SetKeys[covgloss]{enquotetl=true} \else - \setkeys{covington}{tlr=false} + \SetKeys[covgloss]{enquotetl=false} \fi% - \ifx#1\empty\else\setkeys{covington}{#1}\fi% - \ifgexample - \begin{covexample} + \def\cov@gl@preamble{\cov@gl@preamble@global}% + \def\cov@gl@postamble{\cov@gl@postamble@global}% + \ifx#1\empty\else\SetKeys[covgloss]{#1}\fi% + \ifcov@ex@gloss + \begin{covexample} \fi% \@ifundefined{lglosslineone}{}{\def\glosslineone{\lglosslineone}}% \@ifundefined{lglosslinetwo}{}{\def\glosslinetwo{\lglosslinetwo}}% \@ifundefined{lglosslinethree}{}{\def\glosslinethree{\lglosslinethree}}% - \@ifundefined{cov@lglp}{}{\def\cov@gglp{\cov@lglp}}% - \ifx\cov@gglp\empty\else\def\cov@glp{\cov@gglp}\fi% - \@ifundefined{cov@lglpst}{}{\def\cov@gglpst{\cov@lglpst}}% - \ifx\cov@gglpst\empty\else\def\cov@glpst{\cov@gglpst}\fi% + \edef\cov@gl@preamble@text{\cov@gl@preamble}% + \def\cov@gl@postamble@text{\cov@gl@postamble}% + \@ifundefined{cov@fsglpreamble@local}% + {\let\fsglpreamble\cov@fsglpreamble@global}% + {\let\fsglpreamble\cov@fsglpreamble@local}% + \@ifundefined{cov@fsglpostamble@local}% + {\let\fsglpostamble\cov@fsglpostamble@global}% + {\let\fsglpostamble\cov@fsglpostamble@local}% + \@ifundefined{cov@fstl@local}% + {\let\cov@fstl\cov@fstl@global}% + {\let\cov@fstl\cov@fstl@local}% \xgll #2\xgle #3\xgle - \ifgtright + \ifcov@tlr \gln #4% \else \glot{#4}% \fi - \ifx\cov@glpst\empty\else\glosslinepostamble{\cov@glpst}\cov@nopagebreak\fi% + \ifx\cov@gl@postamble@text\empty% + \else% + \glosslinepostamble{\cov@gl@postamble@text}\cov@nopagebreak% + \fi% \glend - \ifgexample - \end{covexample} + \ifcov@ex@gloss + \end{covexample} \fi% \let\lglosslineone\relax% \let\lglosslinetwo\relax% \let\lglosslinethree\relax% - \let\cov@lglp\relax% + \let\cov@fsglpreamble@local\relax% + \let\cov@fsglpostamble@local\relax% + \let\cov@fstl@local\relax% } % 2. \trigloss[<opts>]{<line 1>}{<line 2>}{<line 3>}{<translation>} \newcommand\trigloss[5][\empty]{% - \ifggexample - \setkeys{covington}{ex=true} + \let\lglosslineone\relax% + \let\lglosslinetwo\relax% + \let\lglosslinethree\relax% + \let\glosslineone\glosslineone@global% + \let\glosslinetwo\glosslinetwo@global% + \let\glosslinethree\glosslinethree@global% + \ifcov@ex@gloss@global + \SetKeys[covgloss]{ex=true} + \else + \SetKeys[covgloss]{ex=false} + \fi% + \ifcov@tlr@global + \SetKeys[covgloss]{tlr=true} \else - \setkeys{covington}{ex=false} + \SetKeys[covgloss]{tlr=false} \fi% - \ifggtright - \setkeys{covington}{tlr=true} + \ifcov@enquote@tl@global + \SetKeys[covgloss]{enquotetl=true} \else - \setkeys{covington}{tlr=false} + \SetKeys[covgloss]{enquotetl=false} \fi% - \ifx#1\empty\else\setkeys{covington}{#1}\fi% - \ifgexample - \begin{covexample} + \def\cov@gl@preamble{\cov@gl@preamble@global}% + \def\cov@gl@postamble{\cov@gl@postamble@global}% + \ifx#1\empty\else\SetKeys[covgloss]{#1}\fi% + \ifcov@ex@gloss + \begin{covexample} \fi% \@ifundefined{lglosslineone}{}{\def\glosslineone{\lglosslineone}}% \@ifundefined{lglosslinetwo}{}{\def\glosslinetwo{\lglosslinetwo}}% \@ifundefined{lglosslinethree}{}{\def\glosslinethree{\lglosslinethree}}% - \@ifundefined{cov@lglp}{}{\def\cov@gglp{\cov@lglp}}% - \ifx\cov@gglp\empty\else\def\cov@glp{\cov@gglp}\fi% - \@ifundefined{cov@lglpst}{}{\def\cov@gglpst{\cov@lglpst}}% - \ifx\cov@gglpst\empty\else\def\cov@glpst{\cov@gglpst}\fi% + \edef\cov@gl@preamble@text{\cov@gl@preamble}% + \def\cov@gl@postamble@text{\cov@gl@postamble}% + \@ifundefined{cov@fsglpreamble@local}% + {\let\fsglpreamble\cov@fsglpreamble@global}% + {\let\fsglpreamble\cov@fsglpreamble@local}% + \@ifundefined{cov@fsglpostamble@local}% + {\let\fsglpostamble\cov@fsglpostamble@global}% + {\let\fsglpostamble\cov@fsglpostamble@local}% + \@ifundefined{cov@fstl@local}% + {\let\cov@fstl\cov@fstl@global}% + {\let\cov@fstl\cov@fstl@local}% \xglll #2\xgle #3\xgle #4\xgle - \ifgtright + \ifcov@tlr \gln #5% \else \glot{#5}% \fi - \ifx\cov@glpst\empty\else\glosslinepostamble{\cov@glpst}\cov@nopagebreak\fi% + \ifx\cov@gl@postamble@text\empty% + \else% + \glosslinepostamble{\cov@gl@postamble@text}\cov@nopagebreak% + \fi% \glend - \ifgexample - \end{covexample} + \ifcov@ex@gloss + \end{covexample} \fi% \let\lglosslineone\relax% \let\lglosslinetwo\relax% \let\lglosslinethree\relax% + \let\cov@fsglpreamble@local\relax% + \let\cov@fsglpostamble@local\relax% + \let\cov@fstl@local\relax% } @@ -1009,12 +1268,13 @@ } } -\providecommand{\sdrs}[3] -{\begin{tabular}{l} -\mbox{\cov@emphasized #1} \\ -~ \\ -\drs{#2}{#3} -\end{tabular}} +\providecommand{\sdrs}[3]{% + \begin{tabular}{l} + \mbox{\cov@emphasized #1} \\ + ~ \\ + \drs{#2}{#3} + \end{tabular}% +} \providecommand{\ifdrs}[4] { @@ -1077,15 +1337,15 @@ \@ifundefined{exercise}{% \newenvironment{exercise}{\begin{covexercise}}{\end{covexercise}} }{% -\ifforceredef - \renewenvironment{exercise}{\begin{covexercise}}{\end{covexercise}} - \cov@warning{The exercise environment was already defined. Redefining it.} -\else - \cov@warning{The exercise environment was already defined.^^J - Covington does not touch it.^^J - Use covexercise if you want to access covington's^^J - version, or use the force package option.} -\fi + \ifforceredef + \renewenvironment{exercise}{\begin{covexercise}}{\end{covexercise}} + \cov@warning{The exercise environment was already defined. Redefining it.} + \else + \cov@warning{The exercise environment was already defined.^^J + Covington does not touch it.^^J + Use covexercise if you want to access covington's^^J + version, or use the force package option.} + \fi } \newlength\reflistindent @@ -1095,14 +1355,16 @@ \newlength\reflistparsep \setlength\reflistparsep{\parsep} \@ifundefined{reflist}{ -\newenvironment{reflist}{\begin{list}{}% -{\setlength{\labelwidth}{0pt}% - \setlength{\labelsep}{0pt}% - \setlength{\leftmargin}{\reflistindent}% - \setlength{\itemindent}{-\reflistindent}% - \setlength{\listparindent}{-\reflistindent}% - \setlength{\itemsep}{\reflistitemsep}% - \setlength{\parsep}{\reflistparsep}}\item}{\end{list}} + \newenvironment{reflist}{% + \begin{list}{}{% + \setlength{\labelwidth}{0pt}% + \setlength{\labelsep}{0pt}% + \setlength{\leftmargin}{\reflistindent}% + \setlength{\itemindent}{-\reflistindent}% + \setlength{\listparindent}{-\reflistindent}% + \setlength{\itemsep}{\reflistitemsep}% + \setlength{\parsep}{\reflistparsep}}\item% + }{\end{list}}% } % Modified 1992 Nov 8 to skip defining reflist if reflist is already % defined. Permits using uga.sty with covingtn.sty. @@ -1110,8 +1372,11 @@ % V. 2.0: Add macro for font settings customization \newcommand*\sentencefs{\cov@emphasized} -\newcommand{\sentence}[1] - {\begin{flushleft}{\sentencefs #1}\end{flushleft}} +\newcommand{\sentence}[1]{% + \begin{flushleft}% + {\sentencefs #1}% + \end{flushleft}% +} % V. 2.0: Further semantic markup \providecommand*\lexp[1]{\textit{#1}} diff --git a/macros/latex/contrib/covington/covington.tex b/macros/latex/contrib/covington/covington.tex index 5dbc41c275..f8fe4ee94c 100644 --- a/macros/latex/contrib/covington/covington.tex +++ b/macros/latex/contrib/covington/covington.tex @@ -65,10 +65,13 @@ \usepackage{tocloft} \setlength{\cftbeforesecskip}{0pt} \renewcommand{\cfttoctitlefont}{\normalsize\bfseries} -\renewcommand{\cftsecfont}{\footnotesize} -\renewcommand{\cftsecpagefont}{\footnotesize} -\renewcommand{\cftsubsecfont}{\footnotesize} -\renewcommand{\cftsubsecpagefont}{\footnotesize} +\renewcommand{\cftsecfont}{\small} +\renewcommand{\cftsecpagefont}{\small} +\renewcommand{\cftsubsecfont}{\small} +\renewcommand{\cftsubsecpagefont}{\small} +\renewcommand{\cftsubsubsecfont}{\footnotesize} +\renewcommand{\cftsubsubsecpagefont}{\footnotesize} +\tocloftpagestyle{empty} \usepackage{babel} @@ -94,8 +97,8 @@ % % Titling % -\def\pversion{Version 2.9} -\def\pdate{May 26, 2023} +\def\pversion{Version 2.10} +\def\pdate{June 2, 2023} \title{\textbf{The \cvt\ Package\\\Large Macros for Linguistics}} \author{Michael A. Covington \and J\"urgen Spitzm\"uller\thanks{Current maintainer. @@ -109,15 +112,15 @@ \begin{abstract} \noindent This package, initially a collection of Michael A. Covington's private macros, provides -numerous minor \LaTeX\ enhancements for linguistics, including multiple diacritics on the -same letter, interlinear glosses (word-by-word translations), Discourse Representation Structures, -example numbering, and semantic markup. +numerous customizable \LaTeX\ macros that are helpful for linguists, including macros that allow +for multiple diacritics on the same letter, numbered linguistic examples, interlinear glosses +(word-by-word translations), Discourse Representation Structures, phrase structure rules and disjunctions, +linguistic feature structures, and for semantic markup commonly used in linguistic notation. \end{abstract} +\enlargethispage{2\baselineskip} \tableofcontents -\clearpage - \section{Introduction}\label{sec:intro} This is the documentation for \MakeLowercase{\pversion} @@ -126,50 +129,53 @@ for typing some special notations common in linguistics.% \footnote{The package has a long history. It started off as a collection of private macros back in the \LaTeX\ 2.09 days and was initially released as \texttt{covingtn.sty} (following the old 8.3 \textsc{fat} file name limit). In em\TeX\ under \textsc{ms-dos}, the file was distributed as \texttt{covingto.sty}. -Eventually, it has been renamed to \cvt\ and adapted to \LaTeXe.} +Eventually, it has been renamed to \cvt\ and adapted to \LaTeXe. The current version requires a resonably +recent version of \LaTeXe, as it employs some newer kernel features.} -To use \cvt\ with \LaTeXe, load the package as usual by adding the command -\lstinline"\usepackage{covington}" to your document preamble. -The package has the following options: +To use \cvt, load the package as usual by adding the command +\begin{lstlisting} +\usepackage[<options>]{covington} +\end{lstlisting} +to your document preamble. The package has the following options to customize its behavior: \begin{description} - \item{\joption{force}:} Force the redefinition of environments that have already been - defined by other packages or the class. + \item{\joption{force=\jparam{true|false}}} Default: \emph{false}. + Force the redefinition of environments that have already been defined by other packages or the class. + + This applies to the \jenv{example}, \jenv{examples}, \jenv{subexamples} and \jenv{exercise} environments, + which are by default not touched if they are already defined before \cvt\ is loaded. + See sec.~\ref{sec:ex}, \ref{sec:exs}, \ref{sec:subexs} and \ref{sec:exercises} for details. + \item{\joption{keeplayout=\jparam{true|false}}} Default: \emph{false}. Do not tweak the layout. - This applies to the \jenv{example}, \jenv{examples}, \jenv{subexamples} and \jenv{exercise} environments, - which are by default not touched if they are already defined before \cvt\ is loaded. - See sec.~\ref{sec:ex}, \ref{sec:exs}, \ref{sec:subexs} and \ref{sec:exercises} for details. + \Cvt\ sets \jfcsmacro{raggedbottom} and redefines the value of the \jfcsmacro{textfloatsep} length. + This just follows the preferences of the original package author and is not necessary + for the package's functionality. Yet for backwards compatibility reasons, we cannot change this. + Thus, we provide the option described here to opt out this presetting. And we actually encourage you to use it. + \item{\joption{noglossbreaks=\jparam{true|false}}} Default: \emph{false}. + If this option is set to \joption{true}, \cvt\ will try hard to prevent page breaks within glosses. - \item{\joption{keeplayout}:} Do not tweak the layout. + If this option is not set, page breaks can occur between interlinearized text and free translation of a gloss, as + well as between gloss preamble and interlinearized text, which is usually not what you will want. + Nonetheless the option is not set by default. This is for backwards compatibility reasons (in order to not change + page breaking of existing documents). Note that page breaks might still occur in some cases even if the option is set. + In order to prevent them definitely, you can put the gloss in a parbox or minipage. + \item{\joption{owncounter=\jparam{true|false}}} Default: \emph{false}. Use an own counter for numbered examples. + + By default, \cvt\ uses \LaTeX's equation counter for example numbering, so that if you use equations and numbered examples + in the same paper, you get a single continuous series of numbers. While some people (including the original author of this package) + consider this a feature, others might prefer to number equations and linguistic examples separately. If you count to the latter sort, + use this option. + \item{\joption{fnexamplecounter=\jparam{main|own|own-reset}}} Default: \emph{main}. + Specifics of the counter for numbered examples in footnotes. - \Cvt\ sets \jfcsmacro{raggedbottom} and redefines the value of the \jfcsmacro{textfloatsep} length. - This just follows the preferences of the original package author and is not necessary - for the package's functionality. Yet for backwards compatibility reasons, we cannot change this. - Thus, we provide the option described here to opt out this presetting. - -\item{\joption{noglossbreaks}:} If this option is set, \cvt\ will try hard to prevent page breaks within glosses. - - If this option is not set, page breaks can occur between interlinearized text and free translation of a gloss, as - well as between gloss preamble and interlinearized text, which is usually not what you will want. - Nonetheless the option is not set by default. This is for backwards compatibility reasons (in order to not change - page breaking of existing documents). Note that page breaks might still occur in some cases even if the option is set. - In order to prevent them definitely, you can put the gloss in a parbox or minipage. - -\item{\joption{owncounter}:} Use an own counter for numbered examples. - - By default, \cvt\ uses \LaTeX's equation counter for example numbering, so that if you use equations and numbered examples - in the same paper, you get a single continuous series of numbers. While some people (including the original author of this package) - consider this a feature, others might prefer to number equations and linguistic examples separately. If you count to the latter sort, - use this option. - -\item{\joption{ownfncounter}:} Use a separate counter for numbered examples in footnotes. - - By default, \cvt\ numbers examples in footnotes in sequence with the numbering used in the main text. With this option, - examples in footnotes get a different numbering. This uses by default lowercase Roman numbering (see sec.~\ref{sec:custno} - on how to change this) and is incremented throughout the whole footnote apparatus. - -\item{\joption{ownfncounter*}:} Same as \joption{ownfncounter}, except that this variant resets the counter at each footnote - (similar to \textsf{linguex} and \textsf{gb4e}). - + By default, \cvt\ numbers examples in footnotes in sequence with the numbering used in the main text (this conforms to + the default value of this option, \joption{fnexamplecounter=main}). If you set \joption{fnexamplecounter=own}, + examples in footnotes get a different numbering which is incremented throughout the whole footnote apparatus.% + \footnote{The previous option \joption{ownfncounter} is still supported, + but deprecated.} + If you set \joption{fnexamplecounter=own-reset}, examples in footnotes get an own counter as well, but this variant + resets the counter at each footnote (similar to \textsf{linguex} and \textsf{gb4e}).\footnote{The previous option + \joption{ownfncounter*} is still supported, but deprecated.} + Both own counters use lowercase Roman numbering by default (see sec.~\ref{sec:ex} on how to change this) \end{description} % Please note the following package-related caveats: @@ -234,8 +240,17 @@ Linguistic papers often include numbered examples. With \cvt, generating those i In this section, we describe how you can typeset a self-stepping example number (see section~\ref{sec:exno}), a single numbered example (sec.~\ref{sec:ex}), a consecutive range of numbered examples (sec.~\ref{sec:exs}), and alpha-numerically labeled sub-examples (sec.~\ref{sec:subexs}). -All numbered examples can be referred to in the text via \jfcsmacro{label} and \jfcsmacro{ref} as usual -(see sec.~\ref{sec:ref} for details). + +\Cvt's numbered examples can be customized in many ways. For instance, you can make them by default be +typeset in italics, as common in linguistics, you can adjust the way the numbers +are displayed, and you can customize the spacing and indentation if the default +settings do not suit you. This can be achieved via example options that can be set locally to a specific +environment as optional arguments or globally via the \jcsmacro{setexampleoptions} macro (see sec.~\ref{sec:ex} +for details). + +All numbered examples can be referred to in the text via \jfcsmacro{label} and \jfcsmacro{ref} as usual, +or with a convenience macro \jcsmacro{pxref} that adds the parentheses that are usually used +in example references (see sec.~\ref{sec:ref} for details). \subsection{Example numbers}\label{sec:exno} @@ -251,16 +266,24 @@ Here's what you get: \begin{flushleft} This is a sentence. \hfill (\exampleno) \end{flushleft} -If you want to output the (current) number without stepping it, the starred form \jcsmacro{exampleno*} will do that. +If you want to output the (current) number without stepping it at the same time, the starred form +\jcsmacro{exampleno*} will do that. Normally, however, you do not need to manually place \jcsmacro{exampleno} yourselves, as in the example above. For the common case where example numbers in parentheses are placed left to the example, \cvt\ provides more convenient solutions. These are described in turn. -\subsection[The \texttt{example} environment]{The \jenv{example} environment}\label{sec:ex} +\subsection[The \jenv{example} environment]{The \jenv{example} environment}\label{sec:ex} -The \jenv{example} environment (alias \jenv{covexample}) displays a single example +The \jenv{example} environment (alias \jenv{covexample}\footnote{\label{fn:fallbacks}% + As of version 1.1, \cvt\ checks if there is already an \jfenv{example} environment defined (e.\,g., by the class). + If so, \cvt\ does not define its own one. The alias environment \jenv{covexample} which can be used in order to + produce \texttt{covington's} example, however, is always defined and can be used in such cases. + If you use the package option \joption{force}, \cvt\ will override existing \jfenv{example} environments. + In any case, the package will issue a warning if \jfenv{example} is already defined (this is the case, + for instance, if you use \cvt\ with the \texttt{beamer} class).}% +) displays a single example with a generated example number to the left of it. If you type \begin{lstlisting} @@ -280,65 +303,78 @@ This is a sentence.\label{expl} \end{example} The example can be of any length; it can consist of many lines (separated by \verb"\\"), or even whole paragraphs. -The \jenv{example} environment provides the following options: +The \jenv{example} environment provides the following options which also allow for customization of their appearance: \begin{description} + \item[\joption{fs=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of the example text. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{fsno=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of the example number. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. \item[\joption{preamble=\{\jparam{arbitrary text}\}}] Arbitrary text that is inserted on an own line - after the example number (preceding the actual example text). This might be useful, for instance, + after the example number (preceding the example text). This might be useful, for instance, to give context information, to specify the language or the source in case of cited examples. - The advantage over just adding a line manually in the example is that you can globally set the markup - (see sec.~\ref{sec:custno}). - \item[\joption{postamble=\{\jparam{arbitrary text}\}}] Arbitrary text that is appended to example (on the - same line after a space). + The advantage over just adding a line manually in the example is that you can globally or locally + set the markup with the \joption{fspreamble} option. + \item[\joption{postamble=\{\jparam{arbitrary text}\}}] Arbitrary text that is appended to the example + (on the same line after a space). This might be useful to add a reference or an explanation to the translation. - The advantage over just adding text manually in the example is that this uses its own markup - (see sec.~\ref{sec:custno}). + The advantage over just adding text manually in the example is that that you can globally or locally + set the markup with the \joption{fspostamble} option. \item[\joption{postamble*=\{\jparam{arbitrary text}\}}] A variant of \joption{postamble} that does not add a space. This might be preferred if you want to add a footnote. Note that \joption{postamble} and \joption{postamble*} are mutually exclusive. + + If you want the postamble text to be on a line of its own, simply add a line break + (i.\,e., \verb|postamble={\\Text}| or, to the same effect, \verb|postamble*={\\Text}|). + \item[\joption{fspreamble=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of the preamble text. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{fspostamble=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of the postamble text. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{leftmargin=\{\jparam{length}\}}] Default: \verb|{0pt}|. + Lets you change the indentation of examples (including number). Positive values will increase, + negative values will decrease the indentation of the example. + \item[\joption{addnumbersep=\{\jparam{length}\}}] Default: \verb|{0pt}|. + Increases or (with negative values) decreases the spacing between example number and example. + \item[\joption{numberformat=\{\jparam{template}\}}] Default: \verb|{(1)}|. + The format of the example number. The option takes templates as known from the \textsf{enumerate} + package \cite{enumerate}. + Arabic numbering is represented by \jparam{1}, Roman by \jparam{i} and \jparam{I}, alphabetic by + \jparam{a} and \jparam{A}. Any text before and after the number are inserted as is. + + For instance, \verb|numberformat={[a.]}| results in lower alphabetic numbering followed by a dot, + embraced in brackets. + \item[\joption{fnnumberformat=\{\jparam{template}\}}] Default: \verb|{(i)}|. + The format of the example number if \joption{fnexamplecounter=own} or \joption{fnexamplecounter=own-reset} + and example is in a footnote. For the template format, see \joption{numberformat}. \end{description} % -If you want the postamble text be on a line of its own, simply add a line break (i.\,e., \verb|postamble={\\Text}|). - -If you need more space between the example number and the text, you can increase it by means of -the length \jcsmacro{examplenumbersep} (which is preset to \texttt{0pt}). Doing \lstinline|\setlength\examplenumbersep{1em}|, -for instance, will increase the space by 1\,em (negative values will decrease the space accordingly). - -If you need to change the indentation (left margin) of examples, you can do so by means of -the length \jcsmacro{exampleind} (preset to \texttt{0pt}). Doing \lstinline|\setlength\exampleind{1em}|, -for instance, will increase the indentation by 1\,em, negative values will decrease it accordingly. +If you pass the options as optional argument to an environment, they will only apply to the current environment. -Note that, as of version 1.1, \cvt\ checks if there is already an \jenv{example} environment defined -(e.\,g., by the class). If so, \cvt\ does not -define its own one. However, there is always the alias environment \jenv{covexample} which can be used in order to -produce \texttt{covington's} example. If you use the package option \joption{force}, \cvt\ will override -existing \jenv{example} environments. In any case, the package will issue a warning if \jenv{example} is already defined -(this is the case, for instance, if you use \cvt\ with the \texttt{beamer} class). - -One way to number sub-examples is to use \jfenv{itemize} or \jfenv{enumerate} -within an example, like this: -\begin{lstlisting} -\begin{example} +If you want to make a global change, you can use the macro \begin{itemize} -\item[(a)] This is the first sentence. -\item[(b)] This is the second sentence. + \item \jcsmacro{setexampleoptions\{\jparam{options}\}} \end{itemize} -\end{example} -\end{lstlisting} -This prints as: -\begin{example} -\begin{itemize} -\item[(a)] This is the first sentence. -\item[(b)] This is the second sentence. -\end{itemize} -\end{example} -However, the \jenv{subexamples} environment, described in sec.~\ref{sec:subexs}, is usually more -convenient for this task. +and pass either of the above options to it (as usual separated by comma). This will apply to all subsequent examples +(the \jenv{example} environment described here as well as \jenv{examples}, \jenv{subexamples} and glosses with the +\joption{ex} option) until further global change and unless an option is altered locally via optional argument. + +Please refer to sec.~\ref{sec:exex} for exemplifications of the options. -\subsection[The \texttt{examples} environment]{The \jenv{examples} environment}\label{sec:exs} +\subsection[The \jenv{examples} environment]{The \jenv{examples} environment}\label{sec:exs} To display a series of examples together, each with its own example number, use \jenv{examples} -(or \jenv{covexamples}) instead of \jenv{example} or \jenv{covexample}. +(or \jenv{covexamples}\footnote{% + As for \jenv{example}, \cvt\ checks if there is already an \jfenv{examples} environment defined, + and if this is the case, \cvt\ does not define its own one. The alias environment \jenv{covexamples} + is always available as a fallback. If you use the package option \joption{force}, \cvt\ will override + existing \jfenv{examples} environments. The package will issue a warning if \jenv{examples} is already defined + (this is the case, for instance, if you use \cvt\ with the \texttt{beamer} class), telling you + how the package has dealt with the situation.% +}) instead of \jenv{example} or \jenv{covexample}. There can be more than one example with this environment, and each of them has to be introduced by \jfcsmacro{item}, like this: \begin{lstlisting} @@ -360,48 +396,71 @@ This prints as: \item This is the second sentence. \end{examples} % -To add additional text to specific items (analogous to the \joption{preamble} option of the \jenv{example} environment), -you can use the \jcsmacro{expreamble} macro, like this: +The \jenv{examples} environments accepts the same options than the \jenv{example} environment (please refer +to sec.~\ref{sec:ex} for details). +However, there is one notable exception: \joption{preamble} and \joption{postamble[*]} do not have any effect since, +if you want to add preceding or trailing text, you will want to add this to specific items in the set. + +To this end, we provide specific macros, namely \jcsmacro{expreamble} and \jcsmacro{expostamble}, which can be placed +where they should appear in the example, and which take the same markup than the texts passed via \joption{preamble} +or \joption{postamble} option in the \jenv{example} environment. + +Hence, also here, the advantage over just adding text as is in the example is that an own, globally settable markup is used. +This is particularly relevant if you globally set examples to be italicized via the \joption{fs} option (as we have done it +in our examples in sec.~\ref{sec:exex}). + +Consider: \begin{lstlisting}[moretexcs={expreamble}] \begin{examples} \item \expreamble{Here is Jakobson's famous poetic example:} - I like Ike + I like Ike! \item \expreamble{Here is the less poetic variant:} - I am in favor of Mr. Eisenhover + I am in favor of Mr. Eisenhower. \end{examples} \end{lstlisting} % -which prints: +This prints as follows: \begin{examples} \item \expreamble{Here is Jakobson's famous poetic example:} - I like Ike + I like Ike! \item \expreamble{Here is the less poetic variant:} - I am in favor of Mr. Eisenhover + I am in favor of Mr. Eisenhower. \end{examples} % -Again, the advantage over just adding a line manually in the example is that you can globally set the markup -(see sec.~\ref{sec:custno}). - -Along the same line, trailing text (analogous to the \joption{postamble} option of the \jenv{example} environment) -can be added to specific items via the \jcsmacro{expostamble} macro, like this: +To see the advantage more clearly, let us locally set the markup of the example text: +\begin{lstlisting}[moretexcs={expreamble}] +\begin{examples}[fs={\itshape}] +\item \expreamble{Here is Jakobson's famous poetic example:} + I like Ike! +\item \expreamble{Here is the less poetic variant:} + I am in favor of Mr. Eisenhower. +\end{examples} +\end{lstlisting} +% +As you can see, the preamble text is untouched: +\begin{examples}[fs={\itshape}] + \item \expreamble{Here is Jakobson's famous poetic example:} + I like Ike! + \item \expreamble{Here is the less poetic variant:} + I am in favor of Mr. Eisenhower. +\end{examples} +% +Along the same line, consider: \begin{lstlisting}[moretexcs={expostamble}] -\begin{examples} -\item I like Ike \expostamble{(Jakobson 1960: 357)} -\item I am in favor of Mr. Eisenhover\expostamble{\footnote{He actually didn't.}} +\begin{examples}[fs={\itshape}] +\item I like Ike! \expostamble{(Jakobson 1960: 357)} +\item I am in favor of Mr. Eisenhower.\expostamble{\footnote{He actually wasn't.}} \end{examples} \end{lstlisting} % which results in: -\begin{examples} - \item I like Ike \expostamble{(Jakobson 1960: 357)} - \item I am in favor of Mr. Eisenhover\expostamble{\footnote{He actually didn't.}} +\begin{examples}[fs={\itshape}] + \item I like Ike! \expostamble{(Jakobson 1960: 357)} + \item I am in favor of Mr. Eisenhower.\expostamble{\footnote{He actually wasn't.}} \end{examples} % -The advantage over just adding text as is in the example is that this has its own, globally settable markup, -which is particularly relevant if you globally set examples to be italicized (see sec.~\ref{sec:custno}). - Like in any other \LaTeX\ list, the numbering can be freely set via the optional argument of \jfcsmacro{item}. -For a somewhat practical example, consider +For a somewhat realistic example, observe how: \begin{lstlisting}[moretexcs={covexnumber,exampleno}] \begin{examples} \item A proposition. @@ -409,27 +468,38 @@ For a somewhat practical example, consider \end{examples} \end{lstlisting} % -which results in: +results in: \begin{examples} \item A proposition. \item[\covexnumber{\exampleno*'}] An alternative proposition. \end{examples} -% -As for \jenv{example}, \cvt\ checks if there is already an \jenv{examples} environment defined, -and if this is the case, \cvt\ does not define its own one. The alias environment \jenv{covexamples} -is always available as a fallback. If you use the package option \joption{force}, \cvt\ will override -existing \jenv{examples} environments. The package will issue a warning if \jenv{examples} is already defined -(this is the case, for instance, if you use \cvt\ with the \texttt{beamer} class), telling you -how it has dealt with the situation. -Please refer to sec.~\ref{sec:ex} for ways to adjust the spacing of the environment. - -\subsection[The \texttt{subexamples} environment]{The \jenv{subexamples} environment}\label{sec:subexs} +\subsection[The \jenv{subexamples} environment]{The \jenv{subexamples} environment}\label{sec:subexs} Sometimes a set of (paradigmatic) sub-examples gets only one main example number with alphabetic sub-numbering, -as in \pxref{sbex}. To achieve this most conveniently, \cvt\ provides the \jenv{subexamples} (or \jenv{covsubexamples}) -environment. The difference to \jenv{examples}\slash \jenv{covexamples} is the numbering: +as in \pxref{sbex} below. An ad-hoc way to achieve this is to use \jfenv{itemize} or \jfenv{enumerate} +within an example with customized items, like this: +\begin{lstlisting} +\begin{example} +\begin{itemize} +\item[(a)] This is the first sentence. +\item[(b)] This is the second sentence. +\end{itemize} +\end{example} +\end{lstlisting} +This prints as: +\begin{example} + \begin{itemize} + \item[(a)] This is the first sentence. + \item[(b)] This is the second sentence. + \end{itemize} +\end{example} +However, the \jenv{subexamples} (or \jenv{covsubexamples}\footnote{The fallback mechanism described in + footnote~\ref{fn:fallbacks} for \jfenv{example} apply here, too.% +}) environment, described in this section, is usually more convenient for +this task. +As opposed to \jenv{examples}\slash \jenv{covexamples}, this environment sub-numbers its items. Thus \begin{lstlisting} \begin{subexamples} \item This is the first sentence. @@ -449,63 +519,59 @@ prints as: \item This is the second sentence. \end{subexamples} % -Again, \cvt\ checks if there is already an \jenv{subexamples} environment defined, -and if this is the case, \cvt\ does not define its own one. The alias environment \jenv{covsubexamples} -is always available as a fallback. If you use the package option \joption{force}, \cvt\ will override -existing \jenv{subexamples} environments. The package will issue a warning if \jenv{subexamples} is already defined. - -\medskip -\noindent The \jenv{subexamples} environment provides the following options: +The \jenv{subexamples}/\jenv{covsubexamples} environment provides the same options than the \jenv{example} +and \jenv{examples} environment (see sec.~\ref{sec:ex}) with the following deviations and additions: \begin{description} - \item[\joption{preamble=\{\jparam{arbitrary text}\}}] Arbitrary text that is inserted in the first line - (after the main number and before the first sub-example, which then follows in a new line). + \item[\joption{preamble=\{\jparam{arbitrary text}\}}] Arbitrary text is inserted here on the first line + (after the main number and before the first sub-example, which then follows on a new line). This might be useful, for instance, to give context information, to specify the language or the source - in case of cited sub-examples. You can globally set the markup of this preamble text (see sec.~\ref{sec:custno}). - \item[\joption{postamble=\{\jparam{arbitrary text}\}}] Arbitrary text that is appended after all sub-examples (on a - new line). This might be useful to add a reference or an explanation to the set. - The advantage over just adding text manually in the example is that this uses its own markup - (see sec.~\ref{sec:custno}). + in case of cited sub-examples. + \item[\joption{postamble=\{\jparam{arbitrary text}\}}] Arbitrary text is appended here after all sub-examples (on a + new line). This might be useful to add a reference or an explanation to the whole set. + \item[\joption{addsubnumbersep=\{\jparam{length}\}}] Default: \verb|{0pt}|. + Increases or (with negative values) decreases the spacing between example subnumber and example text. + \item[\joption{subnumberformat=\{\jparam{template}\}}] Default: \verb|{(a)}|. + The format of the sub-example number. For the template format, consult the documentation of + \joption{numberformat} in sec.~\ref{sec:ex}. \end{description} % -For instance, -\begin{lstlisting} -\begin{subexamples}[preamble={Here are two sentences},postamble={(Doe 1974: 12)}] -\item This is the first sentence. -\item This is the second sentence. -\end{subexamples} -\end{lstlisting} -or, respectively: -\begin{lstlisting} -\begin{covsubexamples}[preamble={Here are two sentences},postamble={(Doe 1974: 12)}] -\item This is the first sentence. -\item This is the second sentence. -\end{covsubexamples} -\end{lstlisting} -prints as: -\begin{subexamples}[preamble={Here are two sentences},postamble={(Doe 1974: 12)}] - \item This is the first sentence. - \item This is the second sentence. -\end{subexamples} +Also note that, if you set options globally via \jcsmacro{setexampleoptions}, the following derivating options +should be used to distinguish the \jenv{subexample} from the \jenv{example} case. +\begin{description} + \item[\joption{fssubpreamble=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of subexample's preamble text and the \jcsmacro{subexpreamble} + macro described below. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{fssubpostamble=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Tweaks the sub\-example's postamble text font settings and the \jcsmacro{subexpostamble} + macro described below. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. +\end{description} % -To add additional text to specific subitems, you can use the \jcsmacro{subexpreamble} macro, which uses the -same markup than the \joption{preamble} option, like this: +For convenience, both options actually also work (as aliases) in optional arguments. + +To add additional text preceding or following specific subitems, you can principally use the \jcsmacro{expreamble} and +\jcsmacro{expostamble} macros desribed in sec.~\ref{sec:exs}. To allow for separating the markup of such texts +in subexample from the example case, we also provide specific macros, \jcsmacro{subexpreamble} and +\jcsmacro{subexpostamble} which use their own font settings (and the same than the \joption{preamble} and +\joption{postamble} options of this environment). + +For example: \begin{lstlisting}[moretexcs={subexpreamble}] -\begin{covsubexamples}[preamble={Here are two sentences}] -\item This is the first sentence. -\item \subexpreamble{Note particular this one} - This is the second sentence. +\begin{covsubexamples}[preamble={Here are two sentences:}] +\item \subexpreamble{English:} This is the first sentence. +\item \subexpreamble{German:} Das ist der zweite Satz. \end{covsubexamples} \end{lstlisting} % -which prints: -\begin{covsubexamples}[preamble={Here are two sentences}] - \item This is the first sentence. - \item \subexpreamble{Note particular this one} - This is the second sentence. +\begin{covsubexamples}[preamble={Here are two sentences:}] + \item \subexpreamble{English:} + This is the first sentence. + \item \subexpreamble{German:} + Das ist der zweite Satz. \end{covsubexamples} % -Along the same line, trailing text (analogous to the \joption{postamble} option) -can be added to specific subitems via the \jcsmacro{subexpostamble} macro, like this: +Analoguously, with: \begin{lstlisting}[moretexcs={subexpostamble}] \begin{subexamples} \item This is the first sentence. \subexpostamble{(Miller 2022: 15)} @@ -513,98 +579,157 @@ can be added to specific subitems via the \jcsmacro{subexpostamble} macro, like \end{subexamples} \end{lstlisting} % -which results in: +you will get: \begin{subexamples} \item This is the first sentence. \subexpostamble{(Miller 2022: 15)} \item This is the second sentence.\subexpostamble{\footnote{My own.}} \end{subexamples} % -Again, the advantage over just adding text as is is that this has its own, globally settable markup, -which is particularly relevant if you globally set examples to be italicized (see sec.~\ref{sec:custno}). +More customization possibilities of examples and subexamples are elaborated in the following section. -The distance between example number and subnumber (letter) can be changed via the length \jcsmacro{examplenumbersep} -(which is preset to \texttt{0pt}). The distance between example subnumber and text can be changed via the length -\jcsmacro{subexamplenumbersep} (preset to \texttt{0pt} as well). In both cases, a positive value will increase, a negative -value will decrease the respective distance. -Doing -\begin{lstlisting}[moretexcs={setlength,examplenumbersep,subexamplenumbersep}] -\setlength{\examplenumbersep}{-0.4em} -\setlength{\subexamplenumbersep}{0.4em} -\end{lstlisting} -for instance, will come out like this: +\subsection{Examples of examples}\label{sec:exex} -\bgroup -\setlength{\examplenumbersep}{-0.4em} -\setlength{\subexamplenumbersep}{0.4em} +As already noted, all example environments can be customized in many aspects via the example options. +If passed as an optional argument to the respective environment, the change only applies to this very environment. +If passed via \jcsmacro{setexampleoptions}, the change will apply to any subsequent \jenv{example}, \jenv{examples}, +or \jenv{subexamples} environment unless a local option overrides a setting. -\begin{subexamples} +For this section and the purpose of demonstration, we globally set the markup of example sentences to italics, +as common in linguistics. As you now already know, this is very easy to do, via: +\begin{lstlisting}[morekeywords=fs,moretexcs={setexampleoptions}] +\setexampleoptions{fs=\itshape} +\end{lstlisting} +\setexampleoptions{fs=\itshape} +% +which applies from now on. If we now enter: +\begin{lstlisting} +\begin{example}[preamble={This example showcases the pre- and postamble options:}, + postamble={(German)}] +Das ist ein Satz. +\end{example} +\end{lstlisting} +% +We will get: +\begin{example}[preamble={This example showcases the pre- and postamble options:},postamble={(German)}] + Das ist ein Satz. +\end{example} +% +And with a similar subexample: +\begin{lstlisting} +\begin{subexamples}[preamble={Here are two sentences}, + postamble={(Doe 1974: 12)}] +\item This is the first sentence. +\item This is the second sentence. +\end{subexamples} +\end{lstlisting} +we get the following output: +\begin{subexamples}[preamble={Here are two sentences},postamble={(Doe 1974: 12)}] \item This is the first sentence. \item This is the second sentence. \end{subexamples} % -To change the indentation (left margin) of subexamples, adjust the length \jcsmacro{exampleind} -(preset to \texttt{0pt}). Note that this also applies to the \jenv{examples} environment. -\egroup - - -\subsection{Customizing number display and example markup}\label{sec:custno} - -You can change the display of the example number by redefining (via \jfcsmacro{renewcommand*}) the macro -\jcsmacro{covexnumber}, which has the following default definition: -\begin{lstlisting}[moretexcs={covexnumber}] -\newcommand*\covexnumber[1]{(#1)} +In what follows, we demonstrate the adjustment of the spacing of examples. +The space between the example number and the text (or the subnumber in case of subexamples) +can be adjusted, as documented above, by means of the \joption{addnumbersep} example option. +So, for instance, +\begin{lstlisting}[moretexcs={addnumbersep}] +\begin{example}[addnumbersep={2em}] +Look, I am shifted right! +\end{example} \end{lstlisting} +will come out like this: + +\begin{example}[addnumbersep={2em}] + Look, I am shifted right! +\end{example} % -with the variable \texttt{\#1} representing the number. -If you use \joption{ownfncounter}, example numbers in footnote use this macro as well. If you want -a different display, you can redefine -\begin{lstlisting}[moretexcs={covexnumberfn,covexnumber}] -\newcommand*\covexnumberfn[1]{\covexnumber{#1}} +The indentation (left margin) of examples and subexamples is controlled by the \joption{leftmargin} +example option. Doing \joption{leftmargin=1em}, for instance, will increase the indentation by 1\,em, +negative values will decrease it accordingly. +For the latter, consider: +\begin{lstlisting}[moretexcs={leftmargin}] +\begin{example}[leftmargin={-2.6em}] +This is a marginal case. +\end{example} \end{lstlisting} +which will come out like this: % -In the same vein, you can customize the display of the subexample letter by redefining -the macro \jcsmacro{covsubexnumber}, which has the following default definition: -\begin{lstlisting}[moretexcs={covsubexnumber}] -\newcommand*\covsubexnumber[1]{(#1)} -\end{lstlisting} +\begin{example}[leftmargin={-2.6em}] +This is a marginal case. +\end{example} % -To remove the parentheses from the subexample letter, for instance, to this: -\begin{lstlisting}[moretexcs={covsubexnumber}] -\renewcommand*\covsubexnumber[1]{#1} +In case of \jenv{subexamples}, the distance between example subnumber and text can be changed +via the \joption{addsubnumbersep} option. +Again, a positive value will increase, a negative value will decrease the distance. +Doing +\begin{lstlisting}[moretexcs={addnumbersep,addsubnumbersep}] +\begin{subexamples}[addnumbersep={-0.4em},addsubnumbersep={0.4em}] +\item My numbers have been moved. +\item Mine as well. +\end{subexamples} \end{lstlisting} +for instance, will yield: + +\begin{subexamples}[addnumbersep={-0.4em},addsubnumbersep={0.4em}] + \item My numbers have been moved. + \item Mine as well. +\end{subexamples} % -\noindent You can also customize the markup of the example sentences by redefining the macro -\jcsmacro{covexamplefs} (which is empty by default). To have all example sentences italicized, for instance, do: -\begin{lstlisting}[moretexcs={covexamplefs}] -\renewcommand*{\covexamplefs}{\itshape} +The example also demonstrates how, in subexamples, \joption{addnumbersep} alters (here: decreases) the spacing +between main number and subnumber. + +Next, we showcase how to change the display of the example number or subnumber via the \joption{numberformat} and +\joption{subnumberformat} options. As described in sec.~\ref{sec:ex}, these take a `mini template' as known from +the \textsf{enumerate} package \cite{enumerate}. In these templates, the first occurrence of the characters \jparam{1}, +\jparam{i}, \jparam{I}, \jparam{a}, and \jparam{A} represents the numeric system where the respective character marks +the first positive value. All the rest of the template (including following occurrences of the mentioned characters) +is interpreted literally. +For instance, \jparam{(1)} is an alphabetic number in parentheses, \jparam{a.} a lower alphabetic value followed by a dot, +etc. + +So to equip the examples with a dot after the number, we use \joption{numberformat=\{(1.)\}} +To remove the parentheses from the subexample letter, for instance, we can use \joption{subnumberformat=\{a\}}. +The following example demonstrates both options: +\begin{lstlisting}[moretexcs={numberformat,subnumberformat}] +\begin{subexamples}[numberformat={(1.)}, subnumberformat={a}] +\item This is a statement. +\item This is an adjacent statement. +\end{subexamples} \end{lstlisting} % -Note that this does, deliberately, not include the numbers, since those are controlled by another font setting macro, -\jcsmacro{covexamplenofs}, which defaults to \jfcsmacro{normalfont}. Of course you are free to redefine this as well, -if you wish do to so. - -Furthermore, you can customize the markup of the example and sub-example preamble text (supplied via the \joption{preamble} -option or the \jcsmacro{expreamble} or \jcsmacro{subexpreamble} macro) by redefining the macro -\jcsmacro{expreamblefs} or \jcsmacro{subexpreamblefs}, which also both default to \jfcsmacro{normalfont}. -To have them italicized, analogously do: -\begin{lstlisting}[moretexcs={expreamblefs}] -\renewcommand*{\expreamblefs}{\itshape} -\end{lstlisting} -or -\begin{lstlisting}[moretexcs={subexpreamblefs}] -\renewcommand*{\subexpreamblefs}{\itshape} -\end{lstlisting} +And we get what we want: +\begin{subexamples}[numberformat={(1.)}, subnumberformat={a}] + \item This is a statement. + \item This is an adjacent statement. +\end{subexamples} % -Likewise, you can customize the markup of the example and sub-example postamble text (supplied via the -\joption{postamble[*]} option or the \jcsmacro{expostamble} or \jcsmacro{subexpostamble} macro) by redefining the macro -\jcsmacro{expostamblefs} or \jcsmacro{subexpostamblefs}, which also both default to \jfcsmacro{normalfont}. - -The separate footnote example number with \joption{ownfncounter} uses lowercase Roman numbering by default. -This can be changed by redefining -\begin{lstlisting}[moretexcs={thecovfnex}] -\renewcommand{\thecovfnex}{\roman{covfnex}} -\end{lstlisting} +Note that the \joption{numberformat} option by default also changes the numbers of examples in footnotes, even if +\joption{fnexamplecounter=own} or \joption{fnexamplecounter=own-reset} is used. This does not apply to the counter format, +however. So \joption{numberformat=\{[1.])\}} will also make the example numbers in footnote appear in brackets and with the +dot, but it will still use the lower Roman numbering. Use \joption{fnnumberformat} to fully change the appearance. +With the last examples, we return to example markup. Remember, we have globally set the markup of example sentences to italics +at the beginning of this section. Now if we want to have it bold instead for one single occurence, we can reset it for the one +case via the environment options (if we wanted to change it globally from now on, we would use \jcsmacro{setexampleoptions} once more). + +Observe how: +\begin{lstlisting}[moretexcs={covsubexnumber}] +\begin{example}[fs=\bfseries,preamble={This is the preamble}, + postamble={(Postamble)}] +This is a bold statement! +\end{example} +\end{lstlisting} +% +results in: +\begin{example}[fs=\bfseries,preamble={This is the preamble}, + postamble={(Postamble)}] + This is a bold statement! +\end{example} +% +As outlined in sec.~\ref{sec:ex} and \ref{sec:subexs}, all elements of examples and subexamples +(number, actual example text, pre- and postamble) can be marked up independently via \joption{fsno}, +\joption{fspreamble}, \joption{fspostamble}, etc. Hence, many useful (and also lots of nonsensical) +example formats are easily achievable. \subsection{Referring to examples}\label{sec:ref} @@ -664,8 +789,8 @@ Note that: line is in italics, subsequent lines are set upright, and the free translation in single quotation marks (using the language-sensitive \textsf{csquotes} \cite{csquotes} macros if this package is loaded). This can be customized, though, via the macro options or globally - (for the latter, see sec.~\ref{sec:glossfc}). - \item By default, page breaks might occur within glosses. In order to prevent it, the option + via the macro \jcsmacro{setglossoptions} which will be documented below. + \item By default, page breaks might occur within glosses. In order to prevent it, the package option \joption{noglossbreaks} (see sec.~\ref{sec:intro}) will help in many cases. If it doesn't, you can wrap the whole gloss into a minipage or parbox. \item The words do not have to be typed lining up; \TeX\ counts and aligns them. @@ -697,30 +822,52 @@ Note that: \begin{description} \item[\joption{ex=\jparam{true|false}}] Default: \emph{false}. Wraps the gloss in an example environment - (i.\,e., it is numbered). + (i.\,e., it is numbered). In this case, any example settings done via \jcsmacro{setexampleoptions} + (sec.~\ref{sec:ex}) apply. \item[\joption{tlr=\jparam{true|false}}] Default: \emph{false}. If set to true, the translation line (content of the \jparam{free translation} argument) is set right to the gloss lines, rather than into a new line below. Since the gloss itself is set in a box, this means the \jparam{free translation} will appear lined up with the first line of the gloss. This can be useful when no translation, but an aligned number or something similar, is to be inserted right to the gloss (please refer to sec.~\ref{sec:glossex} for an example). - \item[\joption{fsi=\{\jparam{font settings}\}}] Adjusts the font settings of the first gloss line. - Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. - \item[\joption{fsii=\{\jparam{font settings}\}}] Adjusts the font settings of the second gloss line. - Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. - \item[\joption{fsiii=\{\jparam{font settings}\}}] Adjusts the font settings of the third gloss line. - Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{fsi=\{\jparam{font settings}\}}]. Default: \verb|{\normalfont\itshape}|. + Adjusts the font settings of the first gloss line. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{fsii=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of the second gloss line. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{fsiii=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of the third gloss line (in case of \jcsmacro{trigloss}). + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{fstl=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of the translation line. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{enquotetl=\jparam{true|false}}] Default: \emph{true}. + By default, the translation line is embraced in single quotation marks. Set this option to + \jparam{false} to omit this. + + Note that for \joption{enquotetl=true}, \cvt\ checks at document begin whether the \textsf{csquotes} + \cite{csquotes} package is loaded. If so, it uses its language-sensitive \jcsmacro{enquote*} macro + for enquoting the translation. + If not, a fallback quotation (using English single quotation marks) is used. The usage of + \textsf{csquotes} is highly recommended! \item[\joption{preamble=\{\jparam{arbitrary text}\}}] Arbitrary text that is inserted on an own line before the interlinearized gloss. This might be useful, for instance, to give context information, to specify the language or the source in case of cited glosses. - The advantages over just adding a line manually above the gloss are that you can globally set the - markup (see sec.~\ref{sec:glossfc}), and that such lines are kept on the same page than the gloss - with the option \joption{noglossbreaks} (at least as long as preamble does not exceed one line). + The advantages over just adding a line manually above the gloss are that you can locally and globally + set the markup with the \joption{fspreamble} option, and that such lines are kept on the same page than + the gloss with the option \joption{noglossbreaks} (at least as long as preamble does not exceed one line). Furthermore, this option is the only way to add such text when the \joption{ex} option is used. \item[\joption{postamble=\{\jparam{arbitrary text}\}}] Arbitrary text that is appended to the translation line, but after the closing quotation mark. This might be useful to add a footnote or some additional text to the translation line, after the actual translation. + \item[\joption{fspreamble=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of the preamble line. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. + \item[\joption{fspostamble=\{\jparam{font settings}\}}] Default: \verb|{\normalfont\upshape}|. + Adjusts the font settings of the postamble line. + Valid values are \LaTeX\ font switches such as \jfcsmacro{itshape}, \jfcsmacro{bfseries} etc. \end{description} % If given as optional arguments to a \jcsmacro{digloss} or \jcsmacro{trigloss} macro, the options will only apply to @@ -771,12 +918,30 @@ The following is a complete list of all low-level glossing commands: and a smarter way to insert a translation line. Other than \jcsmacro{glt}, it marks up (by default: enquotes) the translation line. Also, it does not add an empty line if the translation is empty. This command has been introduced in \cvt\ 2.0. + The markup can be customized by redefining the following macro: +\begin{lstlisting}[moretexcs={glosslinetrans,covenquote,cov@fstl,ifcov@enquote@tl}] +\newcommand*\glosslinetrans[1]{% + \bgroup\cov@fstl\ifcov@enquote@tl\covenquote{#1}\else#1\fi\egroup} +\end{lstlisting} + Note that for \jcsmacro{covenquote}, as used in the default definition, \cvt\ checks at + document begin whether the \textsf{csquotes} \cite{csquotes} package is loaded. If so, + it uses its language-sensitive \jcsmacro{enquote*} macro for enquoting the translation. + If not, a fallback quotation (using English single quotation marks) is used. The usage of + \textsf{csquotes} is highly recommended! + + The \jcsmacro{ifcov@enquote@tl} boolean checks for the \joption{enquotetl} option of the gloss + macro. The macro \jcsmacro{cov@fstl} holds the font settings as set via the \joption{fstl} gloss option. + These are both relevant also for low-level commands if you set the respective options via + \jcsmacro{setglossoptions}. + + In general, please take care when redefining this macro that the functioning of some gloss environment + options relies on some of the macros contained in the default definition. \item[\jcsmacro{glosspreamble\{\jparam{arbitrary text}\}}] lets you enter text that is printed immediately before the interlinearized gloss (on a line of its own). This might be useful, for instance, to give context information, to specify the language or the source in case of cited glosses. The advantages over just adding a line manually above the gloss are that you can globally set the markup - (see sec.~\ref{sec:glossfc}) and that such lines are kept on the same page than the gloss with the option - \joption{noglossbreaks}. Note, however, that page breaks might occur if this text spans multiple lines. + and that such lines are kept on the same page than the gloss with the option \joption{noglossbreaks}. + Note, however, that page breaks might occur if this text spans multiple lines. In this case, you can wrap the whole gloss into a minipage. This command has been introduced in \cvt\ 2.1. \item[\jcsmacro{glend}] ends the special \jfenv{flushleft}-like environment. @@ -808,7 +973,7 @@ This is not so if you use \jcsmacro{glot}: % The advantage of \jcsmacro{glot} is that you can easily customize the translation markup globally. Also, \jcsmacro{glot} uses the language-sensitive \textsf{csquotes} \cite{csquotes} macros if -this package is loaded (see sec.~\ref{sec:glossfc}). +this package is loaded (see sec.~\ref{sec:gmacros}). Since \jcsmacro{gll} and \jcsmacro{glll} locally activate the end of line in glosses in order to identify the different lines of the gloss (via category code change), they do not work inside macros @@ -833,47 +998,10 @@ To sum up: With low-level commands, every glossed sentence begins with either \j Layout is critical in the part preceding \jcsmacro{glt} or \jcsmacro{gln}, and fairly free afterward. -\subsection{Customization}\label{sec:glossfc} - -The font settings of each gloss line can be customized globally by way of -the global options macro \jcsmacro{setglossoptions} and the \joption{fsi}, -\joption{fsii} or \joption{fsiii} key, respectively (see sec.~\ref{sec:gmacros}). -Alternatively, you can also redefine these macros: -\begin{lstlisting}[moretexcs={glosslineone,glosslinetwo,glosslinethree}] -\newcommand*\glosslineone{\normalfont\itshape}% font settings 1st gloss line -\newcommand*\glosslinetwo{\normalfont\upshape}% font settings 2nd gloss line -\newcommand*\glosslinethree{\normalfont\upshape}% font settings 3rd gloss line -\end{lstlisting} -% -The markup of the translation line (if the \jcsmacro{digloss} or \jcsmacro{trigloss} -macro or the \jcsmacro{glot} low-level command is used) can be customized by redefining -the following macro. -\begin{lstlisting}[moretexcs={glosslinetrans,covenquote}] -\newcommand*\glosslinetrans[1]{\covenquote{#1}} -\end{lstlisting} -Note that for \jcsmacro{covenquote}, as used in the default definition, \cvt\ checks at -document begin whether the \textsf{csquotes} \cite{csquotes} package is loaded. If so, -it uses its language-sensitive \jcsmacro{enquote*} macro for enquoting the translation. -If not, a fallback quotation (using English single quotation marks) is used. The usage of -\textsf{csquotes} is highly recommended! - -The markup of the preamble line (which is not marked up at all by default) can be customized -by redefining the macro: -\begin{lstlisting}[moretexcs={glosslinepreamble}] -\newcommand*\glosslinepreamble[1]{#1} -\end{lstlisting} - -Analogously, the markup of the postamble text (which is not marked up at all by default either) -can be customized by redefining the macro: -\begin{lstlisting}[moretexcs={glosslinepostamble}] -\newcommand*\glosslinepostamble[1]{#1} -\end{lstlisting} - - -\subsection{Examples}\label{sec:glossex} +\subsection{Example glosses}\label{sec:glossex} -This section gives some further examples. First, a sentence with three lines aligned, -instead of just two: +This section gives some further examples and showcases some options. +First, a sentence with three lines aligned, instead of just two: \trigloss[fsii={\normalfont\scshape}] {Hoc est aliud exemplum} {n.sg.nom 3sg n.sg.nom n.sg.nom} @@ -881,7 +1009,8 @@ instead of just two: {This is another example.} In order to produce this, we use the \jcsmacro{trigloss} macro for a three-line gloss and pass the \joption{fsii} option with the respective font switches in order to -get small capitals in the second line: +get small capitals in the second line (\jcsmacro{normalfont} is needed here to +disable the italics set for the first line): \begin{lstlisting}[moretexcs={trigloss}] \trigloss[fsii={\normalfont\scshape}] {Hoc est aliud exemplum} @@ -956,7 +1085,6 @@ This has been input as follows: {Do you have matches?} \end{lstlisting} - \section{Phrase structure rules} To print phrase structure rules such as \psr{S}{NP~VP} you can use \texttt{covington's} macro @@ -1274,6 +1402,29 @@ it. \section{Release history} +\subsection*{2.10 (2023 June 2)} +\begin{itemize} + \item Use \LaTeXe's own keyval mechanism rather than \textsf{xkeyval}. + \item Introduce a better interface to customize the appearance of examples. Now everything can + be easily adjusted globally and locally via key-val options. This entails the following changes: + \begin{itemize} + \item Allow to globally set example options via the new macro \jcsmacro{setexampleoptions}. + \item Add way to customize example and subexample number format (see sec.~\ref{sec:subexs}). + \item Add new example options: \joption{fs}, \joption{fsno}, \joption{fspreamble}, \joption{fspostamble}, + \joption{leftmargin}, \joption{addnumbersep}, \joption{addsubnumbersep}, \joption{numberformat}, + \joption{subnumberformat}, as well as \joption{fnnumberformat} (see sec.~\ref{sec:ex}). + \end{itemize} + \item Add new gloss options: \joption{fspreamble}, \joption{fspostamble}, \joption{fstl}, + and \joption{enquotetl}. This allows for full customization of glosses via options, + both locally and globally (see sec.~\ref{sec:gloss}). + \item Package options now all have a key-value format as well. + \item Introduce new package choice-option \joption{fnexamplecounter} that + supersedes the two boolean, mutually exclusive options \joption{ownfncounter} + and \joption{ownfncounter*} (which are still supported for backwards + compatibility reasons). + \item Major documentation revisions. +\end{itemize} + \subsection*{2.9 (2023 May 26)} \begin{itemize} \item Add \joption{postamble} and \joption{postamble*} options to \jenv{example} and \jenv{subexamples} environment @@ -1296,7 +1447,7 @@ it. \begin{itemize} \item Add \joption{postamble} gloss macro option for arbitrary text that is appended to the free translation line (after closing quotation marks). See sec.~\ref{sec:gmacros}. -\item Add \jcsmacro{glosslinepostamble} command to markup this text. See sec.~\ref{sec:glossfc}. +\item Add \jcsmacro{glosslinepostamble} command to markup this text. \end{itemize} \subsection*{2.6 (2021 May 19)} @@ -1335,7 +1486,6 @@ it. \item Add starred \jcsmacro{exampleno*} command that outputs the current example number value without stepping it. See sec.~\ref{sec:exno}. \item Add macros \jcsmacro{covexamplefs} and \jcsmacro{covexamplenofs} for global setting of example text markup. - See sec.~\ref{sec:custno}. \end{itemize} \subsection*{2.1 (2019 May 12)} @@ -1360,8 +1510,8 @@ it. \begin{itemize} \item Fix font markup of second gloss line (do not force rm). - \item Add possibility to customize gloss line font setting. See sec.~\ref{sec:custno}. - \item Add possibility to customize example number display. See sec.~\ref{sec:custno}. + \item Add possibility to customize gloss line font setting. See sec.~\ref{sec:ex}. + \item Add possibility to customize example number display. See sec.~\ref{sec:ex}. \end{itemize} \subsection*{1.7 (2018 September 8)} @@ -1473,6 +1623,8 @@ it. by morpheme glosses}. Revised version of February 2008. Department of Linguistics, Max Plank Institute for Evolutionary Anthropology. \url{http://www.eva.mpg.de/lingua/resources/glossing-rules.php}. + \bibitem{enumerate} Carlisle, David: \emph{The enumerate package}. July 23, 2015. + \url{https://www.ctan.org/pkg/enumerate}. \bibitem{drs} Dimitriadis, Alexis: \emph{drs -- Typeset Discourse Representation Structures (DRS)}. June 10, 2010. \url{https://ctan.org/pkg/drs}. \bibitem{sdrt} Isambert, Paul: \emph{sdrt -- Macros for Segmented Discourse Representation Theory}. |