summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/currency/currency_doc.tex
blob: a6cc83efcdd4b3d3f934162d3f82a134274f01dd (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
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
\documentclass[12pt,add-index]{cnltx-doc}
\usepackage[T1]{fontenc}
\usepackage[english]{babel}
\usepackage[utf8]{inputenc}
\usepackage{csquotes}
\usepackage{currency}
\usepackage{enumitem}
\usepackage{filecontents}
\usepackage[
backend=biber,
%style=cnltx,  % incompatible with biblatex 3.3
sortlocale=en_EN,
indexing=cite,
useprefix]{biblatex}
\usepackage{nicefrac}

\addbibresource{\jobname.bib}

\newnote*\doccorrectedsinceversion[1]{Documentation corrected in version~#1}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{filecontents*}{\jobname.bib}
@online{iso,
    author = {{ISO committee}},
    title = {Currency codes - ISO 4217},
    url = {http://www.iso.org/iso/home/standards/currency_codes.htm},
    year = {2015},
}

@online{iso:wikipedia,
    editor = {Wikipedia},
    title = {ISO 4217},
    url = {https://en.wikipedia.org/wiki/ISO_4217},
    year = {2015},
}

@package{siunitx,
    author = {Wright, Joseph},
    title = {\texttt{siunitx} — A comprehensive (SI) units package},
    date = {2014-10-28},
   note = {Version 2.6d},
}

@package{translations, 
    author = {Niederberger, Clemens},
    title = {\texttt{translations}, Internationalization of \LaTeX2e Packages},
    date = {2017-05-16},
    note = {Version 1.6},
}
    
\end{filecontents*}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\setcnltx{
  package  = {currency},
  info     = {Print monetary units} ,
  url      = https://github.com/antoinelejay/currency.git ,
  authors  = Antoine Lejay,
  email    = antoine.lejay@univ-lorraine.fr ,
  abstract = {%
      This packages aims at typesetting monetary units in a consistent way.
  } ,
  add-cmds = 
  {
      dXXX,cXXX,CurrencySetup
  } ,
  add-silent-cmds = {
  } ,
  index-setup = { othercode=\footnotesize, level=\section , noclearpage } ,
  makeindex-setup = {  columns=3, columnsep=1em }
}

% Some currencies definition
\DefineCurrency{EUR}{name={euro},plural={euros},symbol={\euro},iso={EUR},kind=iso,base=2}
\DefineCurrency{USD}{name={dollar},plural={dollars},symbol={\$},iso={USD},kind=iso,base=2}
\DefineCurrency{JPY}{name={yen}, plural={yens}, symbol={\textyen}, iso={JPY}, kind=iso,cents=false} 
\DefineCurrency{GBP}{name={pound},pre=true,plural={pounds}, symbol={\pounds}, iso={GBP}, kind=iso,base=2} 


\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Introduction
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}

Strangely enough, it seems that no package deals with a conveninent, 
normalized way to print monetary units and values. Built on the top
of the \pkg{siunitx}, this package 
then aims at providing a consistant and coherent way to format such 
quantities. In particular, we consider printing values and unit 
\begin{itemize}[noitemsep=0pt,topsep=0pt]
\item In the ISO format (ISO 4217),
\item In their usual name (dollar, \cEUR[kind=name], ...), singular and plurals,
\item Using their ususal symbols (\$, \cEUR[kind=symbol],...).
\end{itemize}

The currency code ISO 4217 specifies the code of the currency as
a three-letters code. The first two ones are the code of the country
according to ISO 3166. The last one is the name of the currency name. 

This package creates macros for defined currencies which follow
the ISO 4217 codes. 

This package is then useful for current monetary units, using 
the decimal systems and cents, written in western format.
Non decimal systems such as 
the \emph{pound shilling pennies} are not supported. 

\section{Licence and Requirements}
\license

The \pkg*{currency} package needs and thus loads the packages
\pkg{siunitx}, \pkg{pgfkeys}, \pkg{etoolbox}, \pkg{xparse}, 
\pkg{expl3}, \pkg{textcomp} and \pkg{eurosym}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Currency definition
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
\section{Currency definition}

\begin{commands}
    \command{DefineCurrency}[\marg{ISO}\marg{maps}] 
    defines a new currency (there is no warning if a currency is being redefined).
\end{commands}

A new currency is defined  with this command. The argument \Darg{ISO}
is the ISO format (a unique code in three letters based on country codes \cite{iso,iso:wikipedia}, \eg, USD
for \emph{United States Dollar}), or any suitable name from which commands will be created.
Its characteristics are defined through key-values pairs, the so-called \Darg{map}.

When \verb|XXX| is the ISO code (or any other code), it defines 
two commands \verb|\dXXX| and \verb|\cXXX| for using these units in the text.
These commands are defined globally. 
See Section~\ref{sec:using}.


For example, to define the US dollars, we set

\begin{sourcecode}
    \DefineCurrency{USD}{name={dollar},plural={dollars},iso={USD},kind=iso,symbol={\$}}
\end{sourcecode}


Other styles may be defined through \cs*{pgfkeys} by following this example:
\begin{example}
    \pgfkeys{/currency/my style/.style={locale=US,kind=plural}}
    \dUSD[my style]{100.10}
\end{example}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\paragraph*{Key-values when defining or using a currency.}

Several key-values pair are defined. Since this package relies on \pkg{siunitx},
it is also possible to use any key-values from this latest package, for example 
to control the ways the values are printed (separators, ...).

\begin{options}
    \keyval{name}{name}\Default{ZZZ} The name of the currency (\eg, dollar, yen, ...).
    \keyval{plural}{plural}\Default{\textit{name} s} The plural form of the name of the currency.
    \keyval{iso}{iso} The ISO code of the currency.
    \keyval{symbol}{symbol}\Default{\textcurrency} The symbol for the currency, if any (\eg, \cEUR[kind=symbol], \cUSD[kind=symbol], ...).
    \keyval{pre-between}{tokens}\Default{no break space}
	The tokens that are placed between the name and the value when the name 
	is printed before. 
    \keyval{post-between}{tokens}\Default{no break space} 
	The tokens that are placed between the name and the value when the name 
	is printed after. 
    \keyval{before}{tokens}\Default{} What is printed before. 
    \keyval{before+}{tokens} Append the content to \option{before}.
    \keyval{before<}{tokens} Prepend the content to \option{before}.
    \keyval{font}{tokens} For setting up the font which is used for both the unit and the amount (previous uses of \option{font} are overrided).
    \keyval{font+}{tokens} Add the content to \option{font}.
    \keyval{after}{tokens} What is printed after.
    \keyval{after+}{tokens} Append to what is print after.
    \keyval{after<}{tokens} Prepend to what is print after.
    \keyval{prefix}{tokens}\Default What is printed before the name (\eg, k, M, ...).
    \keychoice{kind}{\default{iso},plural,name,symbol}
    The representation of the monetary unit.
    \keychoice{cents}{\default{true},false,always}
    Control the way the cents are printed.
    \keychoice{pre}{true,\default{false}} Select if the unit should be print before or after the value (only for ISO code and symbols).
    \keybool{number} Parse the values (interface to \option{parse-numbers} from \pkg{siunitx}).

    \keyval{base}{integer}\Default{2} Number of digits for the cents.
\end{options}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%% Examples 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\paragraph*{Examples}

No currency are actually defined in \pkg{currency}.
Euros, US dollars, yens and pounds could be defined by 
\begin{sourcecode}
    \DefineCurrency{EUR}{name={euro}, plural={euros}, symbol={\euro}, iso={EUR}, kind=iso}
    \DefineCurrency{USD}{name={dollar}, plural={dollars}, symbol={\$}, iso={USD}, kind=iso} 
    \DefineCurrency{JPY}{name={yen}, plural={yens}, symbol={\textyen}, iso={JPY}, kind=iso,cents=false} 
    \DefineCurrency{GBP}{name={pound},pre=true,plural={pounds}, symbol={\pounds}, iso={GBP}, kind=iso} 
\end{sourcecode}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%% Using currencies
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Using currencies}
\label{sec:using}

\subsection{Using currencies}

Currencies are used with or without amounts. They could also be changed locally. 

\begin{commands}
    \command{CurrencySetup}[\marg{maps}]
    This command defines a \emph{style} in the sense of \pkg{pgfkeys}, that 
    is a series of keys-values pairs.  
    These maps are exectued after
    the ones defining the format of the currency but before the optional 
    argument passed to \cs{dXXX} or \cs{cXXX} where \texttt{XXX} is
    the ISO 4217 code of the currency. It could be used to change locally 
    the setting of a currency. Using this command overrides the previous settings of
    \cs*{CurrencySetup}. The command \cs{CurrencySetupAppend} append to the current style.:w
    The style is stored in \verbcode|/currency/currency/.style|.
    \command{CurrencySetupAppend}[\marg{maps}] Similar to \cs{CurrencySetup} but 
    append the style.
    \doccorrectedsinceversion{0.2}
    \command{cXXX}[\oarg{maps}] Print only the monetary unit with currency code \texttt{XXX}
    (mnemonic \textit{c} stands for \textit{currency}).
    \command{dXXX}[\oarg{maps}\marg{value}] Print the value with the monetary unit with currency code \texttt{XXX} (mnemonic \textit{d} stands for \textit{display}).
    \command{vXXX}[\oarg{maps}\marg{value}]\sinceversion{0.2}
    alias for \verbcode|\dXXX| (mnemonic \textit{v} stands for \textit{value}).
\end{commands}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{How currencies are composed?}

The commands \cs{cXXX} and \cs{dXXX} are expanded inside a group. 
The argument \meta{value} for \cs{cXXX} is stored into \cs*{value}.
Besides, the unit is stored into \cs*{currencyunit} according 
to the value of \option{kind}.

When using \cs{dXXX}, the order in which the elements are composed is 
\begin{quote}
    \option{font}\ \option{before}\ \option{prefix}\ \cs*{currencyunit}\ \option{pre-between}\
    \cs*{value}\ \option{after}
\end{quote}
when the currency unit is printed before (\code{pre=false}), and 
\begin{quote}
     \option{font}\ \option{before}\ \cs*{value}\ \option{post-betwen}\ \option{prefix}\ \cs*{currencyunit}\ \option{after}
\end{quote}
otherwise (\code{pre=true}).

The rules are
\begin{itemize}[leftmargin=2em,itemsep=0pt]
    \item The value (mandatory argument) specified by \meta{value} is printed
	using \verbcode|\num{\value}| using the \cs{num} command from \pkg{siunitx}, and the value
	is stored locally into \cs*{value}.
    \item Both \option{prefix} and \option{unit} are enclosed into a \cs{text} command
	so that they could safely be used in math mode.
\end{itemize}

When using \cs{cXXX}, the order in which the elements are composed is 
\begin{quote}
    \option{font}\ \option{before}\ \option{prefix}\ \cs*{currencyunit}\ \option{after}
\end{quote}
where \option{prefix} and \cs*{currencyunit} are enclosed in a \cs{text} command.
The boolean option \option{pre} is useless in this case.

\subsection{The hierarchy of keys definitions}

The order in which the keys are defined (and then overwritten) is
\begin{itemize}[leftmargin=2em,itemsep=0pt]
    \item Default options values.
    \item Command \cs{DefineCurrency}.
    \item Command \cs{CurrencySetup}, which is a shorthand for defining 
	the pgfkey \verbcode|/currency/currency/.style|. 
    \item Command \cs{cXXX} ou \cs{dXXX} (the commands are executed
	in a group).
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Examples
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Examples}

\subsubsection{Punctuation.}

The commands \cs{dXXX} and \cs{cXXX} are defined using 
the \pkg{xparse} package. The space is preserved after the command
so that there is no need to use \verbcode|\| after a command.

\begin{example}
    The total gross salary is \dEUR{2000}. A part of \dEUR{1500} forms the net salary.
\end{example}

\subsection*{Using a prefix}

\begin{example}
    The total cost of the project is \dEUR[prefix=M,kind=symbol]{0.5}.
\end{example}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Changing the base}

Most of the currencies have \emph{cents}, that is a monetary unit equal to $\nicefrac{1}{100}$ 
of the monetary unit. It is however possible to use another number of digits, either 
for special purposes, or for monetary units with other bases such as the Kuwaiti dinar
which is decomposed in \num{1000} fils.

\begin{example}
    \DefineCurrency{KWD}{name={dinar},plural={dinars},symbol={KD},iso={KWD},kind=iso,base=3}
    $\dUSD{1}=\dKWD{0.29963}$
\end{example}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Changing the font}

Using the \key{font}{tokens} key, it is possible to change the font which 
is used for the monetary units (remember that everything is enclosed into a group). 
When used in the currency definition and in \cs{CurrencySetup}, 
it is however supersed by any other \key{font}{tokens} key used in \cs{dXXX}
(A similar result could be obtained with \key{before}{tokens}, which aims
at putting some material). To avoid this, \key{font+}{tokens} shall be used.

Numbers are typesetted using a upright font. The \option*{detect-...}
options of \pkg{siunitx} could be used to change \cite[\S~5.2]{siunitx}.
However, they should be passed as boolean keys. 


\begin{example}
    \textit{It costs \dUSD{1}}.
    \textit{It costs \dUSD[font=\normalfont]{1}}.
    \begin{empty}
    \CurrencySetup{font=\normalfont}
    \textit{It costs \dUSD{1}}.
    \textit{It costs \dUSD[font+=\bfseries]{1}}.
    \textit{It costs \dUSD[font=\bfseries]{1}}.
    \textit{It costs \dUSD[font=\bfseries,detect-weight=true]{1}}.
    \textit{It costs \dUSD[font=\bfseries,detect-all=true]{1}}.
    \end{empty}
\end{example}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Using options before and after}

The use of \key{before}{tokens} is similar to the one of \key{font}{tokens}.
It is possible to append or to prepend the value to existing ones
defined as a higher level through \key{before+}{tokens} and \key{before<}{tokens}.
Similarly, one could use \key{after}{tokens}, \key{after+}{tokens} and \key{after<}{tokens}.

\begin{example}
    \CurrencySetup{before=X}
    \dUSD[before+={\color{red}}]{1}
    \dUSD[before<={\color{red}}]{1}
\end{example}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Using siunitx's features}

Any key of the \pkg{siunitx} package could be used. 
For example, localization may change the unit separator (comma, ...).

\begin{example}
    This costs \dEUR{12 345.76}.
    {\sisetup{locale=FR} Cela co\^ute \dEUR{12 345.76}.}
\end{example}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Using raw formula}

A raw formula could be typeseted using the number option \verbcode|number=false|.
Beware, this propagate \verbcode|parse-numbers=false| to \verbcode|\num|
so that any inner call to the latter command should specify 
\verbcode|parse-numbers=true| if needed. 

A style (see Section~\ref{sec:styles}) \verbcode|no-parse| is equivalent
to \verbcode|number=false|.

\begin{example}
    We get a total of \dEUR[number=false]{2\times \num[parse-numbers=true]{10000}}=\dEUR{20000}.

    We get a total of \dEUR[number=false]{2\times \num{10000}}=\dEUR{20000}.
\end{example}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Using styles}
\label{sec:styles}

Some styles are aldeary defined to shorten the typesetting. 
For example, \verbcode|@iso| expands to \verbcode|kind=iso|.
It
acts similarly for \verbcode|@sy| (or \verbcode|@symb|), \verbcode|@na| (or \verbcode|@name|) and \verbcode|@pl|
(or \verbcode|@plural|).

\begin{example}
    \dEUR[@iso]{10}; \dEUR[@symb]{10}; \dEUR[@name]{10}; \dEUR[@pl]{10}

    \dGBP{10} ; \dGBP[@symb]{10} ; \dGBP[@pl]{10} ; \dGBP{5}
\end{example}

A style \verbcode|no-parse| is also equivalent to \verbcode|number=false|.
\sinceversion{0.2}






%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%% TODO
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{To Do}

\begin{itemize}
    \item Store the values to use them later. 
    \item Automatic detection of plurals.
    \item Perform simple arithmetics.
    \item Behavior of \verbcode{detect-...} keys from \pkg{siunitx} with default argument.
    \item Internationalization using the \texttt{translations} packages \cite{translations}.
    \item Non decimal systems such as pounds, shillings, and pence.
    \item Column definition for a table.
    \item ...
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%% References 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\printbibliography


\end{document}