\documentclass[full]{l3doc}
\usepackage[scheme=chinese]{ctex}
\usepackage{geometry}
\usepackage{fancyvrb-ex}
\usepackage{ninecolors}
\usepackage{suanpan-l3}

\IndexPrologue
  {
    % \section*{索引}
    % \markboth{索引}{索引}
    % \addcontentsline{toc}{section}{索引}
    % 斜体数字说明了对应索引内容出现的页码，
    % 带有下划线的数据给出了索引内容的定义，
    % 其它的数字给出了索引内容引用的位置。
    \section*{Index}
    \markboth{Index}{Index}
    \addcontentsline{toc}{section}{Index}
    The~italic~numbers~denote~the~pages~where~the~
    corresponding~entry~is~described,~
    numbers~underlined~point~to~the~definition,~
    all~others~indicate~the~places~where~it~is~used.
  }

\newcommand\tikzmark[1]{\tikz \coordinate[overlay, remember picture] (#1);}

\geometry{
  left=4.5cm,
  right=2cm,
  top=2cm,
  bottom=2cm,
}
\hypersetup {
  CJKbookmarks,
  bookmarksopen,
  bookmarksopenlevel=3,
  pdfstartview=FitH,
  pdfinfo = {
   Title = 中国传统7珠圆珠算盘排版宏包 ,
   Subject = A LaTeX3 package ,
   Author = 耿楠
 }
}

\DoNotIndex{\begin, \end}
\setlength{\parskip}{\medskipamount}
\DeclareDocumentEnvironment { noteen } { +b } {
  \par\textbf{\textsf{NOTE:~}}#1\par
} {}
\DeclareDocumentEnvironment { notezh } { +b } {
  \par\textbf{\textsf{注意:~}}#1\par
} {}

\AtEndDocument{
  \newgeometry{
    left=2cm,
    right=2cm,
    top=2cm,
    bottom=2cm
  }
  \PrintChanges
  \PrintIndex
}

\ExplSyntaxOn
\dim_new:N \l__my_syntax_dim
\box_new:N \g__my_syntax_box
\NewDocumentEnvironment { Syntax } { s }
  {
    \dim_set:Nn \l__my_syntax_dim
      { \textwidth }
    \hbox_gset:Nw \g__my_syntax_box
      \small \ttfamily
      \begin{minipage}[t]{\l__my_syntax_dim}
        \raggedright\obeyspaces\obeylines
  }
  {
      \end{minipage}
    \hbox_gset_end:
    \IfValueF { #1 } { \smallskip }
    \box_use_drop:N \g__my_syntax_box
    \smallskip
  }

\DeclareDocumentEnvironment { Description } { o +b } {
  \hbox_set:Nn \l_tmpa_box { #1 }
  \dim_set:Nn \l_tmpa_dim { \box_wd:N \l_tmpa_box }
  \begin{itemize}[labelwidth=\l_tmpa_dim, align=left]
    #2
  \end{itemize}
} {  }

\keys_define:nn { suanpan/doc } {
  opt .tl_set:N = \l_opt_tl,
  desc .tl_set:N = \l_desc_tl,
  init .tl_set:N = \l_init_tl,
  init .initial:n = init-none,
}

\box_new:N \l__option_box
\NewDocumentEnvironment { option } { m +b } {
  \keys_set:nn { suanpan/doc } { #1 }
  \hbox_set:Nw \l__option_box
    \small \ttfamily
    \begin{minipage}[t]{\textwidth}
      \obeyspaces\obeylines
      \textcolor{red}{
        \l_opt_tl
        \exp_args:Nx\SpecialOptionIndex{\l_opt_tl}
      }
      {~}\l_desc_tl
      \hfill(
      \tl_if_eq:NnTF \l_init_tl { init-none } { no~value }
        { init: ~\texttt{\l_init_tl} }
      )
    \end{minipage}
  \hbox_gset_end:
  \box_use_drop:N \l__option_box
  #2
  \medskip
} {  }

\DeclareDocumentCommand \opt { O{} m }
  { \__codedoc_cmd:no {#1} { #2 } }
\ExplSyntaxOff

\def\vers{\texttt{v2.0.0} }

\changes{v1.0.0}{2024/08/20}{first version.}
\changes{v1.2.4}{2024/10/13}{remove tikz patch.}
\changes{v2.0.0}{2026/07/25}{Improved error reporting; added static component caching to avoid redundant drawing and reduce TikZ overhead; renamed `bid` commands to `bead`.}

\begin{document}
\title{
  \pkg{suanpan-l3}---算盘(Abacus)排版宏包
  \rlap{\makebox[4cm][r]{
    \normalsize $\Longrightarrow$ \color{red}
    \protect\hyperlink{en}{English Version}
    \protect\hypertarget{zh}{}
  }}
}
\author{\textit{耿楠} \texttt{<nangeng@nwafu.edu.cn>}}
\date{\the\year 年\the\month 月\the\day 日\qquad \vers
\thanks{\url{https://gitee.com/nwafu_nan/suan-pan}}
}

\maketitle

\begin{abstract}
  \pkg{suanpan-l3}是一个基于\pkg{l3draw}和\pkg{TikZ}绘图宏包(shading高光)，%
  用\pkg{Expl3}开发的中国传统7珠圆珠算盘排版宏包，它能够实现使用普通上珠、下珠
  和底珠、顶珠及悬珠的算盘排版。该宏包提供了唯一的一个
  \env{suanpan}算盘排版环境及仅在该环境中使用的 \tn{rod}、
  \tn{rods}、\tn{bead}、\tn{beads}、\tn{rodmark}和\tn{mkframe}绘制档杆、算珠
  着色、横梁标记和边框排版命令。同时，该宏包还提供了\tn{suanpanset}%
  命令用于对算盘外观进行设置。
  \begin{center}
    \begin{suanpan}[framedraw = brown2, scale = 0.45, beadsep=1.5pt,
                    roddraw = brown3, rodfill = brown4]
      % 各档位数字列表
      \rods{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20}
      % 定位点
      \rod*{4}{3}
      \rod*{18}{17}
      % 使用顶珠
      \bead{12}{9}{azure5}
      \bead{13}{9}{azure5}
      \bead{14}{9}{azure5}
      \bead{15}{9}{azure5}
      \bead{16}{9}{azure5}
      % 使用悬珠
      \bead{17}{11}{red5}
      \bead{18}{11}{red5}
      \bead{19}{11}{red5}
      \bead{20}{11}{red5}
      \bead{21}{11}{red5}
      % 使用底珠
      \bead{11}{3}{olive5}
      \bead{16}{3}{olive5}
      \bead{21}{3}{olive5}
      \rodmark{21,20,19,{},17,16,15,14,13,12,11,10,9,8,7,6,5,{},3,2,1}
      \mkframe
    \end{suanpan}
  \end{center}
\end{abstract}

{\small
\tableofcontents
}
\newpage

\begin{documentation}

\section{引言}

\pkg{suanpan-l3}宏包是一个基于\pkg{l3draw}和\pkg{TikZ}绘图宏包(shading高光)，
用\pkg{Expl3}开发的中国传统7珠圆珠算盘排版宏包，它利用\pkg{l3draw}%
宏包，通过\pkg{l3coffin}容器的平移变换及拼接组装，将使用\pkg{TikZ}宏包绘制的
算珠、档杆、边框等基本图元组装成算盘，从而实现算盘的排版。

由于正常的算珠是通过圆角矩形添加高光实现的，因此当算珠数量较多时，绘制耗时较长，
其编译速度较慢。

\begin{notezh}
  该说明书中的所有颜色名称来自\pkg{ninecolors}宏包。
\end{notezh}

\section{用户接口}

\subsection{\env{suanpan}算盘排版环境}

\begin{function}{suanpan}
  \begin{syntax}
    \tn{begin}|{suanpan}|\oarg{外观选项}
    .....
    \tn{end}|{suanpan}|
  \end{syntax}
\end{function}

  按可选项设置的\oarg{外观选项}实现算盘排版。

  在\env{suanpan}环境中，可以通过专用命令\tn{rod}%
  (排版算盘的一个档位)，\tn{rods}(排版一组档位)，
  \tn{bead}(指定算珠颜色)，\tn{beads}(指定内/外珠颜色)，
  \tn{rodmark}(为档位添加标记)，\tn{mkframe}(排版边框)
  按需实现算盘排版。

  在\oarg{外观选项}中可以通过key-value的方式设置线宽、颜色、
  缩放比例等外观属性。

  通过\oarg{外观选项}设置的外观参数仅对\env{suanpan}环境局部有效。

  \begin{notezh}
    \env{suanpan}环境中\textsf{不可以出现空行}。
  \end{notezh}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  % 为便排版，进行缩放
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rod{1}{0}
    \rod{2}{3}
    \rod{3}{0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{\env{suanpan}环境中的专用命令}

\changes{v1.1.3}{2024/09/04}{add highlight to rod(s) and beam}
\subsubsection{\tn{rod}单一档位排版命令}

\begin{function}{\rod}
  \begin{syntax}
    \cs{rod} \marg{档位编号} \marg{档位数字}
  \end{syntax}
\end{function}

  用于排版\marg{档位编号}(基于1，从左向右进行编号)参数指定的算盘
  档位，本档的计数值由\marg{档位数字}参数指定。

  \marg{档位数字}支持[0, 20]内的数字，其中[0, 9]内的
  数字采用常规4个下珠结合1个上珠的方法进行表示，[10, 15]
  内的数字则需要额外使用\enquote{底珠}和\enquote{顶珠}进行表示，
  [16, 20]内的数字则需要再额外使用\enquote{悬珠}进行表示。

  宏包还为\tn{rod}命令同时提供了\tn{rod*}星号命令用于排版在
  横梁上带有计位点(圆点)的档位。

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rod{1}{1}   % 常规档位
    \rod{2}{6}
    \rod*{3}{10} % 计位点，使用底珠
    \rod{4}{12}  % 使用顶珠
    \rod{5}{18}  % 使用悬珠
  \end{suanpan}
\end{SideBySideExample}

\changes{v2.0.0}{2026/07/26}{add counting point string option.}
\changes{v2.0.0}{2026/08/03}{support interval syntax.}

\subsubsection{\tn{rods}一组档位排版命令}

\begin{function}{\rods}
  \begin{syntax}
    \cs{rods} \marg{数字列表}\oarg{计位点标记}
  \end{syntax}
\end{function}

  用于排版在\marg{数字列表}中用逗号分隔的一组数字指定的档位，
  各档位编号基于1，从左向右进行自动编号。

  \marg{数字列表}中的各档位数字支持[0, 20]内的数字，其中[0, 9]内的
  数字采用常规4个下珠结合1个上珠的方法进行表示，[10, 15]
  内的数字则需要额外使用\enquote{底珠}和\enquote{顶珠}进行表示，
  [16, 20]内的数字则需要再额外使用\enquote{悬珠}进行表示。

  \marg{数字列表}支持区间语法：start-end 表示连续区间（如 4-7 表示 4,5,6,7），
  start-end-step 表示等步长区间（如 4-7-2 表示 4,6）。

  \oarg{计位点标记}用于指示在指定的档位绘制计位点，其中，每个字符对应
  一个档位，用``*''星号  表示该档位有计位点，其它非空白字符表示无计位点。
  当\oarg{计位点标记}长度大于档数时，多余的标记会被自动忽略；
  当\oarg{计位点标记}长度小于档数时，则剩余档位不添加计位点。

  \begin{notezh}
    \oarg{计位点标记}中的空白字符会被\textsf{自动忽略}。
  \end{notezh}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 6, 12, 18, 0}[x.*-]
  \end{suanpan}
\end{SideBySideExample}

\changes{v1.0.1}{2024/08/26}{rename \tn{beadclr} to \tn{bead}.}
\changes{v1.1.3}{2024/09/01}{add draw color option to \tn{bead},
                             change \texttt{pos} to clist and
                             set default bead draw color to \texttt{innerdrawcolor}.}
\changes{v1.1.3}{2024/09/04}{add highlight to bead(s)}

\subsubsection{\tn{bead}算珠着色命令}

\begin{function}{\bead}
  \begin{syntax}
    \cs{bead} \marg{档位编号}\marg{位置列表}\marg{填充颜色}\oarg{绘制颜色}
  \end{syntax}
\end{function}

  用于将\marg{档位编号}指定的档位中，用逗号分隔的\marg{位置列表}中
  指定的所有算珠的填充色设置为\marg{填充颜色}指定的颜色，将其绘制
  颜色设置为可选项\oarg{绘制颜色}(默认为内珠绘制颜色)。

  一个档位中的\marg{算珠位置}自下向上，按\enquote{$1, 2, \cdots, 11$}%
  的顺序进行编号。其中下珠占\enquote{$1, 2, \cdots, 7$}的位置，上珠占
  \enquote{$8, 9, 10$}的位置，悬珠占\enquote{$11$}的位置。

  \begin{notezh}
    该类型的算珠称为\textsf{浮珠}，浮珠是指通过 \tn{bead} 或 \tn{beads} 命令
    动态指定颜色的算珠，它独立于内珠和外珠的默认颜色设置。
  \end{notezh}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 0, 7, 11, 8, 19}
    \bead{1}{1}{brown5}
    \bead{2}{5}{brown5}
    \bead{3}{6}{red5}
    \bead{4}{7}{red5}
    \bead{4}{8}{azure5}
    \bead{4}{9}{yellow5}
    \bead{5}{10}{violet5}
    \bead{6}{4,5,6,11}{teal4}[magenta5]
  \end{suanpan}
\end{SideBySideExample}

\changes{v1.1.0}{2024/08/28}{adde \tn{beads} macro.}
\changes{v1.1.3}{2024/09/01}{change \tn{beads} macro inner beads draw color to
                             \texttt{innerdrawcolor} and outter beads draw
                             color to \texttt{outerdrawcolor}.}

\subsubsection{\tn{beads}内珠或外珠着色命令}

\begin{function}{\beads}
  \begin{syntax}
    \cs{beads} \marg{档位编号}\marg{档位数字}\marg{填充颜色}
  \end{syntax}
\end{function}

  用于将\marg{档位编号}指定的档位中，所有\marg{档位数字}的内珠
  设置为\marg{填充颜色}指定的颜色。同时，该命令还将
  算珠绘制颜色设置内珠绘制颜色(\texttt{innerdrawcolor})。

  宏包还为\tn{beads}命令同时提供了\tn{beads*}星号命令用于设置该档
  所有外珠的颜色。此时，算珠绘制颜色设置外珠绘制颜色
  (\texttt{outerdrawcolor})。

  \begin{notezh}
    该命令只能选择内珠或外珠进行着色，不能同时选择内珠和外珠。
    这些算珠同样称为浮珠。
  \end{notezh}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 0, 7, 11, 8, 19}
    \beads{3}{7}{teal4}
    \beads*{5}{8}{azure5}
  \end{suanpan}
\end{SideBySideExample}

\changes{v1.2.0}{2024/09/04}{add \tn{rodmark} macro for marking rod(s) on beams.}

\subsubsection{\tn{rodmark}横梁标记命令}

\begin{function}{\rodmark}
  \begin{syntax}
    \cs{rodmark} \oarg{起始档位}\marg{标记列表}
  \end{syntax}
\end{function}

  用于从\oarg{起始档位}可选项指定的档位开始，用\marg{标记列表}%
  中逗号分隔的标记在算盘横梁上为各档位添加标记。

  \begin{notezh}
    如果\marg{标记列表}中的标记数量超出从\oarg{起始档位}开始的
    档位数，多余的标记将被忽略。在\marg{标记列表}中，可以用一
    对``\{\}''分组符号表示空白标记。
  \end{notezh}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 2, 6, 6, 9, 0}
    \rodmark{4,{},2,1,0,-1,-2}
  \end{suanpan}
\end{SideBySideExample}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 2, 6, 6, 9, 0}
    \rodmark[2]{千,百,十,个}
  \end{suanpan}
\end{SideBySideExample}

\changes{v1.1.3}{2024/09/04}{highlight all frame and remove arguments of \tn{lrframe},
                             at the same time change \tn{lrframe} to \tn{mkframe}.}

\subsubsection{\tn{mkframe}边框排版命令}

\begin{function}{\mkframe}
  \begin{syntax}
    \cs{mkframe}
  \end{syntax}
\end{function}

  用于排版算盘的边框。

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 6, 12, 18, 0}
    \mkframe
  \end{suanpan}
\end{SideBySideExample}

\subsection{\tn{suanpanset}选项设置命令}

\begin{function}{\suanpanset}
  \begin{syntax}
    \cs{suanpanset} \marg{外观选项}
  \end{syntax}
\end{function}

  通过\marg{外观选项}的key-value选项设置算盘的算珠、边框等元素的
  绘制颜色、填充颜色、线条宽度；各档位之间的间距、算珠之间的间距；
  算盘整体的缩放比例等外观属性。

  通过\cs{suanpanset}\marg{外观选项}设置的外观属性对后续所有算盘排版
  操作有效。

  \begin{notezh}
    由于\pkg{suanpan-l3}宏包涉及大量绘图操作，因此建议尽量减少在每个
    \env{suanpan}排版环境的可选项中使用\oarg{外观选项}设置，以
    节约编译时间。如需要更改算盘外观，可以在引用宏包时，通过为宏包
    添加选项实现，也可以执行\tn{suanpanset}命令进行必要的
    全局设置或在一定范围内进行统一设置。

    另外，为了提高编译速度，宏包采用组件缓存机制，将已绘制的算珠、
    档杆等组件缓存以供复用，从而避免重复绘制。因此，部分选项
    （如颜色、尺寸等）的设置会影响后续所有使用该缓存的绘制操作。
  \end{notezh}

\section{宏包选项}

在\pkg{suanpan-l3}宏包中，算盘颜色、线条宽度、档位及算珠间距等
算盘外观属性可以在引入宏包时通过\oarg{宏包选项}进行设置，
也可以在\env{suanpan}环境的\oarg{外观选项}中进行局部设置，
还可以通过\cs{suanpanset}命令进行全局或局部设置。

强烈建议在引用宏包时通过\oarg{宏包选项}为一个文档统一全局设置
算盘外观属性，以节约编译时间。应避免频繁\env{suanpan}环境中使用
\oarg{宏包选项}或使用\cs{suanpanset}命令设置算盘外观属性。

\pkg{suanpan-l3}宏包选项是一个英文逗号分隔的选项列表，其
选项是\marg{key}|=|\marg{value}形式。部分选项的\marg{value}可以省略。
对于同一选项，后续设置会覆盖以前设置。

\pkg{suanpan-l3}宏包采用\LaTeX3风格的键值设置，支持不同类型以及多种层次的
选项设定。键值列表中，``|=|''左右的空格不影响设置。但需注意，参数列表中%
\textsf{不可以出现空行}。

布尔型的参数\marg{选项}|=true|中的``|=true|''可以省略。

\changes{v1.2.1}{2024/09/05}{change bead(s) figure to a single
                             round cap line in draft and remove
                             all highlight of bead(s), rod(s) and
                             frame.}

\subsection{草稿模式}

\begin{option}{ opt = draft, desc = {= \meta{草稿模式}}, init=false }
  设置草稿模式。
\end{option}

  \oarg{draft}选项会将算珠用圆角线帽直线实现绘制，取消所有高光效果，
  从而加快编译速度。同时，\oarg{draft}选项还会将空档算珠绘制选项\oarg{empty}%
  设置为\texttt{false}，也就是不绘制空档上的算珠。

  \begin{notezh}
    在草稿模式下算盘排版会与期望的排版结果有出入。
  \end{notezh}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.53\linewidth,gobble=2]
  % \usepackage[draft]{suanpan}
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}[draft]
    \rods{0, 6, 12, 18, 0}
  \end{suanpan}
\end{SideBySideExample}

\changes{v1.1.2}{2024/08/31}{add empty option to remove beads on empty rod.}

\subsection{是否绘制空档算珠}

\begin{option}{ opt = empty, desc = {= \meta{空档}}, init=true }
  设置是否绘制空档算珠。
\end{option}

  \oarg{empty}选项用于选择是否绘制空档上的算珠，如果不绘制，
  在一定程度上可以加快编译速度。

  \begin{notezh}
    如有需要，可以使用\tn{bead}或\tn{beads*}命令为空档绘制算珠。
  \end{notezh}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.53\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}[empty = false]
    \rods{0, 6, 12, 18, 0}
    \beads*{5}{0}{gray6}
  \end{suanpan}
\end{SideBySideExample}

\changes{v2.0.0}{2026/08/03}{add numrods option to set the maximun number of rods.}

\subsection{档数上限}

\begin{option}{ opt = numrods, desc = {= \meta{总档数}}, init=21 }
  设置算盘的总档数上限值。
\end{option}

  \oarg{numrods}选项设置算盘的最大档数上限。当绘制的档数超过此值时，
  宏包会报错；否则按实际档数正常绘制。

\subsection{线宽}

\begin{option}{ opt = linewd, desc = {= \meta{线宽}}, init=2pt }
  设置算盘绘制中的线宽。
\end{option}

  \oarg{linewd}选项用于设置算盘边框内线线宽，同时会将
  边框外线设置为linewd的7.00倍，将档杆和算珠线宽
  设置为linewd的0.2倍。

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, linewd = 3pt}
  \begin{suanpan}
    \rods{0, 6, 12, 18, 0}
  \end{suanpan}
\end{SideBySideExample}

\changes{v1.2.2}{2024/09/07}{add beadh, beadd, rodd and framew options
                             to set the base size of suanpan.}

\subsection{算珠高度}

\begin{option}{ opt = beadh, desc = {= \meta{算珠高度}}, init=12mm }
  设置算珠高度。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, beadh = 18mm}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{算珠直径}

\begin{option}{ opt = beadd, desc = {= \meta{算珠直径}}, init=23mm }
  设置算珠直径。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, beadd = 36mm}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{档杆直径}

\begin{option}{ opt = rodd, desc = {= \meta{档杆直径}}, init=7mm }
  设置档杆直径。
\end{option}

\begin{notezh}
  档杆直径rodd应该小于算珠直径beadd。
\end{notezh}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, rodd = 3mm}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{边框宽度}

\begin{option}{ opt = framew, desc = {= \meta{边框宽度}}, init=13mm }
  设置边框宽度。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, framew = 7mm}
  \begin{suanpan}
    \rods{0, 6, 12, 18, 0}
    \mkframe
  \end{suanpan}
\end{SideBySideExample}

\subsection{档位间距}

\begin{option}{ opt = rodsep, desc = {= \meta{档位间距}}, init=3.0pt }
  设置算盘各档间的间距。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, rodsep = 15pt}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

  \begin{notezh}
    修改档位间距会改变算盘排版的宽度。
  \end{notezh}

\subsection{算珠间距}

\begin{option}{ opt = beadsep, desc = {= \meta{算珠间距}}, init=1.8pt }
  设置算珠间的间距。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, beadsep = 4pt}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

  \begin{notezh}
    修改算珠间距不会改变算盘的尺寸，但算珠高度会发生变化。
    另外，过小的算珠高度会造成算珠圆角的畸变。
  \end{notezh}

\subsection{缩放比例}

\begin{option}{ opt = scale, desc = {= \meta{缩放比例}}, init=1.0 }
  设置算盘输出结果的整体缩放比例。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 1.20}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{边框颜色}

\begin{option}{ opt = framedraw, desc = {= \meta{边框颜色}}, init=black }
  设置算盘边框颜色。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, framedraw = brown3}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

  \begin{notezh}
    边框颜色包括内外边框和横梁颜色。
  \end{notezh}

\subsection{档杆绘制颜色}

\begin{option}{ opt = roddraw, desc = {= \meta{档杆绘制颜色}}, init=black }
  设置档杆绘制颜色。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, roddraw = red8}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{档杆填充颜色}

\begin{option}{ opt = rodfill, desc = {= \meta{档杆填充颜色}}, init=white }
  设置档杆填充颜色。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, rodfill = brown6}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{外珠绘制颜色}

\begin{option}{ opt = outerdraw, desc = {= \meta{外珠绘制颜色}}, init=black }
  设置档杆上外珠\footnote{外珠是指离梁不记数的算珠。}绘制颜色。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, outerdraw = red8}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{外珠填充颜色}

\begin{option}{ opt = outerfill, desc = {= \meta{外珠填充颜色}}, init=black!40 }
  设置外珠填充颜色。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, outerfill = yellow6}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{内珠绘制颜色}

\begin{option}{ opt = innerdraw, desc = {= \meta{内珠绘制颜色}}, init=black }
  设置档杆上内珠\footnote{内珠是指靠梁记数的算珠。}绘制颜色。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, innerdraw = red8}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{内珠填充颜色}

\begin{option}{ opt = innerfill, desc = {= \meta{内珠填充颜色}}, init=black}
  设置内珠填充颜色。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, innerfill = red5}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\changes{v1.2.2}{2024/09/07}{add font option
                             to set the font of mark.}
\subsection{标记字体}

\begin{option}{ opt = font, desc = {= \meta{标记字体}}, init=\tn{bfseries}\tn{Large} }
  设置标记字体。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65,
              font=\rmfamily\Huge}
  \begin{suanpan}
    \rods{0, 2, 6, 6, 9, 0}
    \rodmark{4,3,2,1,0,-1}
  \end{suanpan}
\end{SideBySideExample}

\changes{v1.2.3}{2024/09/10}{change bead's highlight to shading=ball
                             and add beadspot option to set the angle
                             of shading.}

\subsection{高光位置(角度)}

\begin{option}{ opt = beadspot, desc = {= \meta{高光位置}}, init=0 }
  设置算珠高光点的位置，用角度表示，逆时针为正。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.44\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, beadspot = 180}
  \begin{suanpan}
    \rods{0, 0, 7, 11, 8, 19}
    \bead{1}{1}{brown5}
    \bead{2}{5}{brown5}
    \bead{3}{6}{red5}
    \bead{4}{7}{red5}
    \bead{4}{8}{azure5}
    \bead{4}{9}{yellow5}
    \bead{5}{10}{violet5}
    \bead{6}{4,5,6,11}{teal4}[magenta5]
  \end{suanpan}
\end{SideBySideExample}

\bigskip

\changes{v1.1.1}{2024/08/30}{add English documentation.}

\title{
  \pkg{suanpan-l3} package for traditional Chinese 7-beads suanpan(abacus)
  \rlap{\makebox[4cm][r]{
    \normalsize $\Longrightarrow$ \color{red}
    \protect\hyperlink{zh}{中文版本}
    \protect\hypertarget{en}{}
  }}
}
\author{Nan Geng \texttt{<nangeng@nwafu.edu.cn>}}
\date{\today\qquad \vers}

\maketitle

% 恢复选项默认值：
\suanpanset{%
  linewd  = 2.0pt,
  rodsep  = 3.0pt,
  beadsep = 1.8pt,
  scale   = 1.0,
  empty   = true,
}

\section{Introduction}

\pkg{suanpan-l3} is a traditional Chinese 7-beads suanpan drawing package
utilizes \pkg{l3draw} and \pkg{TikZ}, and is developed with \pkg{Expl3}.
It can effectively manage both upper and lower beads, while also considering
bottom bead, top bead, and hanging bead.

This package offers a unique environment for drawing suanpan,
denoted as \env{suanpan}. Within this environment, 8 specialized macros
are available for the creation of suanpan. The \tn{rod} macro is used
to lay out a single rod, while the \tn{rod*} macro draws a counting point
on this rod’s beam. The \tn{rods} macro is capable of laying out a set of rods.
The \tn{bead} macro colors the specified bead. The \tn{beads} macro colors
all inner beads that are near the beam, while the \tn{beads*} macro colors
all outer beads that are far from the beam. The \tn{rodmark} macro marks all rods
on beam. Lastly, the \tn{mkframe} macro
is used to lay out the left and right frames of an abacus.

At the same time, the package offers customization options for suanpan,
including line width, draw color, fill color, bead space, rod space, etc.
These can be configured through package options, \env{suanpan} environment
options, or the \tn{suanpanset} macro.

\begin{center}
  \begin{suanpan}[framedraw = brown2, scale = 0.45, beadsep=1.5pt,
                  roddraw = brown3, rodfill = brown4]
    % rod's val list
    \rods{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20}
    % counting point
    \rod*{4}{3}
    \rod*{18}{17}
    % top bead
    \bead{12}{9}{azure5}
    \bead{13}{9}{azure5}
    \bead{14}{9}{azure5}
    \bead{15}{9}{azure5}
    \bead{16}{9}{azure5}
    % hanging bead
    \bead{17}{11}{red5}
    \bead{18}{11}{red5}
    \bead{19}{11}{red5}
    \bead{20}{11}{red5}
    \bead{21}{11}{red5}
    % bottom bead
    \bead{11}{3}{olive5}
    \bead{16}{3}{olive5}
    \bead{21}{3}{olive5}
    \rodmark{21,20,19,{},17,16,15,14,13,12,11,10,9,8,7,6,5,{},3,2,1}
    \mkframe
  \end{suanpan}
\end{center}

\begin{noteen}
  The color names appearing throughout this documentation are defined in the \pkg{ninecolors} package.
\end{noteen}

\section{Interface}

\subsection{\env{suanpan} environment}

\begin{function}{suanpan}
  \begin{syntax}
    \tn{begin}|{suanpan}|\oarg{options}
    .....
    \tn{end}|{suanpan}|
  \end{syntax}
\end{function}

  Typesetting 7-beads Chinese suanpan with \oarg{options}.

  Within the \env{suanpan} environment, \tn{rod}, \tn{rod*}, \tn{rods}, \tn{bead},
  \tn{beads}, \tn{beads*}, \tn{rodmark} and \tn{mkframe} 8 specialized macros
  are available for the creation of suanpan.

  \oarg{options} is a key-value list for line width, draw color, fill color,
  bead space, rod space, etc.

  \oarg{options} is environment's local setting.

  \begin{noteen}
    You should remove all blank lines in \env{suanpan} environment.
  \end{noteen}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rod{1}{0}
    \rod{2}{3}
    \rod{3}{0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{\env{suanpan}'s specialized macros}

\subsubsection{\tn{rod}---single rod}

\begin{function}{\rod}
  \begin{syntax}
    \cs{rod} \marg{num} \marg{val}
  \end{syntax}
\end{function}

  The \tn{rod} macro is used to lay out a single rod.

  The \marg{num} argument numbers the rods from left to right.
  The \marg{val} is the number to be represented on the rod from
  0 to 20. For number within [0, 9], it is represented using 4 lower deck
  beads and 1 upper deck bead. Numbers within [10, 15] are represented additionally
  using bottom bead and top bead. For numbers within [16, 20], hanging bead is also
  required for representation.

  The starred version \tn{rod*} will draw a counting point on this rod's beam.

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rod{1}{1}   % normal rod
    \rod{2}{6}
    \rod*{3}{10} % counting point and
                 % bottom bead
    \rod{4}{12}  % top bead
    \rod{5}{18}  % hanging bead
  \end{suanpan}
\end{SideBySideExample}

\subsubsection{\tn{rods}---a set of rods}

\begin{function}{\rods}
  \begin{syntax}
    \cs{rods} \marg{val list}\oarg{counting point string}
  \end{syntax}
\end{function}

  The \tn{rods} macro is used to lay out a set of rods.

  The \marg{val list} is a value list of each rod separated by commas.
  Each rod number is automatically numbered from left to right.

  Each value in \marg{val list} is the number to be represented on the rod from
  0 to 20. For number within [0, 9], it is represented using 4 lower deck
  beads and 1 upper deck bead. Numbers within [10, 15] are represented additionally
  using bottom bead and top bead. For numbers within [16, 20], hanging bead is also
  required for representation.

  The \marg{val list} supports range syntax in the forms start-end and start-end-step.
  For example, 4-7 expands to 4, 5, 6, 7, and 4-7-2 expands to 4, 6 (with a step size of 2).

  The \oarg{counting point string} is used to indicate the rods where counting
  points should be drawn. Each character corresponds to a rod, and ``*''
  indicates that the rod has a counting point, while other characters
  indicate no counting point. When the length of the mark string is greater
  than the number of rods, the excess marks are ignored; when it is shorter,
  the remaining rods will have no counting point.

  \begin{noteen}
    All spaces in the \oarg{counting point marks} will be \textsf{ignored}.
  \end{noteen}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 6, 12, 18, 0}[x.*-]
  \end{suanpan}
\end{SideBySideExample}

\subsubsection{\tn{bead}---color bead}

\begin{function}{\bead}
  \begin{syntax}
    \cs{bead} \marg{num}\marg{pos list}\marg{fill color}\oarg{draw color}
  \end{syntax}
\end{function}

  The \tn{bead} macro fills the specified bead.

  The \marg{num} is the same as for \tn{rod}; the \marg{fill color} argument
  defines the fill color and the comma-separated \marg{pos list} argument tells
  which bead has to be colored in \marg{num} rod. The \oarg{draw color} option
  gives the draw color (default is inner bead draw color).

  The \marg{pos} in a rod is numbered from the bottom up in the order
  $1, 2, \cdots, 11$. The lower deck beads occupies position
  $1, 2, \cdots, 7$, the upper deck beads occupies position $8, 9, 10$,
  and the hanging bead occupies position $11$ between $9$ and $10$ .

  \begin{noteen}
    This type of bead is called a \textsf{float bead}, which refers to beads
    whose colors are dynamically specified by the \tn{bead} or \tn{beads}
    command, independent of the default color settings for inner and outer beads.
  \end{noteen}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 0, 7, 11, 8, 19}
    \bead{1}{1}{brown5}
    \bead{2}{5}{brown5}
    \bead{3}{6}{red5}
    \bead{4}{7}{red5}
    \bead{4}{8}{azure5}
    \bead{4}{9}{yellow5}
    \bead{5}{10}{violet5}
    \bead{6}{4,5,6,11}{teal4}[magenta5]
  \end{suanpan}
\end{SideBySideExample}

\subsubsection{\tn{beads}---color inner/outer beads}

\begin{function}{\beads}
  \begin{syntax}
    \cs{beads} \marg{num}\marg{val}\marg{color}
  \end{syntax}
\end{function}

  The \tn{beads} macro fills all inner beads that are near the beam.

  \marg{num} and \marg{color} are the same as for \tn{bead};
  the \marg{val} argument is the same as for \tn{rod}.

  The \marg{color} is fill color for inner beads. it also sets
  \texttt{innercolor} to be used for inner beads drawing color.

  The starred version \tn{beads*} is used to color outer beads of \marg{num} rod.
  it also sets \texttt{outercolor} to be used for inner beads drawing color.

  \begin{noteen}
    This macro can only select the inner beads or the outer beads for coloring,
    you can't select both the inner and outer beads at the same time.
    These beads are also called \textsf{float beads}.
  \end{noteen}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 0, 7, 11, 8, 19}
    \beads{3}{7}{teal4}
    \beads*{5}{8}{azure5}
  \end{suanpan}
\end{SideBySideExample}

\subsubsection{\tn{rodmark} rod(s) marking on beam}

\begin{function}{\rodmark}
  \begin{syntax}
    \cs{rodmark} \oarg{st}\marg{marker list}
  \end{syntax}
\end{function}

  The \tn{rodmark} macro marks the rod(s) on the beam.

  The \oarg{st} argument is the start rod and \marg{marker list}
  is the marker list.

  \begin{noteen}
    If the number of \marg{marker list} exceeds the number of
    rods from \oarg{st}, the excess markers will be ignored.
    In the \marg{marker list}, it is possible to use a pair of
    ``\{\}'' grouping to indicate blank marker.
  \end{noteen}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 2, 6, 6, 9, 0}
    \rodmark{4,{},2,1,0,-1,-2}
  \end{suanpan}
\end{SideBySideExample}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 2, 6, 6, 9, 0}
    \rodmark[2]{Q,C,X,I}
  \end{suanpan}
\end{SideBySideExample}

\subsubsection{\tn{mkframe}---layout frame}

\begin{function}{\mkframe}
  \begin{syntax}
    \cs{mkframe}
  \end{syntax}
\end{function}

  The \tn{mkframe} macro is used to lay out the frames of
  a suanpan.

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.48\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}
    \rods{0, 6, 12, 18, 0}
    \mkframe
  \end{suanpan}
\end{SideBySideExample}

\subsection{\tn{suanpanset}}

\begin{function}{\suanpanset}
  \begin{syntax}
    \cs{suanpanset} \marg{options}
  \end{syntax}
\end{function}

  The \tn{suanpanset} macro offers customization options for suanpan,
  including line width, draw color, fill color, bead space, rod space, etc.

  The \marg{options} is a key-value list.

  The options set by the \cs{suanpanset} are valid for all subsequent
  \env{suanpan} environments. This is useful for global style settings
  that apply to multiple suanpan drawings in a document.

\section{options}

The \pkg{suanpan-l3} package offers customization options for abacus,
including line width, draw color, fill color, bead space, rod space, etc.
These can be configured through package \oarg{options}, \env{suanpan}
environment \oarg{options}, or the \tn{suanpanset} macro.

It is strongly recommended that suanpan options be set globally
for a document uniformly via \oarg{options} of packages to save compilation time.
Frequent use of \oarg{options} in \env{suanpan} environments or
use of the \tn{suanpanset} command to set suanpan options should be avoided.

The \oarg{options} is a comma-separated list of options in the form
\marg{key}|=|\marg{value}. The \marg{value} can be omitted for some options.
For the same option, subsequent settings will override the previous one.

The \pkg{suanpan-l3} package uses \LaTeX3 style key settings,
supporting different types and levels of options. In the key list,
spaces around ``='' do not affect the settings.
However, it is important to note that blank lines are not allowed in the list.

The ``|=true|'' in the \marg{option}|=true| for Boolean types can be omitted.

Furthermore, to enhance compilation speed, the package utilizes a component
caching mechanism that reuses previously drawn components such as beads and rods,
thereby avoiding repeated rendering. Consequently, changes to certain options
(e.g., colors, dimensions) will affect all subsequent drawing operations that
rely on these cached components.

\subsection{draft}

\begin{option}{ opt = draft, desc = {= \meta{draft}}, init=false }
  Draft mode.
\end{option}

  The \oarg{draft} option speeds up compilation by drawing
  beads using round cap line, at same time it will remove all
  highlight of bead(s), rod(s) and frame.

  At the same time \oarg{draft} option will set the \oarg{empty} option
  to \texttt{false} to remove all beads on empty rod.

  \begin{noteen}
    Suanpan layout in draft mode may differ from the desired layout.
  \end{noteen}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.53\linewidth,gobble=2]
  % \usepackage[draft]{suanpan}
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}[draft]
    \rods{0, 6, 12, 18, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{empty}

\begin{option}{ opt = empty, desc = {= \meta{empty}}, init=true }
  Remove beads on empty rod or not.
\end{option}

  The \oarg{empty} option will remove all beads on empty rod.

  \begin{noteen}
    If necessary, you can use the \tn{bead} or \tn{beads*} macro to
    draw bead(s) for the empty rod.
  \end{noteen}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.53\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65}
  \begin{suanpan}[empty=false]
    \rods{0, 6, 12, 18, 0}
    \beads*{5}{0}{gray6}
  \end{suanpan}
\end{SideBySideExample}

\subsection{max limit number of rods}

\begin{option}{ opt = numrods, desc = {= \meta{number}}, init=21 }
  Sets the maximum number of rods.
\end{option}

  If the actual number of rods exceeds this limit, an error is raised;
  otherwise, the suanpan is drawn with the actual number of rods.

\subsection{line width}

\begin{option}{ opt = linewd, desc = {= \meta{linewd}}, init=2pt }
  Drawing line width.
\end{option}

  The \oarg{linewd} is used to set the line width of the frame inner,
  and will also set the line width the frame outer to 7.00 times linewd,
  and the rod and bead line widths to 0.2 times linewd.

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, linewd = 3pt}
  \begin{suanpan}
    \rods{0, 6, 12, 18, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{bead height}

\begin{option}{ opt = beadh, desc = {= \meta{beadh}}, init=12mm }
  The height of bead.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, beadh = 18mm}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{bead diameter}

\begin{option}{ opt = beadd, desc = {= \meta{beadd}}, init=23mm }
  The diameter of bead.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, beadd = 36mm}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{rod diameter}

\begin{option}{ opt = rodd, desc = {= \meta{rodd}}, init=7mm }
  The diameter of rod.
\end{option}

\begin{noteen}
  The rodd should be smaller than the beadd.
\end{noteen}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, rodd = 3mm}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{frame width}

\begin{option}{ opt = framew, desc = {= \meta{framew}}, init=13mm }
  The width of frame.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, framew = 7mm}
  \begin{suanpan}
    \rods{0, 6, 12, 18, 0}
    \mkframe
  \end{suanpan}
\end{SideBySideExample}

\subsection{rod spacing}

\begin{option}{ opt = rodsep, desc = {= \meta{rodsep}}, init=3.0pt }
  The spacing between suanpan rods.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, rodsep = 15pt}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

  \begin{noteen}
    The \oarg{rodsep} will change the width of the suanpan.
  \end{noteen}

\subsection{bead spacing}

\begin{option}{ opt = beadsep, desc = {= \meta{beadsep}}, init=1.8pt }
  The spacing between suanpan beads.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, beadsep = 4pt}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

  \begin{noteen}
    The \oarg{beadsep} does not change the size of the suanpan.
    But the height of each bead will be changed.
    In addition, too small a bead height will cause distortion
    of the rounded corners of the bead.
  \end{noteen}

\subsection{scale}

\begin{option}{ opt = scale, desc = {= \meta{scale}}, init=1.0 }
  Scaling factor of whole suanpan.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 1.20}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{frame color}

\begin{option}{ opt = framedraw, desc = {= \meta{framedraw}}, init=black }
  Frame drawing color.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, framedraw = brown3}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

  \begin{noteen}
    Frame colors include inner and outer of frame and beam colors.
  \end{noteen}

\subsection{rod drawing color}

\begin{option}{ opt = roddraw, desc = {= \meta{roddraw}}, init=black }
  Rod drawing color.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, roddraw = red8}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{rod filling color}

\begin{option}{ opt = rodfill, desc = {= \meta{rodfill}}, init=white }
  Rod filling color.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, rodfill = brown6}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{outer beads drawing color}

\begin{option}{ opt = outerdraw, desc = {= \meta{outerdraw}}, init=black }
  The outer beads\footnote{The outer bead is that is not counted away from the beam.}drawing color.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, outerdraw = red8}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{outer beads filling color}

\begin{option}{ opt = outerfill, desc = {= \meta{outerfill}}, init=black!40 }
  The outer beads filling color。
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, outerfill = yellow6}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{inner beads drawing color}

\begin{option}{ opt = innerdraw, desc = {= \meta{innerdraw}}, init=black }
  The inner beads\footnote{The inner bead is that is counted near to the beam.}drawing color.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, innerdraw = red8}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{inner beads filling color}

\begin{option}{ opt = innerfill, desc = {= \meta{innerfill}}, init=black}
  The inner beads filling color.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.37\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, innerfill = red5}
  \begin{suanpan}
    \rods{0, 6, 0}
  \end{suanpan}
\end{SideBySideExample}

\subsection{mark font}

\begin{option}{ opt = font, desc = {= \meta{font}}, init=\tn{bfseries}\tn{Large} }
  The font of mark(s).
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
                xrightmargin=.40\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65,
              font=\rmfamily\Huge}
  \begin{suanpan}
    \rods{0, 2, 6, 6, 9, 0}
    \rodmark{4,3,2,1,0,-1}
  \end{suanpan}
\end{SideBySideExample}

\subsection{highlight pos/angle}

\begin{option}{ opt = beadspot, desc = {= \meta{beadspot}}, init=0 }
  The bead's highlight angle.
\end{option}

\begin{SideBySideExample}[frame=single,numbers=left,%
    xrightmargin=.44\linewidth,gobble=2]
  \centering
  \suanpanset{scale = 0.65, beadspot = 180}
  \begin{suanpan}
    \rods{0, 0, 7, 11, 8, 19}
    \bead{1}{1}{brown5}
    \bead{2}{5}{brown5}
    \bead{3}{6}{red5}
    \bead{4}{7}{red5}
    \bead{4}{8}{azure5}
    \bead{4}{9}{yellow5}
    \bead{5}{10}{violet5}
    \bead{6}{4,5,6,11}{teal4}[magenta5]
  \end{suanpan}
\end{SideBySideExample}

\end{documentation}

\end{document}