Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % This is the scalebar package, scalebar.dtx
4 %
5 % Copyright (C) 2003 by Michael Lake <[email protected]>
6 %
7 % This file may be distributed and/or modified under the conditions of
8 % the LaTeX Project Public License, either version 1.2 of this license
9 % or (at your option) any later version. The latest version of this
10 % license is in:
11 %
12 % http://www.latex-project.org/lppl.txt
13 %
14 % and version 1.2 or later is part of all distributions of
15 % LaTeX version 1999/12/01 or later.
16 %
17 %
18 %<*driver>
19 \ProvidesFile{scalebar.dtx}
20 %</driver>
21 %
22 %
23 %<package>\ProvidesPackage{scalebar}%
24 [2003/05/01 v1.0 Scalebars for maps and diagrams]
25 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
26 %<package>\RequirePackage{ifthen}
27 %<package>\RequirePackage{calc}
28 %<package>\RequirePackage{fp}
29 %
30 %<*driver>
31 \documentclass{ltxdoc}
32 \GetFileInfo{scalebar.dtx}
33 \EnableCrossrefs
34 \CodelineIndex
35 \RecordChanges
36 %\OnlyDescription
37 \begin{document}
38 \DocInput{scalebar.dtx}
39 \end{document}
40 %</driver>
41 %
42 % \fi
43 %
44 % \CheckSum{187}
45 %
46 % \CharacterTable
47 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
48 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
49 % Digits \0\1\2\3\4\5\6\7\8\9
50 % Exclamation \! Double quote \" Hash (number) \#
51 % Dollar \$ Percent \% Ampersand \&
52 % Acute accent \' Left paren \( Right paren \)
53 % Asterisk \* Plus \+ Comma \,
54 % Minus \- Point \. Solidus \/
55 % Colon \: Semicolon \; Less than \<
56 % Equals \= Greater than \> Question mark \?
57 % Commercial at \@ Left bracket \[ Backslash \\
58 % Right bracket \] Circumflex \^ Underscore \_
59 % Grave accent \` Left brace \{ Vertical bar \|
60 % Right brace \} Tilde \~}
61 %
62 % \changes{v1.0}{2003/05/01}{Initial version}
63 %
64 % \DoNotIndex{
65 % \newcounter,\setcounter,\addtocounter,\newlength,\setlength,
66 % \else,\fi,\hfill,\hspace,\rule,\newcommand}
67 %
68 % \setlength{\parskip}{0.4\baselineskip}
69 % \setlength{\parindent}{0pt}
70 %
71 % \title{The \textsf{scalebar} package}
72 % \author{Michael Lake\\ \texttt{[email protected]}}
73 % \date{\fileversion{} -- \filedate}
74 % \maketitle
75 %
76 %
77 %
78 % \section{Introduction}
79 %
80 % This document describes the \textsf{scalebar} package for \LaTeXe, which
81 % creates scalebars for maps, diagrams or photos.
82 % It was designed for use with cave maps, but
83 % can be used for anything from showing a scalebar in kilometers for
84 % topographic maps to a scalebar in micrometers for
85 % an electron microscope image.
86 %
87 % Here is an example scalebar.
88 % See the scalebar\_examples file for further examples and possible uses.
89 %
90 % ^^A In the scalebar below I have not used the \scalebar command
91 % ^^A as the user would not have it yet to typeset the scalebar so I
92 % ^^A have used two temporary commands to typeset some rules and created
93 % ^^A the scalebar from those.
94 % \newcommand{\tempA}[1]{\rule{#1}{2mm}\hspace{-#1}\raisebox{-2mm}{\rule{#1}{0.2mm}}}
95 % \newcommand{\tempB}[1]{\raisebox{1.8mm}{\rule{#1}{0.2mm}}\hspace{-#1}\raisebox{-2mm}{\rule{#1}{2mm}}}
96 % ^^A Now from the above two commands create a scalebar.
97 % \raisebox{-2mm}{\rule{0.2mm}{4mm}}\tempA{5mm}\tempB{5mm}\tempA{5mm}\tempB{5mm}\tempA{20mm}\tempB{20mm}\tempA{20mm}\tempB{20mm}\raisebox{-2mm}{\rule{0.2mm}{4mm}}
98 %
99 % ^^A Scale the text manually. Normally \scalebar would do this for you.
100 %\hspace{-0.5ex}0\hspace{1.85cm}2\hspace{1.8cm}4\hspace{1.85cm}6\hspace{1.8cm}8\hspace{1.75cm}10\,m
101 %
102 % \section{Usage}
103 %
104 %
105 % \DescribeMacro{\scalebar}
106 % The \textsf{scalebar} package defines one user command.
107 % To use the command you write;
108 %
109 % |\scalebar|\oarg{inverse}\marg{length}\marg{minordivs}\marg{majordivs}\\
110 % | |\marg{starting No.}\marg{ending No.}\marg{units}
111 %
112 % \noindent where the six mandatory arguments are:
113 %
114 % \begin{tabular}{lp{9.5cm}}
115 % \meta{length}&the desired length of the scalebar on paper
116 % e.g.\ 10cm or 4in\\
117 % \meta{minordivs}&number of minor divisions within the first major
118 % division e.g.\ 4 (the first major division will always be
119 % subdivided unless this value is set to 1)\\
120 % \meta{majordivs}&number of major divisions e.g.\ 5 \\
121 % \meta{starting No.}&the number that the scalebar text will start from
122 % e.g.\ 0 or -0.5\\
123 % \meta{ending No.}&the number that the scalebar text will end with
124 % e.g.\ 2.5 or 25\\
125 % \meta{units}&the units for the scalebar text e.g.\ $\mu$m or km.
126 % \end{tabular}
127 % \vspace{0.4\baselineskip}
128 %
129 % The optional argument \meta{inverse} reverses the black and white regions.
130 % The default setting is for the top of the first bar to be black.
131 %
132 %
133 % \newpage
134 % \section{Current Limitations and Future Enhancements}
135 % \begin{description}
136 % \item[Scalebar height/text ratio is hardcoded]
137 % The height of the black rules in the scalebars is |1.2ex| so it scales
138 % with the current font height. This value seems about right but if you
139 % want a different height compared to the text height you will have to modify
140 % the style file (modify |\SB@Height|). This could possibly be set as
141 % an optional argument to the package.
142 % \item[Thickness of the thin rule is fixed] The thickness of the thin rule
143 % is set to 0.2\,mm. This seems about right. If you wish to change it is easy
144 % to modify the style file (|\SB@Thick|).
145 % \item[Number of decimal places is limited to one] Scalebars rarely display
146 % more than one decimal place in the scalebar text. This package rounds the
147 % decimals of the displayed text to one place. If you want two decimal places
148 % you will have to modify the style file.
149 % \end{description}
150 %
151 % Please let me know if you encounter any problems.
152 % If you have suggestions for extra options to add, then code for that
153 % would be appeciated.
154 %
155 %
156 % \StopEventually{\PrintChanges \PrintIndex}
157 %
158 % \section{Implementation}
159 %
160 % First we have to decide how a scalebar is constructed. Looking a a scalebar
161 % one can see that it is made up of alternating black and white bars. It would
162 % seem sensible therefore to define some sort of ``unit'' or ``building block''
163 % that can be iterated any number of times to create a scalebar of arbitary
164 % length and with an arbitary number of divisions. The diagram below of a
165 % scalebar and its deconstruction shows one way to break it up into units.
166 % \vspace{0.4\baselineskip}
167 %
168 % \raisebox{-2mm}{\rule{0.2mm}{4mm}}\tempA{5mm}\tempB{5mm}\tempA{5mm}\tempB{5mm}\tempA{20mm}\tempB{20mm}\tempA{20mm}\raisebox{-2mm}{\rule{0.2mm}{4mm}}
169 % \vspace{0.6\baselineskip}
170 %
171 % \raisebox{-2mm}{\rule{0.2mm}{4mm}} \mbox{}
172 % \tempA{5mm} \mbox{} \tempB{5mm} \mbox{} \tempA{5mm} \mbox{} \tempB{5mm} \mbox{}
173 % \tempA{20mm} \mbox{} \tempB{20mm} \mbox{} \tempA{20mm} \mbox{} \raisebox{-2mm}{\rule{0.2mm}{4mm}}
174 % \vspace{0.8\baselineskip}
175 %
176 % Looking at the parts above you can see there is a thin vertical rule at the
177 % start of each scalebar. This is followed by repeating ``scalebar units'' each
178 % one of which alternates in color. Finally there is a thin vertical rule to
179 % close the end of the scalebar.
180 %
181 % I have therefore defined two scalebar units. The first one typesets the thick
182 % black rule on the top. After writing this rule we then move back
183 % horizontally a distance equal to the width of the rule written. Then we write
184 % the thinner rule underneath it by using a raisebox with a negative vertical
185 % distance. This unit looks like this:
186 %
187 % \hspace{2em}\tempA{5mm}\ X%
188 % \hspace{2em}(the X shows the position of the baseline)
189 % \vspace{0.2\baselineskip}
190 %
191 % The second type of unit has the thick black rule on the bottom like this:
192 %
193 % \hspace{2em}\tempB{5mm}\ X
194 % \vspace{0.2\baselineskip}
195 %
196 % By stringing these two types of units together within a while loop
197 % we can create our scalebars.
198 % Let's now proceed to the start of the macro.
199 %
200 % \subsection{Required Packages}
201 %
202 % We have used the \textsf{fp} package to provide floating point calculations
203 % and a rounding function via the |\FPupn| macro. The \textsf{calc} package
204 % provides an easy calculation syntax for simple subtraction of lengths.
205 % The \textsf{ifthen} package provides the whiledo loop and the
206 % ifthenelse contruct.
207 %
208 % \subsection{Initialisation}
209 %
210 % Note that we have to place a \% at the end of each command to suppress any
211 % whitespace. Otherwise the scalebar will ``break apart''.
212 %
213 % \begin{macro}{counters/lengths}
214 %
215 % Define counters and lengths.
216 %
217 % The first three mandatory arguments specify the length of the scalebar and
218 % the numbers of the divisions. The arguments that specify the format of text
219 % underneath the scalebar will be introduced later.
220 %
221 % \begin{macrocode}
222 \newlength{\SB@Length}%
223 \newcounter{SB@majordivs}%
224 \newcounter{SB@minordivs}%
225 % \end{macrocode}
226 %
227 % These are some further general counters and lengths.
228 %
229 % \begin{macrocode}
230 \newcounter{SB@evenodd}%
231 \newcounter{SB@countup}%
232 \newlength{\SB@Height}%
233 \newlength{\SB@Thick}%
234 \newlength{\SB@MajorWidth}%
235 \newlength{\SB@MinorWidth}%
236 \newlength{\SB@DivisionWidth}%
237 \newlength{\SB@TextWidth}%
238 % \end{macrocode}
239 % \end{macro}
240 %
241 %
242 % Now define two small commands to typeset the two `scalebar units'.
243 %
244 % \begin{macro}{\SB@unitT}
245 %
246 % This command typesets the unit with the thick black rule on the \emph{top}.
247 %
248 % \begin{macrocode}
249 \newcommand{\SB@unitT}{%
250 \rule{\SB@DivisionWidth}{\SB@Height}\hspace{-\SB@DivisionWidth}%
251 \raisebox{-\SB@Height}{\rule{\SB@DivisionWidth}{\SB@Thick}}}%
252 % \end{macrocode}
253 % \end{macro}
254 %
255 %
256 % \begin{macro}{\SB@unitB}
257 %
258 % This command typesets the thick black rule on the \emph{bottom}.
259 %
260 % \begin{macrocode}
261 \newcommand{\SB@unitB}{%
262 \raisebox{\SB@Height-\SB@Thick}%
263 {\rule{\SB@DivisionWidth}{\SB@Thick}}\hspace{-\SB@DivisionWidth}%
264 \raisebox{-\SB@Height}{\rule{\SB@DivisionWidth}{\SB@Height}}}%
265 % \end{macrocode}
266 % \end{macro}
267 %
268 %
269 % \newpage
270 % \subsection{The scalebar macro}
271 %
272 % \begin{macro}{\scalebar}
273 % Start the scalebar command and process the command arguments.
274 %
275 % \begin{macro}{args}
276 % The first argument is an optional argument which is set to
277 % nothing as default. Normally the value
278 % of |SB@evenodd| is 0 which will result in the black rule of
279 % the first division being on top. If \meta{inverse} is set the
280 % black rule will be set on the bottom.
281 %
282 % \begin{macrocode}
283 \newcommand{\scalebar}[7][]{%
284 %
285 \ifthenelse{\equal{inverse}{#1}}%
286 {\setcounter{SB@evenodd}{1}}%
287 {\setcounter{SB@evenodd}{0}}%
288 % \end{macrocode}
289 %
290 % Read in the next three mandatory arguments.
291 %
292 % \begin{macrocode}
293 \setlength{\SB@Length}{#2}%
294 \setcounter{SB@minordivs}{#3}%
295 \setcounter{SB@majordivs}{#4}%
296 % \end{macrocode}
297 %
298 % Define the number at which the text will start by |\SB@StartNo|;
299 % the number at which it will end by |\SB@EndNo| and the units the text
300 % represents by |\SB@TextUnits|. These are set to the last three mandatory
301 % arguments.
302 %
303 % \begin{macrocode}
304 \def\SB@StartNo{#5}%
305 \def\SB@EndNo{#6}%
306 \def\SB@TextUnits{#7}%
307 % \end{macrocode}
308 % \end{macro}
309 %
310 %
311 % Set the height of the scalebar and thickness of the thin enclosing rule.
312 %
313 % Let the height of the thick black rule of a division be |\SB@Height| and set
314 % it to a value related to the x-height of the current font. This is because
315 % we want the scalebar to increase in height if the user specifies a change in
316 % font size. It's set after the command begins rather than earlier as we want
317 % it to pickup a font change immediately before the scalebar command if any.
318 % The thin rule that encloses the divisions (|\SB@Thick|) will be hard coded to
319 % 0.2\,mm. This was chosen as it looked about right :-)
320 %
321 % \begin{macrocode}
322 \setlength{\SB@Height}{1.2ex}%
323 \setlength{\SB@Thick}{0.2mm}%
324 % \end{macrocode}
325 %
326 %
327 % Calculate the lengths of the divisions.
328 %
329 % Let's define |\SB@MajorWidth| to be the width (i.e.\ length) of a
330 % major division.
331 % To calculate this we take the total scalebar length and divide by
332 % the number of major divisions.
333 % To calculate the length of a minor division, |\SB@MinorWidth|, we divide
334 % the major division length just calculated by the number of minor divisions.
335 %
336 % \begin{macrocode}
337 \setlength{\SB@MajorWidth}{\SB@Length / \theSB@majordivs}%
338 \setlength{\SB@MinorWidth}{\SB@MajorWidth / \theSB@minordivs}%
339 % \end{macrocode}
340 %
341 %
342 %
343 % \subsection{Drawing the scalebar}
344 %
345 % Now we can start placing ink to paper.
346 % Place onto the page the thin vertical rule at the start of the scalebar.
347 % As it starts at the baseline we have to make it twice the height of
348 % |\SB@Height| and lower it by |\SB@Height|.
349 %
350 % \begin{macrocode}
351 \raisebox{-\SB@Height}{\rule{\SB@Thick}{2\SB@Height}}%
352 % \end{macrocode}
353 %
354 %
355 % Use a while loop to place the minor divisions onto the page. (Use a new
356 % counter rather than decrementing minordivs variable.) Note
357 % that we alternate between using the |\SB@unitT| or the |\SB@unitB| unit
358 % depending on the value of the |SB@evenodd| variable. That value
359 % is set at the beginning and depends on the setting of the optional
360 % \meta{inverse} argument.
361 %
362 % \begin{macrocode}
363 \setlength{\SB@DivisionWidth}{\SB@MinorWidth}%
364 \setcounter{SB@countup}{0}%
365 \whiledo{\not\theSB@countup=\theSB@minordivs}{%
366 \ifthenelse{\isodd{\value{SB@evenodd}}}{\SB@unitB}{\SB@unitT}%
367 \addtocounter{SB@evenodd}{1}%
368 \addtocounter{SB@countup}{1}}%
369 % \end{macrocode}
370 %
371 %
372 % Now that the minor divisions are done we can write the major divisions.
373 %
374 % Note that we have to reset the length of the rule from the
375 % current width of a minor division to the width of a major division.
376 % Set the counter this time to start at 1 rather than 0
377 % as we have already written all the minor divisions which adds up
378 % to one major division.
379 %
380 % \begin{macrocode}
381 \setlength{\SB@DivisionWidth}{\SB@MajorWidth}%
382 \setcounter{SB@countup}{1}%
383 \whiledo{\not\theSB@countup=\theSB@majordivs}{%
384 \ifthenelse{\isodd{\value{SB@evenodd}}}{\SB@unitB}{\SB@unitT}%
385 \addtocounter{SB@evenodd}{1}%
386 \addtocounter{SB@countup}{1}}%
387 % \end{macrocode}
388 %
389 % Finally we have to print the thin vertical rule at the end.
390 %
391 % \begin{macrocode}
392 \raisebox{-\SB@Height}{\rule{\SB@Thick}{2\SB@Height}}%
393 % \end{macrocode}
394 %
395 %
396 % \subsection{Typesetting the scalebar numbers}
397 %
398 % Typesetting of the text underneath the scalebar requires three
399 % pieces of information; the number at which the text will start,
400 % the number at which it will end and what units the text represents.
401 % The numbering does not have to start at zero.
402 %
403 % Some scalebars will consist of integers only as in the text below.\\
404 % 0\hspace{1.5cm}2\hspace{1.5cm}4\hspace{1.5cm}6\hspace{1.5cm}8\hspace{1.5cm}10\,km
405 %
406 % Other scalebars will have decimals. Althought usually scalebars only show
407 % one decimal place at most. \\
408 % -0.5\hspace{1.5cm}0\hspace{1.5cm}1.5\hspace{1.5cm}2.0\hspace{1.5cm}2.5\,cm
409 %
410 %
411 % We now use macros provided by the fp.sty (fixed point)
412 % package to perform some simple arithmetic and rounding.
413 %
414 % Calculate how much we will increment the numbers by subtracting
415 % the starting and ending numbers (|SB@StartNo| and |SB@EndNo|) then dividing their difference by the
416 % number of major divisions.
417 %
418 % \begin{macrocode}
419 \FPupn\SBIncrement%
420 {\the\value{SB@majordivs} \SB@StartNo{} \SB@EndNo{} - /}%
421 % \end{macrocode}
422 %
423 %
424 % Now we need to work out how many decimal places to display for the numbers.
425 %
426 % Start off with rounding set to none. If the calculated increment
427 % is an integer then don't do anything, otherwise set rounding on and
428 % round the increment to one decimal place. This would suffice for many
429 % variations of starting and ending number, however if the user entered
430 % -0.5 to 2.5 for these values respectively then the increment (3.0) would be
431 % an integer and the rounding would be set to zero. In theses cases though
432 % the starting and ending numbers must be non-integer thus by testing all three
433 % numbers we can cover all cases.
434 %
435 % \begin{macrocode}
436 \def\SBRound{0}%
437 \FPifint\SBIncrement%
438 \else\def\SBRound{1}\FPupn\SBIncrement{\SBIncrement{} 1 round}\fi%
439 \FPifint\SB@StartNo%
440 \else\def\SBRound{1}\FPupn\SB@StartNo{\SB@StartNo{} 1 round}\fi%
441 \FPifint\SB@EndNo%
442 \else\def\SBRound{1}\FPupn\SB@EndNo{\SB@EndNo{} 1 round}\fi%
443 % \end{macrocode}
444 %
445 %
446 % Now remember that we are at the end of the scalebar so to print the
447 % text underneath we have to move back to the left and down.
448 % Move left by a distance equal to the scalebar length (|\SB@Length|)
449 % plus a little bit more to take into account the thickness of the thin
450 % line at the start and end of the scalebar (|\SB@Thick|).
451 % Then move down by enough to place the
452 % text at a nice distance below the scalebar. Remember that the distance
453 % |\SB@Height| depends on the current font in a fixed ratio set earlier.
454 %
455 % \begin{macrocode}
456 \hspace{-\SB@Length}\hspace{-\SB@Thick}%
457 \raisebox{-3\SB@Height}{%
458 % \end{macrocode}
459 %
460 % Now we are ready to print the numbers.
461 % The length |\SB@TextWidth| contains the
462 % width of the text that we are about to put to page.
463 % We need to calculate this so that we can fine position the center of
464 % the text to be exactly under the start of each major division.
465 % Note how we use the value of |\SBRound| to set the number of
466 % decimal places in the text we typeset.
467 %
468 % \begin{macrocode}
469 \FPset\SBNextNo\SB@StartNo%
470 \setcounter{SB@countup}{0}%
471 \whiledo{\not\theSB@countup>\theSB@majordivs}{%
472 \FPupn\SBNextNo{\SBNextNo{} \SBRound{} round}%
473 \settowidth{\SB@TextWidth}{\SBNextNo}%
474 \hspace{-0.5\SB@TextWidth}%
475 \SBNextNo\hspace{-0.5\SB@TextWidth}\hspace{\SB@MajorWidth}%
476 \FPupn\SBNextNo{\SBNextNo{} \SBIncrement{} add}%
477 \addtocounter{SB@countup}{1}}%
478 % \end{macrocode}
479 %
480 % Now all the numbers are on the page we are nearly ready to append
481 % the scalebars units to the end. First though we have to move back
482 % by the distance |\SB@MajorWidth| as the last while loop added
483 % this unwanted space, then forward half of the width of the last
484 % number printed.
485 % Finally add a thin space and the units and finish the scalebar
486 % command with its closing brace.
487 %
488 % \begin{macrocode}
489 \hspace{-\SB@MajorWidth}\hspace{0.5\SB@TextWidth}\,\SB@TextUnits}%
490 }%
491 % \end{macrocode}
492 % \end{macro}
493 %
494 % That's the end of the macro.
495 %
496 % \section*{License}\label{sec:license}
497 % This program may be distributed and/or modified under the
498 % conditions of the \LaTeX\ Project Public License, either version 1.2
499 % of this license or (at your option) any later version.
500 % The latest version of this license is in
501 %
502 % \hspace{2em}http://www.latex-project.org/lppl.txt
503 %
504 % and version 1.2 or later is part of all distributions of \LaTeX \
505 % version 1999/12/01 or later.
506 %
507 % This program consists of the files \textsf{scalebar.dtx} and
508 % \textsf{scalebar.ins}
509 %
510 %
511 % \section*{Acknowledgements}
512 %
513 % Thanks to the people on the \textsf{comp.text.tex} newsgroup for their
514 % help to me in developing this package.
515 %
516 %
517 % \Finale{\vspace{\baselineskip}\hfill\rule{3in}{0.1pt}\hfill}
518 \endinput