ctxdoc: 重定义 SideBySideExample 环境，方便使用并修正上下间距问题 [ci skip]

jiazhu/jiazhu.dtx

@@ -129,10 +129,14 @@ Copyright and Licence
 %<*driver>
 \documentclass{ctxdoc}
 \usepackage{jiazhu}
-
-\jiazhuset { ideohtratio = 0.8 , opening = 〔 , closing = 〕 }
+\ExplSyntaxOn
+\sys_if_platform_windows:TF
+  { \jiazhuset { ideohtratio = 220/256 } }
+  { \jiazhuset { ideohtratio = 0.8 } }
+\ExplSyntaxOff
+\jiazhuset { opening = 〔 , closing = 〕 }
 \newCJKfontfamily\mincho{HaranoAjiMincho}
-
+\SideBySideExampleSet{xrightmargin=.25\linewidth}
 \begin{document}
   \DocInput{\jobname.dtx}
   \IndexLayout
@@ -185,7 +189,7 @@ Copyright and Licence
 %   如果样式为空值，那么夹注与前后正文的字体保持一致。
 %   如果夹注两端有括弧，那么指定的样式也会作用在这对括弧上。
 %   例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     正文\jiazhu{夹注现在是宋体字}正文\\[5pt]
 %     正文\jiazhu[format=\linespread{1.5}]{夹注行距被扩大了}正文\\[5pt]
 %     正文\jiazhu[format=\sffamily]{夹注现在是黑体字}正文
@@ -197,7 +201,7 @@ Copyright and Licence
 %     lines = \Arg{正整数}
 %   \end{syntax}
 %   指定夹注的行数，必须是正整数。默认值是~2。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     正文\jiazhu[lines=3]{夹注现在变成三行}正文
 %   \end{SideBySideExample}
 % \end{function}
@@ -236,13 +240,11 @@ Copyright and Licence
 %   这是因为 \opt{ideohtratio=0.5} 的默认值是根据直排文档设定的值。
 %   在横排文档中，\opt{ideohtratio} 的值视具体的字体而定，
 %   一般在 0.8 至 0.88 之间。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.27\linewidth,gobble=5]
+%   \begin{SideBySideExample}[xrightmargin=.27\linewidth]
 %     正文\jiazhu{默认的参数设定是以直排优先的}正文\\[5pt]
 %     正文\jiazhu[ideohtratio=0.8]{调整参数来对齐横排夹注与正文}正文
 %   \end{SideBySideExample}
 %
-%   \medskip
-%
 %   这里列出几类常见字体对应的 \opt{ideohtratio} 值：
 %   \begin{center}
 %   \def\hfilll{\hskip 0pt plus 1filll\relax}^^A 慎用
@@ -283,7 +285,7 @@ Copyright and Licence
 %   指定夹注字号与正文字号的比值，是实数
 %   （也接受 \opt{ratio=1/2} 这种分数写法）。
 %   默认值是~2/3。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     正文\jiazhu[ratio=0.5]{夹注字号是正文字号的 50\%}正文\\
 %     正文\jiazhu[ratio=1/2]{夹注字号是正文字号的 50\%}正文
 %   \end{SideBySideExample}
@@ -296,7 +298,7 @@ Copyright and Licence
 %   经文多在夹注两端插入少许空白，以此隔开正文与夹注。
 %   \opt{beforeskip} 指定前置于夹注的空白。
 %   默认值是 \tn{smallskipamount}。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     正文\jiazhu[beforeskip=0pt plus 1pt]{夹注前端紧贴正文}正文
 %   \end{SideBySideExample}
 % \end{function}
@@ -307,7 +309,7 @@ Copyright and Licence
 %   \end{syntax}
 %   指定后置于夹注的空白。
 %   默认值是 \tn{smallskipamount}。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     正文\jiazhu[afterskip=0pt plus 1pt]{夹注后端紧贴正文}正文
 %   \end{SideBySideExample}
 % \end{function}
@@ -317,7 +319,7 @@ Copyright and Licence
 %     opening = \Arg{前置内容}
 %   \end{syntax}
 %   指定前置于夹注的括弧。默认不添加。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.3\linewidth,gobble=5]
+%   \begin{SideBySideExample}[xrightmargin=.3\linewidth]
 %     正文\jiazhu[opening=〖]{夹注前置了左空心括号}正文
 %   \end{SideBySideExample}
 % \end{function}
@@ -327,7 +329,7 @@ Copyright and Licence
 %     closing = \Arg{后置内容}
 %   \end{syntax}
 %   指定后置于夹注的括弧。默认不添加。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.3\linewidth,gobble=5]
+%   \begin{SideBySideExample}[xrightmargin=.3\linewidth]
 %     正文\jiazhu[closing=】]{夹注后置了右实心括号}正文
 %   \end{SideBySideExample}
 % \end{function}
@@ -339,7 +341,7 @@ Copyright and Licence
 %   指定括弧字号与夹注字号的比值，是实数
 %   （也接受 \opt{bracketratio=5/2} 这种分数写法）。
 %   默认值是~2。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     正文\jiazhu[opening=（,bracketratio=1]{括弧字号等于夹注字号}正文
 %   \end{SideBySideExample}
 % \end{function}
@@ -352,13 +354,11 @@ Copyright and Licence
 %
 %   如果夹注本身（或者紧随其后的正文）有超常的高度，
 %   那么夹注前后的正文可能会错位。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     \newcommand\ideobaseline{\llap{\rule[-2.1bp]{76.2625pt}{0.2pt}}}
 %     正文\jiazhu[lines=4]{特殊效果}正文错位\ideobaseline
 %   \end{SideBySideExample}
 %
-%   \medskip
-%
 %   让我们设这个“特殊”夹注所处那一行的行距（\tn{baselineskip}）为
 %   $b$~plus~$y_b$~minus~$z_b$，
 %   又设该夹注与其后同一行正文的最大高度（西文基线以上的部分）为~$h$，
@@ -375,7 +375,7 @@ Copyright and Licence
 %   $\tn{lineskiplimit}=0\,\mathrm{pt}$，
 %   $l=1\,\mathrm{pt}$。
 %   因此，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     \newcommand\ideobaseline{\llap{\rule[-2.1bp]{76.2625pt}{0.2pt}}}
 %     正文\jiazhu[lines=4,baselineshift=3.0376125pt]%
 %       {特殊效果}正文对齐\ideobaseline
@@ -389,26 +389,22 @@ Copyright and Licence
 %   指定夹注内容的横向对齐样式。默认值是 \opt{justified}。
 %   其中，\opt{left}、\opt{right}、\opt{centered}
 %   分别为“左对齐”、“右对齐”、“居中对齐”。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.22\linewidth,gobble=5]
+%   \begin{SideBySideExample}[xrightmargin=.22\linewidth]
 %     \jiazhuset{lines=3,ratio=0.5}
 %     正文\jiazhu[halign=left]{This is a three-line example}正文\\[5pt]
 %     正文\jiazhu[halign=right]{This is a three-line example}正文\\[5pt]
 %     正文\jiazhu[halign=centered]{This is a three-line example}正文
 %   \end{SideBySideExample}
 %
-%   \medskip
-%
 %   另外，\opt{justified}、\opt{distributed} 都是“两端对齐”，它们的区别是：
 %   在 \opt{justified} 样式下，末行左对齐；
 %   在 \opt{distributed} 样式下，末行仍然两端对齐。
 %   例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     正文\jiazhu[halign=justified]{㈠㈡㈢㈣㈤㈥㈦㈧㈨}正文\\
 %     正文\jiazhu[halign=distributed]{㈠㈡㈢㈣㈤㈥㈦㈧㈨}正文
 %   \end{SideBySideExample}
 %
-%   \medskip
-%
 %   \emph{传统排印一般只使用 \opt{justified}，不使用
 %   \opt{left}、\opt{right}、\opt{centered} 或 \opt{distributed}。}
 % \end{function}
@@ -421,7 +417,7 @@ Copyright and Licence
 %   默认值是 \opt{middle}，即中线对齐。
 %   其中，\opt{bottom}、\opt{top}
 %   分别为“底线对齐”、“顶线对齐”。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.25\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     \jiazhuset{lines=1,ratio=0.5}
 %     正文\jiazhu[valign=bottom]{夹注现在底线对齐}正文\\
 %     正文\jiazhu[valign=top]{夹注现在顶线对齐}正文

support/ctxdoc.cls

@@ -1,7 +1,7 @@
 %%
 %% File ctxdoc.cls
 %%
-%%     Copyright (C) 2016--2020
+%%     Copyright (C) 2016--2022
 %%     CTEX.ORG and any individual authors listed in the documentation.
 %%---------------------------------------------------------------------
 %%
@@ -123,6 +123,7 @@
 \setlist[1]{labelindent=\parindent}
 \setlist[enumerate]{leftmargin=*}
 \setlist[itemize]{leftmargin=*}
+\setlist[trivlist]{topsep=\medskipamount}
 \renewlist{arguments}{enumerate}{1}
 \setlist[arguments]{nolistsep,
   leftmargin=\parindent, labelindent=0pt, labelsep=*,
@@ -169,12 +170,9 @@
 \define@key{FV}{labelref}{\def\ctexexamlabelref{\label{#1}}}
 \let\ctexexamlabelref\empty
 \newcounter{ctexexam}
-\BeforeBeginEnvironment{function}{\par\nointerlineskip}
-\AtEndEnvironment{function}{%
-  \par\xdef\ctexfixprevdepth{\prevdepth=\the\prevdepth\space}}
-\AfterEndEnvironment{function}{\ctexfixprevdepth}
+\AtEndEnvironment{function}{\ctexsetverticalspacing}
+\AfterEndEnvironment{function}{\ctexfixverticalspacing}
 \AtBeginEnvironment{syntax}{\linespread{1}\ctexplainps\ctexdisableecglue}
-\BeforeBeginEnvironment{SideBySideExample}{\par\addvspace{\medskipamount}}
 \newrobustcmd\exptarget{%
   \AddLineBeginMainAux{\csgdef{Codedoc@expstar}{}}%
   \Hy@raisedlink{\hypertarget{expstar}{}}}
@@ -184,6 +182,35 @@
 \newrobustcmd\expstar{\hyperlink{expstar}{$\star$}}
 \newrobustcmd\rexpstar{\hyperlink{rexpstar}{\ding{73}}}
 \ExplSyntaxOn
+\cs_new_protected:Npn \ctexsetverticalspacing
+  {
+    \par
+    \tl_gset:Nx \ctexfixverticalspacing
+      { \dim_set:Nn \prevdepth { \dim_use:N \prevdepth } }
+    \int_compare:nNnT \lastnodetype = { 11 }
+      {
+        \tl_gput_right:Nx \ctexfixverticalspacing
+          { \exp_not:N \skip_vertical:n { \skip_use:N \lastskip } }
+        \unskip
+      }
+  }
+\tl_new:N \ctexfixverticalspacing
+\NewDocumentCommand \SideBySideExampleSet { }
+  { \prop_put_from_keyval:Nn \l__ctxdoc_side_example_prop }
+\prop_new:N \l__ctxdoc_side_example_prop
+\prop_set_from_keyval:Nn \l__ctxdoc_side_example_prop
+  { frame=single, numbers=left, gobble=5, xrightmargin=.5\linewidth }
+\tl_put_left:Nn \SideBySideExample
+  {
+    \trivlist \item \relax
+    \exp_args:Ne \fvset
+      { \prop_to_keyval:N \l__ctxdoc_side_example_prop }
+  }
+\tl_put_right:Nn \endSideBySideExample
+  { \endtrivlist }
+\ctex_patch_cmd:Nnn \__codedoc_function_typeset_start:
+  { \bigskip }
+  { \nointerlineskip \addvspace { \bigskipamount } }
 %% l3doc 会设置列表环境中 \listparindent=\z@，我们在这里恢复它。
 \cs_set_eq:NN \list \__codedoc_oldlist:nn
 \cs_new_nopar:Npn \zihaopt #1

xpinyin/xpinyin.dtx

@@ -279,7 +279,7 @@ Copyright and Licence
 %   对于多音字，可以使用 \tn{xpinyin} 为其设置拼音；而 \tn{xpinyin*} 相当于
 %   \env{pinyinscope} 环境的命令形式。\tn{xpinyin} 可以在 \env{pinyinscope} 环境和
 %   \tn{xpinyin*} 中使用。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.5\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     \xpinyin{长}{chang2}\\
 %     \xpinyin*{甄士隐梦幻识通灵}\\
 %     \xpinyin*{\xpinyin{重}{zhong4}要}
@@ -291,7 +291,7 @@ Copyright and Licence
 %     \tn{pinyin} \oarg{options} \Arg{拼音}
 %   \end{syntax}
 %   用于输出拼音，为了输入的方便 \texttt{\"u} 可以用 |v| 代替。例如，
-%   \begin{SideBySideExample}[frame=single,numbers=left,xrightmargin=.5\linewidth,gobble=5]
+%   \begin{SideBySideExample}
 %     \pinyin{lv2zi}\\
 %     \pinyin{nv3hai2zi}
 %   \end{SideBySideExample}