summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/langnames/langnames.dtx
blob: 9da83dc943755d9177829bc92907ee705e8e5769 (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
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
% \iffalse meta-comment
%
% Copyright (C) 2022 Alejandro García Matarredona, निरंजन
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3 of this license or (at your option) any later
% version. The latest version of this license is in:
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of
% LaTeX version 2005/12/01 or later.
%
% \fi
% \iffalse
%<package>\ProvidesPackage{langnames}
%<package> [2022/09/05 v2.0 langnames package for naming and classification of languages]
%
%<*driver>
\documentclass{l3doc}
\usepackage[glottolog]{langnames}
\usepackage{hologo}
\DeclareRobustCommand\XeLaTeX{\hologo{XeLaTeX}}
\usepackage{fontspec}
\newfontfamily\mrtxt[%
  Scale={0.8},%
  Script={Devanagari},%
  Renderer={Harfbuzz}%
]{Shobhika}
\usepackage{expex}
\gathertags
\usepackage{hyperref,hyperxmp}
\hypersetup{%
  unicode,%
  colorlinks=true,%
  urlcolor=blue,%
  pdftitle={The linguistix package},%
  pdfauthor={Alejandro García Matarredona, निरंजन},%
  pdfsubject={The documentation of the LaTeX package `langnames'},%
  pdfcreator={निरंजन},%
  pdfkeywords={Linguistics, typology, languages, LaTeX},%
  pdfcopyright={%
    The LaTeX package langnames\textLF
    This file may be distributed and/or modified under the
    conditions of the LaTeX Project Public License, either
    version 1.3 of this license or (at your option) any later
    version.%
  },%
  pdflicenseurl={http://www.latex-project.org/lppl.txt}%
}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
\DocInput{langnames.dtx}
\end{document}
%</driver>
% \fi
% \CheckSum{100}
% \changes{v1.0}{2022/08/25}{Initial version}
% \changes{v2.0}{2022/09/05}{Optimizing and debugging the code}
% \GetFileInfo{langnames.sty}
% \DoNotIndex{\AddToHook,\def,\ekvdefinekeys,\ekvoProcessLocalOptions,\else,\expandafter,\fi,\ifdefined,\csname,\newcommand,\input,\usepackage,\PackageError,\space,\ssp,\MessageBreak,\langnames@cs@prefix,\endcsname}
% \title{The \textsf{langnames} package\thanks{This document
% corresponds to \textsf{langnames}~\fileversion,
% dated~\filedate.}}
% \author{^^A
%   Alejandro García Matarredona\\^^A
%   \texttt{alejandrogarciaag41@gmail.com}^^A
%   \and
%   {\mrtxt निरंजन}\\^^A
%   \texttt{hi.niranjan@pm.me}^^A
% }
% \maketitle
% \begin{abstract}
% \noindent The \textsf{langnames} package provides a set of macros for formatting names of languages, as well as their identification (in the form of ISO 639-3 codes) and their classification (in the form of its top-level family). The datasets from \href{https://wals.info}{WALS} and \href{https://glottolog.org}{Glottolog} are included in the package. The package also allows users to rename and add new languages.
% \end{abstract}
% \tableofcontents
% \section{Introduction}
% The typing out of language names in academic papers, especially those in language typology or related fields where many names have to be typed many times, is often inconvenient and inconsistent. This package attempts to be a small help to writers, especially of large projects or of collaborative ones, to have a slightly easier time with names of languages. It does so by defining three main commands: |\lname|, |\liso|, and |\lfam|, which respectively print out the name, name and ISO 639-3 code, and name and family of the specified language. While the package comes with about 7500 pre-defined languages, with code, name, and family, the user may also define new ones through the |\newlang| and |\renewlang| commands. The basic use of all five of these commands is explained below.
% \section{Usage}
% \subsection{Installation}
% Download the package from wherever it was found to a place where \LaTeX\ may see it, typically in \texttt{\$TEXMFHOME/tex/latex}. \pkg{langnames} should automatically load the \pkg{expkv-opt} and \pkg{expkv-def} packages.
% \subsection{Package options}
% When calling |\usepackage{langnames}|, the user must specify one of three options: |glottolog|, |wals|, or |none|.
% The first option, \textsf{glottolog}, selects the naming conventions from the \href{https://glottolog.org}{Glottolog} database. The second option, \textsf{wals}, predictably selects the naming conventions of the \href{https://wals.info}{WALS} database. The names and the genetic classification differ in some languages, so the user may choose what convention to follow.
% During the preparation of the dataset, there were instances of languages which appeared in WALS but not in Glottolog, and vice-versa. In such cases, the missing information was added from the other database. For more details on how I built the dataset, one may consult the Python script made for it in the \href{https://github.com/cicervlvs/langnames}{Github repository}.
% The third option, \textsf{none}, tells the package not to load either of the datasets, and instead start off from an empty canvas. If one specifies this option, one will have to fill in the details of each language with the macro |\newlang| (see explanation in Section 2.3 below).
% \subsection{Macros}\label{sec:mac}
% When referring to a language, the author may use one of three macros to print out different information about it. Languages are identified by their ISO 639-3 code.
% \begin{function}{\lname}
%   \begin{syntax}
%     \cs{lname}\marg{ISO code}
%   \end{syntax}
%   The simplest macro is |\lname|, which prints out the name of the specified language according to the code provided. The basic syntax is thus|\newlang| \marg{ISO code}. This can be seen in example (\nextx).
%   
%   \ex
%   |My native language is \lname{cat}.|\par\noindent
%   My native language is \lname{cat}.
%   \xe
% \end{function}
% \begin{function}{\liso}
%   \begin{syntax}
%     \cs{liso}\marg{ISO code}
%   \end{syntax}
%   The |\liso| macro prints out both the name and the ISO 639-3 code of the language specified in the argument (\cs{liso}\marg{ISO code}). Example (\nextx) shows its behavior.
%   \ex
%   |I have recently taken up \liso{brg}.|\par\noindent
%   I have recently taken up \liso{brg}.
%   \xe
% \end{function}
% \begin{function}{\lfam}
%   \begin{syntax}
%     \cs{lfam}\marg{ISO code}
%   \end{syntax}
%   The |\lfam| command prints the name of the language and its family in parenthesis. Once again, the language is identified by its ISO 639-3 code. Example (\nextx) shows how it works.
%   \ex
%   |The tone system of \lfam{pkt} is fascinating.|\par\noindent
%   The tone system of \lfam{pkt} is fascinating.
%   \xe
% \end{function}
% \begin{function}{\langnative}
%   \begin{syntax}
%     \cs{langnative}\marg{code}
%   \end{syntax}
%   This macro may be used to print the native name of the language in its own script. This might require the user to use, for example, Lua\LaTeX{} or \XeLaTeX. Currently, the package provides the native names of a few languages with both their |glottolog| and |wals| code. The concerned files are named |ln_lang_glot_native.tex| and |ln_lang_wals_native.tex| respectively. Unless a user defines their own languages with \cs{newlangnative}, this functionality is only available with the package option |native|. As package authors we are unable to provide the native versions of all names in the dataset; if you cannot see your language in the output, we are open to \href{https://github.com/cicervlvs/langnames/pulls}{pull requests} or \href{https://github.com/cicervlvs/langnames/issues}{issues}.
% \begin{verbatim}
% \documentclass{article}
% \usepackage[glottolog,native]{langnames}
% \usepackage{fontspec}
% \newfontfamily\martxt[%
%   Script=Devanagari,%
%   Scale=0.9,%
%   Renderer=Harfbuzz% Only required with LuaLaTeX
% ]{Shobhika}
% % ctan.org/pkg/shobhika
% \newfontfamily\jpntxt[Scale=0.9]{HaranoAjiMincho-Regular.otf}
% % ctan.org/pkg/haranoaji
% 
% \begin{document}
% The endonym of \lname{mar} is {\martxt\langnative{mar}}.\par
% The endonym of \lname{jpn} is {\jpntxt\langnative{jpn}}.\par
% The endonym of \lname{deu} is {\jpntxt\langnative{deu}}.
% \end{document}
% \end{verbatim}
% \end{function}
% \begin{function}{\newlang}
%   \begin{syntax}
%     \cs{newlang}\marg{pseudo code}\marg{name}\marg{family}
%   \end{syntax}
%   Users may add their own languages via the use of the |\newlang| and |\renewlang| commands. |\newlang| takes three arguments as shown above. Example (\nextx) shows its usage.
% 
% \ex\par\noindent
%
%   \vspace*{-0.8\baselineskip}
%   \begin{minipage}[h]{0.8\linewidth}
% \begin{verbatim}
% \newlang{boo}{Ameli}{Amelian}
% \begin{document}
% My new made up language is \lname{boo}.\par\noindent
% My new made up language is \liso{boo}.\par\noindent
% My new made up language is \lfam{boo}.
% \end{document}
% \end{verbatim}
%   \end{minipage}
%   \medskip
%   
%   \changetonone
%   \newlang{boo}{Ameli}{Amelian}
%   My new made up language is \lname{boo}.\par\noindent
%   My new made up language is \liso{boo}.\par\noindent
%   My new made up language is \lfam{boo}.
%   \xe
%   Note that adding new macros with |\newlang| will not overwrite any from the two other datasets as all three of them have different prefixes. Therefore, if the package was loaded with any option but |none|, none of the \cs{newlang}s defined will work, because `\newlang`s are meant to be used with one's own dataset.
% \end{function}
% \begin{function}{\renewlang}
%   \begin{syntax}
%     \cs{renewlang}\marg{dataset}\marg{code/pseudo code}\marg{name}\marg{family}
%   \end{syntax}
%   Unlike \cs{newlang}, this command actually renews a definition from the specified \meta{dataset}. This macro therefore has one more argument than |\newlang|, the first argument \meta{dataset}.
% \end{function}
% \begin{function}{\newlangnative}
%   \begin{syntax}
%     \cs{langnative}\marg{dataset}\marg{code}\marg{name}
%   \end{syntax}
% This macro is the |native| counterpart to the |\newlang| macro, adding a new language to the |native| dataset. Here the user may define new languages to print in their endonymous form.
% \end{function}
% \subsubsection{Local changes}
% The package offers another set of macros to change the language dataset locally, for example if the |wals| option was passed while loading the package and in one section one needs to use the language name from the |glottolog| set, the following commands may be used. These commands do not take any arguments.
% \begin{function}{\changetoglottolog,\changetowals,\changetonone}
%   As the names suggest, these will change your dataset for the current local group, i.e., the running environment, or the current pair of |{|, |}|, |\begingroup|, |\endgroup| pair, or |\bgroup|, |\egroup| pair.
% \end{function}
% \subsection{A miscellaneous example}
% \emph{The following code}:
% \begin{verbatim}
% \documentclass{article}
% \usepackage[glottolog]{langnames}
% 
% \begin{document}
% \noindent
% My language is \lname{cat}.\par
% {%
%   \changetonone
%   \newlang{cat}{Meow}{Meowian}%
%   \noindent
%   My language is \lname{cat}.\par
% }\noindent
% My language is \lname{cat}.\par
% \renewlang{glottolog}{cat}{Meow}{Meowian}\noindent
% My language is \lname{cat}.
% \end{document}
% \end{verbatim}
% \smallskip
% 
% \noindent
% \emph{Produces}:\par\noindent
% My language is \lname{cat}.\par
% {%
%   \changetonone
%   \newlang{cat}{Meow}{Meowian}%
%   \noindent
%   My language is \lname{cat}.\par
% }\noindent
% My language is \lname{cat}.\par
% \renewlang{glottolog}{cat}{Meow}{Meowian}\noindent
% My language is \lname{cat}.
% 
% \StopEventually{\PrintIndex\PrintChanges}
% \section{Implementation}
% Language codes, names and families are set with simple |\newcommand|s. These commands have a four part structure as follows:
% \begin{description}
% \item[Internalization:] As these commands are for internal use, they should be inaccessible to the users and hence the |@| symbol is used in the command name. The command name starts with the package name, in order to ensure safety. Thus, the first part of macros look like so: |\langnames@|
% \item[Name or family:] The package presents two different sets of names, namely language names and language family names. Internally they are named |name| and |fams| respectively. Thus, combining the first part with this one one gets |\langnames@langs| or |\langname@fams|.
% \item[Prefix:] As there exist three options, three prefixes need to be defined in order to allow for conditional selection. For this there exist three prefixes: |none|, |wals| and |glottolog|.
% \end{description}
% Thus, each language has two internal macros, one defining its name and the other one defining its family, both using the ISO 639-3 code as their key. For more information see |ln_langs_*| and |ln_fams_*| files in the package folder.
% \subsection{Dependencies}
% The \pkg{langnames} package needs to load the \pkg{expkv-def} and \pkg{expkv-opt} packages for their key-value pair setting functionality.
%    \begin{macrocode}
\usepackage{expkv-opt,expkv-def}
%    \end{macrocode}
% \subsection{Option setting}
% Options are set for what dataset to use. |glottolog| uses Glottolog data; |wals| uses WALS data; |none| selects neither datasets and all languages are defined by the user. See |langnames/langnames.py| in the \href{https://github.com/cicervlvs/langnames}{Github repository} to see how I gathered and handled the data.
%    \begin{macrocode}
\ekvdefinekeys{langnames}{%
  noval glottolog       =  {%
    \def\langnames@cs@prefix{glottolog}%
    \input{ln_langs_glot.tex}%
    \input{ln_fams_glot.tex}%
  },%
  noval wals            =  {%
    \def\langnames@cs@prefix{wals}%
    \input{ln_langs_wals.tex}%
    \input{ln_fams_wals.tex}%
  },%
  noval none            =  {%
    \def\langnames@cs@prefix{none}%
  },%
  noval native          =  {%
    \input{ln_langs_wals_native.tex}%
    \input{ln_langs_glot_native.tex}%
  }%
}
%    \end{macrocode}
% This line of code simply tells the package to set the options specified above.
%    \begin{macrocode}
\ekvoProcessLocalOptions{langnames}
%    \end{macrocode}
% \subsection{Macro definitions}
% \begin{macro}{\lname}
% This macro takes the value specified in its mandatory argument to call its corresponding macro from the |names| set, and prints it. This is achieved through the use of the |\csname| and |\endcsname| macros.
%    \begin{macrocode}
\newcommand*{\lname}[1]{%
  {%
    \csname langnames@langs@\langnames@cs@prefix @#1\endcsname
  }%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\liso}
%   This macro takes, like |\lname|, the value from the |names| set from the argument input, and prints the name as well as the ISO 639-3 code (which is the argument verbatim) between parenthesis.
%    \begin{macrocode}
\newcommand*{\liso}[1]{%
  {%
    {\csname langnames@langs@\langnames@cs@prefix @#1\endcsname}
    (ISO 639-3: #1)%
  }%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\lfam}
%   This macro, like |\lname| and |\liso|, calls the macro from the |names| set corresponding to the input of the mandatory argument, plus the macro from the |fams| set which gives it its genetic affiliation, which is printed between parenthesis.
%    \begin{macrocode}
\newcommand*{\lfam}[1]{%
  {%
    {\csname langnames@langs@\langnames@cs@prefix @#1\endcsname}
    (\csname langnames@fams@\langnames@cs@prefix @#1\endcsname)%
  }%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\newlang}
%   This macro defines new macros for a language from three mandatory arguments. The first argument of |\newlang|\marg{code} defines the code which serves as identifier (the ISO code in the case of pre-defined key-value pairs). The second argument \marg{name} defines the printed name of the language. The third argument \marg{family} defines the family to which the language belongs.
%    \begin{macrocode}
\newcommand*{\newlang}[3]{%
  \expandafter\def\csname langnames@langs@none@#1\endcsname{#2}%
  \expandafter\def\csname langnames@fams@none@#1\endcsname{#3}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\renewlang}
%   The following code is used to develop the \cs{renewlang} command.
%    \begin{macrocode}
\newcommand*{\renewlang}[4]{%
  \expandafter\def\csname langnames@langs@#1@#2\endcsname{#3}%
  \expandafter\def\csname langnames@fams@#1@#2\endcsname{#4}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\newlangnative}
%   The following code is used to develop the \cs{newlangnative} command.
%    \begin{macrocode}
\newcommand*{\newlangnative}[4]{%
  \expandafter\def\csname langnames@langs@native@#1@#2\endcsname{#3}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\langnative}
%   The following code is used to develop the \cs{langnative} command.
%    \begin{macrocode}
\newcommand*{\langnative}[1]{%
  {%
    \csname langnames@langs@native@\langnames@cs@prefix @#1\endcsname
  }%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\changetonone,\changetowals,\changetoglottolog}
%   With the following code these three additional macros are defined which change the macro-set locally.
%    \begin{macrocode}
\newcommand*{\changetonone}{%
  \def\langnames@cs@prefix{none}%
}
\newcommand*{\changetowals}{%
  \def\langnames@cs@prefix{wals}%
}
\newcommand*{\changetoglottolog}{%
  \def\langnames@cs@prefix{glottolog}%
}
%    \end{macrocode}
% \end{macro}
% This package demands the user to select one package option from the available ones compulsorily. The mechanism of the package might fail if a user does not pass any option. Hence the package checks whether it is passed or not just before the beginning of the document with the following code. If no valid option is passed, an error is issued and the package defaults to the |none| set.
%    \begin{macrocode}
\def\ssp{\space\space\space\space\space\space}
\AddToHook{begindocument/before}{%
  \ifdefined\langnames@cs@prefix
  \else
    \PackageError{langnames}{%
      You haven't passed any option to `langnames'. Can't\MessageBreak
      proceed. Please pass one from the list given below.\MessageBreak
      ---------------------------------------------------\MessageBreak
      1. glottolog: Glottolog\MessageBreak
      2. wals:\ssp World Atlas of Languages\MessageBreak
      3. none:\ssp Your own list.\MessageBreak
      ---------------------------------------------------\MessageBreak
      Refer to the documentation for more details.\MessageBreak
      At the moment I will default to option `none'%
    }%
  \fi
}
%    \end{macrocode}
%
% \section{License}
%
% Copyright (C) 2022 Alejandro García Matarredona, {\mrtxt निरंजन}
% 
% This file may be distributed and/or modified under the conditions of the LaTeX\ Project Public License, either version 1.3 of this license or (at your option) any later version. The latest version of this license is in:\par
%
% \quad http://www.latex-project.org/lppl.txt\par
%
% and version 1.3 or later is part of all distributions of \LaTeX\ version 2005/12/01 or later.
% 
% \Finale
\endinput