path: root/graphics/pgf/contrib/scsnowman/scsnowman.tex

%%
%% This is the documentation of scsnowman package.
%% (Last Update: 2018/01/15)
%% Maintained on GitHub:
%% https://github.com/aminophen/scsnowman
%%
%% Copyright (c) 2015-2018 Hironobu Yamashita
%%   Email   :  h.y.acetaminophen[a t]gmail.com
%%   GitHub  :  https://github.com/aminophen
%%   Blog    :  http://acetaminophen.hatenablog.com/
%%   Twitter :  @aminophen
%%
\documentclass[a4paper]{article}
\usepackage{doc}
\usepackage[svgnames]{xcolor}
\usepackage{scsnowman}
\pagenumbering{enumsnowman}
\GetFileInfo{scsnowman.sty}
\usepackage{array}
\usepackage{amsthm}
\usepackage{luatexja}
\usepackage{luatexja-fontspec}
\def\BigSnowman#1{\fontsize{60pt}{60pt}\selectfont\symbol{"#1}}
\newjfontfamily\fipam{IPAexMincho}
\newjfontfamily\fhrgnm{HiraMinProN-W3}
\newjfontfamily\fkozm{KozMinPr6N-Regular}
\newjfontfamily\fmsmin{MS-Mincho}
\newjfontfamily\fvlgo{VLGothic}
\usepackage{hyperref}
% documentation
\newtheorem{theorem}{Theorem}
% misc
\def\Lpack#1{\textsf{#1}}
\def\Lopt#1{\texttt{#1}}
% scsnowman in title
\scsnowmandefault{adjustbaseline,scale=2,hat=Green,buttons=RoyalBlue}
\def\scsnowmanleft{\scsnowman[arms=Brown,muffler=Red]}
\def\scsnowmanright{\scsnowman[snow=SkyBlue]}
\title{\scsnowmanleft\ The \Lpack{scsnowman} package \fileversion\ \scsnowmanright}
\author{Hironobu Yamashita}
\date{\filedate}
\begin{document}

\maketitle
\scsnowmandefault{}

The \LaTeX\ package \Lpack{scsnowman} provides a command \verb+\scsnowman+, which can display
many variants of snowmen. This package utilizes Ti\emph{k}Z for drawing snowmen.
\begin{figure}[htb]\centering
\scsnowmandefault{adjustbaseline}
\scsnowman[scale=5,hat,snow,arms]\scsnowman[scale=5,hat=RoyalBlue,muffler=Green]
\scsnowman[scale=2]\scsnowman[scale=5]\scsnowman[scale=7]\par
\scsnowmandefault{scale=6,hat,muffler=Red}
\scsnowman[mouthshape=smile]
\scsnowman[mouthshape=frown]
\scsnowman[mouthshape=tight]
\scsnowman[mouthshape=tight,arms,buttons,sweat]\\[2ex]
\scsnowmandefault{scale=5}
\begin{tabular}{ccc}
  \texttt{U+2603} & \texttt{U+26C4} & \texttt{U+26C7} \\
  \texttt{SNOWMAN} & \texttt{SNOWMAN WITHOUT SNOW} & \texttt{BLACK SNOWMAN} \\
  \scsnowman[body=false,snow=true] & \scsnowman[body=false,snow=false] & \scsnowman[body=true,snow=true]
\end{tabular}
\end{figure}

The package is maintained on GitHub:
\begin{itemize}
\item \url{https://github.com/aminophen/scsnowman}
\end{itemize}

\begin{figure}[htb]\centering
\scsnowmandefault{adjustbaseline,scale=8,buttons=RoyalBlue}
\scsnowman[hat=Green,muffler=Red,arms=Brown,buttons=Green,broom=DarkGoldenrod]
\scsnowman[hat=Green,body,muffler=Red,arms=Brown,nose=Orange,snow=SkyBlue]
\scsnowman[snow=SkyBlue,note=Red]
\scsnowman[hat=Green,muffler=RoyalBlue,arms=Brown,buttons=Green,broom=DarkGoldenrod]
\end{figure}

\clearpage
\tableofcontents\clearpage

\section{The History of Snowman in Unicode}

In October 1991, the first volume of the Unicode standard was published. Since then,
there was a code point assigned to a character ``snowman''; \verb:U+2603:.
\begin{quote}
  \verb:U+2603 SNOWMAN:\\
    = snowy weather
\end{quote}
It seems that the shape of its reference glyph in Unicode 1.0.0 was taken from ``Ryumin'',
which was developed by Morisawa (a famous font vendor in Japan).
\begin{figure}
%\includegraphics[width=0.3\textwidth]{}
\end{figure}
A few years later, the reference glyph has sometimes been changed to another; however,
there had been only one ``snowman'' in Unicode until 2009.
\begin{figure}
%\includegraphics[width=0.3\textwidth]{}
\end{figure}

In October 2009, Unicode 5.2 was published. In this volume, two ``snowman'' code points
were added; \verb:U+26C4: and \verb:U+26C7:.
\begin{quote}
  \verb:U+26C4 SNOWMAN WITHOUT SNOW:\\
    = light snow\\
  \verb:U+26C7 BLACK SNOWMAN:\\
    = heavy snow
\end{quote}
According to the code chart, the origin of these two characters is ARIB STD-B24
(Data Coding and Transmission Specification for Digital Broadcasting;\footnote{%
\url{http://www.arib.or.jp/tyosakenkyu/kikaku_hoso/hoso_std-b024.html}; Abstract in PDF format
(both \href{http://www.arib.or.jp/tyosakenkyu/kikaku_sample/sample-std-b24-1-6.3.pdf}{Japanese}
and \href{http://www.arib.or.jp/english/html/overview/doc/6-STD-B24v5_2-1p3-E1.pdf}{English}) are
available.}), which was established by Association of Radio Industries and Business in
Japan. Since then, it can be said that the old code point \verb:U+2603: has been given
an implicit meaning of ``\verb:SNOWMAN WITH SNOW:''. The reference glyphs were also changed
at that time.
\begin{figure}
%\includegraphics[width=0.3\textwidth]{}
\end{figure}

\section{Variation of Snowman among Actual Fonts}

Since the shapes of the reference glyphs used in the Unicode code charts are not
prescriptive, the actual fonts have a wide variety of glyph designs. However, when it
comes to snowmen, the variation between fonts is enormous. This variation is very
interesting, however, on the other hand, problematic.

Table \ref{table:actualfonts} shows the variety of ``snowman'' in actual fonts.
\begin{table}[tbp]
\caption{The variety of ``snowman'' in actual fonts}\label{table:actualfonts}
\setlength{\extrarowheight}{50pt}%
\centering
\begin{tabular}{cccc}
\hline
 & \raisebox{2ex}{\Large\texttt{U+2603}} & \raisebox{2ex}{\Large\texttt{U+26C4}} & \raisebox{2ex}{\Large\texttt{U+26C7}} \\ \hline
\raisebox{4ex}{\fipam IPAex明朝} & {\fipam \BigSnowman{2603}} &  &  \\
\raisebox{4ex}{\fmsmin ＭＳ 明朝} & {\fmsmin \BigSnowman{2603}} &  &  \\
\raisebox{4ex}{\fkozm 小塚明朝 Pr6N Regular} & {\fkozm \BigSnowman{2603}} &  &  \\
\raisebox{4ex}{\fhrgnm ヒラギノ明朝 ProN W3} & {\fhrgnm \BigSnowman{2603}} &  &  \\
\raisebox{4ex}{\fvlgo VLゴシック} & {\fvlgo \BigSnowman{2603}} & {\fvlgo \BigSnowman{26C4}} & {\fvlgo \BigSnowman{26C7}} \\
\hline
\end{tabular}
\end{table}
The snowman in ``IPA Mincho (IPA明朝)'' from Information-technology Promotion Agency is very similar
to the one in ``Ryumin (リュウミン)'' from Morisawa. However, in ``MS Mincho (ＭＳ 明朝)'' from Microsoft,
the snowman wears a black hat instead of white one. In ``Kozuka Mincho (小塚明朝)'' from Adobe Systems Inc.,
he/she wears a muffler instead of a hat. Moreover, it doesn't snow in ``Hiragino Mincho (ヒラギノ明朝)'' from
SCREEN Graphic and Precision Solutions Co., Ltd. It is natural that some fonts developed before 2009 have
a ``snowman without snow'' glyph in the code point \verb:U+2603:, however, it can be a problem when we
have to transfer the exact information to others.

\section{Introduction to \Lpack{scsnowman} Package}

The \LaTeX\ package \Lpack{scsnowman} provides a command  \verb+\scsnowman+, which can
display many variants of snowmen. This package depends on Ti\emph{k}Z package for drawing
snowman images.

To use this package, load it in preamble:
\begin{quote}\begin{verbatim}
\usepackage{scsnowman}
\end{verbatim}\end{quote}
In the main document, use \verb+\scsnowman+ command to print a snowman: \scsnowman.
By default, the snowman is ``plain'' style, without any decoration such as snow, a hat or
a muffler.

\section{Command Options}

You can customize the style of a snowman using the optional argument. The syntax is
\begin{quote}
\verb+\scsnowman[+\emph{$\langle$key-value list$\rangle$}\verb+]+
\end{quote}

\subsection{Scaling and Adjustment Options}

The following \emph{key}s are available:
\begin{quote}
  \Lopt{scale}, \Lopt{adjustbaseline}
\end{quote}
The key \Lopt{scale} takes a scale factor. The origin of scaling is set at the lower
left corner of the bounding box. For example, \verb+\scsnowman+,
\verb+\scsnowman[scale=3]+ and \verb+\scsnowman[scale=5]+ give:
\begin{quote}\begin{minipage}{.9\textwidth}
\scsnowman\scsnowman[scale=3]\scsnowman[scale=5]\quad
with visualized bounding boxes:
\fboxsep0pt\fbox{\scsnowman}\fbox{\scsnowman[scale=3]}\fbox{\scsnowman[scale=5]}
\end{minipage}\end{quote}
When the key \Lopt{adjustbaseline} is specified (or, \Lopt{adjustbaseline=true}),
the base line of the in-line snowman will be adjusted to that of the surrounding texts.
This will be helpful when a snowman appears to be ``floating in the air.''\\[1ex]
\begin{minipage}{.55\textwidth}\begin{verbatim}
  Text,
  \scsnowman[scale=1]%
  \scsnowman[scale=4]%
  \scsnowman[scale=7],
  T.\par
  Text,
  \scsnowman[adjustbaseline,scale=1]%
  \scsnowman[adjustbaseline,scale=4]%
  \scsnowman[adjustbaseline,scale=7],
  T.
\end{verbatim}\end{minipage}
\begin{minipage}{.4\textwidth}
  Text,
  \scsnowman[scale=1]%
  \scsnowman[scale=4]%
  \scsnowman[scale=7],
  T.\par
  Text,
  \scsnowman[adjustbaseline,scale=1]%
  \scsnowman[adjustbaseline,scale=4]%
  \scsnowman[adjustbaseline,scale=7],
  T.
\end{minipage}

\subsection{Design Options}

Following \emph{key}s take a \emph{value} which specifies color. When the \emph{value} is omitted,
it reacts to the surrounding text color:
\begin{quote}
  \Lopt{body}, \Lopt{eyes}, \Lopt{mouth}, \Lopt{nose}, \Lopt{sweat}, \Lopt{arms},
  \Lopt{hat}, \Lopt{muffler}, \Lopt{buttons}, \Lopt{snow}, \Lopt{note}, \Lopt{broom}
\end{quote}
The following \emph{key}s require one specific \emph{value}:
\begin{quote}
  \Lopt{shape}, \Lopt{mouthshape}
\end{quote}

The key \Lopt{shape} specifies the outline shape of the snowman body.
Currently, only \Lopt{shape=normal} is officially available, but you can define and use other shapes
using \verb+\usescsnowmanlibrary+ command (described later, section \ref{usescsnowmanlibrary}).

The key \Lopt{mouthshape} takes one of the followings: \Lopt{smile}, \Lopt{tight} or \Lopt{frown}.

Here are some examples:\\[1ex]
\begin{minipage}{.7\textwidth}\begin{verbatim}
  \scsnowman[scale=2,body,hat=red,muffler=blue]
  \scsnowman[scale=3,hat,snow,arms,buttons,note]
  \scsnowman[scale=2,muffler=red,arms,broom=brown]
  \scsnowman[scale=2,mouthshape=frown,hat=green]
\end{verbatim}\end{minipage}
\begin{minipage}{.25\textwidth}
  \scsnowman[scale=2,body,hat=red,muffler=blue]
  \scsnowman[scale=3,hat,snow,arms,buttons,note]
  \scsnowman[scale=2,muffler=red,arms,broom=brown]
  \scsnowman[scale=2,mouthshape=frown,hat=green]
\end{minipage}\\[1ex]
\begin{minipage}{.7\textwidth}\begin{verbatim}
 {\color{blue}
  \scsnowman[scale=2,body,hat=red,muffler=blue]
  \scsnowman[scale=2,hat,snow,arms,buttons,note]
  \scsnowman[scale=3,muffler=red,arms,broom=brown]
  \scsnowman[scale=2,mouthshape=frown,hat=green]}
\end{verbatim}\end{minipage}
\begin{minipage}{.25\textwidth}
 {\color{blue}
  \scsnowman[scale=2,body,hat=red,muffler=blue]
  \scsnowman[scale=2,hat,snow,arms,buttons,note]
  \scsnowman[scale=3,muffler=red,arms,broom=brown]
  \scsnowman[scale=2,mouthshape=frown,hat=green]}
\end{minipage}

\section{Changing the Default}

The package default is the ``plain'' style snowman. This default can be changed by using
\verb+\scsnowmandefault+ command. The syntax is
\begin{quote}
\verb+\scsnowmandefault{+\emph{$\langle$key-value list$\rangle$}\verb+}+
\end{quote}
The available \emph{key}s are the same as those in \verb+\scsnowman+.

Here are some examples:\\[1ex]
\begin{minipage}{.6\textwidth}\begin{verbatim}
  \scsnowmandefault{scale=5,hat=red}
  \scsnowman
  \scsnowman[body,muffler=blue,arms]
  \scsnowman[hat=green,snow,nose=orange]
\end{verbatim}\end{minipage}
\begin{minipage}{.35\textwidth}
  \scsnowmandefault{scale=5,hat=red}
  \scsnowman
  \scsnowman[body,muffler=blue,arms]
  \scsnowman[hat=green,snow,nose=orange]
\end{minipage}

\section{Adding User-defined Snowman Shapes}\label{usescsnowmanlibrary}

Any users can define and use custom snowman shape definitions.
Here is a description of adding a shape named \Lopt{myfavorite}.
\begin{enumerate}
  \item Prepare a snowman definition file \texttt{scsnowman-myfavorite.def}
    and put it into \verb+$TEXMF+ tree (e.g. \verb+texmf-local/tex/latex/scsnowman/+).
    For the format of snowman definition files, please refer to \texttt{scsnowman-normal.def}.
  \item Use \verb+\usescsnowmanlibrary+ command (don't forget \emph{sc}!) to load it.
\begin{verbatim}
  \usepackage{scsnowman}
  \usescsnowmanlibrary{myfavorite}
\end{verbatim}
  \item You can use the shape by \verb+\scsnowman[shape=myfavorite]+ command.
\end{enumerate}
If you have created a fancy snowman, please contact me, so that I can incorporate it
into the official release!

\section{Funny Usages}

\subsection{Changing Item Labels and QED Symbols}

For those who want more snowmen in the documents, currently \Lpack{scsnowman} provides
the following additional commands:
\begin{quote}
\verb+\makeitemsnowman+:\\
  \makeitemsnowman
  Change item labels in \Lopt{itemize} environment to snowmen
  {\labelitemi\labelitemii\labelitemiii\labelitemiv}.
  \makeitemother
  The command \verb+\makeitemother+ restores the default,
  usually {\labelitemi\labelitemii\labelitemiii\labelitemiv}.\par
\verb+\makeqedsnowman+:\\
  \makeqedsnowman
  Change the QED symbol in \Lopt{proof} environment to a snowman {\qedsymbol}.
  The package \Lpack{amsthm} is required.
  \makeqedother
  The command \verb+\makeqedother+ restores the default, usually {\qedsymbol}.
\end{quote}
These commands can be used wherever you want, and are effective within the current group.

Here are some examples:\\[1ex]
\begin{minipage}{.5\textwidth}\begin{verbatim}
  \begin{itemize}
    \makeitemsnowman
    \item Foo X.
    \begin{itemize}
      \item Bar A.
      \begin{itemize}
        \item Baz P. \item Baz Q.
      \end{itemize}
      \item Bar B. \item Bar C.
    \end{itemize}
  \end{itemize}
\end{verbatim}\end{minipage}
\begin{minipage}{.45\textwidth}
  \begin{itemize}
    \makeitemsnowman
    \item Foo X.
    \begin{itemize}
      \item Bar A.
      \begin{itemize}
        \item Baz P. \item Baz Q.
      \end{itemize}
      \item Bar B. \item Bar C.
    \end{itemize}
  \end{itemize}
\end{minipage}\\[1ex]
\begin{minipage}{.55\textwidth}\begin{verbatim}
  \makeqedsnowman
  \begin{theorem}
  Given two line segments whose
  lengths are $a$ and $b$ respectively,
  there is a real number $r$ such that
  $b=ra$.
  \end{theorem}
  \begin{proof}
  To prove it by contradiction try and
  asuume that the statement is false,
  proceed from there and at some point
  you will arrive to a contradiction.
  \end{proof}
\end{verbatim}\end{minipage}
\begin{minipage}{.45\textwidth}
  \makeqedsnowman
  \begin{theorem}
  Given two line segments whose
  lengths are $a$ and $b$ respectively,
  there is a real number $r$ such that
  $b=ra$.
  \end{theorem}
  \begin{proof}
  To prove it by contradiction try and
  asuume that the statement is false,
  proceed from there and at some point
  you will arrive to a contradiction.
  \end{proof}
\end{minipage}\medskip

The names of these commands are, of course, named after the \LaTeX\ \verb+\makeatletter+
and \verb+\makeatother+;-)

\subsection{Drawing ``\emph{Kagami-mochi}''}

Using \Lpack{scsnowman} package, you can also draw ``\emph{kagami-mochi}''
(mirror rice cake). It is a traditional Japanese New Year decoration,
which usually consists of two round ``\emph{mochi}'' (rice cakes), the smaller
placed atop the larger, and a ``\emph{daidai}'' (a Japanese bitter orange)
with an attached leaf on top.

Following \emph{key}s are implemented for this usage:\footnote{Strictly speaking,
the orange on top of rice cakes should be ``\emph{daidai}''; however,
a ``\emph{mikan}'' is often substituted for the original ``\emph{daidai}''.}
\begin{quote}
  \Lopt{mikan}, \Lopt{leaf}
\end{quote}
The \emph{key} \Lopt{leaf} is effective only when \Lopt{mikan} is specified.
Here is an example:\\[1ex]
\begin{minipage}{.85\textwidth}\begin{verbatim}
  \scsnowmandefault{scale=5.5}
  \scsnowman[eyes=false,mouth=false,mikan=orange,leaf=green]
\end{verbatim}\end{minipage}
\begin{minipage}{.1\textwidth}
  \scsnowmandefault{scale=5.5}
  \scsnowman[eyes=false,mouth=false,mikan=orange,leaf=green]
\end{minipage}

\subsection{Replacing All ``8'' with Snowmen}

You can replace all ``8'' inside an arabic number expression with snowmen
\scsnowman\ by using \verb+\scsnowmannumeral+.
Here is an example:\\[1ex]
\begin{minipage}{.85\textwidth}\begin{verbatim}
  \scsnowmandefault{adjustbaseline}\scsnowmannumeral{18882}
  \scsnowmannumeral[muffler=blue,scale=1.5]{4283859}
\end{verbatim}\end{minipage}
\begin{minipage}{.1\textwidth}
  \scsnowmandefault{adjustbaseline}\scsnowmannumeral{18882}
  \scsnowmannumeral[muffler=blue,scale=1.5]{4283859}
\end{minipage}\medskip

You can also replace all ``8'' inside the page numbering with snowmen
\scsnowman\ by adding \verb+\pagenumbering{enumsnowman}+.
This documentation itself is an example!

\clearpage

\section*{Version History}

This is the summary of changes. For more detail, see GitHub repository.
\begin{table}[h]
\centering
\begin{tabular}{lll}
Version 0.1 & 2015-12-13 & First public version on GitHub \\
Version 0.8 & 2016-08-08 & Second public version on GitHub: \\
            &            & new variants \Lopt{buttons}, \Lopt{mouthshape}, \Lopt{sweat} are added \\
Version 1.0 & 2016-12-22 & First CTAN release \\
Version 1.1 & 2017-01-22 & Add a new key \Lopt{adjustbaseline} \\
            &            & Update documentation \\
Version 1.2 & 2017-08-08 & Default color reacts to surrounding text color \\
            &            & Support vertical writing on (u)p\TeX\ and Lua\TeX-ja \\
            &            & Add a new key \Lopt{shape} \\
            &            & Add a new command \verb+\usescsnowmanlibrary+ \\
Version 1.2a & 2017-11-25 & Fix a bug in scaling with \Lopt{adjustbaseline} \\
Version 1.2b & 2018-01-05 & Add new keys \Lopt{mikan}, \Lopt{leaf} for drawing `kagami-mochi' \\
             &            & Stopped loading \Lpack{amsthm} by default \\
Version 1.2c & 2018-01-15 & Add a new key \Lopt{broom} \\
Version 1.2d & 2018-06-07 & Add new keys \Lopt{nose}, \Lopt{note} \\
             &            & Add a new command \verb+\scsnowmannumeral+ \\
\end{tabular}
\end{table}

\begin{thebibliography}{9}
\bibitem{NAOI1}
\href{http://d.hatena.ne.jp/NAOI/20080623/1214211959}{雪だるまの親子関係}
\ --- Mac OS Xの文字コード問題に関するメモ
\bibitem{NAOI2}
\href{http://d.hatena.ne.jp/NAOI/20110707/1310031226}{ヒラギノの雪だるまは、なぜ寂しそうなのか}
\ --- Mac OS Xの文字コード問題に関するメモ
\bibitem{DORA1}
\href{http://doratex.hatenablog.jp/entry/20140327/1395878814}{いろいろなゆきだるま}
\ --- TeX Alchemist Online
\bibitem{ACE1}
\href{http://acetaminophen.hatenablog.com/entry/2014/09/05/090313}{「\TeX{}でゆきだるま」をもっとたくさん}
\ --- Acetaminophen's diary
\bibitem{ZR1}
\href{http://d.hatena.ne.jp/zrbabbler/20140911/1410439004}{Unicodeの例の雪だるまは多分アレ}
\ --- マクロツイーター
\bibitem{ACE2}
\href{http://acetaminophen.hatenablog.com/entry/2015/12/13/080226}{\TeX{}でゆきだるまを“もっともっと”たくさん}
\ --- Acetaminophen's diary
\bibitem{ACE3}
\href{http://acetaminophen.hatenablog.com/entry/2016/08/08/080800}{夏といえば、やっぱり「ゆきだるま」！}
\ --- Acetaminophen's diary
\bibitem{SX229957}
\href{http://tex.stackexchange.com/questions/229957/}{How do I redefine the QED symbol to be a Unicode character?}
\ --- \TeX\ -- \LaTeX\ Stack Exchange
\end{thebibliography}

\end{document}