Debian Codegraph @

texmf-dist/source/latex/useclass/useclass.dtx

raw
1 % \iffalse meta-comment
2 % !TEX program = pdfLaTeX
3 %
4 % DO NOT REMOVE THE MARK MANUALLY (used in l3build) -> %
5 %
6 %<*internal>
7 \iffalse
8 %</internal>
9 %<*internal>
10 \fi
11 \begingroup
12 \def\nameofLaTeXe{LaTeX2e}
13 \expandafter\endgroup\ifx\fmtname\nameofLaTeXe\else
14 \csname fi\endcsname
15 %</internal>
16 %<*install>
17 \input docstrip
18 \keepsilent
19 \askforoverwritefalse
20 \preamble
21
22 Copyright (C) 2024 by HUANG Yuxi <[email protected]>
23
24 This work may be distributed and/or modified under the
25 conditions of the LaTeX Project Public License, either
26 version 1.3c of this license or (at your option) any later
27 version. This version of this license is in
28 https://www.latex-project.org/lppl/lppl-1-3c.txt
29 and the latest version of this license is in
30 https://www.latex-project.org/lppl.txt
31 and version 1.3c or later is part of all distributions of LaTeX
32 version 2008 or later.
33
34 This work has the LPPL maintenance status "maintained".
35
36 The Current Maintainer of this work is HUANG Yuxi.
37
38 \endpreamble
39 \postamble
40
41 This work consists of the files \jobname.dtx
42 and the derived files \jobname.sty and \jobname.ins.
43
44 \endpostamble
45
46 \generate
47 {
48 %</install>
49 %<*internal>
50 \usedir{source/latex/useclass}
51 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
52 %</internal>
53 %<*install>
54 \usedir{tex/latex/useclass}
55 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
56 }
57 \endbatchfile
58 %</install>
59 %<*internal>
60 \fi
61 %</internal>
62
63 %<package>\NeedsTeXFormat{LaTeX2e}
64 %<package>\ProvidesExplPackage{useclass}
65 %<package> {2024-10-03}{1.1}{Use Classes as Packages} %
66 %<*driver>
67 \documentclass{article}
68 \usepackage{useclass}
69 \useclass*[full]{l3doc}
70 \RecordChanges
71 \usepackage{mdframed}
72
73 \providecommand{\name}{\jobname}
74 \providecommand{\pkgname}{\pkg{\name}}
75 \begin{document}
76 \DocInput{\jobname.dtx}
77 \PrintChanges
78 \PrintIndex
79 \end{document}
80 %</driver>
81 % \fi
82 %
83 % \title{The \pkgname.sty Package: Load Classes as Packages}
84 % \author
85 % {
86 % Huang Yuxi^^A
87 % \thanks{
88 % \textit{Huang} is his surname.
89 % }
90 % <^^A
91 % \href
92 % {mailto:[email protected]}
93 % {[email protected]}^^A
94 % >
95 % }
96 % \date{2024-10-03 \quad Version 1.1}
97 %
98 %
99 % \maketitle
100 %
101 % \begin{mdframed}
102 % \textsf{TL;DR} \; Use \cs{useclass} to load a class with the same usage as \cs{usepackage}:
103 % \begin{verbatim}
104 % \usepackage{useclass}
105 % \useclass[full]{l3doc}
106 % \end{verbatim}
107 % \end{mdframed}
108 %
109 % \tableofcontents
110 %
111 % \changes{v1.0}{2024-03-05}{Initial release.}
112 %
113 % \begin{documentation}
114 %
115 % \section{Introduction}
116 %
117 % \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.
118 % The package \pkgname{} was initially released on 2024-03-05, under the LaTeX Project Public License Version 1.3c^^A
119 % \footnote{\url{https://www.latex-project.org/lppl/lppl-1-3c.txt}}
120 % or later, and is maintained at \url{https://github.com/huangyxi/useclass}.
121 % The latest documentation can be found at
122 % \url{https://github.com/huangyxi/useclass/releases/latest/download/useclass.pdf}.
123 %
124 %
125 % \section{Installation}
126 %
127 % The following are the methods for installing and updating the package.
128 % You can choose the method that is most suitable for you.
129 %
130 % Since this package is tangled from the \file{.dtx} file,
131 % 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.
132 % You can find \file{\name.sty} at GitHub Release^^A
133 % \footnote{\url{https://github.com/huangyxi/useclass/releases/latest/download/useclass.sty}}.
134 %
135 % For a full installation of the package, you can use the \TeX repository manager, such as \TeX{} Live.
136 % This method will download the package from CTAN, and install all required files to \TeX{} Directory Structure (TDS).
137 % For command-line users, you can use the following command:
138 % \begin{verbatim}
139 % tlmgr [--usermode] install useclass
140 % tlmgr [--usermode] update useclass
141 % \end{verbatim}
142 %
143 % If you're a developer interested in contributing to the project's development,
144 % or just want to try the latest features before they are released,
145 % you can clone the repository from GitHub, and use either |l3build| or |make| to install the package.
146 %
147 % \section{Usage}
148 %
149 % \begin{function}{\useclass, \useclass*}
150 % \begin{syntax}
151 % \cs{useclass} \marg{class}
152 % \cs{useclass} \oarg{options} \marg{class}
153 % \cs{useclass*} \marg{class}
154 % \cs{useclass*} \oarg{options} \marg{class}
155 % \end{syntax}
156 % Load class with options, where \meta{options} is the options for the class and \meta{class} is the class name without the extension.
157 % 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.
158 % Currently, the starred version is only applicable to the \cls{l3doc} class.
159 % \end{function}
160 %
161 % Example for a \file{dtx} file:
162 % \begin{mdframed}
163 % \begin{verbatim}
164 % % \iffalse
165 % \documentclass{article}
166 % \usepackage{useclass}
167 % \useclass*[full]{l3doc}
168 % \begin{document}
169 % \DocInput{\jobname.dtx}
170 % \end{document}
171 % % \fi
172 % %
173 % % \section{Implementation}
174 % % \begin{variable}{\l_demo_tl}
175 % % \begin{macrocode}
176 % \tl_new:N \l_demo_tl
177 % % \end{macrocode}
178 % % \end{variable}
179 % \end{verbatim}
180 % \end{mdframed}
181 %
182 % \end{documentation}
183 %
184 % \begin{implementation}
185 %
186 %
187 % \section{\pkgname{} Implementation}
188 % \begin{macrocode}
189 %<@@=useclass>
190 %<*package>
191 % \end{macrocode}
192 %
193 %
194 % \subsection{Variables}
195 %
196 % \begin{macro}{\c_@@_cs_name_tl}
197 % Prefix of control sequence names for saving and restoring.
198 % \begin{macrocode}
199 \tl_const:Nn \c_@@_cs_name_tl {@@_s_cs_}
200 % \end{macrocode}
201 % \end{macro}
202 %
203 % \begin{variable}{\g_@@_tl_seq, \g_@@_dim_seq, \g_@@_cs_name_seq}
204 % Sequnce of variables to save before, and restore after loading class.
205 % \begin{macrocode}
206 \seq_new:N \g_@@_tl_seq
207 \seq_new:N \g_@@_dim_seq
208 \seq_new:N \g_@@_cs_name_seq
209 % \end{macrocode}
210 % \end{variable}
211 %
212 % \begin{variable}{\l_@@_class_prop}
213 % Temporary property list of class configuration.
214 % \begin{macrocode}
215 \prop_new:N \l_@@_class_prop
216 % \end{macrocode}
217 % \end{variable}
218 %
219 % \begin{variable}{\l_@@_csname_seq}
220 % Temporary sequence of csnames of variables to save and restore.
221 % \begin{macrocode}
222 \seq_new:N \l_@@_csname_seq
223 % \end{macrocode}
224 % \end{variable}
225 %
226 % \begin{variable}{\l_@@_tmpa_tl, \l_@@_tmpb_tl, \l_@@_tmpa_dim, \@@_tempa_cs:w}
227 % Temporary variables used in the implementation.
228 % \begin{macrocode}
229 \tl_new:N \l_@@_tmpa_tl
230 \tl_new:N \l_@@_tmpb_tl
231 \dim_new:N \l_@@_tmpa_dim
232 \cs_new_eq:NN \@@_tempa_cs:w ?
233 % \end{macrocode}
234 % \end{variable}
235 %
236 %
237 % \subsection{Helpers}
238 %
239 % \begin{macro}{\@@_prop_get_prop:NnN, \@@_prop_get_seq:NnN}
240 % Since the values of \cs{c_@@_classes_prop} are token lists, we need to parse them to property.
241 % \begin{macrocode}
242 % \cs_set_eq:NN \@@_prop_set_from_keyval:Nn \prop_set_from_keyval:Nn
243 % \cs_generate_variant:Nn \@@_prop_set_from_keyval:Nn { No }
244 \cs_new_protected:Npn \@@_prop_get_prop:NnN #1 #2 #3
245 {
246 \prop_get:NnN #1 {#2} \l_@@_tmpa_tl
247 \exp_args:NNo \prop_set_from_keyval:Nn #3 \l_@@_tmpa_tl
248 }
249 \cs_new_protected:Npn \@@_prop_get_seq:NnN #1 #2 #3
250 {
251 \prop_get:NnN #1 {#2} \l_@@_tmpa_tl
252 \exp_args:NNo \seq_set_from_clist:Nn #3 \l_@@_tmpa_tl
253 }
254 % \end{macrocode}
255 % \end{macro}
256 %
257 % \begin{macro}{\@@_cs_swap:NN}
258 % Define a helper function to swap two control sequences.
259 % \begin{macrocode}
260 \cs_new:Npn \@@_cs_swap:NN #1 #2
261 {
262 \cs_set_eq:NN \@@_tempa_cs:w #1
263 \cs_set_eq:NN #1 #2
264 \cs_set_eq:NN #2 \@@_tempa_cs:w
265 }
266 % \end{macrocode}
267 % \end{macro}
268 %
269 %
270 % \subsection{Variables Save and Restore}
271 %
272 % \begin{macro}{\@@_save_tl:N, \@@_restore_tl:N}
273 % Save and restore the token lists of the class.
274 % \begin{macrocode}
275 \cs_new_protected:Npn \@@_save_tl:N #1
276 {
277 \@@_prop_get_seq:NnN #1 {tl} \l_@@_csname_seq
278 \seq_map_inline:Nn \l_@@_csname_seq
279 {
280 \tl_set:Nx \l_@@_tmpa_tl {\tl_use:c {##1}}
281 \seq_gput_right:No \g_@@_tl_seq {\l_@@_tmpa_tl}
282 }
283 }
284 \cs_new_protected:Npn \@@_restore_tl:N #1
285 {
286 \@@_prop_get_seq:NnN #1 {tl} \l_@@_csname_seq
287 \seq_map_inline:Nn \l_@@_csname_seq
288 {
289 \seq_gpop_left:NN \g_@@_tl_seq \l_@@_tmpa_tl
290 \tl_set:cn {##1} {\l_@@_tmpa_tl}
291 }
292 }
293 % \end{macrocode}
294 % \end{macro}
295 %
296 % \begin{macro}{\@@_save_dim:N, \@@_restore_dim:n}
297 % Save and restore the dimensions of the class.
298 % \begin{macrocode}
299 \cs_new_protected:Npn \@@_save_dim:N #1
300 {
301 \@@_prop_get_seq:NnN #1 {dim} \l_@@_csname_seq
302 \seq_map_inline:Nn \l_@@_csname_seq
303 {
304 \tl_set:Nx \l_@@_tmpa_tl {\dim_use:c {##1}}
305 \seq_gput_right:No \g_@@_dim_seq {\l_@@_tmpa_tl}
306 }
307 }
308 \cs_new_protected:Npn \@@_restore_dim:N #1
309 {
310 \@@_prop_get_seq:NnN #1 {dim} \l_@@_csname_seq
311 \seq_map_inline:Nn \l_@@_csname_seq
312 {
313 \seq_gpop_left:NN \g_@@_dim_seq \l_@@_tmpa_dim
314 \dim_set:cn {##1} {\l_@@_tmpa_dim}
315 }
316 }
317 % \end{macrocode}
318 % \end{macro}
319 %
320 % \begin{macro}{\@@_save_cs:N, \@@_restore_cs:N}
321 % Create a new control sequence with the transformed name,
322 % and save and restore the original control sequence with the new name.
323 % \begin{macrocode}
324 \cs_new_protected:Npn \@@_save_cs:N #1
325 {
326 \@@_prop_get_seq:NnN #1 {cs} \l_@@_csname_seq
327 \seq_map_inline:Nn \l_@@_csname_seq
328 {
329 \tl_concat:NNN \l_@@_tmpa_tl \c_@@_cs_name_tl {##1}
330 \cs_set_eq:cc \l_@@_tmpa_tl {##1}
331 \seq_gput_right:No \g_@@_cs_name_seq {\l_@@_tmpa_tl}
332 }
333 }
334 \cs_new_protected:Npn \@@_restore_cs:N #1
335 {
336 \@@_prop_get_seq:NnN #1 {cs} \l_@@_csname_seq
337 \seq_map_inline:Nn \l_@@_csname_seq
338 {
339 \seq_gpop_left:NN \g_@@_cs_name_seq \l_@@_tmpa_tl
340 \cs_set_eq:cc {##1} \l_@@_tmpa_tl
341 }
342 }
343 % \end{macrocode}
344 % \end{macro}
345 %
346 %
347 % \subsection{Dependences loading}
348 % \pkgname{} currently don't have any explicit dependences.
349 %
350 % \subsection{Patched Macros}
351 %
352 % \begin{macro}{\@@_LoadClass:n}
353 % Patched \cs{LoadClass} to do nothing.
354 % \begin{macrocode}
355 \cs_new:Npn \@@_LoadClass:n #1 {}
356 % \end{macrocode}
357 % \end{macro}
358 %
359 % \subsection{Before Loading Class}
360 %
361 % \begin{macro}{\@@_save_before:N}
362 % Save variables before loading class.
363 % \begin{macrocode}
364 \cs_new_protected:Npn \@@_save_before:N #1
365 {
366 \@@_save_tl:N #1
367 \@@_save_dim:N #1
368 \@@_save_cs:N #1
369 }
370 % \end{macrocode}
371 % \end{macro}
372 %
373 % \begin{macro}{\@@_use_before:}
374 % These are the general things to do before loading class.
375 % \begin{macrocode}
376 \cs_new_protected:Npn \@@_use_before:
377 {
378 \@@_cs_swap:NN \LoadClass \@@_LoadClass:n
379 }
380 % \end{macrocode}
381 % \end{macro}
382 %
383 % \subsection{Loading Class}
384 %
385 % \begin{macro}{\@@_use_class:nn}
386 % Load class with options.
387 % \begin{macrocode}
388 \cs_new_protected:Npn \@@_use_class:nn #1 #2
389 {
390 \@fileswithoptions\@clsextension[#1]{#2}
391 }
392 % \end{macrocode}
393 % \end{macro}
394 %
395 % \subsection{After Loading Class}
396 %
397 % \begin{macro}{\@@_use_after:}
398 % These are the general things to do after loading class.
399 % \begin{macrocode}
400 \cs_new_protected:Npn \@@_use_after:
401 {
402 \@@_cs_swap:NN \LoadClass \@@_LoadClass:n
403 }
404 % \end{macrocode}
405 % \end{macro}
406 %
407 % \begin{macro}{\@@_restore_after:N}
408 % Restore variables after loading class.
409 % \begin{macrocode}
410 \cs_new_protected:Npn \@@_restore_after:N #1
411 {
412 \@@_restore_cs:N #1
413 \@@_restore_dim:N #1
414 \@@_restore_tl:N #1
415 }
416 % \end{macrocode}
417 % \end{macro}
418 %
419 %
420 % \subsection{User Interface}
421 % \begin{macro}{\useclass, \useclass*}
422 % Load patch class with options.
423 % \begin{macrocode}
424 \NewDocumentCommand {\useclass} { s O{} m }
425 {
426 \bool_if:NTF #1
427 {
428 \@@_prop_get_prop:NnN \c_@@_classes_prop {#3} \l_@@_class_prop
429 \@@_save_before:N \l_@@_class_prop
430 \@@_use_before:
431 \@@_use_class:nn {#2} {#3}
432 \@@_use_after:
433 \@@_restore_after:N \l_@@_class_prop
434 }
435 {
436 \@@_use_before:
437 \@@_use_class:nn {#2} {#3}
438 \@@_use_after:
439 }
440 }
441 % \end{macrocode}
442 % \end{macro}
443 %
444 % \subsection{Classes Configuration}
445 % \begin{variable}{\c_@@_classes_prop}
446 % \changes{v1.1}{2024-10-03}{Support \cls{ctex} classes.}
447 % Configuration for classes to restore after loading.
448 % The defined property is NOT nested, where values in the prop are token lists but not properties or sequences.
449 % \begin{macrocode}
450 \prop_const_from_keyval:Nn \c_@@_classes_prop {
451 l3doc = {
452 tl = {
453 partname,
454 },
455 dim = {
456 textwidth,
457 marginparwidth,
458 oddsidemargin,
459 evensidemargin,
460 parindent,
461 itemindent,
462 parskip,
463 },
464 cs = {
465 list,
466 l@section,
467 l@subsection,
468 @maketitle,
469 },
470 },
471 }
472 % \end{macrocode}
473 % \end{variable}
474 %
475 % \begin{macrocode}
476 %</package>
477 % \end{macrocode}
478 %
479 % \end{implementation}