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
|
% configuration for llmk
% +++
% sequence = [ "latex", "makeindex", "latex", "latex" ]
% latex = "lualatex"
% makeindex = "mendex"
% [programs.makeindex]
% args = ["%B.idx", "-sgind.ist"]
% +++
\documentclass{l3doc}
\usepackage{makeidx}
% Documentation target
\usepackage{numbersets}
\usepackage{booktabs}
\usepackage{bxtexlogo}
\usepackage{listings}
\lstset{basicstyle=\ttfamily, escapeinside=||, tabsize=4, columns=fullflexible}
\usepackage{unicode-math}
\setmainfont{TeX Gyre Pagella}
\setsansfont{TeX Gyre Heros}
\setmonofont{Latin Modern Mono}
\setmathfont{TeX Gyre Pagella Math}
\usepackage{changelog}
\NewDocumentCommand{\ThisPackageName}{}{\pkg{numbersets}}
\NewDocumentCommand{\sourcecode}{m}{\texttt{#1}}
\title{The \ThisPackageName{} Package (v0.2.0)}
\author{Takumi Noguchi (enunun)}
\date{2024-10-15}
\begin{document}
\maketitle
\tableofcontents
\section{Overview}
The \ThisPackageName{} package provides an easy way to implement the common preference for using commands
that represent the \emph{meaning} of concepts to be expressed,
rather than focusing solely on their visual appearance.
For example, using a command like ``\cs[no-index]{RealNumbers}'' to denote the set of all real numbers \(\RealNumbers[style=bb]\) is preferable
to using a purely visual representation like ``\cs[no-index]{mathbb\{R\}}''.
This package provides the following key features:
\begin{itemize}
\item A command to apply the desired typeface for representing sets of numbers.
\item An interface for defining rules that specify the typefaces for these sets.
\item An interface for defining commands that represent sets of numbers.
\item Several predefined presets for common number sets.
\end{itemize}
Although the default configuration assumes the use of the \pkg{unicode-math} package for handling mathematical typefaces,
the \ThisPackageName{} package itself does not load the \pkg{unicode-math} package.
To use the package with default settings,
it is required to import the \pkg{unicode-math} package \emph{explicitly} in your document.
However, since the \pkg{unicode-math} package is not loaded automatically by the \ThisPackageName{} package,
users can modify their configuration even if the \pkg{unicode-math} package cannot be used.
See the section \ref{sec:withoutunicode-math} for more details.
\section{Package Options}
\label{sec:packageoptions}
\DescribeOption{style}
The \ThisPackageName{} package provides a single option for customization:
the \sourcecode{style} option.
This option allows users to specify the typeface to be used when displaying number sets,
and it is defined using a key-value format.
\begin{itemize}
\item \sourcecode{bb}: BlackBoard Bold (default), like \(\NumberSet[style = bb]{N}\).
\item \sourcecode{bfup}: Bold Upright, like \(\NumberSet[style = bfup]{N}\).
\item \sourcecode{bfit}: Bold Italic, like \(\NumberSet[style = bfit]{N}\)
\end{itemize}
\begin{function}{\SetupNumberSetsOptions}
\begin{syntax}
\cs[no-index]{SetupNumberSetsOptions}\marg{options}
\end{syntax}
Changes the global options for the \ThisPackageName{} package,
which can be applied after the package import or at any point in the document.
\end{function}
For example, to set the default style to Bold Upright, you would write:
\begin{lstlisting}
\SetupNumberSetsOptions{style=bfup}
\end{lstlisting}
\section{Basic Usage}
The \cs{NumberSet} command allows users to display number sets using the desired typeface.
The command can be customized by passing an optional \sourcecode{style} argument to specify the typeface locally for the number set.
While the \sourcecode{style} option of this command affects only the local instance, the values
it accepts are the same as those used for the package-level \sourcecode{style} option in the Section \ref{sec:packageoptions}.
\begin{function}{\NumberSet}
\begin{syntax}
\cs{NumberSet}\oarg{options}\marg{symbol}
\end{syntax}
This command displays the specified number set
with the typeface defined by the \sourcecode{style} option. If no style is specified, the default style is applied.
It should be noted that the \cs[no-index]{NumberSet} command is primarily intended for use within math mode,
similar to how the \cs[no-index]{mathbb} command is typically used in math mode to display sets like \cs[no-index]{mathbb\{N\}}.
\end{function}
In the above examples:
\begin{itemize}
\item \cs[no-index]{NumberSet\{N\}}: will be displayed like $\NumberSet{N}$ in the default style.
\item \cs[no-index]{NumberSet[style=bb]\{Z\}}: will be displayed like $\NumberSet[style=bb]{Z}$ in the BlackBoard Bold style.
\item \cs[no-index]{NumberSet[style=bfup]\{R\}}: will be displayed like $\NumberSet[style=bfup]{R}$ in the Bold Upright style.
\item \cs[no-index]{NumberSet[style=bfit]\{C\}}: will be displayed like $\NumberSet[style=bfit]{C}$ in the Bold Italic style.
\end{itemize}
It is important to note that the \cs[no-index]{NumberSet} command,
while versatile, is a more generic and less descriptive command.
For clarity and better readability in the main text,
it is recommended to use more descriptive commands such as \cs[no-index]{NaturalNumbers} for representing the set of natural numbers.
These commands provide more context and meaning, making the content easier to understand.
See the section \ref{sec:customcommand} for defining custom commands for sets of numbers,
and some presets described in the section \ref{sec:predefinedpresets} are provided by this package.
\section{Defining Custom Number Set Commands}
\label{sec:customcommand}
The \cs{DeclareNumberSetCommand} allows users to define new commands for representing number sets with specific names,
enhancing readability and semantic clarity in documents. This command can be particularly useful
when you want to create descriptive names for commonly used number sets.
\begin{function}{\DeclareNumberSetCommand}
\begin{syntax}
\cs{DeclareNumberSetCommand}\marg{cs}\marg{symbol}
\end{syntax}
This command defines a new number set command. The first argument \meta{cs} specifies the control sequence for the new command,
while the second argument \meta{symbol} represents the symbol that will be displayed.
\end{function}
For example, to define a command for the set of all quaternions by \(\NumberSet{H}\), you would write:
\begin{lstlisting}
\DeclareNumberSetCommand{\Quaternions}{H}
\end{lstlisting}
Once defined, you can use the new command \cs[no-index]{Quaternions} in your document to display the symbol for the set of all quaternions.
In addition, you can use the optional argument \sourcecode{style} to specify the typeface locally,
similar to the \cs[no-index]{NumberSet} command.
To display the set of all quaternions that you just defined above, you would write:
\begin{lstlisting}
\Quaternions[style=bfup]
\end{lstlisting}
Internally, the definition using \cs[no-index]{DeclareNumberSetCommand}\marg{cs}\marg{symbol}
is equivalent to the following definition:
\begin{lstlisting}
\NewDocumentCommand{|\meta{cs}|}
{o}
{
\IfValueTF{#1}
{
\NumberSet[#1]{|\meta{symbol}|}
}
{
\NumberSet{|\meta{symbol}|}
}
}
\end{lstlisting}
\section{Defining Custom Number Set Styles}
The \cs{DeclareNumberSetStyle} command allows users to define (or overwrite)
new styles (or registered styles) for displaying number sets,
giving users greater control over the typeface used.
This command can be useful when the built-in styles are insufficient for specific design needs.
\begin{function}{\DeclareNumberSetStyle}
\begin{syntax}
\cs{DeclareNumberSetStyle}\marg{style}\marg{command}
\end{syntax}
This command defines a new style for number sets. The first argument \meta{style} specifies the name of the style,
and the second argument \meta{command} indicates the typeface command that will be applied when this style is selected.
\end{function}
For example, to define a new style using a bold sans-serif font, you would write:
\begin{lstlisting}
\DeclareNumberSetStyle{boldsans}{\symbfsfup}
\end{lstlisting}
Once defined, you can use the identifier ``\sourcecode{boldsans}'' for the value of \sourcecode{style} option
in the following commands:
\begin{itemize}
\item \cs[no-index]{NumberSet} command
\item \cs[no-index]{SetupNumberSetsOptions} command
\item Custom command defined by the \cs[no-index]{DeclareNumberSetCommand} command
\end{itemize}
It should be noted that the \meta{command} argument of the \cs[no-index]{DeclareNumberSetStyle} command
can accept \emph{only} a single control sequence.
Namely, combinations of multiple commands (e.g., \cs[no-index]{overline\cs[no-index]{symbb}}) are not supported.
To avoid this limitation, you should define a single control sequence as an abbreviation for the combinations.
In this case, you should define an abbreviation like ``\cs[no-index]{bbline}'';
after that, you can define the style identifier using this single control sequence:
\begin{lstlisting}
\NewDocumentCommand\bbline{m}{\overline{\symbb{#1}}}
\DeclareNumberSetStyle{bbline}{\bbline}
\end{lstlisting}
The values (\sourcecode{bb}, \sourcecode{bfup}, \sourcecode{bfit}) provided by default for the style option
can be considered as pre-defined identifiers that the \cs[no-index]{DeclareNumberSetStyle} command declares.
The Table \ref{tab:predefinedidentifier} shows
the list of predefined identifiers and the commands corresponding to each identifier.
\begin{table}[h]
\centering
\caption{Predefined identifiers for the values of the \sourcecode{style} option}
\label{tab:predefinedidentifier}
\begin{tabular}{cc}
\toprule
Identifer & Command \\
\midrule
\sourcecode{bb} & \cs[no-index]{symbb} \\
\sourcecode{bfup} & \cs[no-index]{symbfup} \\
\sourcecode{bfit} & \cs[no-index]{symbfit} \\
\bottomrule
\end{tabular}
\end{table}
\section{Using Without the \pkg{unicode-math} Package}
\label{sec:withoutunicode-math}
Although the default configuration of this package assumes the use of \pkg{unicode-math} package for handling mathematical typefaces,
the \ThisPackageName{} package itself does not load the \pkg{unicode-math} package.
Therefore, you can use the \ThisPackageName{} package without the \pkg{unicode-math} package by overriding the default configuration.
Here is an example to use the \ThisPackageName{} package with \pkg{amssymb} package for blackboard bold symbols and \pkg{bm} package for bold italic symbols:
\begin{lstlisting}
\usepackage{amssymb}
\usepackage{bm}
\usepackage{numbersets}
\DeclareNumberSetStyle{bb}{\mathbb}
\DeclareNumberSetStyle{bfup}{\mathbf}
\DeclareNumberSetStyle{bfit}{\bm}
...
% in the document
% equivalent to \mathbb{P}
\NumberSet[style=bb]{P}
% equivalent to \mathbf{A}
\NumberSet[style=bfup]{A}
% equivalent to \bm{H}
\NumberSet[style=bfit]{H}
\end{lstlisting}
Note that you only need to reconfigure the styles that you actually use in your document.
For example, if you only use the \sourcecode{bb} style, there is no need to reconfigure the unused \sourcecode{bfup} and \sourcecode{bfit} styles.
\section{Predefined Presets for Common Number Sets}
\label{sec:predefinedpresets}
\begin{function}{\NaturalNumbers, \Integers, \RationalNumbers, \RealNumbers, \ComplexNumbers}
Several predefined presets are available in the \ThisPackageName{} package for commonly used number sets.
These presets are designed to help you clearly express the intended mathematical meaning,
rather than just applying a specific format.
The table \ref{tab:predefinednumberset} shows the list
of predefined commands for common sets of numbers.
\end{function}
\begin{table}[h]
\centering
\caption{Predefined commands for common sets of numbers}
\label{tab:predefinednumberset}
\begin{tabular}{cc}
\toprule
Command name & Output by default \\
\midrule
\cs{NaturalNumbers} & \(\NaturalNumbers\) \\
\cs{Integers} & \(\Integers\) \\
\cs{RationalNumbers} & \(\RationalNumbers\) \\
\cs{RealNumbers} & \(\RealNumbers\) \\
\cs{ComplexNumbers} & \(\ComplexNumbers\) \\
\bottomrule
\end{tabular}
\end{table}
\section{Contributing, Issue Reporting, and Repository Access}
The source code for the \ThisPackageName{} package is hosted on GitHub at the following repository:
\begin{quote}
\url{https://github.com/enunun/numbersets}
\end{quote}
If you have any suggestions, feature requests, or bug reports,
we encourage you to submit them via the repository's issue tracker.
This ensures that improvements and fixes are addressed efficiently. You can visit the ``Issues'' tab in the repository to create a new issue.
\section{Changelog}
The first is the version 0.1.0. The changelog of this package is shown in this seciton.
\begin{changelog}[section=false]
\begin{version}[v=0.2.0, date=2024-10-15]
\changed
\item Modified the \cs[no-index]{DeclareNumberSetCommand} to accept the control sequence directly
\end{version}
\begin{version}[v=0.1.0, date=2024-10-13]
\added
\item Provided the \cs[no-index]{NumberSet} command
\item Provided the \cs[no-index]{DeclareNumberSetCommand} command
\item Provided the \cs[no-index]{DeclareNumberSetStyle} command
\item Provided the commands \cs[no-index]{NaturalNumbers}, \cs[no-index]{Integers}, \cs[no-index]{RationalNumbers}, \cs[no-index]{RealNumbers}, \cs[no-index]{ComplexNumbers}
\end{version}
\end{changelog}
\printindex
\end{document}
|