\PassOptionsToPackage{AutoFallBack}{xeCJK}
\documentclass{ctxdoc}
\usepackage[enable-zhlipsum,enable-background]{zitie}
\usepackage{geometry}
\usepackage{xcoffins}

\def\zitieversion{1.4.0}
\def\zitiedate{农历二〇二一年八月廿五}
\def\zitieframetitle{
  \framezi[width=3\ccwd,fillcolor=black,charcolor=red!75!black,font=文征明行草简繁,anchor=west]{字}%
  \framezi[width=3\ccwd,fillcolor=black,charcolor=red!75!black,font=文征明行草简繁,position*={\TypesetCoffin##1[l,vc](-.4pt,0pt)}]{帖}%
  \framezi[width=1.5\ccwd,font=楷体,position*={\TypesetCoffin##1[l,b](-.2pt,-.2pt)}]{宏}%
  \framezi[width=1.5\ccwd,font=楷体,position*={\TypesetCoffin##1[r,t](0pt,.2pt)}]{包}%
}
\def\zitietexttitle{zitie宏包}
\def\emptyframe#1{\framezi[#1,charstroke=invisible]{　}}
\let\emptyCJKchar=　% U+3000

\NewDocumentCommand{\init}{+v}{\hspace{\fill}初始值~=~\textcolor{blue}{\bfseries#1}}

\IfFontExistsTF{KaiTi}{\zitienewfont{{楷体}{KaiTi}}}{\typeout{KaiTi not exist.}}
\IfFontExistsTF{FZSunGuoTingCaoShuFU}{\zitienewfont{{孙过庭草繁}{FZSunGuoTingCaoShuFU}{FallBack=SimSun}}}{\typeout{FZSunGuoTingCaoShuFU not exist.}}
\IfFontExistsTF{FZWenZhengMingXingCaoJF}{\zitienewfont{{文征明行草简繁}{FZWenZhengMingXingCaoJF}{FallBack=KaiTi}}}{\typeout{FZWenZhengMingXingCaoJF not exist.}}

\zitiesetup{
  framecolor=green!60!black,charcolor=red!65!black,
  resize=square,frametype=咪,font,savefontname,
}
\title{\texorpdfstring{\zitieframetitle}{\zitietexttitle}}
\date{\texorpdfstring{\framezi*[width=2\ccwd,font=文征明行草简繁,anchor=west]{\zitiedate}}{\zitiedate} v\zitieversion}
\author{雾月, Longaster (\texttt{longaster@163.com})}

\begin{document}

\newgeometry{nomarginpar,textheight=27cm,textwidth=17cm,bottom=1.7cm}

\zitiesetup{holdbasecharheight=true}

\maketitle
\thispagestyle{empty}

\parskip=0pt \parindent=0pt \lineskip=0pt \raggedright
\framezi[
  width=1.8cm,punctuation=onlast,holdbasecharheight,
  fillcolor=black,charcolor=red!75!black,font=文征明行草简繁,
]{
  我欲乘風向北行，
  雪落軒轅大如席。
  我欲借船向東游，
  綽約仙子迎風立。
  我欲踏云千萬裏，
  廟堂龍吟奈我何。}%
\framezi[
  width=1.8cm,punctuation=onlast,charstroke=whitesolid,holdbasecharheight,
  fillcolor=black,charcolor=red!75!black,font=文征明行草简繁,
]{
  昆侖之巔沐日光，
  滄海絕境見青山。
  長風萬裏燕歸來，
  不見天涯人不回。
  \emptyCJKchar\emptyCJKchar}

\bigskip

\zitienewrule{punctuation}{package1}{\makebox[\zitiewidth][l]{ \zitieCJKfamily{\zitiefontname} #1}}
\framezi[
  width=2.5\ccwd,linewidth=.2pt,holdbasecharheight,
  dashpattern={1mm,.5mm},punctuation=package1,
  fillcolor={},framecolor=red,charcolor=black,
  font=孙过庭草繁,
]{
  我欲乘風向北行，
  雪落軒轅大如席。
  我欲借船向東游，
  綽約仙子迎風立。
  我欲踏云千萬裏，
  廟堂龍吟奈我何。
  昆侖之巔沐日光，
  滄海絕境見青山。
  長風萬裏燕歸來，
  不見天涯人不回。
}\hfill ——《少年歌行》

{\heiti\small 注：本文档中的非商业的字体版权为原字体公司（北京方正有限公司及其它相关公司），此处使用该字体仅为显示该宏包的排版效果，不作商业用途。本文档\pkg{zitie.tex}和相应的\pkg{zitie.sty}源文件使用 \href{https://www.latex-project.org/lppl/lppl-1-3c/}{LPPL 1.3c 协议} 开源。}
\zitiesetup{holdbasecharheight=false}

\clearpage
\restoregeometry
\setlength{\parindent}{2\ccwd}
\lineskip=2bp
\zitiebackground[
  on,linewidth=.2pt,dashpattern={1mm,.5mm,2mm,1mm},
  frametype=田,framecolor=green!80!black,
  colboxes=20,rowboxes=30,
]

\pkg{zitie} 宏包是用纯 \LaTeX3 模块编写的（即，不加载 \pkg{pgf}、\pkg{pstricks} 等绘图宏包），也不使用 \pkg{xcolor} 宏包，来生成网格化的字、生成网格化的背景的宏包。绘图功能完全依赖 \pkg{l3draw}，但应注意 \pkg{l3draw} 目前仍然是实验性的，其接口在后续版本可能无法使用。

\LaTeXe 版本应在 2020-10-01 及以后。

\changes{v1.3}{2021/09/25}{开始支持 \LuaTeX。}
目前支持 \XeTeX、\LuaTeX，不支持 \pdfTeX。应注意由于 \LuaTeX{} 处理中文字符和 \XeTeX{} 不同，使用 \XeTeX{} 和 \LuaTeX{} 编译效果会有不同，最好使用 \XeTeX{} 编译。

\tableofcontents

\section{\pkg{zitie} 宏包的加载和基本命令}\label{sec:basics}

加载宏包：\tn{usepackage}\oarg{key-val}\verb|{zitie}|。\meta{key-val} 选项见第 \ref{sec:options} 节。

\changes{v1.2}{2021/09/23}{不再加载 \opt{ctexsize} 宏包。不再设置宋体为主字体}
使用 \XeTeX 将加载 \pkg{xeCJK} 宏包\cite{pkg-xeCJK}。使用 \LuaTeX{} 将加载 \pkg{ctex} 宏包。

\begin{function}{\zitienewfont,\zitieCJKfamily}
  \begin{syntax}
    \cs{zitienewfont} \{ \marg{font family} \marg{font name} , ... \}
    \cs{zitienewfont} \{ \marg{font family} \marg{font name} \marg{font features} , ... \}
    \cs{zitienewfont} * \marg{font family} \marg{font name} \marg{font features}
    \cs{zitieCJKfamily} \marg{font family}
    \cs{zitieCJKfamily} + \marg{font family}
    \cs{zitieCJKfamily} - \marg{font family}
  \end{syntax}
  这个命令用来加载和设置需要的字体，\meta{font family} 为在 \cs{framezi} 等命令的 \opt{font} 选项中使用的名字，也可通过 \cs{zitieCJKfamily} 来在文档中使用该字体。\meta{font name} 为字体的名字，\meta{features}，为 \pkg{fontspec} 宏包\cite{pkg-fontspec}，\pkg{xeCJK} 宏包（\XeTeX 中）或 \pkg{luatexja} 宏包（\LuaTeX 中）支持的字体特性。

  \cs{zitieCJKfamily} 和 \pkg{xeCJK} 宏包的 \cs{CJKfamily} 作用完全相同，只不过首先判断该 \meta{font family} 是否被 \cs{zitienewfont} 声明，若没有，则再使用 \cs{CJKfamily} 进行处理。
\end{function}

\changes{v1.3.2}{2021/09/26}{单个range可达3200字。}
\changes{v1.4.0}{2021/10/01}{新增 \cs{framesingle} 命令。}
\begin{function}{\framesingle,\framezi,\framerange,\framezifile}
  \begin{syntax}
    \cs{framesingle} \oarg{key-val} \marg{字}
    \cs{framezi} * \oarg{key-val} \marg{字或词句}
    \cs{framerange} \oarg{key-val} \marg{逗号分隔的16进制序列}
    \cs{framezifile} * \oarg{key-val} \marg{文件名}
  \end{syntax}
  以上命令用来生成网格化的字。
  
  \meta{key-val} 为第 \ref{sec:options} 节定义的键。

  \meta{字或词句} 应仅包含类代码为 11 或 12 的字符，即正常情况下输入的字符，不应包含 \TeX 控制序列即其它特殊字符。\cs{framezi} 带星号的版本接收一个控制序列，这个序列包含想要网格化的字。

  \meta{逗号分隔的16进制序列} 应使用如下的形式：\verb|"4E00 -> "4E27, "4E30| 或 \verb|`一 -> `丢, `丰|，与其它设置字符序列的宏包相似（如 \pkg{xeCJK} 宏包的 \cs{xeCJKDeclareSubCJKBlock}）。注意，由于网格化操作需要大量的计算，因此单个 \meta{range} 不应太大，依据编译环境而定，一般不应超过 3200 个，否则可能无法成功编译。其它命令中也是如此。若要使用大量字符，则可以使用 \cs{frametallrange}、\cs{framezitallfile} 等 \verb|tall| 型命令，或 \pkg{background} 模块及其 \opt{xrange}、\opt{yrange} 特性。

  \meta{文件名} 为想要网格化的文字的文件名。\cs{framezifile} 带 \verb|*| 的版本，可在 \meta{key-val} 中使用 \opt{filepath} 设置文件搜索路径，详见第 \ref{sec:options} 节的说明。带星号和不带星号的版本实现略有差异，速度也可能不一样。

  当连续多次使用 \cs{framezi} 等命令时，为去掉后面的空白，可使用 \opt{\%} 注释符。

  \cs{framesingle} 专门用于制作单个字的方框。
\end{function}

\begin{function}{
  zitie/framesingle/before, zitie/framesingle/after,
  zitie/framezi/before, zitie/framezi/after,
  zitie/framerange/before, zitie/framerange/after,
  zitie/framerange/range,
  zitie/framezifile/before, zitie/framezifile/after,
}
  这三个命令还各自定义了钩子（hook），其中带有 \verb|after| 为 \verb|reversed|，即先添加的后执行。\verb|before| 为选项设置完成后执行，\verb|after| 为整个命令执行完之后执行。其中 \verb|zitie/framerange/range| 为每一个列表均执行一次，包括无效的和最后一次。

  可以通过 \cs{AddToHook}、\cs{AddToHookNext}、\cs{RemoveFromHook} 来添加和移除，详细请参考 \pkg{source2e.pdf}\cite{pdf-source2e} 或 \pkg{lthooks}\cite{pkg-lthooks} 的说明文档。
\end{function}

\begin{function}{zitieframe,
  zitie/zitieframe/before, zitie/zitieframe/after,
  zitie/zitieframe/par
}
  \begin{syntax}
    \verb|\begin{zitieframe}| \oarg{key-val}
    ~~...
    \verb|\end{zitieframe}|
    \verb|\begin{zitieframe}| \marg{initial material} \oarg{key-val}
    ~~...
    \verb|\end{zitieframe}|
  \end{syntax}
  可以在 \env{zitieframe} 环境中使用分段（显式的或隐式的，特殊命令仍然不可使用）。

  \meta{initial material} 为在选项和钩子执行完毕之后要执行的内容。这里的内容不会被网格化。

  \verb|zitie/zitieframe/par| 钩子为环境中的每个段落分段后要执行的命令。
\end{function}

\begin{function}{
  \frametallrange,
  \framezitallfile,
  zitie/frametallrange/before,
  zitie/frametallrange/after,
  zitie/frametallrange/range,
  zitie/framezitallfile/before,
  zitie/framezitallfile/after
}
  \begin{syntax}
    \cs{frametallrange} \oarg{key-val} \marg{逗号分隔的16进制序列}
    \cs{framezitallfile} * \oarg{key-val} \marg{文件名}
  \end{syntax}
  一般情况下 \pkg{zitie} 宏包的方框化命令只能容纳不超过3200词。但 \cs{frametallrange} 和 \cs{framezitallfile} 却摆脱了这种限制，即使是2万词也不在话下。不过在这种情况下，编译是十分慢的。若要保证速度，可以使用 \pkg{background} 模块及其 \opt{xrange}、\opt{yrange} 特性。
\end{function}

\begin{texnote}
  \verb|tall| 类型命令隐式地在固定词数后进行分段，这个词数由 \opt{tallheight} 选项来控制，见第 \ref{sec:options} 节。

  为了执行速度，\opt{tallheight} 需要手动控制。
\end{texnote}

\section{选项}\label{sec:options}

以下选项在方框化命令的宏中是局部设置的。

\changes{v1.2}{2021/09/23}{新增 \opt{fontsize} 选项，不再使用 \opt{zihao} 选项作为默认字号选项。}
\begin{function}{basechar,fontsize,zihao}
  \begin{syntax}
    basechar = \meta{CJK char} \init{好}
    fontsize = \meta{fontsize command} \init{\normalsize}
    zihao = \meta{字号}
  \end{syntax}
  \opt{basechar} 设置当 \opt{resize} 为 \opt{base} 类时的基字符，这个用来计算缩放比例，基字符不同时，即使给定相同的缩放比例，其实际缩放比例也可能不同。

  \opt{fontsize} 设置计算基字符时的字大小，默认值也为 \tn{normalsize}。\opt{zihao} 设置计算缩放比例时的字号大小，必须加载 \pkg{ctexsize} 或 \pkg{ctex} 宏包才可使用。
\end{function}

\changes{v1.3}{2021/09/25}{新增 \opt{position}、\opt{position*}、\opt{anchor} 键。}
\begin{function}{position,position*,anchor}
  \begin{syntax}
    position = <...>
    position*= \marg{replace}
    anchor   = <east|southeast|south|southwest|west|northwest|
    ~~~~~~~~~~~~north|northeast|center|...> \init{southwest}
  \end{syntax}
  \opt{anchor} 设置当前点与方框化盒子的哪个锚点重合。初始值为 \opt{southwest}，即当前点与盒子的西南角点重合：
  \verb|\framezi[anchor=southwest]|\framezi[width=1.5\ccwd,anchor=southwest]{好}，
  \verb|\framezi[anchor=center]{好}|\framezi[width=1.5\ccwd,anchor=center]{好}。

  \opt{position} 键用于引用 \opt{position} 处理器定义的值，\opt{position} 处理器接收当前方框化的盒子作为其参数。使用 \pkg{xcoffins} 宏包，
  \opt{position} 处理器还可以对已经构造好的盒子进行任意变换，如旋转、重设大小等，只是最后不要忘记使用 \cs{TypesetCoffin} 命令将其输出。
  该盒子为一个 \verb|coffin|。关于 \verb|coffin| 详见 \pkg{xcoffins}\cite{pkg-xcoffins} 宏包的说明。关于“处理器”，详细介绍请看第 \ref{sec:processors} 节。
  
  \opt{position} 处理器预先定义了 \opt{anchor-east}、\opt{anchor-south} … 等规则，实际上，\verb|anchor=east| 就是 \verb|position=anchor-east| 的简写，
  \opt{anchor} 的其它可选值也是如此。因此，只要 \opt{position} 的规则具有 \verb|anchor-|\meta{anchor value} 形式，就可以使用 \verb|anchor=|\meta{anchor value}
  来引用它。

  还可使用 \cs{zitienewrule} 定义新的标点符号处理方式。详见 \cs{zitienewrule} 命令的说明和第 \ref{sec:processors} 节。
  
  \opt{position*} 键将 \opt{position} 处理器定义为其值，接收当前方框化的盒子作为其参数。

  使用 \pkg{xcoffins} 宏包，则设置 \verb|position*={\TypesetCoffin#1[l,b](0pt,0pt)}| 就相当于
  设置了 \verb|anchor=southwest| 或 \verb|position=anchor-southwest|。
\end{function}

\begin{function}{punctuation, punctuation*}
  \begin{syntax}
    punctuation = <ignore|leave|onlast|scale|...> \init{ignore}
    punctuation*= \marg{replace}
  \end{syntax}
  \pkg{zitie} 宏包对字符类型进行区分，对CJK字符和标点符号采用不同的处理方式。
  该选项设置标点符号采用何种处理方式。初始情况下为 \opt{ignore}，即忽略该字符。

  \opt{leave} 选项把该标点符号原样输出，不对其进行任何处理，字体和其它属性和正文相同。

  \opt{onlast} 选项把标点符号放到0宽度的盒子中，并且忽略它的深度和高度，看起来就像是在最后一个字的方框中。

  \opt{scale} 选项把标点符号按最后一个字的缩放倍数进行缩放，再将其进行输出。
  
  选项 \opt{punctuation*} 定义处理标点符号的方式为其值，可接收一个参数。如设置 \verb|punctuation*=\fbox{#1}|，则将标点符号放入 \tn{fbox} 内。
  
  若 \opt{punctuation} 并不存在，则将其值视为已定义的宏。如，假设 \verb|@gobble| 值并不存在，若使用 \verb|punctuation=@gobble|，则标点符号处理命令为 \tn{@gobble}，这是 \LaTeXe 定义的命令，其作用与 \verb|punctuation=ignore| 相同。
  
  还可使用 \cs{zitienewrule} 定义新的标点符号处理方式。详见 \cs{zitienewrule} 命令的说明和第 \ref{sec:processors} 节。
  
  实际上，\opt{onlast} 和 \opt{scale} 就是由 \cs{zitienewrule} 定义的，这个键的处理器接收一个标点符号作为其参数。
  具体的定义第 \ref{sec:processors} 节。
\end{function}

\begin{texnote}
  按照 \pkg{xeCJK} 宏包的字符分类，\pkg{zitie} 宏包将字符类别为 \verb|FullLeft|、\verb|FullRight|、\verb|HalfLeft|、\verb|HalfRight| 视为标点符号。将 \verb|CJK|视为CJK字符。

于是可以通过修改标点符号的字符类别为 \opt{CJK} 来使用CJK的处理规则，但是要注意，一般标点符号的宽高与常用字符的宽高并不一致。某些字符也不是全高的，这时，可用后文介绍的 \opt{holdbasecharheight} 键来保证至少有 \opt{basechar} 字符的高度。
\begin{verbatim}
  \xeCJKDeclareCharClass{CJK}{`。}
  \framezi[resize=real,punctuation=leave,holdbasecharheight=false]{好的。一点、}
  \framezi[resize=real,punctuation=leave,holdbasecharheight]{好的。一点、}
  \xeCJKResetPunctClass
  \framezi[resize=real,punctuation=leave,holdbasecharheight=false]{好的。一点、}
  \framezi[resize=real,punctuation=leave,holdbasecharheight]{好的。一点、}
\end{verbatim}

\xeCJKDeclareCharClass{CJK}{`。}
\framezi[width=1cm,resize=real,punctuation=leave,holdbasecharheight=false]{好的。一点、}
\framezi[width=1cm,resize=real,punctuation=leave,holdbasecharheight]{好的。一点、}
\xeCJKResetPunctClass

\framezi[width=1cm,resize=real,punctuation=leave,holdbasecharheight=false]{好的。一点、}
\framezi[width=1cm,resize=real,punctuation=leave,holdbasecharheight]{好的。一点、}

由于 \LuaTeX-ja 的实现问题，目前这一方法在 \LuaTeX{} 中效果并不好。
\end{texnote}

\changes{v1.4.0}{2021/10/01}{修改了方框的行为，使得当使用设置 \opt{framearc} 时，arc外的线将隐藏。}
\begin{function}{frametype,resize}
  \begin{syntax}
    frametype = <none|口|十|田|×|米|咪|...> \init{none}
    resize    = <none|real|base|square|...> \init{none}
  \end{syntax}
  \opt{frametype} 设置方框样式。可用值的效果正如选项值：\verb|口|--仅方框，\verb|十|--仅中间的横线和竖线，\verb|田|--常见的田字格，\verb|×|--斜的两条线，\verb|米|--十字格再加上斜的两条线，\verb|咪|--常见的米字格。还可自定义方框，详见第 \ref{sec:interface} 节。以下 \opt{frametype} 分别为 \verb|none|，\verb|口|，\verb|十|，\verb|田|，\verb|×|、\verb|米|，\verb|咪|。

  {\zitiesetup{font=楷体,width=1cm,resize=square,framecolor=black,linewidth=.7pt}
  \framezi[frametype=none]{无}
  \framezi[frametype=口]{口}
  \framezi[frametype=十]{十}
  \framezi[frametype=田]{田}
  \framezi[frametype=×]{叉}
  \framezi[frametype=米]{米}
  \framezi[frametype=咪]{咪}}

  \opt{resize} 设置缩放方式。\opt{real}，使用字符实际宽高缩放，\opt{base}，使用 \opt{basechar} 设置的字符的宽高缩放，\opt{square}，使得字符的宽高相等再进行缩放。还可自定义缩放方式，详见第 \ref{sec:interface} 节。

  以下为宽度设置为 1cm，\opt{resize} 分别为 \verb|none|，\verb|real|，\verb|base|，\verb|square|时的缩放情况。

  {\zitiesetup{font=楷体,width=1cm,frametype=咪,framecolor=black}
  \framezi[resize=none]{无}
  \framezi[resize=real]{实}
  \framezi[resize=base]{基}
  \framezi[resize=square]{方}}
\end{function}

\changes{v1.2}{2021/09/23}{新增 \opt{holdbasecharwidth}、\opt{holdbasecharheight}、\opt{holdbasechar} 选项。}
\begin{function}{
  xscale,yscale,scale,
  width,height
}
  \begin{syntax}
    xscale = \meta{scale ratio} \init{1}
    yscale = \meta{scale ratio} \init{1}
    scale  = \meta{scale ratio}
    width  = \meta{dim}
    height = \meta{dim}
    holdbasecharheight = \TTF \init{false}
    holdbasecharwidth  = \TTF \init{false}
    holdbasechar       = \TTF
  \end{syntax}
  设置缩放比例和盒子宽高。

  宽高具有更高的优先级，即若比例和宽高都设置了，则使用宽高来计算。宽高为二者都为0cm视为未设置，二者有一大于0cm，视为设置了宽高。

  此处的宽高和最终的宽高可能略有差异，最终的宽高保存在 \tn{zitiewidth} 和 \tn{zitieheight} dim寄存器中。
  
  \opt{holdbasecharheight}设置为 \opt{true} 时，将保证单个盒子至少有 \opt{basechar} 的高度，\opt{holdbasecharwidth} 设置为 \opt{true} 时，将设置盒子宽度为 \opt{basechar} 的宽度。\opt{holdbasechar} 将同时设置二者的值。
\end{function}

\begin{function}{
  linewidth,
  dashpattern,
  framearc,
  framearc*
}
  \begin{syntax}
    linewidth   = \meta{dim} \init{0.4pt}
    dashpattern = \{ \meta{dim1}, \meta{dim2}, ... \}
    framearc    = \meta{dim}
    framearc*   = \marg{dim1} \marg{dim2}
  \end{syntax}
\end{function}

{\zitiesetup{width=2cm,framecolor=black,font=楷体}
\verb|linewidth=1pt|：\framezi[linewidth=1pt]{好} \\
\verb|dashpattern={1mm,2mm,3mm,4mm}|：\framezi[dashpattern={1.5mm,1mm,2mm,1.5mm}]{好} \\
\verb|framearc=3mm,frametype=|\verb|口|：\framezi[framearc=3mm,frametype=口]{好} \\
\verb|framearc=3mm,frametype=|\verb|咪|：\framezi[framearc=3mm,frametype=咪]{好} \\
\verb|framearc*={3mm}{6mm},frametype=|\verb|口|：\framezi[framearc*={3mm}{6mm},frametype=口]{好} \\
\verb|framearc*={3mm}{6mm},frametype=|\verb|咪|：\framezi[framearc*={3mm}{6mm},frametype=咪]{好}
}

\begin{function}{
  framecolor,
  framecolor*,
  charcolor,
  charcolor*,
  fillcolor,
  fillcolor*
}
  \begin{syntax}
    framecolor  = \meta{color expr} \init{black}
    framecolor* = \marg{model(s)} \marg{value(s)}
    charcolor   = \meta{color expr} \init{black}
    charcolor*  = \marg{model(s)} \marg{value(s)}
    fillcolor   = \meta{color expr}
    fillcolor*  = \marg{model(s)} \marg{value(s)}
  \end{syntax}
  命名的颜色仅支持 \LaTeX3 定义的 black, white, red, green, blue, cyan, magenta 和 yellow。颜色模型和表达式也应使用 \LaTeX3 支持的模型和表达式，详见 \pkg{interface3.pdf}\cite{pdf-interface3} 文档。

  若要去掉 \opt{fillcolor}，应将其设置为空，即 \verb|fillcolor={}|，而不是将其设置为白色。
\end{function}

\changes{v1.2}{2021/09/23}{\opt{charstroke} 新增 \opt{invisible} 值。}
\changes{v1.3}{2021/09/25}{新增带 \opt{thick} 前缀的值。}
\begin{function}{
  charstroke,
  charstrokespecial,
  \zitiestrokechars
}
  \begin{syntax}
    charstroke = <none|solid|dashed|whitesolid|whitedashed|thicksolid|thickdashed|
    ~~~~~~~~~~~~~~thickwhitesolid|thickwhitedashed|invisible|...> \init{none}
    charstrokespecial = \meta{pdf literal}
    \cs{zitiestrokechars} \marg{pdf literal} \marg{typeset material}
  \end{syntax}
  设置字符的外框，类似微软Word中字符的轮廓特效：\framezi[width=2\ccwd,charcolor=blue,charstroke=solid,fillcolor={}]{好}
  \framezi[width=2\ccwd,charcolor=blue,charstroke=dashed,fillcolor={}]{好}

  初始值 \opt{none} 什么也不做。\opt{solid} 设置外轮廓为 0.25bp 的实线，\opt{dashed} 设置外轮廓为 0.25bp 的虚线。这两个
  不会进行填充操作，即背景色是什么颜色，则字显示的就是背景，字轮廓的颜色为 \opt{charcolor} 的颜色。\opt{whitesolid} 和
  \opt{whitedashed} 在 \opt{solid} 和 \opt{dashed} 的基础上将字填充为白色。
  带 \opt{thick} 的值将线宽设为 0.15bp，其它的与不带 \opt{thick} 的一致。\opt{invisible} 将字符设置为不可见，但不影响背景和网格的显示，隐藏的字仍然可被复制。

  \opt{charstrokespecial} 将 \meta{pdf literal} 为用在 \tn{special}\verb|{pdf:code ...}| 中 pdf 的指令，
  其中，\verb|charstroke=solid| 相当于 \verb|charstrokespecial={1 Tr 0.25 w [] 0 d 1 J}|，
  \verb|charstroke=dashed| 相当于 \verb|charstrokespecial={1 Tr 0.25 w [0.8] 0 d 1 J}|，
  \verb|charstroke=whitesolid| 相当于 \verb|charstrokespecial={2 Tr 0.25 w [] 0 d 1 J 1 1 1 rg}|，
  \verb|charstroke=whitedashed| 相当于 \verb|charstrokespecial={2 Tr 0.25 w [0.8] 0 d 1 J 1 1 1 rg}|。
  
  \meta{pdf literal} 可用的算符参考 \pkg{pdf reference}\cite{pdfreference}。
\end{function}
  
于是可将字符渲染模式设置为3来隐藏字：\\
\verb|\framezi[charstroke=solid]{字}|：\framezi[width=1cm,charstroke=solid]{字}， \\
\verb|\framezi[charstrokespecial={3 Tr}]{字}|：\framezi[width=1cm,charstrokespecial={3 Tr}]{字}。

还可使用 \cs{zitienewrule} 来定义新的 \opt{charstroke} 处理规则。这个键的处理器接收当前的 \meta{CJK char} 作为其参数。
具体的定义见 \cs{zitienewrule} 的说明和第 \ref{sec:processors} 节。

\cs{zitiestrokechars} 使用 \meta{pdf literal} 处理 \meta{typeset material}。
  
于是上述隐藏字的效果可用 \cs{zitienewrule} 和 \cs{zitiestrokechars} 来定义一个 \opt{invisible} 规则：
\begin{verbatim}
  \zitienewrule{charstroke}{invisible}{\zitiestrokechars{3 Tr}{#1}}
  \framezi[width=1cm,charstroke=invisible]{字}
\end{verbatim}
  \framezi[width=1cm,charstroke=invisible]{字}。这与上面的效果是相同的。实际上，\pkg{zitie} 就是这样实现的。

\begin{function}{
  font,savefontname,
  fallback,
  fontbackfont,
  fontbackfont+
}
  \begin{syntax}
    font = \meta{font family} \init{宋体}
    savefontname = \TTF \init{false}
    fallback = \TTF \init{false}
    fallbackfont = \marg{fallback font list}
    fallbackfont+= \marg{fallback font list}
  \end{syntax}
  \opt{font} 设置盒子中使用的字体，若将其设置为空，即 \verb|font={}| 或 \verb|font|，则将使用正文字体。

  \opt{savefontname} 设置是否保存字体名字，若设置为真，则将 \opt{font} 键指定的字体名字保存在 \tn{zitiefontname} 中，以便在后文使用，如在标点符号的处理中或页眉页脚中。

  \opt{fallbackfont} 设置当当前字体中不存在此字形时，要使用哪些字体，字体必须被 \cs{zitienewfont} 或 \cs{newCJKfontfamily} 声明。
  \opt{fallbackfont+} 将 \marg{fallback font list} 局部的添加到之前的 \meta{fallback font list} 中。

  该特性仅可在 \XeTeX{} 中使用。

  注意，\opt{fallbackfont} 特性和 \pkg{xeCJK} 的 \verb|FallBack| 并不冲突，当 \opt{fallback font list} 中的所有字体没有对应的字形时，才会使用 \verb|FallBack| 定义的字体。这一特性可通过设置 \verb|fallback=false| 来关闭。
\end{function}

如在 \verb|FZSunGuoTingCaoShuFU|（方正孙过庭草书）字体中没有“丂丄”，
虽然在在导言区使用 \verb|\zitienewfont{ {孙过庭草繁}{FZSunGuoTingCaoShuFU}{FallBack=SimSun} }| 设置其 \verb|FallBack| 字体为 \verb|SimSun|（宋体），但若设置 \verb|fallbackfont={楷体},fallback=true| 则会在楷体中查找是否有该字形，然后才在宋体中查找：

\begin{verbatim}
  \framezi[fallbackfont={楷体},width=1cm,font=孙过庭草繁,fallback,holdbasecharheight]{一丁丂七丄}
\end{verbatim}
\framezi[fallbackfont={楷体},width=1cm,font=孙过庭草繁,fallback,framecolor=black,holdbasecharheight]{一丁丂七丄}

\begin{verbatim}
  \framezi[width=1cm,font=孙过庭草繁,fallback,holdbasecharheight]{一丁丂七丄}
\end{verbatim}
\framezi[width=1cm,font=孙过庭草繁,fallback,framecolor=black,holdbasecharheight]{一丁丂七丄}

\begin{function}{
  filepath,
  filepath+
}
  \begin{syntax}
    filepath = \{ <filepath1>, <filepath2>, ... \}
  \end{syntax}
  \opt{filepath} 为 \cs{framezifile}\verb|*| 添加文件搜索路径。其值为逗号分隔的列表。
  \opt{filepath+} 将新的搜索路径局部地添加到原有的路径上。
\end{function}

\changes{v1.3}{2021/09/25}{新增 \opt{repeat} 功能。}
\changes{v1.3.2}{2021/09/26}{新增 \opt{break}、\opt{tolerance} 功能。}
\begin{function}{
  repeat,
  break,
  tolerance,
  zitie/repeat
}
  \begin{syntax}
    repeat = <integer> \init{1}
    break  = <default|allowbreak|...> \init{allowbreak}
    tolerance = <dim> \init{1em}
  \end{syntax}
  设置 \cs{framezi} 等命令中的字符重复次数。注意是将整体重复 \meta{integer} 次，而不是将单个字符重复 \meta{integer} 次，再进行下一个字符的处理。

  \verb|zitie/repeat| 钩子，只在两两间执行，执行次数为 $\meta{integer}-1$。
  这个钩子的内容在执行完毕后不会被清除，因此，若不自行清除，则在不同的方框化命令中都会执行（如果 $\opt{repeat}>1$）。可将 \cs{RemoveFromHook}\verb|{zitie/repeat}|\oarg{label} 放入 \verb|zitie/.../after| 钩子来清除。

  \begin{verbatim}
    \framezi[width=1cm,repeat=3]{好的}
  \end{verbatim}
  \framezi[width=1cm,repeat=3]{好的}

  \opt{break} 设置单个字符后的断行方法。默认为 \opt{allowbreak}，即将 \tn{allowbreak} 插入到构造好的盒子后。
  \opt{tolerance} 设置断行的允许值，影响 \opt{break} 值为 \opt{default} 时的断行效果，\opt{tolerance} 大，则可能造成 Overfull。

  \opt{break} 和 \opt{tolerance} 仍是实验性的。
\end{function}

\changes{v1.4.0}{2021/10/01}{新增 \opt{tallheight} 选项。}
\begin{function}{tallheight}
  \begin{syntax}
    tallheight = <integer> \init{1000}
  \end{syntax}
  \opt{tallheight} 选项控制 \verb|tall| 型命令隐式地在 \meta{integer} 个词后进行分段。因此，为了保证排版美观，\opt{tallheight} 最好为每行能容纳词数的倍数。而且这个值也受单个最大能处理的词数的限制，即不能超过3200。
\end{function}

\changes{v1.4.0}{2021/10/01}{新增 \opt{validateglyph} 选项。}
\begin{function}{validateglyph}
  \begin{syntax}
    validateglyph = \TTF \init{false}
  \end{syntax}
  这个选项设置为真时，将先判断使用的字体是否包含该字形，若不包含，则忽略该字符。判断字形时不会考虑 FallBack 字体。

  目前这个选项仅在 \cs{framesingle} 命令中有效。
\end{function}

\begin{function}{
  \zitiesetup,
  \zitiecolorlet,
}
  \begin{syntax}
    \cs{zitiesetup} \marg{key-val}
    \cs{zitiecolorlet} \marg{name} \oarg{model} \marg{value}
  \end{syntax}
  \cs{zitiesetup} 为 \pkg{zitie} 宏包的设置命令，这个命令设置的值在当前组中有效。\cs{zitiecolorlet} 定义新的颜色。注意，若加载 \pkg{xcolor} 宏包，使用 \tn{colorlet} 命令定义的颜色无法在 \pkg{zitie} 宏包的选项中使用，必须使用 \cs{zitiecolorlet} 来定义颜色。
\end{function}

\begin{function}{\zitienewprocessorrule,\zitienewrule,\zitieuseprocessorrule}
  \begin{syntax}
    \cs{zitienewprocessorrule} \oarg{arg nums} \marg{processor} \marg{rule} \marg{replace}
    \cs{zitieuseprocessorrule} \oarg{arg nums} \marg{processor} \marg{rule} \meta{args}
  \end{syntax}
  \cs{zitienewprocessorrule} 为 \pkg{zitie} 宏包的处理器 \meta{processor} 定义新的处理规则。将忽略 \meta{option key} 和 \meta{rule} 两端的空格。
  \cs{zitienewrule} 与 \cs{zitienewprocessorrule} 的作用相同。
  
  \cs{zitieuseprocessorrule} 使用 \meta{processor} 的 \meta{rule} 规则，\meta{args} 为 \meta{processor} 处理器的参数。

  关于处理器和规则，见第 \ref{sec:processors} 节。

  \meta{arg nums} 为键预先定义的参数数目。若未设置 \meta{arg nums}，则将其设置为1。
\end{function}

\begin{function}{
  \zitiebasechar,
  \zitiebasecharwidth,
  \zitiebasecharheight,
  \zitiewidth,
  \zitieheight,
  \zitieboxwd,
  \zitieboxht,
  \zitieboxdp,
  \zitiefontname,
  \zitiexscaleratio,
  \zitieyscaleratio,
}
  \cs{zitiebasechar}、\cs{zitiebasecharwidth}、\cs{zitiebasecharheight} 为局部设置的。其余的命令为全局设置的接口。
\end{function}

\begin{function}{
  zitieframecolor,
  zitiecharcolor,
  zitiefillcolor,
}
  这些是全局保存的颜色名，可在 \pkg{xcolor} 宏包的 \tn{color} 命令和 \LaTeX3 \cs{color_select:n} 命令中使用。
\end{function}


\section{background}\label{sec:background}

在宏包加载时使用 \opt{enable-background} 以启用该特性。

\begin{function}{\zitiebackground}
  \begin{syntax}
    \cs{zitiebackground} \oarg{background key-val}
  \end{syntax}
  使用背景。
\end{function}

\pkg{background} 可用的键值：（设置是全局的）

\begin{function}{true, on, false, off, next}
  \opt{true} 和 \opt{on} 作用相同，表示设置网格背景。
  \opt{false} 和 \opt{off} 作用相同，表示取消网格背景。
  \opt{next} 表示下一次设置背景，即当前页设置背景。这个选项也将取消之前设置的背景。
\end{function}

\begin{function}{
  colboxes,rowboxes,
  framewidth,frameheight,
  boxwidth,boxheight,
  onpaper,ontext
}
  \begin{syntax}
    colboxes    = \meta{integer} \init{1}
    rowboxes    = \meta{integer} \init{1}
    framewidth  = \meta{dim}
    frameheight = \meta{dim}
    boxwidth    = \meta{dim}
    boxheight   = \meta{dim}
    onpaper
    ontext
  \end{syntax}
  设置背景格子的大小。

  \opt{boxwidth} 和 \opt{boxheight} 具有更高的优先级，若设置了，则背景每个格子的宽高为所设置的值，否则，使用 \opt{framewidth}、\opt{frameheight} 及 \opt{colboxes}、\opt{rowboxes} 来计算大小。

  \opt{onpaper} 设置 \verb|frameheight=\paperheight, framewidth=\paperwidth|，
  \opt{ontext} 设置 \verb|frameheigh=\textheight, framewidth=\textwidth|。
\end{function}

\begin{function}{
  frametype,
  linewidth,
  framecolor,
  framecolor*,
  fillcolor,
  fillcolor*,
  dashpattern
}
  \begin{syntax}
    frametype   = <none|口|十|田|×|米|咪|二|(||)> \init{none}
    linewidth   = <dim> \init{0.4pt}
    framecolor  = <color expr> \init{black}
    framecolor  = \marg{model(s)} \marg{value(s)}
    fillcolor   = <color expr>
    fillcolor*  = \marg{model(s)} \marg{value(s)}
    dashpattern = \{ <dim1>, <dim2>, ... \}
  \end{syntax}
  和 \cs{framezi} 等命令的选项作用相同，但二者互不影响。

  其中 \opt{frametype} 的值 \verb|二| 为画外侧方框和横线，\opt{frametype} 的值 \verb=||= 为画外侧方框和竖线。

  颜色分别保存在 \verb|zitiebackgroundframecolor|，\verb|zitiebackgroundfillcolor| 颜色名中。可在 \tn{color} 中直接使用，也可在 \cs{color_select:n} 中使用。
\end{function}

\begin{function}{xrange,yrange}
  \begin{syntax}
    xrange = \{ \meta{left} , \meta{right} \} \init{{0cm, \paperwidth}}
    yrange = \{ \meta{top} , \meta{bottom} \} \init{{0cm, \paperheight}}
  \end{syntax}
  设置网格显示的范围。\meta{left}、\meta{right} 为距页面左端的距离。\meta{top}、\meta{bottom} 为距页面顶端的距离。
\end{function}

也可以使用 \verb|\zitiesetup{background={|\meta{background key-val}\verb|}}| 来设置键。

本文档的设置为：
\begin{verbatim}
  \zitiebackground[
    on, linewidth=0.2pt, dashpattern={1mm,.5mm,2mm,1mm},
    frametype=田, framecolor=green!80!black,
    colboxes=20, rowboxes=30,
  ]
\end{verbatim}

\section{zhlipsum, 中文乱数假文}

\pkg{zitie} 宏包完全兼容 \pkg{zhlipsum} 宏包\cite{pkg-zhlipsum}。使用 \cs{newzhlipsum} 命令定义的假文也可使用。

在加载宏包时使用 \opt{enable-zhlipsum} 以启用该特性。

\begin{function}{
  \framezhlipsum,
  zitie/framezhlipsum/before,
  zitie/framezhlipsum/after,
  zitie/framezhlipsum/paragraph
}
  \begin{syntax}
    \cs{framezhlipsum} \oarg{key-val} \marg{paragraph list} \oarg{name}
  \end{syntax}
  \meta{key-val} 为 \cs{framezi} 第 \ref{sec:options} 节定义的选项，\meta{paragraph list} 为段落列表，支持如下形式：\verb|6-8,-3,9|。\meta{name} 为假文的名字。可用值为 \opt{simp}、\opt{trad}、\opt{nanshanjing}、\opt{xiangyu}、\opt{zhufu}、\opt{aspirin}，详细说明参考 \pkg{zhlipsum} 宏包的说明文档。

  定义了 \verb|zitie/framezhlipsum/before|、\verb|zitie/framezhlipsum/after|、\verb|zitie/framezhlipsum/paragraph| 三个钩子。其中 \verb|zitie/framezhlipsum/paragraph| 为假文间要执行的代码，如有5段，则在这5个段落中间格执行一次，即执行4次。其它两个钩子的用法和前述相似。
\end{function}


\changes{v1.3}{2021/09/25}{新增处理器和规则一节。}
\section{处理器和规则}\label{sec:processors}

\emph{处理器}实际上就是一个宏，这个宏可以使用指定的\emph{规则}来处理其参数。

规则可以接收给定的参数，这些参数数目及传入顺序是由对应的处理器指定的。例如 \pkg{zitie} 就定义了 \opt{position}、\opt{punctuation}、\opt{charstroke} 等处理器。
它们使用指定的规则对给定参数进行处理。

处理器可以使用 \cs{zitienewprocessorrule} 来定义新的规则。\pkg{zitie} 宏包为 \opt{position}、\opt{punctuation}、\opt{charstroke} 等处理器预先定义了一些规则：

使用
\begin{verbatim}
  \zitie_new_process_rule:nnn { position } { anchor-center }
    { \coffin_typeset:Nnnnn #1 { hc } { vc } { 0pt } { 0pt } }
  \zitie_new_process_rule:nnn { position } { anchor-east }
    { \coffin_typeset:Nnnnn #1 { r } { vc } { 0pt } { 0pt } }
  \zitie_new_process_rule:nnn { position } { anchor-southeast }
    { \coffin_typeset:Nnnnn #1 { r } { b } { 0pt } { 0pt } }
  ...
\end{verbatim}
定义了 \opt{position} 处理规则：\opt{anchor-center}、\opt{anchor-east} 等，这样就可使用 \verb|position=anchor-center| 来引用它们。

使用
\begin{verbatim}
  \zitienewrule{punctuation}{onlast}
    {\penalty10000 \smash{\makebox[0pt]{%
      \color{zitiecharcolor}\zitieCJKfamily{\zitiefontname}#1}}}
  \zitienewrule{punctuation}{scale}{
    \hbox_set:Nn \l_tmpa_box 
      { \color_select:n { zitiecharcolor } \zitieCJKfamily{\zitiefontname} #1 }
    \box_scale:Nnn \l_tmpa_box \zitiexscaleratio \zitieyscaleratio 
    \box_use_drop:N \l_tmpa_box 
  }
\end{verbatim}
定义了两个 \opt{punctuation} 处理规则：\opt{onlast} 和 \opt{scale}，这样就可以使用 \verb|punctuation=onlast| 和 \verb|punctuation=scale| 来对标点符号进行处理。

使用
\begin{verbatim}
  \zitienewrule {charstroke} {solid}
    { \zitiestrokechars { 1 Tr 0.25 w [] 0 d 1 J } {#1} }
  \zitienewrule {charstroke} {dashed}
    { \zitiestrokechars { 1 Tr 0.25 w [0.8] 0 d 1 J } {#1} }
  \zitienewrule {charstroke} {whitesolid}
    { \zitiestrokechars { 2 Tr 0.25 w [] 0 d 1 J 1 1 1 rg } {#1} }
  \zitienewrule {charstroke} {whitedashed}
    { \zitiestrokechars { 2 Tr 0.25 w [0.8] 0 d 1 J 1 1 1 rg } {#1} }
  \zitienewrule {charstroke} {thicksolid}
    { \zitiestrokechars { 1 Tr 0.15 w [] 0 d 1 J } {#1} }
  \zitienewrule {charstroke} {invisible} { \zitiestrokechars {3 Tr} {#1} }
  ...
\end{verbatim}
定义了 \opt{charstroke} 处理规则，这样就可以使用 \verb|charstroke=solid, ...| 来处理字符。

规则的定义中还可以使用 \cs{zitieuseprocessorrule} 来引用已经定义好的规则。

\section{编程接口}\label{sec:interface}

\changes{v1.2}{2021/09/23}{将 \cs{zitie_color_select:..} 改为 \cs{zitie_color_set:..}。}
\changes{v1.3}{2021/09/25}{新增 \cs{...set_eq:nn}。}
\begin{function}{
  \zitie_new_frame_construct:nn,
  \zitie_frame_type:n,
  \zitie_frame_type_c:n,
  \zitie_frame_type_set_eq:nn,
  \zitie_new_resize_method:nn,
  \zitie_resize_method_set_eq:nn,
  \zitie_new_font:n,
  \zitie_new_font:nnn,
}
  创建新的构造器、resize方法和字体。
\end{function}

\begin{function}{
  \zitie_new_process_rule:nnn,
  \zitie_new_process_rule:nnnn,
  \zitie_processor:n,
  \zitie_processor_c:n,
  \zitie_processor:nnn,
  \zitie_processor_c:nnn,
}
  创建和使用处理器。
\end{function}

\begin{function}{
  \zitie_color_set:nn,
  \zitie_color_set:nnn,
}
  颜色选择。
\end{function}

\begin{function}{
  \zitie_cjk_glyph_use:nN,
  \zitie_token_class_dispatch:Nnnnn,
  \zitie_token_class_dispatch_o:Nnnnn,
  \zitie_token_class_dispatch_f:Nnnnn,
}
  字形选择和字符类别判断。仅在 \XeTeX 中有效。
\end{function}

\begin{function}[TF]{
  \zitie_token_if_punctuation:N,
  \zitie_token_if_punctuation_o:N,
  \zitie_token_if_punctuation_f:N,
}
  是否为标点符号。仅在 \XeTeX 中有效。
\end{function}

\changes{v1.4.0}{2021/10/01}{新增 \cs{zitie_single_validate_glyph_construct:N}、\cs{zitie_single_validate_glyph_construct:nN}。}
\begin{function}{
  \zitie_single_construct:N,
  \zitie_single_construct:nN,
  \zitie_single_validate_glyph_construct:N,
  \zitie_single_validate_glyph_construct:nN,
}
  构造单个字的方框。
\end{function}

\begin{function}{
  \zitie_background_new_frame_construct:nn,
  \zitie_background_frame_type:n,
  \zitie_background_frame_type_c:n,
  \zitie_background_frame_type_set_eq:nn
}
  创建和使用新的 background frame 类型。
\end{function}

\section{TODO}

\begin{itemize}
  \item 实现更快的、消耗资源更少的版本。
  \item 修改断行算法。
  \item 优化对 \LuaTeX{} 的支持。
  \item 优化背景模块。
  \item 增加间距功能。
  \item 更多网格效果。
  \item 更多缩放和变换效果。
  \item 对字符类别进行更多的分类处理。
  \item 支持透明度，（需要 \pkg{l3opacity}）。
  \item 等。
\end{itemize}


\begin{thebibliography}{9}
\bibitem{pkg-xeCJK}
\href{http://www.ctex.org}{CTEX.ORG},
\newblock \textit{\pkg{xeCJK} 宏包}
\bibitem{pkg-fontspec}
\textsc{WILL ROBERTSON},
\newblock With contributions by Khaled Hosny, Philipp Gesang, Joseph Wright, and others.
\newblock \textit{The fontspec package}
\bibitem{pdf-source2e}
\textsc{Johannes Braams,
David Carlisle,
Alan Jeffrey,
Leslie Lamport,
Frank Mittelbach,
Chris Rowley,
Rainer Schöpf},
\newblock \textit{The {\LaTeXe} Sources}
\bibitem{pkg-lthooks}
\textsc{Frank Mittelbach},
\newblock \textit{The lthooks package}
\bibitem{pdf-interface3}
\textsc{The {\LaTeX} Project},
\newblock \textit{The {\LaTeX3} Interfaces}
\bibitem{pkg-xcoffins}
\textsc{The \LaTeX{} Project},
\newblock \textit{The xcoffins package}
\bibitem{pkg-zhlipsum}
{\kaishu 曾祥东},
\newblock \textit{zhlipsum: 中文乱数假文（Lorem ipsum）}
\bibitem{pdfreference}
\textsc{Adobe® Systems Incorporated},
\newblock \textit{Adobe® Portable Document Format}
\end{thebibliography}

\IndexLayout
\zitiebackground[off]
\PrintChanges
\PrintIndex
\end{document}