Debian Codegraph @

texmf-dist/source/latex/siunitx/siunitx-command.dtx

raw
1 % \iffalse meta-comment
2 %
3 % File: siunitx-command.dtx Copyright (C) 2019,2021,2023-2026 Joseph Wright
4 %
5 % It may be distributed and/or modified under the conditions of the
6 % LaTeX Project Public License (LPPL), either version 1.3c of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in the file
9 %
10 % https://www.latex-project.org/lppl.txt
11 %
12 % This file is part of the "siunitx bundle" (The Work in LPPL)
13 % and all files in that bundle must be distributed together.
14 %
15 % The released version of this bundle is available from CTAN.
16 %
17 % -----------------------------------------------------------------------
18 %
19 % The development version of the bundle can be found at
20 %
21 % https://github.com/josephwright/siunitx
22 %
23 % for those people who are interested.
24 %
25 % -----------------------------------------------------------------------
26 %
27 %<*driver>
28 \documentclass{l3doc}
29 % Additional commands needed in this source
30 \ProvideDocumentCommand\email{m}{\href{mailto:#1}{\nolinkurl{#1}}}
31 \ProvideDocumentCommand\foreign{m}{\textit{#1}}
32 % The next line is needed so that \GetFileInfo will be able to pick up
33 % version data
34 \usepackage{siunitx}
35 \begin{document}
36 \DocInput{\jobname.dtx}
37 \end{document}
38 %</driver>
39 % \fi
40 %
41 % \GetFileInfo{siunitx.sty}
42 %
43 % \title{^^A
44 % \pkg{siunitx-command} -- Units as document command^^A
45 % \thanks{This file describes \fileversion,
46 % last revised \filedate.}^^A
47 % }
48 %
49 % \author{^^A
50 % Joseph Wright^^A
51 % \thanks{^^A
52 % E-mail:
53 % \email{[email protected]}^^A
54 % }^^A
55 % }
56 %
57 % \date{Released \filedate}
58 %
59 % \maketitle
60 %
61 % \begin{documentation}
62 %
63 % This submodule provides support for creating free-standing document commands
64 % for unit macros.
65 %
66 % \section{Creating units as document commands}
67 %
68 % \begin{function}{\siunitx_command_create:}
69 % \begin{syntax}
70 % \cs{siunitx_command_create:}
71 % \end{syntax}
72 % Maps over the list of know unit commands and creates the appropriate
73 % document command to support them, as controlled by the options below.
74 % \end{function}
75 %
76 % These options are all preamble-only.
77 %
78 % \begin{function}{free-standing-units}
79 % \begin{syntax}
80 % |free-standing-units| = |true|\verb"|"|false|
81 % \end{syntax}
82 % Switch to determine whether free standing document commands are created
83 % for symbolic units. This will include not only units themselves but also
84 % prefixes, \foreign{etc.} The standard setting is |false|.
85 % \end{function}
86 %
87 % \begin{function}{overwrite-commands}
88 % \begin{syntax}
89 % |overwrite-commands| = |true|\verb"|"|false|
90 % \end{syntax}
91 % Switch to determine whether when creating free standing document commands,
92 % any existing document commands are overwritten. The standard setting is
93 % |false|.
94 % \end{function}
95 %
96 % \begin{function}{space-before-unit}
97 % \begin{syntax}
98 % |space-before-unit| = |true|\verb"|"|false|
99 % \end{syntax}
100 % Switch to determine whether a space is inserted before free standing
101 % document commands. The standard setting is |false|.
102 % \end{function}
103 %
104 % \begin{function}{unit-optional-argument}
105 % \begin{syntax}
106 % |unit-optional-argument| = |true|\verb"|"|false|
107 % \end{syntax}
108 % Switch to determine whether free standing document commands take an
109 % optional argument (a number). The standard setting is |false|.
110 % \end{function}
111 %
112 % \begin{function}{use-xspace}
113 % \begin{syntax}
114 % |use-xspace| = |true|\verb"|"|false|
115 % \end{syntax}
116 % Switch to determine whether free standing document commands use the
117 % \pkg{xparse} package to insert space after the command names. The standard
118 % setting is |false|. When set |true|, the \pkg{xparse} package will be
119 % loaded at the start of the document if not already available.
120 % \end{function}
121 %
122 % \end{documentation}
123 %
124 % \begin{implementation}
125 %
126 % \section{\pkg{siunitx-command} implementation}
127 %
128 % Start the \pkg{DocStrip} guards.
129 % \begin{macrocode}
130 %<*package>
131 % \end{macrocode}
132 %
133 % Identify the internal prefix.
134 % \begin{macrocode}
135 %<@@=siunitx_command>
136 % \end{macrocode}
137 %
138 % \begin{macro}{\l_@@_tmp_tl}
139 % \begin{macrocode}
140 \tl_new:N \l_@@_tmp_tl
141 % \end{macrocode}
142 % \end{macro}
143 %
144 % \subsection{Options}
145 %
146 % \begin{variable}
147 % {
148 % \l_@@_create_bool ,
149 % \l_@@_overwrite_bool ,
150 % \l_@@_prespace_bool ,
151 % \l_@@_optarg_bool ,
152 % \l_@@_xspace_bool
153 % }
154 % \begin{macrocode}
155 \keys_define:nn { siunitx }
156 {
157 free-standing-units .bool_set:N =
158 \l_@@_create_bool ,
159 overwrite-commands .bool_set:N =
160 \l_@@_overwrite_bool ,
161 space-before-unit .bool_set:N =
162 \l_@@_prespace_bool ,
163 unit-optional-argument .bool_set:N =
164 \l_@@_optarg_bool ,
165 use-xspace .bool_set:N =
166 \l_@@_xspace_bool
167 }
168 % \end{macrocode}
169 % \end{variable}
170 %
171 % These preamble-only options are all disabled at the start of the document.
172 % \begin{macrocode}
173 \AtBeginDocument
174 {
175 \clist_map_inline:nn
176 {
177 free-standing-units ,
178 overwrite-commands ,
179 space-before-unit ,
180 unit-optional-argument ,
181 use-xspace
182 }
183 {
184 \keys_define:nn { siunitx }
185 {
186 #1 .code:n =
187 { \msg_warning:nnn { siunitx } { option-preamble-only } {#1} }
188 }
189 }
190 }
191 \msg_new:nnn { siunitx } { option-preamble-only }
192 { Option~'#1'~only~available~in~the~preamble. }
193 % \end{macrocode}
194 %
195 % \subsection{Creation of unit document commands}
196 %
197 % \begin{macro}{\siunitx_command_create:, \@@_create:}
198 % \begin{macro}{\@@_create:N}
199 % Creating document commands is all done by a single function which is
200 % set up using expansion: that way the tests are only run once. Other than
201 % that, this is all just a question of picking up all the various routes.
202 % \begin{macrocode}
203 \cs_new_protected:Npn \siunitx_command_create:
204 {
205 \bool_if:NT \l_@@_create_bool
206 { \@@_create: }
207 % \end{macrocode}
208 % At the beginning of table cells and inside \texttt{x}-type expansion,
209 % all symbolic units need to have \emph{some} definition.
210 % \begin{macrocode}
211 \seq_map_inline:Nn \l_siunitx_unit_symbolic_seq
212 {
213 \cs_if_free:NT ##1
214 { \cs_set_protected:Npn ##1 { \ERROR } }
215 }
216 % \end{macrocode}
217 % Where the \pkg{soulpos} package is loaded \emph{after} \pkg{siunitx}, the
218 % commands \cs{hl} and \cs{ul} will be created only after the hook is used.
219 % The \pkg{soul} package creates those using \tn{newcommand}, so we have to
220 % avoid an issue.
221 % \begin{macrocode}
222 \@ifpackageloaded { soulpos }
223 {
224 \@ifpackageloaded { soul }
225 { }
226 {
227 \cs_undefine:N \hl
228 \cs_undefine:N \ul
229 }
230 }
231 { }
232 }
233 \AtBeginDocument { \siunitx_command_create: }
234 \cs_new_protected:Npn \@@_create:
235 {
236 \bool_if:NT \l_@@_xspace_bool
237 { \RequirePackage { xspace } }
238 \bool_if:NT \l_@@_overwrite_bool
239 {
240 \seq_map_inline:Nn \l_siunitx_unit_symbolic_seq
241 { \cs_undefine:N ##1 }
242 }
243 \cs_set_protected:Npe \@@_create:N ##1
244 {
245 \ProvideDocumentCommand ##1 { \bool_if:NT \l_@@_optarg_bool { o } }
246 {
247 \mode_leave_vertical:
248 \group_begin:
249 \bool_if:NTF \l_@@_optarg_bool
250 { \exp_not:N \IfNoValueTF {####1} }
251 { \use_i:nn }
252 {
253 \siunitx_unit_options_apply:n {##1}
254 \siunitx_unit_format:nN {##1}
255 \exp_not:N \l_@@_tmp_tl
256 \bool_if:NTF \l_@@_prespace_bool
257 { \siunitx_quantity_print:nV { } }
258 { \siunitx_print_unit:V }
259 \exp_not:N \l_@@_tmp_tl
260 }
261 { \siunitx_quantity:nn {####1} {##1} }
262 \group_end:
263 \bool_if:NT \l_@@_xspace_bool { \exp_not:N \xspace }
264 }
265 }
266 \seq_map_function:NN \l_siunitx_unit_seq \@@_create:N
267 }
268 \cs_new_protected:Npn \@@_create:N #1 { }
269 % \end{macrocode}
270 % \end{macro}
271 % \end{macro}
272 %
273 % \subsection{Standard settings for module options}
274 %
275 % Some of these follow naturally from the point of definition
276 % (\foreign{e.g.}~boolean variables are always |false| to begin with),
277 % but for clarity everything is set here.
278 % \begin{macrocode}
279 \keys_set:nn { siunitx }
280 {
281 free-standing-units = false ,
282 overwrite-commands = false ,
283 space-before-unit = false ,
284 unit-optional-argument = false ,
285 use-xspace = false
286 }
287 % \end{macrocode}
288 % \begin{macrocode}
289 %</package>
290 % \end{macrocode}
291 %
292 % \end{implementation}
293 %
294 % \PrintIndex