summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/bxwareki/bxwareki.tex
blob: 5fa41fcc26c19e3a57f1181bc4d739715b564644 (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
% LuaLaTeX document; UTF-8
\documentclass[a4paper]{article}
\usepackage[scale=0.75]{geometry}
\usepackage{shortvrb}
\MakeShortVerb{\|}
\newcommand{\PkgVersion}{0.5}
\newcommand{\PkgDate}{2019/04/01}
\newcommand{\Pkg}[1]{\textsf{#1}}
\newcommand{\Meta}[1]{$\langle$\textit{#1}$\rangle$}
\newcommand{\Note}{\par\noindent\emph{Note:}\quad}
\newcommand{\Ie}{i.\,e.}
\newcommand{\Eg}{e.\,g.}
\newcommand{\Means}{~:\quad}
\usepackage{bxtexlogo}
\bxtexlogoimport{*,ApTeX,JTeX}
% Japanese something
\usepackage{fontspec}
\newfontfamily{\fIpaex}{IPAexMincho}[Scale=0.95]
\newcommand*{\Ja}[1]{{\fIpaex#1}}
\newcommand*{\+}{\hspace{0.25em minus 0.25em}}
%-----------------------------------------------------------
\begin{document}
\title{The \Pkg{bxwareki} package}
\author{Takayuki YATO\quad (aka.~``ZR'')}
\date{v\PkgVersion \quad[\PkgDate]}
\maketitle

%===========================================================
\section{Overview}
\label{sec:Overview}

This package provides commands to convert from the Gregorian calendar
(2018/8/28) to the Japanese rendering of the Japanese calendar
(\Ja{平成\+30\+年\+8\+月\+28\+日}).
You can choose whether the numbers are written
in Western numerals (28) or kanji numerals (\Ja{二八}).

Note that the package only deals with dates in the year 1873 or later,
where the Japanese calendar is really a Gregorian calendar
with the different notation of years.

\paragraph{System requirement}

\begin{itemize}
\item \TeX{} format: \LaTeX.
\item \TeX{} engine: {\pdfTeX}, {\LuaTeX}, {\XeTeX},
  {\pTeX}, {\upTeX}, {\ApTeX} ({\pTeX}-ng), NTT-{\JTeX}.
\end{itemize}

\Note The modern (post-1873) Japanese calendar (\emph{wareki}; \Ja{和暦})
can be regarded as a variant of Gregorian calendar
where only the notation of years differs from the original.
To avoid confusion, this document refers to the original Gregorian
calendar as the \emph{Western calendar},
which corresponds to the Japanese term \emph{seireki} (\Ja{西暦}).

%===========================================================
\section{Package Loading}
\label{sec:Loading}

No options are needed in normal use%
\footnote{See Section~\ref{ssec:download2019}
  for the \texttt{download2019} option.}.

\begin{quote}\small\begin{verbatim}
\usepackage{bxwareki}
\end{verbatim}\end{quote}

%===========================================================
\section{Usage}
\label{sec:Usage}

%-------------------
\subsection{Conversion from the given date}

\begin{itemize}
\item |\warekisetdate{|\Meta{year}|}{|\Meta{month}|}{|\Meta{day}|}|\Means
  Converts from the specified Western date.
  The result will be rendered by the commands described
  at the following items, where the result for the invocation
  |\warekisetdate{2018}{8}{28}|
  will be shown as example.

  \Note Although the Japanese calendar differs from the Western calendar
  only in the notation of years,
  the value of months and days are still required,
  since the notation of the year in which
  \emph{kaigen} (\Ja{改元}; change of gengo)
  occurs depends on months and days.

\item |\warekisettoday|\Means
  Does |\warekisetdate| with the current date.

\item Counter |warekiyear|\Means
  The year number (within the gengo); \Eg~``\Ja{30}''.

  \Note Unlike ordinary counters,
  the assignment to |warekiyear| by |\warekisetdate| is \emph{local}.
  Moreover, manual assignment to this counter is not supported.

\item |\warekigengo|\Means
  The gengo in kanji, \Eg~``\Ja{平成}''.

\item |\warekigengoinitial|\Means
  The initial Latin letter of the gengo, \Eg~``\Ja{H}''.

\item |\warekiyear|\Means
  The full notation of the year (without `\Ja{年}'),
  \Eg~``\Ja{平成\+30}''.

  \Note When the year number is one,
  the kanji `\Ja{元}' is used instead of the numeral `\Ja{1}'.

\item |\warekidate|\Means
  The date string, \Eg~``\Ja{平成\+30\+年\+8\+月\+28\+日}''.

\item |\warekikanjidate|\Means
  The date string using kansuji (kanji numerals),
  \Eg~``\Ja{平成三〇年八月二八日}''.

\item |\warekijkanjidate|\Means
  The date string using ``kansuji-by-reading''
  (that is, kanji rendering of numbers in the Japanese language),
  \Eg.``\Ja{平成三十年八月二十八日}''.

\item |\warekicustomdate{|\Meta{option}|}|\Means
  The date string in the form specified with the option.
  The option is a string of letters such as |wk|
  and each letter means a specific setting.
  When the option is empty, the date is rendered in the form
  ``\Ja{2018\+年\+8\+月\+28\+日}'' (using the Western calendar).
  The available option letters are:
  \begin{itemize}
  \item |w|\Means
    uses Japanese calendar (\Ja{2018\+年} $\to$ \Ja{平成\+30\+年});
  \item |k|\Means
    uses kansuji (\Ja{28} $\to$ \Ja{二八});
  \item |j|\Means
    uses kansuji-by-reading (\Ja{28} $\to$ \Ja{二十八});
    \par\smallskip
    \Note Western years does not support kansuji-by-reading
    and thus |k| will be applied instead
    (\Ja{二〇一八}, not \Ja{二千十八}).
  \item |J|\Means
    variant of |j| where ``ten's multiple'' kanji characters
    (\Ja{廿} and \Ja{卅}) are employed (\Ja{28} $\to$ \Ja{廿八});
  \item |o|\Means
    uses \emph{imyo} (\Ja{異名}) for months%
    \footnote{Don't ask me if this form is ever used in {\LaTeX} document!}
    (\Ja{8\+月} $\to$ \Ja{葉月}).
  \end{itemize}

  \Note This command is supported only on {\pdfLaTeX}, {\XeLaTeX},
  {\LuaLaTeX}, {\upLaTeX}, {Ap\LaTeX} and recent versions of {\pLaTeX}.
  On other engines it simply falls back to |\warekidate|.

\item |\WarekiIfCustomDateAvailable{|\Meta{true}|}{|\Meta{false}|}|\Means
  Tests if the command |\warekicustomdate| is
  supported on the engine in use.
\end{itemize}

%-------------------
\subsection{Current date}

These commands always represent the current date,
and are not affected by |\warekisetdate| (or |\warekisettoday|).

\begin{itemize}
\item |\warekitoday|\Means
  The |\warekidate| form of the current date.
\item |\warekikanjitoday|\Means
  The |\warekikanjidate| form.
\item |\warekijkanjitoday|\Means
  The |\warekijkanjidate| form.
\end{itemize}

%-------------------
\subsection{Inter-alphabet-kanji glues}

In quality Japanese typesetting, a thin space
(\emph{shibuaki}; \Ja{四分空き}) must be inserted
between an alphabet letter and a kanji letter.
This package by default inserts a command
suitable for the most prevalent Japanese-typesetting environment
for the engine in use.

\begin{itemize}
\item On {\pLaTeX}, {\upLaTeX} and {Ap\LaTeX}:
  Nothing is inserted,
  since the engine can automatically insert shibuaki spaces.
\item On {\LuaLaTeX} and {\XeLaTeX}:
  Nothing is inserted,
  on the assumption that the package for Japanese typesetting
  (such as \Pkg{\LuaTeX-ja} and \Pkg{xeCJK})
  will automatically insert shibuaki spaces.
\item On {\LaTeX} and {\pdfLaTeX}:
  |~| is inserted,
  on the assumption that the \Pkg{CJK} package is employed
  and |\CJKtilde| is in effect.
\end{itemize}

On the engines with {\eTeX} extension,
the command for shibuaki can be changed with the following commands:
\begin{itemize}
\item |\WarekiUseCustomInterGlue{|\Meta{text}|}|\Means
  Uses \Meta{text} for making shibuaki spaces.
\item |\WarekiUseNormalInterGlue|\Means
  Reverts |\WarekiUseCustomInterGlue|
  and uses the normal setting.
\end{itemize}

%===========================================================
\section{Support for the kaigen planned in 2019}
\label{sec:Kaigen}

In Japan a kaigen (due to the abdication of the Emperor)
is planned on 2019/05/01,
and the new gengo ``\Ja{令和}'' has been announced in advance.
(The announcement was made on 2019/04/01.)
Thus this package has been updated to support the new gengo.

%-------------------
\subsection{The \texttt{download2019} option}
\label{ssec:download2019}

\begin{quote}\itshape
This function is no longer necessary,
since the new gengo is supported by default in the current version.
The function will be removed in near future.
\end{quote}

Instead of manually downloading the new version from CTAN,
you can get the support for the new gengo
with a single run of {\LaTeX}
(of course after the annoucement of the gengo):
when you compile a document which loads this package
with |download2019| option using {\LuaLaTeX}
with \emph{full shell escape} enabled%
\footnote{In most system, full shell escape is enabled
  by \texttt{-shell-escape} option.},
then the run will download an additional file
from the package's GitHub repository
and install it into the user's TEXMF tree.

In short: make the following dummy%
\footnote{Using the dummy document with minimal content
could reduce the risk of using full shell escape,
but you need to trust me, of course.}
document file (named |dummy.tex|)
\begin{quote}\small\begin{verbatim}
\documentclass{article}
\usepackage[download2019]{bxwareki}
\stop
\end{verbatim}\end{quote}
and run |lualatex -shell-escape dummy|.
After that, the new gengo will be supported
on any engine, without shell escape.

%===========================================================
\section{Notices for {\TeX} programmers}
\label{sec:Allez}

\begin{itemize}
\item On the engines with native kanji/Unicode support
  (\Ie~{\LuaLaTeX}, {\XeLaTeX}, {\pLaTeX}, {\upLaTeX}, and {Ap\LaTeX}),
  the content (one-level expansion) of |\wareki...date|
  (except |\warekicustomdate|) and |\wareki...today|
  is a simple string of character tokens,
  unless |\WarekiUseCustomInterGlue| is in effect.
  The same holds for {\LaTeX} and {\pdfLaTeX},
  except that each kanji character is
  represented by the sequence of activated byte tokens
  and |~| is inserted as shibuaki spaces.
\item On the engines with native kanji/Unicode support,
  |\warekicustomdate| fully expands to a simple string
  of character tokens
  (again without |\WarekiUseCustomInterGlue|),
  and the situation on {\LaTeX} and {\pdfLaTeX}
  is parallel to that described at the previous item.
\item The use of |\WarekiUseCustomInterGlue|
  does not break the full expandability
  of |\wareki...date| and |\wareki...today|
  on the engines with native kanji/Unicode support.
\end{itemize}

%===========================================================
\end{document}