summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tonevalue/tonevalue.tex
blob: 6d159e0fe3dc969d195226338e51599bc5f75065 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
% !TEX program = xelatex

\RequirePackage{xcolor}

\documentclass{ltxdockit}
\makeatletter
  \def\@seccntformat#1{\protect\makebox[0pt][r]{\csname the#1\endcsname\hspace{\marglistsep}}}
\makeatother

\usepackage{xltxtra}

\usepackage[defaultcolors]{tonevalue}

\usepackage{cleveref}

\usepackage{listings}
\lstset{
  basicstyle=\ttfamily,
  frame=single,
  columns=flexible,
  language=[LaTeX]TeX,
  breaklines=true,
  postbreak=\mbox{\textcolor{spot}{$\hookrightarrow$}\space},
  morekeywords={drawuntpoint,untpoint,linkuntpoints},
  escapeinside={<@}{@>},
}

\usepackage{xeCJK}
\setCJKmainfont[Script=CJK, Scale=0.9]{Source Han Serif K}
\newCJKfontfamily\simplified[Script=CJK, Language=Chinese Simplified, Scale=0.9]{Source Han Serif K}
\setmainfont[Script=Latin]{Minion 3}
\setCJKsansfont[Script=CJK, Scale=0.9]{Source Han Sans K}
\setsansfont[Script=Latin]{Myriad Pro}
\setCJKmonofont[Script=CJK, Scale=0.9]{Sarasa Mono K}
\setmonofont[Script=Latin, Scale=0.9]{Sarasa Mono K}

\usepackage{graphicx}
\usepackage{caption}
\usepackage{microtype}

\newcommand{\colourcirc}[1]{\tikz{\node[draw, shape=circle, scale=0.9, inner sep=0.1em, fill, #1, text=white] {\sffamily #1};}}
\newcommand{\showcolour}[2]{{\raisebox{-0.2em}{\colourcirc{#1}} \sffamily\textcolor{#1}{#2}}}

\makeatletter
\def\blfootnote{\gdef\@thefnmark{}\@footnotetext}
\makeatother

\title{The \texttt{tonevalue} package}
\author{Yuanhao Chen}
\date{\today{\quad}v1.0}
\begin{document}
\maketitle
\tableofcontents

\section{Introduction}
This package provides a \sty{tikz}-based solution to typeset visualisations of tone vales. In this version (v1.0), unt's model\footnote{\simplified unt. 一种直观的调值格局可视化方法 (A Novel Approach to Visualization of Tone Value Pattern). 第十四届中国语音学学术会议 (The 14th Phonetic Association of China). July 2021.} is implemented. Support for more models is planned.

\section{User Interface}

\subsection{Basic Usage}
Put in your preamble
\begin{lstlisting}
\usepackage<@\oprm{\sty{tonevalue} options}@>{tonevalue}
\end{lstlisting}
then after \lstinline|\begin{document}|, use
\begin{lstlisting}
\begin{<@\prm{name of visualisation environment}@>}[<@\prm{visualisation environment options}@>]
  \<@\prm{name of drawing command}@>[<@\prm{drawing options}@>]{<@\prm{tone value}@>}{<@\prm{name of tone}@>}
\end{<@\prm{name of visualisation environment}@>}
\end{lstlisting}

\subsection{A Brief Working Example}
An example of complete working code looks like
\begin{lstlisting}[caption={basic example.}]
\documentclass{article}

% load the package, and use the predefined color set
\usepackage[defaultcolors]{tonevalue}

\begin{document}

% set showlabels to true
% set range of tone values to 1 to 4
% set scale of graph to 0.8
\begin{untVisualisation}[showlabels=true, minmax={1,4}, scale=0.8]
  % T1
  \untpoint[bgcolor=1, label=left]{312}{T1}
  \untpoint[bgcolor=1]{33}{T1}
  % change in tone value
  \linkuntpoints[color=1, bend=bend right]{{312}{T1}}{{33}{T1}}
\end{untVisualisation}

\end{document}
\end{lstlisting}
with the result
\begin{figure}[htb]
  \centering
  % set showlabels to true
  % set range of tone values to 1 to 4
  % set scale of graph to 0.8
  \begin{untVisualisation}[showlabels=true, minmax={1,4}, scale=0.8]
    % T1
    \untpoint[bgcolor=1, label=left, stem=true]{312}{T1}
    \untpoint[bgcolor=1]{33}{T1}
    % change in tone value
    \linkuntpoints[color=1, bend=bend right]{{312}{T1}}{{33}{T1}}
  \end{untVisualisation}
  \caption{}
  \label{exampleuntVisualisation}
\end{figure}

\subsection{Details}
\subsubsection{Package Options}
The package options can be called like in
\ltxsyntax
\cmditem{usepackage}
\lstinline[mathescape]|[defaultcolors, draft, fontcmd=$\prm{font commands}$,|\newline
\lstinline[mathescape]| contourlength=$\prm{length}$, contournumber=$\prm{integer}$]{tonevalue}|
\endltxsyntax

The effects of the options are listed below.
\begin{optionlist}
  \optitem[]{defaultcolors}{no value required\footnote{}}\footnotetext{`No value required' means it could be called on its own, i.e.~\opt{defaultcolors}, or with an arbitrary string passed to it, i.e.~\lstinline|defaultcolors={any string}| without affecting the result.}
  Use the pre-defined colour scheme designed for the four-tone and the eight-tone systems (四聲八聲) and their simplifications. The colours are chosen such that the representative character taken from each of their names falls into the category of the tone it describes, and such that the \emph{yin} tone is of the same colour tone as but darker than its corresponding \emph{yang} tone in the eight-tone system. 
  
  The colours are programmatically named \lstinline{1} to \lstinline{8}, defined as \sty{xcolor} \textsc{html} colours. 
  
  {\centering
    \showcolour{1}{蘇/蘇芳色}\quad\showcolour{3}{朽/朽葉色}\quad\showcolour{5}{熨/熨斗目花色}\quad\showcolour{7}{竹/老竹色}\\
    \showcolour{2}{梅/紅梅色}\quad\showcolour{4}{柿/柿 色}\quad\showcolour{6}{露/露 草 色}\quad\showcolour{8}{鶸/鶸萌黄}\par
  }

  The names are taken with reference to \emph{A Dictionary of Color Combinations}\footnote{青幻舎 (Seigensha). 配色事典 (\emph{A Dictionary of Color Combinations}).}.

  \optitem[]{draft}{no value required}
  This will speed up compilations by \lstinline|\contournumber{50}| defined by \sty{contour}.

  \optitem[\cmd{sffamily}]{fontcmd}{\prm{font commands}}
  This sets the font commands to use in all graphs.

  \optitem[0.075em]{contourlength}{\prm{length}}
  This sets the width of contours around labels of tones to allow them stand out in the grid.

  \optitem[1000]{contournumber}{\prm{integer}}
  Increase this to improve contour quality; decrease to compile faster.
\end{optionlist}

\subsubsection{The \env{untVisualisation} environment}
Use this environment to draw the axes and, optionally, labels of unt's model. Later, put the drawing commands of points and lines inside this environment.
\ltxsyntax
\cmditem{begin}\lstinline|{untVisualisation}|\lstinline[mathescape]|[minmax=$\prm{range of tone values}$,|\newline
\lstinline[mathescape]|                   scale=$\prm{float}$, showlabels=$\prm{boolean}$]|
\cmditem{untpoint}\lstinline[mathescape]|[$\prm{\cmd{untpoint} options}$]{$\prm{tone value, e.g.~3124}$}{$\prm{tone name, e.g.~上}$}|
\cmditem{linkuntpoints}\lstinline[mathescape]|[$\prm{\cmd{linkuntpoints} options}$]{{$\prm{tone value}$}{$\prm{tone name}$}}{{$\prm{tone value}$}{$\prm{tone name}$}}|
\cmditem{end}\lstinline|{untVisualisation}|
\endltxsyntax

A default empty \env{untVisualisation} environment looks like \cref{defaultuntVisualisation}. A modified\\\env{untVisualisation} environment looks like \cref{exampleuntVisualisation}.
\begin{figure}[htb]
  \centering
  \begin{untVisualisation}[]
    % 
  \end{untVisualisation}
  \caption{empty \env{untVisualisation}.}
  \label{defaultuntVisualisation}
\end{figure}

\begin{optionlist}
  \optitem[\{1,5\}]{minmax}{\prm{range of tone values}}
  Sometimes we deal with languages whose tone values do not range from 1 to 5. Use this command to modify the minima and maxima of the axes.

  \optitem[1]{scale}{\prm{float}}
  Scales the grid, but not the font size, as in \cref{showlabelsuntVisualisation}.

  \optitem[false]{showlabels}{\prm{boolean}}
  Controls whether to display the labels, as in \cref{showlabelsuntVisualisation}.
\end{optionlist}
\begin{figure}[!h]
  \centering
  \begin{untVisualisation}[showlabels=true, scale=0.5]
    % 
  \end{untVisualisation}
  \caption{\env{untVisualisation} with labels, and scaled to factor \lstinline|0.5|.}
  \label{showlabelsuntVisualisation}
\end{figure}

\subsubsection{The \lstinline|\\untpoint| Command}
Use inside the \env{untVisualisation} environment to plot tone values.
\ltxsyntax
\cmditem{untpoint}[list of options]{tone value, e.g.~3124}{tone name, e.g.~上}
\endltxsyntax
Below is a complete list of \lstinline{\untpoint} options.
\begin{optionlist}
  \optitem[false]{stem}{\prm{boolean}}
  Use \lstinline{stem=true} to add a stem for turning tones.

  \optitem[above]{label}{\prm{combinations of \lstinline|above, below, left, right|}}
  For instance, use \lstinline|label=below left| to put the label (tone value) below left of the point.

  \optitem[black]{bgcolor}{\prm{color}}
  For instance, with the package option \opt{defaultcolors} on, use \lstinline|bgcolor=4| to colour the point in \textcolor{4}{the \emph{yangshang} colour}.

  \optitem[0pt]{xshift}{\prm{length}}
  When there are two different points at the same coordinates, use this option to slightly shift the points horizontally, e.g.~\lstinline|xshift=0.8em|.

  \optitem[0pt]{yshift}{\prm{length}}
  The vertical variant of \opt{xshift}.

  \optitem[1]{scale}{\prm{float}}
  Scales the size of the point.

  \optitem[\{\}]{tikzoptions}{\prm{\sty{tikz} options not in the key-value format} \emph{\textcolor{spot}{Unstable (this might clash with the options required to plot the point). Use at risk.}}}
  For instance, use \lstinline|tikzoptions={black}| to make the point completely black (the name of the tone becomes invisible), but preserving the size of the point which fits to the invisible name of the tone.
\end{optionlist}

\subsubsection{The \lstinline|\\linkuntpoints| Command}
It must be called after the points involved are drawn.
\ltxsyntax
\cmditem{linkuntpoints}[list of options]\lstinline|{{tone value 1}{tone name 1}}{{tone value 2}{tone name 2}}|
\endltxsyntax
Below is a complete list of \lstinline{\linkuntpoints} options.
\begin{optionlist}
  \optitem[black]{color}{\prm{color}}
  Colours the connecting line.

  \optitem[\{\}]{bend}{\prm{bend direction}}
  Set \lstinline{bend=bend left} or \lstinline{bend=bend right} to bend the line.
\end{optionlist}

\subsection{A More Complicated Example}
Shifts in the tone value pattern of Shanghainese in the past 150 years (\cref{shanghaineseexample})\footnote{unt. Ibid.},
\begin{figure}[!htb]
  \centering
  \begin{untVisualisation}[showlabels=true]
    % 1
    \untpoint[bgcolor=1]{53}{平}
    \untpoint[bgcolor=1]{51}{平}
    % 2
    \untpoint[bgcolor=2, label=right, xshift=0.8em]{11}{平}
    % 3
    \untpoint[bgcolor=3, xshift=-0.8em]{55}{上}
    \untpoint[bgcolor=3, label=left]{44}{上}
    % 4
    \untpoint[bgcolor=4, label=below]{113}{上}
    % 5
    \untpoint[bgcolor=5]{35}{去}
    \untpoint[bgcolor=5, label=below]{34}{去}
    \untpoint[bgcolor=5]{445}{去}
    % 6
    \untpoint[bgcolor=6]{13}{去}
    % 7
    \untpoint[bgcolor=7, xshift=0.8em]{5}{入}
    % 8
    \untpoint[bgcolor=8, label=left, xshift=-0.8em]{1}{入}
    \untpoint[bgcolor=8]{23}{入}
    % 
    \linkuntpoints[color=1]{{53}{平}}{{51}{平}}
    \linkuntpoints[color=3]{{55}{上}}{{44}{上}}
    \linkuntpoints[color=3]{{44}{上}}{{34}{去}}
    \linkuntpoints[color=4]{{113}{上}}{{13}{去}}
    \linkuntpoints[color=5]{{35}{去}}{{34}{去}}
    \linkuntpoints[color=5]{{34}{去}}{{445}{去}}
    \linkuntpoints[color=2]{{11}{平}}{{13}{去}}
    \linkuntpoints[color=8]{{1}{入}}{{23}{入}}
    % 
  \end{untVisualisation}
  \caption{shifts in the tone value pattern of Shanghainese in the past 150 years.}
  \label{shanghaineseexample}
\end{figure}
drawn with the following code, compiled with \XeLaTeX{}.
\begin{lstlisting}[caption={example regarding Shanghainese.}]
% !TEX program = xelatex

\documentclass{ctexart}

\usepackage[defaultcolors]{tonevalue}

\begin{document}

\begin{untVisualisation}[showlabels=true]
  % 1
  \untpoint[bgcolor=1]{53}{平}
  \untpoint[bgcolor=1]{51}{平}
  % 2
  \untpoint[bgcolor=2, label=right, xshift=0.8em]{11}{平}
  % 3
  \untpoint[bgcolor=3, xshift=-0.8em]{55}{上}
  \untpoint[bgcolor=3, label=left]{44}{上}
  % 4
  \untpoint[bgcolor=4, label=below]{113}{上}
  % 5
  \untpoint[bgcolor=5]{35}{去}
  \untpoint[bgcolor=5, label=below]{34}{去}
  \untpoint[bgcolor=5]{445}{去}
  % 6
  \untpoint[bgcolor=6]{13}{去}
  % 7
  \untpoint[bgcolor=7, xshift=0.8em]{5}{入}
  % 8
  \untpoint[bgcolor=8, label=left, xshift=-0.8em]{1}{入}
  \untpoint[bgcolor=8]{23}{入}
  % 
  \linkuntpoints[color=1]{{53}{平}}{{51}{平}}
  \linkuntpoints[color=3]{{55}{上}}{{44}{上}}
  \linkuntpoints[color=3]{{44}{上}}{{34}{去}}
  \linkuntpoints[color=4]{{113}{上}}{{13}{去}}
  \linkuntpoints[color=5]{{35}{去}}{{34}{去}}
  \linkuntpoints[color=5]{{34}{去}}{{445}{去}}
  \linkuntpoints[color=2]{{11}{平}}{{13}{去}}
  \linkuntpoints[color=8]{{1}{入}}{{23}{入}}
  % 
\end{untVisualisation}

\end{document}  
\end{lstlisting}

\section{Implementation}
\lstinputlisting[caption={the implementation.}]{tonevalue.sty}

\end{document}