summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/bxwareki
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-10-02 01:05:54 +0000
committerKarl Berry <karl@freefriends.org>2018-10-02 01:05:54 +0000
commitce46cfeac58868701de09c0e4a836a9bbbdcf049 (patch)
tree02f2a68c1c6171442ea3d5a7858c11176e2f98b6 /Master/texmf-dist/doc/latex/bxwareki
parent60e8c3cc3a1065efdbecf837cd389599f261e588 (diff)
bxwareki (1oct18) [recommit]
git-svn-id: svn://tug.org/texlive/trunk@48799 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/bxwareki')
-rw-r--r--Master/texmf-dist/doc/latex/bxwareki/README.md135
-rw-r--r--Master/texmf-dist/doc/latex/bxwareki/bxwareki.pdfbin0 -> 192795 bytes
-rw-r--r--Master/texmf-dist/doc/latex/bxwareki/bxwareki.tex286
3 files changed, 290 insertions, 131 deletions
diff --git a/Master/texmf-dist/doc/latex/bxwareki/README.md b/Master/texmf-dist/doc/latex/bxwareki/README.md
index 637f814a7b7..14367e7e6ca 100644
--- a/Master/texmf-dist/doc/latex/bxwareki/README.md
+++ b/Master/texmf-dist/doc/latex/bxwareki/README.md
@@ -30,142 +30,15 @@ This package is distributed under the MIT License.
The bxwareki Package ― main
----------------------------
-Note: The modern (post-1873) Japanese calendar (*wareki*; 和暦) 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 *Western calendar*, which
-corresponds to the Japanese term *seireki* (西暦).
-
-### Package Loading
-
- \usepackage{bxwareki}
-
-### Usage
-
-#### Conversion from the given date
-
- * `\warekisetdate{<year>}{<month>}{<day>}`: 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 *kaigen* (改元;
- change of gengo) occurs depends on months and days.
-
- * `\warekisettoday`: Does `\warekisetdate` with the current date.
-
- * Counter `warekiyear`: The year number (within the gengo); e.g. 30.
-
- Note: Unlike ordinary counters, the assignment to `warekiyear` by
- `\warekisetdate` is *local*. Moreover, manual assignment to this
- counter is not supported.
-
- * `\warekigengo`: The gengo in kanji, e.g. “平成”.
-
- * `\warekiyear`: The full notation of the year (without ‘年’),
- e.g. “平成30”.
-
- Note: When the year number is one, the kanji ‘元’ is used instead
- of the numeral ‘1’.
-
- * `\warekidate`: The date string, e.g. “平成30年8月28日”.
-
- * `\warekikanjidate`: The date string using kansuji (kanji numerals),
- e.g. “平成三〇年八月二八日”.
-
- * `\warekijkanjidate`: The date string using “kansuji-by-reading”
- (that is, kanji rendering of numbers in the Japanese language),
- e.g. “平成三十年八月二十八日”.
-
- * `\warekicustomdate{<option>}`: 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 “2018年8月28日” (using the Western
- calendar). The available option letters are:
-
- - `w`: uses Japanese calendar (2018年 → 平成30年)
- - `k`: uses kansuji (28 → 二八)
- - `j`: uses kansuji-by-reading (28 → 二十八)
- Note: Western years does not support kansuji-by-reading and thus
- `k` will be applied instead (二〇一八, not 二千十八)
- - `J`: variant of `j` where “ten’s multiple” kanji characters
- (廿 and 卅) are employed (28 → 廿八)
- - `o`: uses *imyo* (異名) for months (8月 → 葉月)
- (Don’t ask me if this form is ever used in LaTeX document!)
-
- Note: This command is supported only on pdfLaTeX, XeLaTeX, LuaLaTeX,
- upLaTeX, ApLaTeX and recent versions of pLaTeX. On other engines it
- simply falls back to `\warekidate`.
-
- * `\WarekiIfCustomDateAvailable{<true>}{<false>}`: Tests if the command
- `\warekicustomdate` is supported on the engine in use.
-
-#### Current date
-
-These commands always represent the current date, and are not affected
-by `\warekisetdate` (or `\warekisettoday`).
-
- * `\warekitoday`: The `\warekidate` form of the current date.
- * `\warekikanjitoday`: The `\warekikanjidate` form.
- * `\warekijkanjitoday`: The `\warekijkanjidate` form.
-
-#### Inter-alphabet-kanji glues
-
-In quality Japanese typesetting, a thin space (*shibuaki*; 四分空き)
-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.
-
- * On pLaTeX, upLaTeX and ApLaTeX: Nothing is inserted, since the engine
- can automatically insert shibuaki spaces.
- * On LuaLaTeX and XeLaTeX: Nothing is inserted, on the assumption that
- the package for Japanese typesetting (such as LuaTeXja and xeCJK)
- will automatically insert shibuaki spaces.
- * On LaTeX and pdfLaTeX: `~` is inserted, on the assumption that the
- CJK package is employed and `\CJKtilde` is in effect.
-
-On the engines with e-TeX extension, the command for shibuaki can be
-changed with the following commands:
-
- * `\WarekiUseCustomInterGlue{<text>}`: Uses `<text>` for making shibuaki
- spaces.
- * `\WarekiUseNormalInterGlue`: Reverts `\WarekiUseCustomInterGlue` and
- uses the normal setting.
-
-### Support for the kaigen planned in 2019
-
-In Japan a kaigen (due to the abdication of the Emperor) is planned on
-2019/05/01, but the new gengo is not yet announced. Thus in the current
-version of the package, the date of the day or later is not supported
-(the Western year will be printed instead).
-.
-This package will be updated to support the new gengo and uploaded to
-CTAN, as soon as the new gengo is announced.
-
-### Notices for TeX programmers
-
- * On the engines with support for native kanji/Unicode characters
- (i.e. LuaLaTeX, XeLaTeX, pLaTeX, upLaTeX, and ApLaTeX), 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.
- * 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 item above.
- * The use of `\WarekiUseCustomInterGlue` does not break the full
- expandability of `\wareki…date` and `\wareki…today` on the engines
- with native kanji/Unicode support.
+See the manual `bxwareki.pdf` for detail.
Revision History
----------------
+ * Version 0.4 ‹2018/10/01›
+ - Add `\warekigengoinitial`.
+ - Add option `download2019`.
* Version 0.3 ‹2018/09/24›
- The total rewrite.
* Version 0.2 ‹2018/04/08›
diff --git a/Master/texmf-dist/doc/latex/bxwareki/bxwareki.pdf b/Master/texmf-dist/doc/latex/bxwareki/bxwareki.pdf
new file mode 100644
index 00000000000..02f5b8a159b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/bxwareki/bxwareki.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/bxwareki/bxwareki.tex b/Master/texmf-dist/doc/latex/bxwareki/bxwareki.tex
new file mode 100644
index 00000000000..e05dbdf9342
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/bxwareki/bxwareki.tex
@@ -0,0 +1,286 @@
+% LuaLaTeX document; UTF-8
+\documentclass[a4paper]{article}
+\usepackage[scale=0.75]{geometry}
+\usepackage{shortvrb}
+\MakeShortVerb{\|}
+\newcommand{\PkgVersion}{0.4}
+\newcommand{\PkgDate}{2018/10/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,
+but the new gengo is not yet announced.
+Thus in the current version of the package,
+the date of the day or later is not supported
+(the Western year will be printed instead).
+
+This package will be updated to support the new gengo
+and uploaded to CTAN,
+as soon as the new gengo is announced.
+
+%-------------------
+\subsection{The \texttt{download2019} option}
+\label{ssec:download2019}
+
+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}