Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %<*internal>
3 \iffalse
4 %</internal>
5 %<*readme>
6 ----------------------------------------------------------------
7 The lengthconvert package --- Convert a length to an other unit.
8 E-mail: [email protected]
9 Released under the LaTeX Project Public License v1.3c or later
10 See http://www.latex-project.org/lppl.txt
11 ----------------------------------------------------------------
12
13 Requires expl3
14 %</readme>
15 %<*internal>
16 \fi
17 \def\nameofplainTeX{plain}
18 \ifx\fmtname\nameofplainTeX\else
19 \expandafter\begingroup
20 \fi
21 %</internal>
22 %<*install>
23 \input l3docstrip.tex
24 \keepsilent
25 \askforoverwritefalse
26 \preamble
27 ----------------------------------------------------------------
28 The lengthconvert package --- Convert a length to an other unit.
29 E-mail: [email protected]
30 Released under the LaTeX Project Public License v1.3c or later
31 See http://www.latex-project.org/lppl.txt
32 ----------------------------------------------------------------
33
34 \endpreamble
35 \postamble
36 Copyright (C) 2013 by
37 Marco Daniel [email protected]
38
39 It may be distributed and/or modified under the conditions of
40 the LaTeX Project Public License (LPPL), either version 1.3c of
41 this license or (at your option) any later version. The latest
42 version of this license is in the file:
43 http://www.latex-project.org/lppl.txt
44
45 This work is "maintained" (as per LPPL maintenance status) by
46 Marco Daniel.
47
48 \endpostamble
49 \usedir{tex/latex/lengthconvert}
50 \generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
51 %</install>
52 %<install>\endbatchfile
53 %<*internal>
54 \usedir{source/latex/lengthconvert}
55 \generate{
56 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
57 }
58 \nopreamble\nopostamble
59 \usedir{doc/latex/lengthconvert}
60 \generate{
61 \file{README.txt}{\from{\jobname.dtx}{readme}}
62 }
63 \ifx\fmtname\nameofplainTeX
64 \expandafter\endbatchfile
65 \else
66 \expandafter\endgroup
67 \fi
68 %</internal>
69 %<*driver|package>
70 \RequirePackage{expl3,xparse}
71 %</driver|package>
72 %<*driver>
73 \setcounter{errorcontextlines}{999}
74 \documentclass[full]{l3doc}
75 \usepackage{amsmath,array,booktabs}
76 \usepackage{siunitx}
77 \usepackage{lengthconvert}
78 \usepackage{parskip}
79 \usepackage{setspace}\onehalfspacing
80 \begin{document}
81 \DocInput{\jobname.dtx}
82 \end{document}
83 %</driver>
84 % \fi
85 %
86 % \title{^^A
87 % The \textsf{lengthconvert} package
88 % }
89 %
90 % \author{^^A
91 % Marco Daniel
92 % {^^A
93 % E-mail:
94 % \href{mailto:[email protected]}
95 % {[email protected]}^^A
96 % }^^A
97 % }
98 %
99 % \date{Released 2013/06/13}
100 %
101 % \changes{v1.0}{2013/06/13}{First official release}
102 % \changes{v1.0a}{2013/06/15}{fixed typo in package name}
103 % \maketitle
104 %
105 % \begin{documentation}
106 %
107 % Sometimes it's useful for some explanation to provide lengths in
108 % standardizations units instead of the default unit of \TeX.
109 % This package can do this for your.
110 %
111 %
112 % \tableofcontents
113 %
114 % \section{Basics}
115 %
116 % The package needs the newest version of \pkg{l3kernel} available at CTAN.
117 % Internally it uses the modul \pkg{l3fp} to convert the length.
118 %
119 % All allowed units in \TeX\ are listed in the table below.
120 %
121 % \begin{table}[!ht]
122 % \centering
123 % \caption{Allowed \TeX\ units}
124 % \vspace*{1em}
125 % \begin{tabular}{cl}
126 % \toprule
127 % \textbf{Unit} & \textbf{Measurement} \\
128 % \midrule
129 % pt & point \\
130 % pc & pica(1pc=12pt) \\
131 % in & inch (1 in = 72.27 pt) \\
132 % bp & bigpoint(72bp=1in) \\
133 % cm & centimeter (2.54 cm = 1 in) \\
134 % mm & millimeter (10 mm = 1 cm) \\
135 % dd & didot point (1157 dd = 1238 pt) \\
136 % cc & cicero (1 cc = 12 dd) \\
137 % sp & scaled point (65536 sp = 1 pt) \\
138 % \bottomrule
139 % \end{tabular}
140 % \end{table}
141 %
142 %
143 % \section{Usage}
144 %
145 % The usage is really simple. Pass the length to the command \cs{Convert}
146 % and get the result.
147 %
148 % \begin{function}{\Convert}
149 % \begin{syntax}
150 % \cs{Convert}\oarg{options} \Arg{length}
151 % \end{syntax}
152 % \end{function}
153 % The command converts the given length to the unit specified by an option. The
154 % default unit is cm.
155 % After the conversion the result will be printed.
156 %
157 % \begin{function}{\Convertsetup}
158 % \begin{syntax}
159 % \cs{Convertsetup} \Arg{options}
160 % \end{syntax}
161 % \end{function}
162 % Allows the specification of options.
163 %
164 % \section{Options}
165 %
166 % The package is simple and the options too.
167 %
168 %\DescribeOption{unit}
169 % The option accepts only the abbrevation unit. Allowed units are described in
170 % the table above.
171
172 % You can also use only the abbrevation or a complete word. The following table
173 % lists all allowed inputs.
174 %
175 %
176 % \begin{center}
177 % \def\arraystretch{1.4}
178 % \begin{tabular}{*{6}{c}}
179 % \toprule
180 % pt & pc & in & bp & cm & mm \\
181 % dd & cc & sp & point & pica & inch \\
182 % big-point & centimeter & millimeter & didot-point & cicero & scaled-point \\
183 % \bottomrule
184 % \end{tabular}
185 %
186 % \end{center}
187 %
188 %
189 %
190 %\DescribeOption{use-siunitx}
191 % It's a bool flag which can be either \texttt{true} or \texttt{false}.
192 % If it is true, the output of the new length is done by the package
193 % \pkg{siunitx} using the command \cs{SI}.
194 %
195 %\DescribeOption{precision}
196 % This option accepts an integer and specifies the precision of the output.
197 %
198 %\DescribeOption{number-only}
199 % It's a bool flag which can be either \texttt{true} or \texttt{false}.
200 % If it's true, only the number is printed.
201 %
202 % \section{Examples}
203 % Some examples are shown in the following table. In the left column
204 % you see the input and in the right the output.
205 %
206 % \begin{center}
207 % \def\arraystretch{1.4}
208 % \begin{tabular}{ll}
209 % \toprule
210 % \verb+\Convert{36pt}+ & \Convert{36pt} \\
211 % \verb+\Convert[precision=2]{36pt}+ & \Convert[precision=2]{36pt} \\
212 % \verb+\Convert[use-siunitx]{36pt}+ & \Convert[use-siunitx]{36pt} \\
213 % \verb+\Convert[unit=pt]{2cm}+ & \Convert[unit=pt]{2cm} \\
214 % \verb+\Convert[unit=dd,number-only]{2cm}+ &
215 % \Convert[unit=dd,number-only]{2cm} \\
216 % \verb+\Convert[pt]{2cm}+ & \Convert[pt]{2cm} \\
217 % \verb+\Convert[scaled-point]{2cm}+ & \Convert[scaled-point]{2cm} \\
218 % \bottomrule
219 % \end{tabular}
220 %
221 % \end{center}
222 %
223 %
224 %\end{documentation}
225 %
226 % \clearpage
227 %
228 %\begin{implementation}
229 %
230 %\section{\pkg{lengthconvert} Implementation}
231 %
232 % \begin{macrocode}
233 %<*package>
234 % \end{macrocode}
235 %
236 % \begin{macrocode}
237 %<@@=lconv>
238 % \end{macrocode}
239 %
240 % \begin{macrocode}
241 \ProvidesExplPackage
242 {lengthconvert}{2013/05/13}{1.0}{Convert length to another unit}
243 % \end{macrocode}
244 %
245 % Make sure that the version of \pkg{l3kernel} in use is sufficiently new.
246 % This will also trap any problems with \pkg{l3packages} (as the two are now
247 % tied together, version-wise).
248 % \begin{macrocode}
249 \@ifpackagelater { expl3 } { 2012/11/21 }
250 { }
251 {
252 \PackageError { lengthtconvert } { Support~package~expl3~too~old }
253 {
254 You~need~to~update~your~installation~of~the~bundles~'l3kernel'~and~
255 'l3packages'.\MessageBreak
256 Loading~lengthtconvert~will~abort!
257 }
258 \tex_endinput:D
259 }
260 % \end{macrocode}
261 %
262 % Now load the support packages.
263 % \begin{macrocode}
264 \RequirePackage{ l3keys2e }
265 % \end{macrocode}
266 %
267 %
268 % \begin{macro}{\@@_allowed_shortunits_clist}
269 % \begin{macro}{\@@_allowed_longunits_clist}
270 % \begin{macro}{\@@_allowed_allunits_clist}
271 % Save all allowed units in a clist
272 % \begin{macrocode}
273 \clist_new:N \g__@@_allowed_shortunits_clist
274 \clist_gset:Nn \g__@@_allowed_shortunits_clist
275 { pt , pc , in , bp , cm , mm , dd , cc ,sp }
276 \clist_new:N \g__@@_allowed_longunits_clist
277 \clist_gset:Nn \g__@@_allowed_longunits_clist
278 { point , pica , inch , big-point , centimeter , millimeter ,
279 didot-point , cicero , scaled-point }
280 \clist_new:N \g__@@_allowed_allunits_clist
281 \clist_gset:NV \g__@@_allowed_allunits_clist \g__@@_allowed_shortunits_clist
282 \clist_gput_right:NV \g__@@_allowed_allunits_clist \g__@@_allowed_longunits_clist
283 % \end{macrocode}
284 % \end{macro}
285 % \end{macro}
286 % \end{macro}
287 %
288 % \begin{macro}{\@@_unit_tl}
289 % Save the default unit in a token list variable and provide them as option
290 %
291 % \begin{macrocode}
292 \tl_new:N \l__@@_unit_tl
293 \keys_define:nn { lengthconvert }
294 {
295 unit .tl_set:N = \l__@@_unit_tl
296 }
297 \keys_set:nn { lengthconvert }
298 {
299 unit = cm ,
300 }
301 % \end{macrocode}
302 %
303 %
304 % Provide also abbreviation and word of units
305 %
306 % \begin{macrocode}
307 \tl_new:N \l_@@_default_unit_tl
308 \keys_define:nn { lengthconvert }
309 {
310 pt .meta:n =
311 { unit = pt },
312 pc .meta:n =
313 { unit = pc },
314 in .meta:n =
315 { unit = in },
316 bp .meta:n =
317 { unit = bp },
318 cm .meta:n =
319 { unit = cm },
320 mm .meta:n =
321 { unit = mm },
322 dd .meta:n =
323 { unit = dd },
324 cc .meta:n =
325 { unit = cc },
326 sp .meta:n =
327 { unit = sp },
328 point .meta:n =
329 { unit = pt },
330 pica .meta:n =
331 { unit = pc },
332 inch .meta:n =
333 { unit = in },
334 big-point .meta:n =
335 { unit = bp },
336 centimeter .meta:n =
337 { unit = cm },
338 millimeter .meta:n =
339 { unit = mm },
340 didot-point .meta:n =
341 { unit = dd },
342 cicero .meta:n =
343 { unit = cc },
344 scaled-point .meta:n =
345 { unit = sp },
346 }
347 % \end{macrocode}
348 % \end{macro}
349 %
350 %
351 % \begin{macro}{\l__@@_use_siunitx_bool}
352 % Output should be done by \pkg{sinutix}.
353 % \begin{macrocode}
354 \keys_define:nn { lengthconvert } {
355 use-siunitx .bool_set:N = \l__@@_use_siunitx_bool
356 }
357 % \end{macrocode}
358 % \end{macro}
359 %
360 % \begin{macro}{\l_@@_precision_tl}
361 % Specify the precision
362 % \begin{macrocode}
363 \keys_define:nn { lengthconvert } {
364 precision .int_set:N = \l__@@_precision_int
365 }
366 \keys_set:nn { lengthconvert }
367 {
368 precision = 5 ,
369 }
370 % \end{macrocode}
371 % \end{macro}
372 %
373 % \begin{macro}{\l__@@_only_num_bool}
374 % Only the number should be used
375 % \begin{macrocode}
376 \keys_define:nn { lengthconvert } {
377 number-only .bool_set:N = \l__@@_only_num_bool
378 }
379 % \end{macrocode}
380 % \end{macro}
381 %
382 % Unknown options should be raised an error
383 % \begin{macrocode}
384 \keys_define:nn { lengthconvert } {
385 unknown .code:n =
386 {
387 \msg_error:nnx { lengthconvert } { option-unknown }
388 { \exp_not:V \l_keys_key_tl }
389 }
390 }
391 % \end{macrocode}
392 %
393 %
394 %
395 % \begin{macro}{\Convertsetup}
396 % User settings
397 % \begin{macrocode}
398 \NewDocumentCommand \Convertsetup { m }
399 {
400 \keys_set:nn { lengthconvert } { #1 }
401 }
402 % \end{macrocode}
403 % \end{macro}
404 %
405 %
406 % \begin{macro}{\Convert}
407 % Expandable definition of the main command
408 % \begin{macrocode}
409 \DeclareExpandableDocumentCommand \Convert { O{} m }
410 {
411 \group_begin:
412 \keys_set:nn { lengthconvert } { #1 }
413 \clist_if_in:NVTF \g_@@_allowed_allunits_clist \l__@@_unit_tl
414 {
415 \bool_if:NTF \l__@@_use_siunitx_bool
416 {
417 \@@_using_siunitx:n { #2 }
418 }
419 {
420 \@@_nousing_siunitx:n { #2 }
421 }
422 }
423 {
424 \msg_error:nnx { lengthconvert } { unit-unknown }
425 { \exp_not:V \l__@@_unit_tl }
426 }
427 \group_end:
428 }
429 % \end{macrocode}
430 % \end{macro}
431 %
432 % \begin{macro}{\@@_calc_dim:n}
433 % Output using \pkg{siunitx}
434 % \begin{macrocode}
435 \cs_new:Npn \@@_calc_dim:n #1
436 {
437 \fp_eval:n
438 {
439 round( \dim_to_fp:n { #1 } / 1\l__@@_unit_tl , \l__@@_precision_int)
440 }
441 }
442 % \end{macrocode}
443 % \end{macro}
444
445 %
446 % \begin{macro}{\@@_using_siunitx:n}
447 % Output using \pkg{siunitx}
448 % \begin{macrocode}
449 \cs_new:Npn \@@_using_siunitx:n #1
450 {
451 \bool_if:NTF \l__@@_only_num_bool
452 {
453 \num { \@@_calc_dim:n { #1 } }
454 }
455 {
456 \SI { \@@_calc_dim:n { #1 } } { \l__@@_unit_tl }
457 }
458 }
459 % \end{macrocode}
460 % \end{macro}
461 %
462 % \begin{macro}{\@@_nousing_siunitx:n}
463 % Output using \pkg{siunitx}
464 % \begin{macrocode}
465 \cs_new:Npn \@@_nousing_siunitx:n #1
466 {
467 \bool_if:NTF \l__@@_only_num_bool
468 {
469 \@@_calc_dim:n { #1 }
470 }
471 {
472 \@@_calc_dim:n { #1 } \, \l__@@_unit_tl
473 }
474 }
475 % \end{macrocode}
476 % \end{macro}
477 %
478 %
479 % \begin{macrocode}
480 \msg_new:nnnn { lengthconvert } { option-unknown }
481 { Unknown~option~'#1'~for~package~#2. }
482 {
483 LaTeX~has~been~asked~to~set~an~option~called~'#1'~
484 but~the~#2~package~has~not~created~an~option~with~this~name.
485 }
486 % \end{macrocode}
487 %
488 % \begin{macrocode}
489 \msg_new:nnnn { lengthconvert } { unit-unknown }
490 { Unknown~unit~'#1'~for~package~#2. }
491 {
492 You~are~setting~an~unit~'#1'~which~
493 is~unknonw~for~the~package~#2.
494 }
495 % \end{macrocode}
496 %
497 %
498 %
499 % Finally apply the settings given at load time.
500 % \begin{macrocode}
501 \ProcessKeysOptions { lengthconvert }
502 % \end{macrocode}
503 %
504 %
505 % \begin{macrocode}
506 %</package>
507 % \end{macrocode}
508 %
509 % \end{implementation}
510 %
511 % \begingroup
512 % \clearpage
513 % \let\part\section
514 % \PrintChanges
515 % \clearpage
516 % \PrintIndex
517 % \endgroup