diff options
Diffstat (limited to 'macros/latex/contrib/useclass/useclass.dtx')
| -rw-r--r-- | macros/latex/contrib/useclass/useclass.dtx | 279 |
1 files changed, 251 insertions, 28 deletions
diff --git a/macros/latex/contrib/useclass/useclass.dtx b/macros/latex/contrib/useclass/useclass.dtx index 74d9d63ca1..37016e738b 100644 --- a/macros/latex/contrib/useclass/useclass.dtx +++ b/macros/latex/contrib/useclass/useclass.dtx @@ -23,13 +23,13 @@ This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either - version 1.3 of this license or (at your option) any later + version 1.3c of this license or (at your option) any later version. This version of this license is in https://www.latex-project.org/lppl/lppl-1-3c.txt and the latest version of this license is in https://www.latex-project.org/lppl.txt - and version 1.3 or later is part of all distributions of - LaTeX version 2005/12/01 or later. + and version 1.3c or later is part of all distributions of LaTeX + version 2008 or later. This work has the LPPL maintenance status "maintained". @@ -62,14 +62,15 @@ %<package>\NeedsTeXFormat{LaTeX2e} %<package>\ProvidesExplPackage{useclass} -%<package> {2024-03-04}{0.9}{Use Classes as Packages} % +%<package> {2024-03-06}{1.0}{Use Classes as Packages} % %<*driver> \documentclass{article} \usepackage{useclass} -\useclass[full]{l3doc} +\useclass*[full]{l3doc} \usepackage{mdframed} -\providecommand{\pkgname}{\pkg{\jobname}} +\providecommand{\name}{\jobname} +\providecommand{\pkgname}{\pkg{\name}} \begin{document} \DocInput{\jobname.dtx} \PrintIndex @@ -77,7 +78,7 @@ %</driver> % \fi % -% \title{The \pkgname.sty Package: Use Classes as Packages} +% \title{The \pkgname.sty Package: Load Classes as Packages} % \author % { % Huang Yuxi @@ -90,19 +91,17 @@ % {useclass@hyxi.dev}^^A % > % } -% \date{2024-03-04 \quad Version 0.9} -% - -% \maketitle +% \date{2024-03-06 \quad Version 1.0} % % +% \maketitle % % \begin{mdframed} -% \textsf{TL;DR} \; Use \cs{useclass} to load a class with the same usage as \cs{usepackage}: -% \begin{verbatim} +% \textsf{TL;DR} \; Use \cs{useclass} to load a class with the same usage as \cs{usepackage}: +% \begin{verbatim} % \usepackage{useclass} % \useclass[full]{l3doc} -% \end{verbatim} +% \end{verbatim} % \end{mdframed} % % \tableofcontents @@ -112,19 +111,47 @@ % \section{Introduction} % % \pkgname{} is a package that enables the usage of classes as packages. It was originally designed for the \cls{l3doc} class, which is employed for documenting \LaTeX{} code with numerous useful features. However, employing the \cls{l3doc} class as a package is not convenient when using the developing class as the style for the document. Therefore, this package provides a simple interface for utilizing classes as packages. -% The package \pkgname{} was initially released on 2024-03-04, under the LaTeX Project Public License Version 1.3c^^A +% The package \pkgname{} was initially released on 2024-03-05, under the LaTeX Project Public License Version 1.3c^^A % \footnote{\url{https://www.latex-project.org/lppl/lppl-1-3c.txt}} % or later, and is maintained at \url{https://github.com/huangyxi/useclass}. +% The latest documentation can be found at +% \url{https://github.com/huangyxi/useclass/releases/latest/download/useclass.pdf}. +% +% +% \section{Installation} +% +% The following are the methods for installing and updating the package. +% You can choose the method that is most suitable for you. +% +% Since this package is tangled from the \file{.dtx} file, +% the easiest way to install or update the package is to place or replace the \file{\name.sty} file in the same directory as your working document. +% You can find \file{\name.sty} at GitHub Release^^A +% \footnote{\url{https://github.com/huangyxi/useclass/releases/latest/download/useclass.sty}}. +% +% For a full installation of the package, you can use the \TeX repository manager, such as \TeX{} Live. +% This method will download the package from CTAN, and install all required files to \TeX{} Directory Structure (TDS). +% For command-line users, you can use the following command: +% \begin{verbatim} +% tlmgr [--usermode] install useclass +% tlmgr [--usermode] update useclass +% \end{verbatim} +% +% If you're a developer interested in contributing to the project's development, +% or just want to try the latest features before they are released, +% you can clone the repository from GitHub, and use either |l3build| or |make| to install the package. % % \section{Usage} - % -% \begin{function}{\useclass} +% \begin{function}{\useclass, \useclass*} % \begin{syntax} - % \cs{useclass} \marg{class} +% \cs{useclass} \marg{class} % \cs{useclass} \oarg{options} \marg{class} +% \cs{useclass*} \marg{class} +% \cs{useclass*} \oarg{options} \marg{class} % \end{syntax} % Load class with options, where \meta{options} is the options for the class and \meta{class} is the class name without the extension. +% When using the starred version \cs{useclass*}, the tokens, dimensions, and control sequences modified by the class will be saved before loading the class and restored after loading the class. +% Currently, the starred version is only applicable to the \cls{l3doc} class. % \end{function} % % Example for a \file{dtx} file: @@ -161,15 +188,67 @@ % % \subsection{Variables} % -% \begin{variable}{\@@_tempa_cs:w} -% Temporary control sequence. +% \begin{macro}{\c_@@_cs_name_tl} +% Prefix of control sequence names for saving and restoring. % \begin{macrocode} +\tl_const:Nn \c_@@_cs_name_tl {@@_s_cs_} +% \end{macrocode} +% \end{macro} +% +% \begin{variable}{\g_@@_tl_seq, \g_@@_dim_seq, \g_@@_cs_name_seq} +% Sequnce of variables to save before, and restore after loading class. +% \begin{macrocode} +\seq_new:N \g_@@_tl_seq +\seq_new:N \g_@@_dim_seq +\seq_new:N \g_@@_cs_name_seq +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\l_@@_class_prop} +% Temporary property list of class configuration. +% \begin{macrocode} +\prop_new:N \l_@@_class_prop +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\l_@@_csname_seq} +% Temporary sequence of csnames of variables to save and restore. +% \begin{macrocode} +\seq_new:N \l_@@_csname_seq +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\l_@@_tmpa_tl, \l_@@_tmpb_tl, \l_@@_tmpa_dim, \@@_tempa_cs:w} +% Temporary variables used in the implementation. +% \begin{macrocode} +\tl_new:N \l_@@_tmpa_tl +\tl_new:N \l_@@_tmpb_tl +\dim_new:N \l_@@_tmpa_dim \cs_new_eq:NN \@@_tempa_cs:w ? % \end{macrocode} % \end{variable} % +% % \subsection{Helpers} % +% \begin{macro}{\@@_prop_get_prop:NnN, \@@_prop_get_seq:NnN} +% Since the values of \cs{c_@@_classes_prop} are token lists, we need to parse them to property. +% \begin{macrocode} +% \cs_set_eq:NN \@@_prop_set_from_keyval:Nn \prop_set_from_keyval:Nn +% \cs_generate_variant:Nn \@@_prop_set_from_keyval:Nn { No } +\cs_new_protected:Npn \@@_prop_get_prop:NnN #1 #2 #3 + { + \prop_get:NnN #1 {#2} \l_@@_tmpa_tl + \exp_args:NNo \prop_set_from_keyval:Nn #3 \l_@@_tmpa_tl + } +\cs_new_protected:Npn \@@_prop_get_seq:NnN #1 #2 #3 + { + \prop_get:NnN #1 {#2} \l_@@_tmpa_tl + \exp_args:NNo \seq_set_from_clist:Nn #3 \l_@@_tmpa_tl + } +% \end{macrocode} +% \end{macro} +% % \begin{macro}{\@@_cs_swap:NN} % Define a helper function to swap two control sequences. % \begin{macrocode} @@ -181,6 +260,85 @@ } % \end{macrocode} % \end{macro} +% +% +% \subsection{Variables Save and Restore} +% +% \begin{macro}{\@@_save_tl:N, \@@_restore_tl:N} +% Save and restore the token lists of the class. +% \begin{macrocode} +\cs_new_protected:Npn \@@_save_tl:N #1 + { + \@@_prop_get_seq:NnN #1 {tl} \l_@@_csname_seq + \seq_map_inline:Nn \l_@@_csname_seq + { + \tl_set:Nx \l_@@_tmpa_tl {\tl_use:c {##1}} + \seq_gput_right:No \g_@@_tl_seq {\l_@@_tmpa_tl} + } + } +\cs_new_protected:Npn \@@_restore_tl:N #1 + { + \@@_prop_get_seq:NnN #1 {tl} \l_@@_csname_seq + \seq_map_inline:Nn \l_@@_csname_seq + { + \seq_gpop_left:NN \g_@@_tl_seq \l_@@_tmpa_tl + \tl_set:cn {##1} {\l_@@_tmpa_tl} + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@@_save_dim:N, \@@_restore_dim:n} +% Save and restore the dimensions of the class. +% \begin{macrocode} +\cs_new_protected:Npn \@@_save_dim:N #1 + { + \@@_prop_get_seq:NnN #1 {dim} \l_@@_csname_seq + \seq_map_inline:Nn \l_@@_csname_seq + { + \tl_set:Nx \l_@@_tmpa_tl {\dim_use:c {##1}} + \seq_gput_right:No \g_@@_dim_seq {\l_@@_tmpa_tl} + } + } +\cs_new_protected:Npn \@@_restore_dim:N #1 + { + \@@_prop_get_seq:NnN #1 {dim} \l_@@_csname_seq + \seq_map_inline:Nn \l_@@_csname_seq + { + \seq_gpop_left:NN \g_@@_dim_seq \l_@@_tmpa_dim + \dim_set:cn {##1} {\l_@@_tmpa_dim} + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@@_save_cs:N, \@@_restore_cs:N} +% Create a new control sequence with the transformed name, +% and save and restore the original control sequence with the new name. +% \begin{macrocode} +\cs_new_protected:Npn \@@_save_cs:N #1 + { + \@@_prop_get_seq:NnN #1 {cs} \l_@@_csname_seq + \seq_map_inline:Nn \l_@@_csname_seq + { + \tl_concat:NNN \l_@@_tmpa_tl \c_@@_cs_name_tl {##1} + \cs_set_eq:cc \l_@@_tmpa_tl {##1} + \seq_gput_right:No \g_@@_cs_name_seq {\l_@@_tmpa_tl} + } + } +\cs_new_protected:Npn \@@_restore_cs:N #1 + { + \@@_prop_get_seq:NnN #1 {cs} \l_@@_csname_seq + \seq_map_inline:Nn \l_@@_csname_seq + { + \seq_gpop_left:NN \g_@@_cs_name_seq \l_@@_tmpa_tl + \cs_set_eq:cc {##1} \l_@@_tmpa_tl + } + } +% \end{macrocode} +% \end{macro} +% +% % \subsection{Dependences loading} % \pkgname{} currently don't have any explicit dependences. % @@ -195,8 +353,20 @@ % % \subsection{Before Loading Class} % +% \begin{macro}{\@@_save_before:N} +% Save variables before loading class. +% \begin{macrocode} +\cs_new_protected:Npn \@@_save_before:N #1 + { + \@@_save_tl:N #1 + \@@_save_dim:N #1 + \@@_save_cs:N #1 + } +% \end{macrocode} +% \end{macro} +% % \begin{macro}{\@@_use_before:} -% These are the things to do before loading class. +% These are the general things to do before loading class. % \begin{macrocode} \cs_new_protected:Npn \@@_use_before: { @@ -220,7 +390,7 @@ % \subsection{After Loading Class} % % \begin{macro}{\@@_use_after:} -% These are the things to do after loading class. +% These are the general things to do after loading class. % \begin{macrocode} \cs_new_protected:Npn \@@_use_after: { @@ -229,22 +399,75 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\@@_restore_after:N} +% Restore variables after loading class. +% \begin{macrocode} +\cs_new_protected:Npn \@@_restore_after:N #1 + { + \@@_restore_cs:N #1 + \@@_restore_dim:N #1 + \@@_restore_tl:N #1 + } +% \end{macrocode} +% \end{macro} +% +% % \subsection{User Interface} -% \begin{macro}{\useclass} +% \begin{macro}{\useclass, \useclass*} % Load patch class with options. % \begin{macrocode} -\NewDocumentCommand {\useclass} { O{} m } +\NewDocumentCommand {\useclass} { s O{} m } { - \@@_use_before: - \@@_use_class:nn {#1} {#2} - \@@_use_after: + \bool_if:NTF #1 + { + \@@_prop_get_prop:NnN \c_@@_classes_prop {#3} \l_@@_class_prop + \@@_save_before:N \l_@@_class_prop + \@@_use_before: + \@@_use_class:nn {#2} {#3} + \@@_use_after: + \@@_restore_after:N \l_@@_class_prop + } + { + \@@_use_before: + \@@_use_class:nn {#2} {#3} + \@@_use_after: + } } % \end{macrocode} % \end{macro} % +% \subsection{Classes Configuration} +% \begin{variable}{\c_@@_classes_prop} +% Configuration for classes to restore after loading. +% The defined property is NOT nested, where values in the prop are token lists but not properties or sequences. +% \begin{macrocode} +\prop_const_from_keyval:Nn \c_@@_classes_prop { + l3doc = { + tl = { + partname, + }, + dim = { + textwidth, + marginparwidth, + oddsidemargin, + evensidemargin, + parindent, + itemindent, + parskip, + }, + cs = { + list, + l@section, + l@subsection, + }, + }, +} +% \end{macrocode} +% \end{variable} +% % \begin{macrocode} %</package> % \end{macrocode} - +% % \end{implementation} % \PrintIndex |