% ^^A  ================================== 元注释 ==================================
% \iffalse meta-comment
%
% 文件：drawmgr.dtx
%
% 版权 (C) 2024-2026 By Ms_yam
%
% 它可以在 LaTeX 项目公共许可（LPPL）1.3c 及之后的任意版本（随你的意见）下分发或修改。
% 这个许可的最新版本在如下文件中：
%
%   https://www.latex-project.org/lppl.txt
% 
% 本文件的 LPPL 维护状态为 "maintained"。
% 
% 本文件的当前维护者是 Ms_yam。
%
% \fi
%
% ^^A ================================== 安装信息 ==================================
% \iffalse 
%<*install>
\begingroup

\input docstrip.tex
\keepsilent
\usedir{tex/latex/drawmgr}
\askforoverwritefalse

\preamble
\endpreamble

\postamble
\endpostamble

\generate{
    \file{drawmgr.ins} {\from{\jobname.dtx}{install}}
    \file{drawmgr.sty} {\from{\jobname.dtx}{package}}   
    \nopreamble\nopostamble
    \file{README.md}   {\from{\jobname.dtx}{readme}}
  }

\endgroup
%</install>
% \fi
%
% ^^A ================================== 文档驱动 ==================================
% \iffalse
%<*driver>
\documentclass[show-notes]{l3doc}
\usepackage{drawmgr}
\usepackage{ctex}
\usepackage{l3draw}
\usepackage{listings}

% ^^A 汉化 l3doc 的部分定义
\NewDocumentEnvironment { texnote } { }% 不能用 Renew...，原因未知
{
  \endgraf
  \vspace{0.5em}% 3mm => 0.5em
  \small\textbf{\TeX{} 黑客笔记：}% \TeX~hackers~note:
}
{
  \vspace{0.5em}% 3mm => 0.5em
}

\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% 
% ^^A ================================ RADME ME ================================
% \iffalse
%<*readme> ^^A README

# 基本说明 Description

本宏包提供一个集体管理绘图脚本的工具，它允许用户将绘图脚本组织成模块，并在文档中按需调用。

This package provides a tool for collectively managing drawing scripts, 
which allows users to organize drawing scripts into modules and call them on demand in documents.


# 许可 License

版权 Copyright (C) 2023-2025 By Ms_yam


本宏包可以在 LaTeX 项目公共许可（LPPL）1.3c 及之后的任意版本（随你的意见）下分发或修改。
这个许可的最新版本在如下文件中：

   https://www.latex-project.org/lppl.txt

It may be distributed and/or modified under the conditions of the
LaTeX Project Public License (LPPL), either version 1.3c of this
license or (at your option) any later version.  The latest version
of this license is in the file

   https://www.latex-project.org/lppl.txt


本文件的 LPPL 维护状态为 "maintained"。

This file has LPPL maintenance status "maintained".

本文件的当前维护者是 Ms_yam。

The current maintainer of this file is Ms_yam.

本宏包由以下文件组成：
  drawmgr.dtx（源代码）、
  drawmgr.ins、
  drawmgr.sty、
  drawmgr.pdf 和 
  README.md （本文件）。

This package consists of 
  the source file  drawmgr.dtx,
  the install file drawmgr.ins,
  the drived files drawmgr.sty,
                   drawmgr.pdf and
                   README.md(this file).

# 编译 Compilation

本宏包设计为单文件包，你可以直接使用以下命令编译：

This package is designed as a single-file package and can be
compiled directly with the following commands:

```sh
xelatex drawmgr.dtx
makeindex -s gglo.ist -o drawmgr.gls drawmgr.glo
makeindex -s gind.ist -o drawmgr.ind drawmgr.idx
xelatex drawmgr.dtx
xelatex drawmgr.dtx
```

# 备注 Remark

英文版本描述由 AI 翻译，如有差异，请以中文版本为准。

The English version description is translated by AI. In case of 
any discrepancies, please refer to the Chinese version as the standard.

%</readme>
% \fi
% 
%
% ^^A ================================== 文档内容 ==================================
%
% \title{集中管理图形脚本的宏\\[0.5em]
%   \large Macros for Centralized Management of Graphics Scripts}
% \author{Ms_yam（\href{mailto:Ms_yam@163.com}{Ms_yam@163.com}）}
% ^^A \date{\zhdigits*{2025}年\zhnumber{12}月\zhnumber{25}日}
%
% \maketitle
%
% ^^A ---------------------------------- 文档部分 ----------------------------------
%
% \begin{documentation}
%
% \section{文档 Documentation}
%
% 本宏包设计用于集中管理 \LaTeX 图形脚本，以便维护。\par
% This package is designed to centrally manage \LaTeX{} graphics scripts for easier maintenance.
%
% \subsection{用户接口 User Interface}
%
%
% \begin{function}{\newdraw, \usedraw}
%   \begin{syntax}
%     \cs{newdraw} \Arg{图形索引} \Arg{图形脚本}
%     \cs{newdraw} \Arg{graphics-index} \Arg{graphics-script}
%     \cs{usedraw} \Arg{图形索引}
%     \cs{usedraw} \Arg{graphics-index}
%   \end{syntax}
%   创建和使用图形。\\
%   Create and use graphics.
% \end{function}
%
% 
% \noindent 如下示例代码：\\
% For instance: 
% \begin{verbatim}
%   \ExplSyntaxOn
%   \newdraw{sampleA}{
%     \draw_begin:
%       % 曲线 Curves
%       \color_stroke:n { blue!30!black } 
%       \draw_path_rectangle:nn { 0cm, 0cm } { 4cm, 3cm }
%       \draw_path_circle:nn { 1cm, 1.1cm } { 0.8cm }
%       \draw_path_circle:nn { 2.5cm, 1.5cm } { 1.2cm }
%       \draw_path_use_clear:n { stroke }
%     \draw_end:
%   }
%   \newdraw{sampleB}{
%     \draw_begin:
%       % 曲线 Curves
%       \color_stroke:n { blue!30!black } 
%       \draw_path_rectangle:nn { 0cm, 0cm } { 4cm, 3cm }
%       \draw_path_circle:nn { 1cm, 1.1cm } { 0.8cm }
%       \draw_path_circle:nn { 2.5cm, 1.5cm } { 1.2cm }
%       \draw_path_use_clear:n { stroke }
%       % 标签 Labels
%       \color_fill:n { blue!50!black }
%       \hbox_set:Nn \l_tmpa_box { $\varOmega$ }
%       \draw_box_use:Nn \l_tmpa_box { 3.5cm, 2.5cm }
%       \hbox_set:Nn \l_tmpa_box { $A$ }
%       \draw_box_use:Nn \l_tmpa_box { 0.4cm, 0.7cm }
%       \hbox_set:Nn \l_tmpa_box { $B$ }
%       \draw_box_use:Nn \l_tmpa_box { 2.7cm, 0.7cm }
%     \draw_end:
%   }
%   \usedraw{sampleB}
%   \usedraw{sampleA}
%   \ExplSyntaxOff
% \end{verbatim}
% 将输出：\\
% Results: \\
% \ExplSyntaxOn
% \newdraw{sampleA}{
%   \draw_begin:
%     ^^A Curves
%     \color_stroke:n { blue!30!black } 
%     \draw_path_rectangle:nn { 0cm, 0cm } { 4cm, 3cm }
%     \draw_path_circle:nn { 1cm, 1.1cm } { 0.8cm }
%     \draw_path_circle:nn { 2.5cm, 1.5cm } { 1.2cm }
%     \draw_path_use_clear:n { stroke }
%   \draw_end:
% }
% \newdraw{sampleB}{
%   \draw_begin:
%     ^^A Curves
%     \color_stroke:n { blue!30!black } 
%     \draw_path_rectangle:nn { 0cm, 0cm } { 4cm, 3cm }
%     \draw_path_circle:nn { 1cm, 1.1cm } { 0.8cm }
%     \draw_path_circle:nn { 2.5cm, 1.5cm } { 1.2cm }
%     \draw_path_use_clear:n { stroke }
%     ^^A Labels
%     \color_fill:n { blue!50!black }
%     \hbox_set:Nn \l_tmpa_box { $\varOmega$ }
%     \draw_box_use:Nn \l_tmpa_box { 3.5cm, 2.5cm }
%     \hbox_set:Nn \l_tmpa_box { $A$ }
%     \draw_box_use:Nn \l_tmpa_box { 0.4cm, 0.7cm }
%     \hbox_set:Nn \l_tmpa_box { $B$ }
%     \draw_box_use:Nn \l_tmpa_box { 2.7cm, 0.7cm }
%   \draw_end:
% }
% \usedraw{sampleB}
% \usedraw{sampleA} 
% \ExplSyntaxOff
%
%
% \begin{function}{\showdraw, \cleardraw}
%   \begin{syntax}
%     \cs{showdraw} [*]
%     \cs{cleardraw}
%   \end{syntax}
%   显示或清空已添加的图形。星号版本会显示索引及图形本身。\\
%   Display or clear added graphics. The starred version shows both indices and graphics.
% \end{function}
%
% \noindent 不带星号的版本（|\showdraw|）效果如下：\\
% The without star version results:\par
% \showdraw
%
% \noindent 带星号的版本（|\showdraw*|）效果如下：\\
% The without star version results:\par
% \showdraw*
%
% \begin{function}[added=2025-12-25]{\setfigurewidth}
%   \begin{syntax}
%     \cs{setfigurewidth} \Arg{宽度列表} 
%     \cs{setfigurewidth} \Arg{wd-clist} 
%   \end{syntax}
%   设置并排排版两张或三张图形时的各图形的宽度比例。
%   \Arg{宽度列表} 是一个长度为 $2$ 或 $3$ 的逗号分隔的列表，每个元素代表一张图形其相对于当前文本宽度的比例。
%   注意，图形之间包含一个 $0.05$ 倍的文本宽度，即逗号列表之和不应当大于 $1 - 0.05(n-1)$。\\
%   Set the width ratios of each figure when typesetting two or three figures side by side.
%   \Arg{wd-clist} is a comma-separated list of length 2 or 3, 
%   where each element represents the ratio of the corresponding figure relative to the current text width.
%   Note that there is a gap of 0.05 times the text width between adjacent figures, 
%   meaning the sum of the values in the comma-separated list should not exceed 1-0.05(n-1).
%   \begin{texnote}
%     这个命令用于修改 \cs{addfiguredbl}、\cs{addfigurethr} 命令插入的图形的默认宽度。
%     This command is used to modify the default widths of the figures inserted by
%     the \cs{addfiguredbl} and \cs{addfigurethr} commands.
%   \end{texnote}
% \end{function}
%
% \begin{function}[updated=2025-12-25]{\addfigure, \addfiguredbl, \addfigurethr}
%   \begin{syntax}
%     \cs{addfigure} \Arg{图形索引} \oarg{图形标签} \Arg{图形标题}
%     \cs{addfigure} \Arg{graph-index} \oarg{graph-label} \Arg{graph-title} 
%   \end{syntax}
%   使用浮动体添加插图。插图内容为 \Arg{图形索引} 关联的图形，插图标题由\Arg{图形标题} 指定。
%   本命令会自动为插图添加标签（“fig:” + \Arg{图形标签}），\Arg{图形标签} 默认与 \Arg{图形索引}  一致。
%   对于多个图形，每个图形的参数完全一致。\par
%   Using a floating environment to add illustrations. 
%   The content of the illustration corresponds to the graphic associated with \Arg{graph-index}, 
%   and the caption is specified by \Arg{graph-title}. 
%   This command automatically adds a label to the illustration (“fig:” + \Arg{graph-label}), 
%   where \Arg{graph-label} defaults to \Arg{graph-index}. 
%   For multiple graphics, the parameters for each graphic are completely consistent.
%   \begin{texnote}
%     单个图形始终独立整个文本宽度，多个图形则按 \cs{setfigurewidth} 指定的比例排版。
%     对于两个图形的场景，还可以使用可选参数（参数一）来临时指定图形的宽度。\\
%     A single figure always occupies the full text width independently, 
%     while multiple figures are typeset according to the ratios specified by \cs{setfigurewidth}.
%     For the scenario with two figures, an optional parameter (Parameter 1) can also be used to 
%     temporarily specify the widths of the figures.
%   \end{texnote}
% \end{function}
%
%
% \noindent 如下示例代码：\\
% For instance: \par
% \begin{verbatim}
%   \setfigurewidth { 0.3,  0.3 }
%   \setfigurewidth { 0.27, 0.27, 0.27 }
%   \addfigure    {sampleA} [addfigure]      {\cs{addfigure} 的效果} 
%   \addfiguredbl {sampleA} [addfiguredbl.1] {两张图的效果1} 
%                 {sampleB} [addfiguredbl.2] {两张图的效果2}
%   \addfigurethr {sampleA} [addfigurethr.1] {三张图的效果1} 
%                 {sampleB} [addfigurethr.2] {三张图的效果2} 
%                 {sampleA} [addfigurethr.3] {三张图的效果3}
% \end{verbatim}
%
%
% \noindent 将输出：图 \ref{fig:addfigure} \~{} \ref{fig:addfigurethr.3}。\\
% will output pic \ref{fig:addfigure} \~{} \ref{fig:addfigurethr.3}. \\
% 
% \setfigurewidth {0.3, 0.3}
% \setfigurewidth {0.27, 0.27, 0.27}
% \addfigure{sampleA} [addfigure] {\cs{addfigure} 的效果}
% \addfiguredbl{sampleA} [addfiguredbl.1] {两张图的效果1} {sampleB}  [addfiguredbl.2] {两张图的效果2}
% \addfigurethr{sampleA} [addfigurethr.1] {三张图的效果1} {sampleB}  [addfigurethr.2] {三张图的效果2} {sampleA}  [addfigurethr.3] {三张图的效果3}
%
%
% \end{documentation}
% \clearpage
%
% ^^A ---------------------------------- 实现部分 ----------------------------------
%
% \begin{implementation}
%
% \section{代码实现 Implementation}
%
% \subsection{初始化 Init}
%
%    \begin{macrocode}
%<*package>
%<@@=drawmgr>
\ExplSyntaxOn
\NeedsTeXFormat{LaTeX2e}
\ProvidesExplPackage{drawmgr}{2025-12-25}{0.2} 
  {集中管理图形脚本的宏}
%    \end{macrocode}
%
%
% \subsection{变量 Variable}
%
%
% \begin{variable}{\g_@@_scripts_prop, \g_@@_wd_dbl_clist, \g_@@_wd_thr_clist, \l_@@_wd_clist}
% 变量定义
%    \begin{macrocode}
\prop_new:N \g_@@_scripts_prop
\clist_new:N \g_@@_wd_dbl_clist
\clist_new:N \g_@@_wd_thr_clist
\clist_new:N \l_@@_wd_clist
%    \end{macrocode}
%    \begin{macrocode}
\clist_set:Nn \g_@@_wd_dbl_clist { 0.49, 0.49 }
\clist_set:Nn \g_@@_wd_thr_clist { 0.33, 0.33, 0.33 }
%    \end{macrocode}
% \end{variable}
%
% \subsection{命令 Command}
% 
% \begin{macro}{\newdraw, \usedraw, \showdraw, \cleardraw}
% 定义保存、使用、显示、清空图形脚本：
%    \begin{macrocode}
\NewDocumentCommand \newdraw { m +m }
  {
    \prop_gput:Nnn \g_@@_scripts_prop { #1 } { #2 }
  }
\NewDocumentCommand \usedraw { m }
  {
    \prop_if_in:NnT \g_@@_scripts_prop { #1 }
      { \prop_item:Nn \g_@@_scripts_prop { #1 } }
  }
\NewDocumentCommand \showdraw { s }
  {
    \IfBooleanTF { #1 }
      {
        已保存的图形如下：\par
        \prop_map_inline:Nn \g_@@_scripts_prop
          { ##1: \par ##2 \par }
      }
      {
        已保存的图形有：
        \prop_map_inline:Nn \g_@@_scripts_prop
          { ##1 ；}
      }
  }
\NewDocumentCommand \cleardraw { }
  {
    \prop_gclear:N \g_@@_scripts_prop
  }
%    \end{macrocode}
% \end{macro}
%
% 
% \begin{macro}{\setfigurewidth}
% 设置图形宽度：
%    \begin{macrocode}
\NewDocumentCommand \setfigurewidth { m }
  {
    \clist_set:Nn \l_@@_wd_clist { #1 }
    \int_compare:nNnTF { \clist_count:N \l_@@_wd_clist } = { 2 }
      { \clist_gset:Nn \g_@@_wd_dbl_clist { #1 } }
      { \clist_gset:Nn \g_@@_wd_thr_clist { #1 } }
  }
%    \end{macrocode}
% \end{macro}
% 
% 
% 
% \begin{macro}{\@@_insert_draw:nnnn}
% 向文档中插入图片（|#1| 图形宽度；|#2| 图形索引；|#3| 图形标签；|#4| 图形标题名）：
%    \begin{macrocode}
\cs_new:Npn \@@_insert_draw:nnnn #1#2#3#4
  {
    \begin{minipage}[t]{ #1\textwidth } 
      \centering
      \usedraw{#2}
      \caption{#4}
      \label{fig:#3}
    \end{minipage}
  }
\cs_generate_variant:Nn \@@_insert_draw:nnnn { Vnnn }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\addfigure, \addfiguredbl, \addfigurethr}
% 用于（并排）插入单张、两张或三张图片：
%    \begin{macrocode}
\NewDocumentCommand \addfigure {  m o m }
  {
    \begin{figure}[!htbp]
      \centering
      \IfNoValueTF { #2 }
        { \@@_insert_draw:nnnn { 1 } { #1 } { #1 } { #3 } }
        { \@@_insert_draw:nnnn { 1 } { #1 } { #2 } { #3 } }        
    \end{figure}
  }
\NewDocumentCommand \addfiguredbl { o m o m m o m }
  {
    \IfNoValueTF {#1}
      { \clist_set_eq:NN \l_@@_wd_clist \g_@@_wd_dbl_clist }
      { \clist_set:Nn \l_@@_wd_clist {#1} }
    \clist_log:N \l_@@_wd_clist
    \begin{figure}[!htbp]
      \centering
      \str_set:Ne \l_tmpa_str { \clist_item:Nn \l_@@_wd_clist { 1 } }
      \IfNoValueTF { #3 }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #2 } { #2 } { #4 } }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #2 } { #3 } { #4 } }        
      \rule{ 0.05\textwidth } { 0pt }
      \str_set:Ne \l_tmpa_str { \clist_item:Nn \l_@@_wd_clist { 2 } }
      \IfNoValueTF { #6 }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #5 } { #5 } { #7 } }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #5 } { #6 } { #7 } }    
    \end{figure}
  }
\NewDocumentCommand \addfigurethr { m o m m o m m o m }
  {
    \clist_set_eq:NN \l_@@_wd_clist \g_@@_wd_thr_clist
    \begin{figure}[!htbp]
      \centering
      \str_set:Ne \l_tmpa_str { \clist_item:Nn \l_@@_wd_clist { 1 } }
      \IfNoValueTF { #2 }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #1 } { #1 } { #3 } }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #1 } { #2 } { #3 } }  
      \rule{ 0.05\textwidth } { 0pt }
      \str_set:Ne \l_tmpa_str { \clist_item:Nn \l_@@_wd_clist { 2 } }
      \IfNoValueTF { #5 }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #4 } { #4 } { #6 } }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #4 } { #5 } { #6 } }    
      \rule{ 0.05\textwidth } { 0pt }
      \str_set:Ne \l_tmpa_str { \clist_item:Nn \l_@@_wd_clist { 3 } }
      \IfNoValueTF { #8 }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #7 } { #7 } { #9 } }
        { \@@_insert_draw:Vnnn \l_tmpa_str { #7 } { #8 } { #9 } }       
    \end{figure}
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\ExplSyntaxOff
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintChanges
% \PrintIndex
% 
\endinput