Source Browser ?

1% language=us runpath=texruns:manuals/units
2
3% author    : Hans Hagen
4% copyright : ConTeXt Development Team
5% license   : Creative Commons Attribution ShareAlike 4.0 International
6% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
7% origin    : the ConTeXt distribution
8%
9% comment   : Because this manual is distributed with TeX distributions it comes with a rather
10%             liberal license. We try to adapt these documents to upgrades in the (sub)systems
11%             that they describe. Using parts of the content otherwise can therefore conflict
12%             with existing functionality and we cannot be held responsible for that. Many of
13%             the manuals contain characteristic graphics and personal notes or examples that
14%             make no sense when used out-of-context.
15%
16% comment   : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
17%             Group journal or otherwise. Thanks to the editors for corrections. Also thanks
18%             to users for testing, feedback and corrections.
19
20\usemodule[art-01,abr-02,physics-units]
21
22\definecolor[red]    [darkred]
23\definecolor[green]  [darkgreen]
24\definecolor[blue]   [darkblue]
25\definecolor[yellow] [darkyellow]
26\definecolor[magenta][darkmagenta]
27\definecolor[cyan]   [darkcyan]
28
29\definecolor[maincolor] [darkcyan]
30\definecolor[extracolor][darkmagenta]
31
32\setupbodyfont
33  [10pt]
34
35\setuptyping
36  [color=extracolor]
37
38\setuptype
39  [color=extracolor] % darkyellow
40
41% \setupnumbering
42%   [alternative=doublesided]
43
44\setupinteraction
45  [hidden]
46
47\setuphead
48  [section]
49  [color=maincolor]
50
51\usesymbols[cc]
52
53\startdocument
54  [metadata:author=Hans Hagen,
55   metadata:title=Units,
56   author=Hans Hagen,
57   affiliation=PRAGMA ADE,
58   location=Hasselt NL,
59   title=Units,
60   extra=ConTeXt MkIV,
61   support=www.contextgarden.net,
62   website=www.pragma-ade.nl]
63
64\unexpanded\def\UnitsHack#1#2%
65  {\setbox\scratchbox\hbox{\bf\strut#1#2/}% kerning and such
66   \hbox to \wd\scratchbox{\bf\strut#1\hss/\hss#2}}
67
68\startMPpage
69
70    StartPage ;
71        fill Page enlarged 2mm withcolor \MPcolor{darkcyan} ;
72        pickup pencircle scaled 2mm ;
73        picture p, q, r ;
74        p := textext("\ssbf\WORD{\documentvariable{title}}")  xsized (bbheight Page - 2cm) rotated 90 ;
75        q := textext("\ssbf\WORD{\documentvariable{author}}") ysized 1cm ;
76        r := textext("\ssbf\WORD{\documentvariable{extra}}")  xsized bbwidth q ;
77        draw anchored.rt (p, center rightboundary Page shifted (-1cm,   0mm)) withcolor white ;
78        draw anchored.lft(q, ulcorner             Page shifted ( 1cm, -84mm)) withcolor white ; % \MPcolor{darkred} ;
79        draw anchored.lft(r, ulcorner             Page shifted ( 1cm,-108mm)) withcolor white ; % \MPcolor{darkred} ;
80    StopPage ;
81
82\stopMPpage
83
84% \page[empty] \setuppagenumber[start=1]
85
86\startsubject[title={Contents}]
87
88\placelist[section][criterium=all,interaction=all]
89
90\stopsubject
91
92\startsection[title={Introduction}]
93
94In \CONTEXT\ \MKII\ there is a module that implements consistent
95typesetting of units (quantities and dimensions). In \MKIV\ this
96functionality is now part of the physics core modules. This is
97also one of the mechanisms that got a new user interface: instead
98of using commands we now parse text. Thanks to those users who
99provided input we're more complete now that in \MKII. You can browse
100the mailing list archive to get some sense of history.
101
102\stopsection
103
104\startsection[title={The main command}]
105
106The core command is \type {\unit}. The argument to this command gets
107parsed and converted into a properly typeset dimension. Normally there
108will be a quantity in front.
109
110\starttabulate
111\NC \type{10 meter}                   \NC \unit{10 meter}                   \NC \NR
112\NC \type{10 meter per second}        \NC \unit{10 meter per second}        \NC \NR
113\NC \type{10 square meter per second} \NC \unit{10 square meter per second} \NC \NR
114\stoptabulate
115
116The parser knows about special cases, like synonyms:
117
118\starttabulate
119\NC \type{10 degree celsius}  \NC \unit{10 degree celsius}  \NC \NR
120\NC \type{10 degrees celsius} \NC \unit{10 degrees celsius} \NC \NR
121\NC \type{10 celsius}         \NC \unit{10 celsius}         \NC \NR
122\stoptabulate
123
124The units can be rather complex, for example:
125
126\startbuffer
127\unit{30 kilo pascal square meter / second kelvin}
128\stopbuffer
129
130\typebuffer
131
132This comes out as: \ignorespaces\getbuffer\removeunwantedspaces. Depending
133on the unit at had, recognition is quite flexible. The following variants
134all work out ok.
135
136\starttabulate
137\NC \type{10 kilogram}  \NC \unit{10 kilogram}  \NC \NR
138\NC \type{10 kilo gram} \NC \unit{10 kilo gram} \NC \NR
139\NC \type{10 k gram}    \NC \unit{10 k gram}    \NC \NR
140\NC \type{10 kilo g}    \NC \unit{10 kilo g}    \NC \NR
141\NC \type{10 k g}       \NC \unit{10 k g}       \NC \NR
142\NC \type{10 kg}        \NC \unit{10 kg}        \NC \NR
143\NC \type{10 kilog}     \NC \unit{10 kilog}     \NC \NR
144\NC \type{10 kgram}     \NC \unit{10 kgram}     \NC \NR
145\stoptabulate
146
147Of course being consistent makes sense, so normally you will use
148a consistent mix of short or long keywords.
149
150You can provide a qualifier that gets lowered and appended to
151the preceding unit.
152
153\startbuffer
154\unit{112 decibel (A)}
155\stopbuffer
156
157\typebuffer
158
159This gives: \ignorespaces\getbuffer\removeunwantedspaces. Combinations
160are also possible:
161
162\starttabulate
163\NC \type{5 watt per meter celsius}         \NC \unit{5 watt per meter celsius}         \NC \NR
164\NC \type{5 watt per meter degrees celsius} \NC \unit{5 watt per meter degrees celsius} \NC \NR
165\NC \type{5 watt per meter kelvin}          \NC \unit{5 watt per meter kelvin}          \NC \NR
166\NC \type{5 watt per meter per kelvin}      \NC \unit{5 watt per meter per kelvin}      \NC \NR
167\NC \type{10 arcminute}                     \NC \unit{10 arcminute}                     \NC \NR
168\NC \type{10 arcminute 20 arcsecond}        \NC \unit{10 arcminute 20 arcsecond}        \NC \NR
169\stoptabulate
170
171\stopsection
172
173\startsection[title={Extra units}]
174
175To some extent units can be tuned. You can for instance
176influence the spacing between a number and a unit:
177
178\startbuffer
179                         \unit{35 kilogram per cubic meter}
180\setupunit[space=normal] \unit{35 kilogram per cubic meter}
181\setupunit[space=big]    \unit{35 kilogram per cubic meter}
182\setupunit[space=medium] \unit{35 kilogram per cubic meter}
183\setupunit[space=small]  \unit{35 kilogram per cubic meter}
184\setupunit[space=none]   \unit{35 kilogram per cubic meter}
185\stopbuffer
186
187\typebuffer
188
189Of course no spacing looks rather bad:
190
191\startlines
192\getbuffer
193\stoplines
194
195Another parameter is \type {separator}. In order to demonstrate
196this we define an extra unit command:
197
198\startbuffer
199\defineunit[sunit][separator=small]
200\defineunit[nunit][separator=none]
201\stopbuffer
202
203\typebuffer \getbuffer
204
205We now have two more commands:
206
207\startbuffer
208\unit {35 kilogram cubic meter}
209\sunit{35 kilogram cubic meter}
210\nunit{35 kilogram cubic meter}
211\stopbuffer
212
213\typebuffer
214
215These three commands give different results:
216
217\startlines
218\getbuffer
219\stoplines
220
221Valid separators are \type {normal}, \type {big}, \type {medium},
222\type {small}, \type {none}. You can let units stand out by
223applying color or a specific style.
224
225\startbuffer
226\setupunit[style=\bi,color=maincolor]
227\unit{10 square meter per second}
228\stopbuffer
229
230\typebuffer
231
232Keep in mind that all defined units inherit from their parent
233definition unless they are set up themselves.
234
235\start \blank \getbuffer \blank \stop
236
237To some extent you can control rendering in text and math mode. As
238an example we define an extra instance.
239
240\startbuffer
241\defineunit[textunit][alternative=text]
242\stopbuffer
243
244\typebuffer \getbuffer
245
246\startbuffer
247test  \unit    {10 cubic meter per second}  test
248test  \textunit{10 cubic meter per second}  test
249test $\unit    {10 cubic meter per second}$ test
250test $\textunit{10 cubic meter per second}$ test
251test  10 \unit    {cubic meter per second}  test
252test  10 \textunit{cubic meter per second}  test
253test $10 \unit    {cubic meter per second}$ test
254test $10 \textunit{cubic meter per second}$ test
255\stopbuffer
256
257\typebuffer
258
259\startlines
260\getbuffer
261\stoplines
262
263\stopsection
264
265\startsection[title={Labels}]
266
267The units, prefixes and operators are typeset using the label
268mechanism which means that they can be made to adapt to a language
269and|/|or adapted. Instead of language specific labels you can also
270introduce mappings that don't relate to a language at all. As an
271example we define some bogus mapping.
272
273\startbuffer
274\setupunittext
275  [whatever]
276  [meter=retem,
277   second=dnoces]
278
279\setupprefixtext
280  [whatever]
281  [kilo=olik]
282
283\setupoperatortext
284  [whatever]
285  [solidus={ rep }]
286\stopbuffer
287
288\typebuffer \getbuffer
289
290Such a mapping can be partial and the current language will
291be the default fallback and itselfs falls back on the English
292language mapping.
293
294\startbuffer
295\unit{10 km/s}
296\unit{10 Kilo Meter/s}
297\unit{10 kilo Meter/s}
298\unit{10 Kilo m/s}
299\unit{10 k Meter/s}
300\stopbuffer
301
302\typebuffer
303
304When we typeset this we get the normal rendering:
305
306\startlines
307\getbuffer
308\stoplines
309
310However, when we change the language parameter, we get
311a different result:
312
313\startlines
314\setupunit[language=whatever]\getbuffer
315\stoplines
316
317The alternative rendering is set up as follows:
318
319\starttyping
320\setupunit[language=whatever]
321\stoptyping
322
323You can also decide to use a special instance of units:
324
325\starttyping
326\defineunit[wunit][language=whatever]
327\stoptyping
328
329This will define the \type {\wunit} command and leave the original
330\type {\unit} command untouched.
331
332\stopsection
333
334\startsection[title={Digits}]
335
336In addition to units we have digits. These can be used independently
337but the same functionality is also integrated in the unit commands.
338The main purpose of this command is formatting in tables, of which
339we give an example below.
340
341\starttabulate[|l|r|]
342\NC \type{12,345.67 kilogram} \NC \unit{12,345.67 kilogram} \NR
343\NC \type{__,__1.23 kilogram} \NC \unit{__,__1.23 kilogram} \NR
344\NC \type{__,___.12 kilogram} \NC \unit{__,___.12 kilogram} \NR
345\NC \type{__,__1.== kilogram} \NC \unit{__,__1.== kilogram} \NR
346\NC \type{__,___:23 kilogram} \NC \unit{__,___:23 kilogram} \NR
347\stoptabulate
348
349The \type {_} character serves as placeholders. There are some
350assumptions to how numbers are constructed. In principe the input
351assumes a comma to separate thousands and a period to separate the
352fraction.
353
354\getbuffer
355
356You can swap periods and commas in the output. In fact there are a
357few methods available. For instance we can separate the thousands
358with a small space instead of a symbol.
359
360\startbuffer
361\starttabulate[|c|r|r|]
362\HL
363\NC 0 \NC \setupunit[method=0]\unit{00,000.10 kilogram}
364      \NC \setupunit[method=0]\unit{@@,@@0.10 kilogram} \NC \NR
365\NC 1 \NC \setupunit[method=1]\unit{00,000.10 kilogram}
366      \NC \setupunit[method=1]\unit{@@,@@0.10 kilogram} \NC \NR
367\NC 2 \NC \setupunit[method=2]\unit{00,000.10 kilogram}
368      \NC \setupunit[method=2]\unit{@@,@@0.10 kilogram} \NC \NR
369\NC 3 \NC \setupunit[method=3]\unit{00,000.10 kilogram}
370      \NC \setupunit[method=3]\unit{@@,@@0.10 kilogram} \NC \NR
371\NC 4 \NC \setupunit[method=4]\unit{00,000.10 kilogram}
372      \NC \setupunit[method=4]\unit{@@,@@0.10 kilogram} \NC \NR
373\NC 5 \NC \setupunit[method=5]\unit{00,000.10 kilogram}
374      \NC \setupunit[method=5]\unit{@@,@@0.10 kilogram} \NC \NR
375\NC 6 \NC \setupunit[method=6]\unit{00,000.10 kilogram}
376      \NC \setupunit[method=6]\unit{@@,@@0.10 kilogram} \NC \NR
377\HL
378\stoptabulate
379\stopbuffer
380
381\typebuffer % [bodyfont=9pt]
382
383\getbuffer
384
385The digit modes can be summarized as::
386
387\startitemize[n,packed]
388\item periods/comma
389\item commas/period
390\item thinmuskips/comma
391\item thinmuskips/period
392\item thickmuskips/comma
393\item thickmuskips/period
394\stopitemize
395
396You can reverse the order of commas and period in the input by
397setting the parameter \type {order} to \type {reverse}.
398
399The digit parser handles a bunch of special characters as
400well as different formats. We strongly suggest you to use
401the grouped call.
402
403\starttabulate[|l|l|l|]
404\NC \type{.}  \NC , .           \NC comma or period     \NC \NR
405\NC \type{,}  \NC , .           \NC comma or period     \NC \NR
406\NC \type{:}  \NC               \NC invisible period    \NC \NR
407\NC \type{;}  \NC               \NC invisible comma     \NC \NR
408\NC \type{_}  \NC               \NC invisible space     \NC \NR
409\NC \type{/}  \NC               \NC invisible sign      \NC \NR
410\NC \type{-}  \NC $-$           \NC minus sign          \NC \NR
411\NC \type{+}  \NC $+$           \NC plus sign           \NC \NR
412\NC \type{//} \NC               \NC invisible high sign \NC \NR
413\NC \type{--} \NC $\negative$   \NC high minus sign     \NC \NR
414\NC \type{++} \NC $\positive$   \NC high plus sign      \NC \NR
415\NC \type{=}  \NC $\zeroamount$ \NC zero padding        \NC \NR
416\stoptabulate
417
418Let's give some examples:
419
420\starttabulate[|l|r|]
421\NC \type{1}                      \NC \ruledhbox{\strut\digits{1}}                      \NC \NR
422\NC \type{12}                     \NC \ruledhbox{\strut\digits{12}}                     \NC \NR
423\NC \type{12.34}                  \NC \ruledhbox{\strut\digits{12.34}}                  \NC \NR
424\NC \type{123,456}                \NC \ruledhbox{\strut\digits{123,456}}                \NC \NR
425\NC \type{123,456.78}             \NC \ruledhbox{\strut\digits{123,456.78}}             \NC \NR
426\NC \type{12,34}                  \NC \ruledhbox{\strut\digits{12,34}}                  \NC \NR
427\NC \type{.1234}                  \NC \ruledhbox{\strut\digits{.1234}}                  \NC \NR
428\NC \type{1234}                   \NC \ruledhbox{\strut\digits{1234}}                   \NC \NR
429\NC \type{123,456.78^9}           \NC \ruledhbox{\strut\digits{123,456.78^9}}           \NC \NR
430\NC \type{123,456.78e9}           \NC \ruledhbox{\strut\digits{123,456.78e9}}           \NC \NR
431\NC \type{/123,456.78e-9}         \NC \ruledhbox{\strut\digits{/123,456.78e-9}}         \NC \NR
432\NC \type{-123,456.78e-9}         \NC \ruledhbox{\strut\digits{-123,456.78e-9}}         \NC \NR
433\NC \type{+123,456.78e-9}         \NC \ruledhbox{\strut\digits{+123,456.78e-9}}         \NC \NR
434\NC \type{//123,456.78e-9}        \NC \ruledhbox{\strut\digits{//123,456.78e-9}}        \NC \NR
435\NC \type{--123,456.78e-9}        \NC \ruledhbox{\strut\digits{--123,456.78e-9}}        \NC \NR
436\NC \type{++123,456.78e-9}        \NC \ruledhbox{\strut\digits{++123,456.78e-9}}        \NC \NR
437\NC \type{___,___,123,456,789.00} \NC \ruledhbox{\strut\digits{___,___,123,456,789.00}} \NC \NR
438\NC \type{___,___,_12,345,678.==} \NC \ruledhbox{\strut\digits{___,___,_12,345,678.==}} \NC \NR
439\stoptabulate
440
441\stopsection
442
443\startsection[title={Adding units}]
444
445It is possible to add extra snippets. This is a two step process:
446first some snippet is defined, next a proper label is set up. In the
447next example we define a couple of \TEX\ dimensions:
448
449\startbuffer
450\registerunit
451  [unit]
452  [point=point,
453   basepoint=basepoint,
454   scaledpoint=scaledpoint,
455   didot=didot,
456   cicero=cicero]
457\stopbuffer
458
459\typebuffer \getbuffer
460
461Possible categories are: \type {prefix}, \type {unit}, \type {operator},
462\type {suffix}, \type {symbol},\type {packaged}. Next we define labels:
463
464\startbuffer
465\setupunittext
466  [point=pt,
467   basepoint=bp,
468   scaledpoint=sp,
469   didot=dd,
470   cicero=cc]
471\stopbuffer
472
473\typebuffer \getbuffer
474
475Now we can use use these:
476
477\startbuffer
478\unit{10 point / second}
479\stopbuffer
480
481\typebuffer
482
483Of course you can wonder what this means.
484
485\blank \getbuffer \blank
486
487When no label is defined the long name is used:
488
489\startbuffer
490\registerunit
491  [unit]
492  [page=page]
493\stopbuffer
494
495\typebuffer \getbuffer
496
497This is used as:
498
499\startbuffer
500\unit{10 point / page}
501\stopbuffer
502
503\typebuffer
504
505Which gives:
506
507\blank \getbuffer \blank
508
509\stopsection
510
511\startsection[title={Goodies}]
512
513Here are some goodies:
514
515\startbuffer
516\type{1 } : \unit  {30^2            meter per second}
517\type{2a} : \unit  {30    ± 10      meter per second}
518\type{2b} : \unit  {30    – 10      meter per second}
519\type{3a} : \unit  {30^2  ± 10^2    meter per second}
520\type{3b} : \unit  {30^2  – 10^2    meter per second}
521\type{4 } : \unit  {30   (10)       meter per second}
522\type{5a} : \unit  {30   (± 10)     meter per second}
523\type{5b} : \unit  {30^2 (± 10^2)   meter per second}
524\type{6a} : \unit {(30    ± 10)     meter per second}
525\type{6b} : \unit {(30^2  ± 10^2)   meter per second}
526\type{6c} : \unit {(30^2  – 10^2)   meter per second}
527\type{7a} : \unit {(30    ± 10)^2   meter per second}
528\type{7b} : \unit {(30    – 10)^2   meter per second}
529\type{7c} : \unit {(30^2  – 10^3)^5 meter per second}
530\stopbuffer
531
532Instead of \type {±} one can use \type {pm} and \type {to} can be used instead of
533\type {–}.
534
535\typebuffer
536
537Their rendering explains their intention:
538
539\startlines
540\getbuffer
541\stoplines
542
543\stopsection
544
545\startsection[title={Built in keywords}]
546
547A given sequence of keywords is translated in an list of internal
548keywords. For instance \type {m}, \type {Meter} and \type {meter}
549all become \type {meter} and that one is used when resolving a
550label. In the next tables the right column mentions the internal
551keyword. The right column shows the Cased variant, but a lowercase
552one is built|-|in as well.
553
554The following prefixes are built|-|in:
555
556\showunits[prefixes]
557
558The following units are supported, including some combinations:
559
560\showunits[units]
561
562The amount of operators is small:
563
564\showunits[operators]
565
566There is also a small set of (names) suffixes:
567
568\showunits[suffixes]
569
570Some symbols get a special treatment:
571
572\showunits[symbols]
573
574These are also special:
575
576\showunits[packaged]
577
578\stopsection
579
580\startsection[title={Colofon}]
581
582\starttabulate[|B|p|]
583\NC author    \NC \documentvariable{author}, \documentvariable{affiliation}, \documentvariable{location} \NC \NR
584\NC version   \NC \currentdate \NC \NR
585\NC website   \NC \documentvariable{website} \endash\ \documentvariable{support} \NC \NR
586\NC copyright \NC \symbol[cc][cc-by-sa] \NC \NR
587\stoptabulate
588
589\stopsection
590
591\stopdocument
592