Debian Codegraph @

texmf-dist/doc/latex/tonevalue/tonevalue.tex

raw
1 % !TEX program = xelatex
2
3 \RequirePackage{xcolor}
4
5 \documentclass{ltxdockit}
6 \makeatletter
7 \def\@seccntformat#1{\protect\makebox[0pt][r]{\csname the#1\endcsname\hspace{\marglistsep}}}
8 \makeatother
9
10 \usepackage{xltxtra}
11
12 \usepackage[defaultcolors]{tonevalue}
13
14 \usepackage{cleveref}
15
16 \usepackage{listings}
17 \lstset{
18 basicstyle=\ttfamily,
19 frame=single,
20 columns=flexible,
21 language=[LaTeX]TeX,
22 breaklines=true,
23 postbreak=\mbox{\textcolor{spot}{$\hookrightarrow$}\space},
24 morekeywords={drawuntpoint,untpoint,linkuntpoints},
25 escapeinside={<@}{@>},
26 }
27
28 \usepackage{xeCJK}
29 \setCJKmainfont[Script=CJK, Scale=0.9]{Source Han Serif K}
30 \newCJKfontfamily\simplified[Script=CJK, Language=Chinese Simplified, Scale=0.9]{Source Han Serif K}
31 \setmainfont[Script=Latin]{Minion 3}
32 \setCJKsansfont[Script=CJK, Scale=0.9]{Source Han Sans K}
33 \setsansfont[Script=Latin]{Myriad Pro}
34 \setCJKmonofont[Script=CJK, Scale=0.9]{Sarasa Mono K}
35 \setmonofont[Script=Latin, Scale=0.9]{Sarasa Mono K}
36
37 \usepackage{graphicx}
38 \usepackage{caption}
39 \usepackage{microtype}
40
41 \newcommand{\colourcirc}[1]{\tikz{\node[draw, shape=circle, scale=0.9, inner sep=0.1em, fill, #1, text=white] {\sffamily #1};}}
42 \newcommand{\showcolour}[2]{{\raisebox{-0.2em}{\colourcirc{#1}} \sffamily\textcolor{#1}{#2}}}
43
44 \makeatletter
45 \def\blfootnote{\gdef\@thefnmark{}\@footnotetext}
46 \makeatother
47
48 \title{The \texttt{tonevalue} package}
49 \author{Yuanhao Chen}
50 \date{\today{\quad}v1.0}
51 \begin{document}
52 \maketitle
53 \tableofcontents
54
55 \section{Introduction}
56 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.
57
58 \section{User Interface}
59
60 \subsection{Basic Usage}
61 Put in your preamble
62 \begin{lstlisting}
63 \usepackage<@\oprm{\sty{tonevalue} options}@>{tonevalue}
64 \end{lstlisting}
65 then after \lstinline|\begin{document}|, use
66 \begin{lstlisting}
67 \begin{<@\prm{name of visualisation environment}@>}[<@\prm{visualisation environment options}@>]
68 \<@\prm{name of drawing command}@>[<@\prm{drawing options}@>]{<@\prm{tone value}@>}{<@\prm{name of tone}@>}
69 \end{<@\prm{name of visualisation environment}@>}
70 \end{lstlisting}
71
72 \subsection{A Brief Working Example}
73 An example of complete working code looks like
74 \begin{lstlisting}[caption={basic example.}]
75 \documentclass{article}
76
77 % load the package, and use the predefined color set
78 \usepackage[defaultcolors]{tonevalue}
79
80 \begin{document}
81
82 % set showlabels to true
83 % set range of tone values to 1 to 4
84 % set scale of graph to 0.8
85 \begin{untVisualisation}[showlabels=true, minmax={1,4}, scale=0.8]
86 % T1
87 \untpoint[bgcolor=1, label=left]{312}{T1}
88 \untpoint[bgcolor=1]{33}{T1}
89 % change in tone value
90 \linkuntpoints[color=1, bend=bend right]{{312}{T1}}{{33}{T1}}
91 \end{untVisualisation}
92
93 \end{document}
94 \end{lstlisting}
95 with the result
96 \begin{figure}[htb]
97 \centering
98 % set showlabels to true
99 % set range of tone values to 1 to 4
100 % set scale of graph to 0.8
101 \begin{untVisualisation}[showlabels=true, minmax={1,4}, scale=0.8]
102 % T1
103 \untpoint[bgcolor=1, label=left, stem=true]{312}{T1}
104 \untpoint[bgcolor=1]{33}{T1}
105 % change in tone value
106 \linkuntpoints[color=1, bend=bend right]{{312}{T1}}{{33}{T1}}
107 \end{untVisualisation}
108 \caption{}
109 \label{exampleuntVisualisation}
110 \end{figure}
111
112 \subsection{Details}
113 \subsubsection{Package Options}
114 The package options can be called like in
115 \ltxsyntax
116 \cmditem{usepackage}
117 \lstinline[mathescape]|[defaultcolors, draft, fontcmd=$\prm{font commands}$,|\newline
118 \lstinline[mathescape]| contourlength=$\prm{length}$, contournumber=$\prm{integer}$]{tonevalue}|
119 \endltxsyntax
120
121 The effects of the options are listed below.
122 \begin{optionlist}
123 \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.}
124 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.
125
126 The colours are programmatically named \lstinline{1} to \lstinline{8}, defined as \sty{xcolor} \textsc{html} colours.
127
128 {\centering
129 \showcolour{1}{蘇/蘇芳色}\quad\showcolour{3}{朽/朽葉色}\quad\showcolour{5}{熨/熨斗目花色}\quad\showcolour{7}{竹/老竹色}\\
130 \showcolour{2}{梅/紅梅色}\quad\showcolour{4}{柿/柿 色}\quad\showcolour{6}{露/露 草 色}\quad\showcolour{8}{鶸/鶸萌黄}\par
131 }
132
133 The names are taken with reference to \emph{A Dictionary of Color Combinations}\footnote{青幻舎 (Seigensha). 配色事典 (\emph{A Dictionary of Color Combinations}).}.
134
135 \optitem[]{draft}{no value required}
136 This will speed up compilations by \lstinline|\contournumber{50}| defined by \sty{contour}.
137
138 \optitem[\cmd{sffamily}]{fontcmd}{\prm{font commands}}
139 This sets the font commands to use in all graphs.
140
141 \optitem[0.075em]{contourlength}{\prm{length}}
142 This sets the width of contours around labels of tones to allow them stand out in the grid.
143
144 \optitem[1000]{contournumber}{\prm{integer}}
145 Increase this to improve contour quality; decrease to compile faster.
146 \end{optionlist}
147
148 \subsubsection{The \env{untVisualisation} environment}
149 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.
150 \ltxsyntax
151 \cmditem{begin}\lstinline|{untVisualisation}|\lstinline[mathescape]|[minmax=$\prm{range of tone values}$,|\newline
152 \lstinline[mathescape]| scale=$\prm{float}$, showlabels=$\prm{boolean}$]|
153 \cmditem{untpoint}\lstinline[mathescape]|[$\prm{\cmd{untpoint} options}$]{$\prm{tone value, e.g.~3124}$}{$\prm{tone name, e.g.~上}$}|
154 \cmditem{linkuntpoints}\lstinline[mathescape]|[$\prm{\cmd{linkuntpoints} options}$]{{$\prm{tone value}$}{$\prm{tone name}$}}{{$\prm{tone value}$}{$\prm{tone name}$}}|
155 \cmditem{end}\lstinline|{untVisualisation}|
156 \endltxsyntax
157
158 A default empty \env{untVisualisation} environment looks like \cref{defaultuntVisualisation}. A modified\\\env{untVisualisation} environment looks like \cref{exampleuntVisualisation}.
159 \begin{figure}[htb]
160 \centering
161 \begin{untVisualisation}[]
162 %
163 \end{untVisualisation}
164 \caption{empty \env{untVisualisation}.}
165 \label{defaultuntVisualisation}
166 \end{figure}
167
168 \begin{optionlist}
169 \optitem[\{1,5\}]{minmax}{\prm{range of tone values}}
170 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.
171
172 \optitem[1]{scale}{\prm{float}}
173 Scales the grid, but not the font size, as in \cref{showlabelsuntVisualisation}.
174
175 \optitem[false]{showlabels}{\prm{boolean}}
176 Controls whether to display the labels, as in \cref{showlabelsuntVisualisation}.
177 \end{optionlist}
178 \begin{figure}[!h]
179 \centering
180 \begin{untVisualisation}[showlabels=true, scale=0.5]
181 %
182 \end{untVisualisation}
183 \caption{\env{untVisualisation} with labels, and scaled to factor \lstinline|0.5|.}
184 \label{showlabelsuntVisualisation}
185 \end{figure}
186
187 \subsubsection{The \lstinline|\\untpoint| Command}
188 Use inside the \env{untVisualisation} environment to plot tone values.
189 \ltxsyntax
190 \cmditem{untpoint}[list of options]{tone value, e.g.~3124}{tone name, e.g.~上}
191 \endltxsyntax
192 Below is a complete list of \lstinline{\untpoint} options.
193 \begin{optionlist}
194 \optitem[false]{stem}{\prm{boolean}}
195 Use \lstinline{stem=true} to add a stem for turning tones.
196
197 \optitem[above]{label}{\prm{combinations of \lstinline|above, below, left, right|}}
198 For instance, use \lstinline|label=below left| to put the label (tone value) below left of the point.
199
200 \optitem[black]{bgcolor}{\prm{color}}
201 For instance, with the package option \opt{defaultcolors} on, use \lstinline|bgcolor=4| to colour the point in \textcolor{4}{the \emph{yangshang} colour}.
202
203 \optitem[0pt]{xshift}{\prm{length}}
204 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|.
205
206 \optitem[0pt]{yshift}{\prm{length}}
207 The vertical variant of \opt{xshift}.
208
209 \optitem[1]{scale}{\prm{float}}
210 Scales the size of the point.
211
212 \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.}}}
213 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.
214 \end{optionlist}
215
216 \subsubsection{The \lstinline|\\linkuntpoints| Command}
217 It must be called after the points involved are drawn.
218 \ltxsyntax
219 \cmditem{linkuntpoints}[list of options]\lstinline|{{tone value 1}{tone name 1}}{{tone value 2}{tone name 2}}|
220 \endltxsyntax
221 Below is a complete list of \lstinline{\linkuntpoints} options.
222 \begin{optionlist}
223 \optitem[black]{color}{\prm{color}}
224 Colours the connecting line.
225
226 \optitem[\{\}]{bend}{\prm{bend direction}}
227 Set \lstinline{bend=bend left} or \lstinline{bend=bend right} to bend the line.
228 \end{optionlist}
229
230 \subsection{A More Complicated Example}
231 Shifts in the tone value pattern of Shanghainese in the past 150 years (\cref{shanghaineseexample})\footnote{unt. Ibid.},
232 \begin{figure}[!htb]
233 \centering
234 \begin{untVisualisation}[showlabels=true]
235 % 1
236 \untpoint[bgcolor=1]{53}{平}
237 \untpoint[bgcolor=1]{51}{平}
238 % 2
239 \untpoint[bgcolor=2, label=right, xshift=0.8em]{11}{平}
240 % 3
241 \untpoint[bgcolor=3, xshift=-0.8em]{55}{上}
242 \untpoint[bgcolor=3, label=left]{44}{上}
243 % 4
244 \untpoint[bgcolor=4, label=below]{113}{上}
245 % 5
246 \untpoint[bgcolor=5]{35}{去}
247 \untpoint[bgcolor=5, label=below]{34}{去}
248 \untpoint[bgcolor=5]{445}{去}
249 % 6
250 \untpoint[bgcolor=6]{13}{去}
251 % 7
252 \untpoint[bgcolor=7, xshift=0.8em]{5}{入}
253 % 8
254 \untpoint[bgcolor=8, label=left, xshift=-0.8em]{1}{入}
255 \untpoint[bgcolor=8]{23}{入}
256 %
257 \linkuntpoints[color=1]{{53}{平}}{{51}{平}}
258 \linkuntpoints[color=3]{{55}{上}}{{44}{上}}
259 \linkuntpoints[color=3]{{44}{上}}{{34}{去}}
260 \linkuntpoints[color=4]{{113}{上}}{{13}{去}}
261 \linkuntpoints[color=5]{{35}{去}}{{34}{去}}
262 \linkuntpoints[color=5]{{34}{去}}{{445}{去}}
263 \linkuntpoints[color=2]{{11}{平}}{{13}{去}}
264 \linkuntpoints[color=8]{{1}{入}}{{23}{入}}
265 %
266 \end{untVisualisation}
267 \caption{shifts in the tone value pattern of Shanghainese in the past 150 years.}
268 \label{shanghaineseexample}
269 \end{figure}
270 drawn with the following code, compiled with \XeLaTeX{}.
271 \begin{lstlisting}[caption={example regarding Shanghainese.}]
272 % !TEX program = xelatex
273
274 \documentclass{ctexart}
275
276 \usepackage[defaultcolors]{tonevalue}
277
278 \begin{document}
279
280 \begin{untVisualisation}[showlabels=true]
281 % 1
282 \untpoint[bgcolor=1]{53}{平}
283 \untpoint[bgcolor=1]{51}{平}
284 % 2
285 \untpoint[bgcolor=2, label=right, xshift=0.8em]{11}{平}
286 % 3
287 \untpoint[bgcolor=3, xshift=-0.8em]{55}{上}
288 \untpoint[bgcolor=3, label=left]{44}{上}
289 % 4
290 \untpoint[bgcolor=4, label=below]{113}{上}
291 % 5
292 \untpoint[bgcolor=5]{35}{去}
293 \untpoint[bgcolor=5, label=below]{34}{去}
294 \untpoint[bgcolor=5]{445}{去}
295 % 6
296 \untpoint[bgcolor=6]{13}{去}
297 % 7
298 \untpoint[bgcolor=7, xshift=0.8em]{5}{入}
299 % 8
300 \untpoint[bgcolor=8, label=left, xshift=-0.8em]{1}{入}
301 \untpoint[bgcolor=8]{23}{入}
302 %
303 \linkuntpoints[color=1]{{53}{平}}{{51}{平}}
304 \linkuntpoints[color=3]{{55}{上}}{{44}{上}}
305 \linkuntpoints[color=3]{{44}{上}}{{34}{去}}
306 \linkuntpoints[color=4]{{113}{上}}{{13}{去}}
307 \linkuntpoints[color=5]{{35}{去}}{{34}{去}}
308 \linkuntpoints[color=5]{{34}{去}}{{445}{去}}
309 \linkuntpoints[color=2]{{11}{平}}{{13}{去}}
310 \linkuntpoints[color=8]{{1}{入}}{{23}{入}}
311 %
312 \end{untVisualisation}
313
314 \end{document}
315 \end{lstlisting}
316
317 \section{Implementation}
318 \lstinputlisting[caption={the implementation.}]{tonevalue.sty}
319
320 \end{document}