summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/useclass
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-03-07 03:01:25 +0000
committerNorbert Preining <norbert@preining.info>2024-03-07 03:01:25 +0000
commitdc177b2cd4ed993d65860adc66d256969c1bb6ad (patch)
tree1a00cd47175882c0f48969af3b0204c842c1e584 /macros/latex/contrib/useclass
parente500c9e5fc807971a29d8544e9e2fad59f670fb5 (diff)
CTAN sync 202403070301
Diffstat (limited to 'macros/latex/contrib/useclass')
-rw-r--r--macros/latex/contrib/useclass/README.md35
-rw-r--r--macros/latex/contrib/useclass/useclass.dtx279
-rw-r--r--macros/latex/contrib/useclass/useclass.ins16
-rw-r--r--macros/latex/contrib/useclass/useclass.pdfbin490171 -> 539822 bytes
4 files changed, 288 insertions, 42 deletions
diff --git a/macros/latex/contrib/useclass/README.md b/macros/latex/contrib/useclass/README.md
index baabb9b6e7..d3bd24274d 100644
--- a/macros/latex/contrib/useclass/README.md
+++ b/macros/latex/contrib/useclass/README.md
@@ -1,7 +1,32 @@
-# The `useclass.sty` Package: Use Classes as Packages
+# The `useclass.sty` Package: Load Classes as Packages
## Introduction
-`useclass` is a package that enables the usage of classes as packages. It was originally designed for the `l3doc` class, which is employed for documenting LaTeX code with numerous useful features. However, employing the `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.
+`useclass` is a package that enables the usage of classes as packages.
+It was originally designed for the `l3doc` class, which is employed for documenting LaTeX code with numerous useful features.
+However, employing the `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 latest documentation is available [here](https://github.com/huangyxi/useclass/releases/latest/download/useclass.pdf).
+
+
+## Installation
+
+The following methods are available for installing and updating the package.
+Choose the method that best suits your needs.
+
+Since this package is derived from the `.dtx` file, the easiest way to install or update it is to place or replace the `useclass.sty` file in the same directory as your working document.
+You can download `useclass.sty` from the [GitHub Release](https://github.com/huangyxi/useclass/releases/latest/download/useclass.sty).
+
+For a full installation of the package, you can use a 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, the following commands can be used:
+
+```bash
+tlmgr [--usermode] install useclass
+tlmgr [--usermode] update useclass
+```
+
+If you're a developer interested in contributing to the project's development, or if you simply 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.
+
## Usage
Use `\useclass` to load a class with the same usage as `\usepackage`:
@@ -18,9 +43,11 @@ Example:
## License
This work may be distributed and/or modified under the
-conditions of the LaTeX Project Public License, either version 1.3
+conditions of the LaTeX Project Public License, either version 1.3c
of this license or (at your option) any later version.
-The latest version of this license is in
+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.3c or later is part of all distributions of LaTeX
version 2008 or later.
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
diff --git a/macros/latex/contrib/useclass/useclass.ins b/macros/latex/contrib/useclass/useclass.ins
index 3d8431cde6..878cfc6626 100644
--- a/macros/latex/contrib/useclass/useclass.ins
+++ b/macros/latex/contrib/useclass/useclass.ins
@@ -10,13 +10,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".
%%
@@ -31,13 +31,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".
@@ -58,10 +58,6 @@
}
\endbatchfile
-
-
- % \cs{useclass} \marg{class}
-
%%
%% This work consists of the files useclass.dtx
%% and the derived files useclass.sty and useclass.ins.
diff --git a/macros/latex/contrib/useclass/useclass.pdf b/macros/latex/contrib/useclass/useclass.pdf
index 499da57e29..2623e72d2b 100644
--- a/macros/latex/contrib/useclass/useclass.pdf
+++ b/macros/latex/contrib/useclass/useclass.pdf
Binary files differ