% LuaLaTeX document; UTF-8
\documentclass[a4paper]{article}
\usepackage[scale=0.75]{geometry}
\usepackage{shortvrb}
\MakeShortVerb{\|}
\newcommand{\PkgVersion}{0.7}
\newcommand{\PkgDate}{2023/07/07}
\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
(2022/8/28) to the Japanese rendering of the Japanese calendar
(\Ja{令和\+4\+年\+8\+月\+28\+日}).
You can choose whether the numbers are written
in Western numerals (like 28)
or kanji numerals (\emph{kansuji}, like \Ja{二八}).

Note that the package only deals with dates in the year 1873 or later,
where the Japanese calendar (\emph{wareki}; \Ja{和暦})
can be regarded as a variant of Gregorian calendar
with the different notation of years.

\Note 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{西暦}).

\paragraph{System requirement}

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

This package is designed to be very generic,
and it could work on engines other than those mentioned above.
Starting from v0.7,
when the package \emph{knows} that it cannot properly handle
kanji characters on the engine in use,
then it will switch to the ``fallback mode'',
where all kanji characters are replaced with a `?' symbol.
Users can use |\WarekiIfAvailable| to know
whether the package really works.
It is expected
that this package never fails on load.

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

No options are available.

\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.
  This command itself prints nothing
  and the result will be rendered by the commands described
  at the following items, where the result for the invocation
  |\warekisetdate{2022}{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{4}''.

  \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 (\Ja{元号}) in kanji, \Eg~``\Ja{令和}''.

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

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

  \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{令和\+4\+年\+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{2022\+年\+8\+月\+28\+日}'' (using the Western calendar).
  The available option letters are:
  \begin{itemize}
  \item |w|\Means
    uses Japanese calendar (\Ja{2022\+年} $\to$ \Ja{令和\+4\+年});
  \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}

There are also handy commands solely for printing the 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 spaces}

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}:
  A tie (|~|) is inserted,
  on the assumption that the \Pkg{CJK} package is employed
  and |\CJKtilde| is in effect.
\end{itemize}

The command for shibuaki can be changed with the following commands:
\begin{itemize}
\item |\WarekiUseNormalInterGlue|\Means
  Uses the normal setting, as mentioned above.
\item |\WarekiUseNoInterGlue|\Means
  Disables shibuaki spaces.
\item |\WarekiUseCustomInterGlue{|\Meta{text}|}|\Means
  Uses \Meta{text} for making shibuaki spaces.
  \Note This command is supported
  only on engines with {\eTeX} extension.
\end{itemize}

%-------------------
\subsection{Counter output commands}

The following commands are intended
to use with |warekiyear| counter,
but they can probably be used
as general-use counter output commands
(like |\arabic|):
\begin{itemize}
\item |\WarekiKansuji{|\Meta{counter}|}|\Means
  Prints the counter value using kansuji.
\item |\WarekiJKansuji{|\Meta{counter}|}|\Means
  Prints the counter value using kansuji-by-reading.
  Only valid for numbers less than 1000.
\end{itemize}

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

%-------------------
\subsection{Expandability of the commands}

\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 When |\WarekiUseCustomInterGlue| is used with some argument,
  the content of |\wareki...date| and |\wareki...today|
  could contain some occurrences of the argument.
  If the argument is fully expandable,
  the commands are still fully expandable
  on the engines with native kanji/Unicode support.
\end{itemize}

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