summaryrefslogtreecommitdiff
path: root/info/beginlatex/html/chapter9.html
blob: 537a26a7fcd639441be55233dd962a8fba30f4ee (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
<!DOCTYPE html
  PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "/dtds/html4t.dtd">

<!--Generated from beginlatex.XML.xml with typebook-html.xslt on 2005-04-04T01:02:47--><html>
   <head>
      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   
      <title>Formatting information: Chapter 9&nbsp;&#8212; Programmability (macros)</title>
      <link rel="stylesheet" href="typebook.css" type="text/css">
      <meta http-equiv="Content-Style-Type" content="text/css">
   </head>
   <body>
      <table width="100%">
         <tr>
            <th class="title" width="66%">
               <h1><a name="doctitle">Formatting information</a></h1>
               <h2>A beginner's introduction to typesetting with
                  <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span></h2>
               <h3>Chapter 9&nbsp;&#8212; Programmability (macros)</h3>
               <h3>Peter Flynn</h3>
               <h4>Silmaril Consultants<br>Textual Therapy Division
               </h4><br>v. 3.6 (March 2005)
            </th>
            <td class="toc" width="33%">
               <h4><a name="doctoc">Contents</a></h4>
               <dl>
                  <dd class=""><a href="intro.html#intro">Introduction</a></dd>
                  <dd class=""><a href="foreword.html#foreword">Foreword</a></dd>
                  <dd class=""><a href="preface.html#preface">Preface</a></dd>
               </dl>
               <ol>
                  <li class=""><a href="chapter1.html#get">Installing <span class="TEX">T<span class="E">E</span>X</span> and <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span></a></li>
                  <li class=""><a href="chapter2.html#plaintext">Using your editor to create documents</a></li>
                  <li class=""><a href="chapter3.html#basic">Basic document structures</a></li>
                  <li class=""><a href="chapter4.html#process">Typesetting, viewing and printing</a></li>
                  <li class=""><a href="chapter5.html#ctan">CTAN, packages, and online help</a></li>
                  <li class=""><a href="chapter6.html#otherdoc">Other document structures</a></li>
                  <li class=""><a href="chapter7.html#texttools">Textual tools</a></li>
                  <li class=""><a href="chapter8.html#typo">Fonts and layouts</a></li>
                  <li class="current"><a href="chapter9.html#macros">Programmability (macros)</a></li>
                  <li class=""><a href="chapter10.html#compat">Compatibility with other systems</a></li>
               </ol>
               <ol type="A">
                  <li class=""><a href="appendixA.html#cnf">Configuring <span class="TEX">T<span class="E">E</span>X</span> search paths</a></li>
                  <li class=""><a href="appendixB.html#tugform"><span class="TEX">T<span class="E">E</span>X</span> Users Group membership</a></li>
                  <li class=""><a href="appendixC.html#asciicharset">The ASCII character set</a></li>
                  <li class=""><a href="appendixD.html#gfdl">GNU Free Documentation License</a></li>
               </ol>
               <dl>
                  <dd class=""><a href="bibliography.html#biblio">References</a></dd>
                  <dd class=""><a href="index.html#index">Index</a></dd>
               </dl>
            </td>
         </tr>
         <tr>
            <td class="credits">
               <p>This edition of <cite>Formatting
                     	  Information</cite> was prompted by the generous help I
                  	have received from <span class="TEX">T<span class="E">E</span>X</span> users too numerous to mention
                  	individually. Shortly after TUGboat published the November
                  	2003 edition, I was reminded by a spate of email of the
                  	fragility of documentation for a system like <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> which is
                  	constantly under development. There have been revisions to
                  	packages; issues of new distributions, new tools, and new
                  	interfaces; new books and other new documents; corrections to
                  	my own errors; suggestions for rewording; and in one or two
                  	cases mild abuse for having omitted package X which the author
                  	felt to be indispensable to users. &para;&nbsp;I am grateful as always to the people who sent me
                  	corrections and suggestions for improvement. Please keep them
                  	coming: only this way can this book reflect what people
                  	want to learn. The same limitation still applies, however: no
                  	mathematics, as there are already a dozen or more excellent
                  	books on the market&nbsp;&#8212; as well as other online
                  	documents&nbsp;&#8212; dealing with mathematical typesetting in
                  <span class="TEX">T<span class="E">E</span>X</span> and <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> in finer and better detail than I am
                  	capable of. &para;&nbsp;The structure remains the same, but I have revised and
                  	rephrased a lot of material, especially in the earlier
                  	chapters where a new user cannot be expected yet to have
                  	acquired any depth of knowledge. Many of the screenshots have
                  	been updated, and most of the examples and code fragments have
                  	been retested. &para;&nbsp;As I was finishing this edition, I was asked to review
                  	an article for <cite><a href="http://www.tug.org/pracjourn/" name="C3">The Prac<span class="TEX">T<span class="E">E</span>X</span> Journal</a></cite>, which
                  	grew out of the Practical <span class="TEX">T<span class="E">E</span>X</span> Conference in 2004. The
                  	author specifically took the writers of documentation to task
                  	for failing to explain things more clearly, and as I read
                  	more, I found myself agreeing, and resolving to clear up some
                  	specific problems areas as far as possible. It is very
                  	difficult for people who write technical documentation to
                  	remember how they struggled to learn what has now become a
                  	familiar system. So much of what we do is second nature, and a
                  	lot of it actually has nothing to do with the software, but
                  	more with the way in which we view and approach information,
                  	and the general level of knowledge of computing. If I have
                  	obscured something by making unreasonable assumptions about
                  	<em>your</em> knowledge, please let me know so
                  	that I can correct&nbsp;it. 
                  <p>Peter Flynn is author of <cite><a href="bibliography.html#htmlbook" name="C4">The HTML Handbook</a></cite> and <cite><a href="bibliography.html#sgmltools" name="C5">Understanding SGML and XML Tools</a></cite>, and editor of <cite><a href="http://www.ucc.ie/xml/" name="C6">The XML FAQ</a></cite>.
                  </p>
               </p>
            </td>
            <td class="legal">
               <p>
                  <p>This document is Copyright &copy; 1999&#8211;2005 by
                     Silmaril Consultants under the terms of what is now the GNU
                     Free Documentation License (copyleft).
                  </p>
                  <p>Permission is granted to copy, distribute and/or modify
                     this document under the terms of the GNU Free Documentation
                     License, Version 1.2 or any later version published by the
                     Free Software Foundation; with no Invariant Sections, no
                     Front-Cover Texts, and no Back-Cover Texts. A copy of the
                     license is included in the section entitled <cite><a href="http://www.fsf.org/copyleft/fdl.html" name="C1">The GNU Free Documentation License</a></cite>.
                  </p>
                  <p>You are allowed to distribute, reproduce, and modify it
                     without fee or further requirement for consent subject to the
                     conditions in <a href="appendixD.html#gfdl-4">section D.5</a>. The author has
                     asserted his right to be identified as the author of this
                     document. If you make useful modifications you are asked to
                     inform the author so that the master copy can be updated. See
                     the full text of the License in <a href="appendixD.html#gfdl">Appendix D</a>.
                     
                  </p>
               </p>
            </td>
         </tr>
      </table>
      <div class="chapter">
         <table width="100%">
            <tr>
               <td align="center"><small><i class="chaphead"><b><a name="macros">CHAPTER</a></b></i></small><br><table border="1">
                     <tr>
                        <td class="chapno">9</td>
                     </tr>
                  </table>
               </td>
               <td><pre class="spacing"></pre></td>
               <td>
                  <p>&nbsp;</p>
                  <h1>Programmability (macros)</h1>
               </td>
               <td class="toc">
                  <p>&nbsp;</p>
                  <ol>
                     <li><a href="#replacement">Simple replacement macros</a></li>
                     <li><a href="#macinf">Macros using information gathered previously</a></li>
                     <li><a href="#macargs">Macros with arguments</a></li>
                     <li><a href="#macnest">Nested macros</a></li>
                     <li><a href="#macenv">Macros and environments</a></li>
                     <li><a href="#reprog">Reprogramming <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>'s internals</a></li>
                  </ol>
               </td>
               <td align="right"><a href="#doctoc"><img src="top.png" title="Table of Contents" width="32" alt="ToC" align="right" border="0"></a></td>
            </tr>
         </table><a name="I158"></a><p>We've touched several times on the ability of <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>
            to be reprogrammed. This is one of its central features, and one
            that still, after nearly a quarter of a century, puts it well
            above many other typesetting systems, even those with macro
            systems of their own. It's also the one that needs most
            foreknowledge, which is why this chapter is in this
            position.
         </p>
         <p><span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> is in fact itself just a collection of
            macros&nbsp;&#8212; rather a big collection&nbsp;&#8212; written in
            <span class="TEX">T<span class="E">E</span>X</span>'s internal typesetting language. These <b><i><a name="macs">macros</a></i></b> are little program-like sets of
            instructions with a name which can be used as shorthand for an
            operation you wish to perform more than once.
         </p>
         <p>Macros can be arbitrarily complex. Many of the ones used in
            the standard <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> packages are several pages long, but as we
            will see, even short ones can very simply automate otherwise
            tedious chores and allow the author to concentrate on
            <em>writing</em>.
         </p>
         <div class="sect1">
            <h2><a href="#macros"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>9.1 <a name="replacement">Simple replacement macros</a></h2>
            <p>In its simplest form, a <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> macro can just be a
               straightforward text replacement of a phrase to avoid
               misspelling something each time you need it, e.g.
            </p>
            <blockquote><pre>
\newcommand{\ef}{European Foundation for the 
    Improvement of Living and Working Conditions}
      </pre></blockquote>
            <p>Put this in your preamble, and you can then use
               <code class="command"><a name="c265">\ef</a></code> in your document and it will typeset it
               as the full text. Remember that after a command ending in a
               letter you need to leave a space to avoid the next word
               getting gobbled up as part of the command (see
               <a href="chapter2.html#swallow">the first paragraph  in section 2.4.1</a>). And when you want to force a space
               to be printed, use a backslash followed by a space,
               e.g.
            </p>
            <blockquote><pre>
The \ef\ is an institution of the Commission of the 
 European Union.
      </pre></blockquote>
            <p>As you can see from this example, the
               <code class="command"><a name="c266">\newcommand</a></code> command takes two arguments:
                <i>a</i>)&nbsp;the name you want to give the new command;  and <i>b</i>)&nbsp;the expansion to be performed when you use it, so there are always two sets of curly braces
               after <code class="command"><a name="c267">\newcommand</a></code>.
            </p>
         </div>
         <div class="sect1">
            <h2><a href="#macros"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>9.2 <a name="macinf">Macros using information gathered previously</a></h2>
            <p>A more complex example is the macro
               <code class="command"><a name="c268">\maketitle</a></code> which is used in almost every
               formal document to format the title block. In the basic
               document classes (book, report, and article) it performs small
               variations on the layout of a centred block with the title
               followed by the author followed by the date, as we saw in
               <a href="chapter3.html#titling">section 3.3</a>.
            </p>
            <p>If you inspect one of these document class files, such as
               <code>texmf/tex/latex/base/report.cls</code> you will
               see <code class="command"><a name="c269">\maketitle</a></code> defined (and several variants
               called <code class="command"><a name="c270">\@maketitle</a></code> for use in different
               circumstances). It uses the values for the title, author, and
               date which are assumed already to have been stored in the
               internal macros <code class="command"><a name="c271">\@title</a></code>,
               <code class="command"><a name="c272">\@author</a></code>, and <code class="command"><a name="c273">\@date</a></code> by
               the author using the matching <code class="command"><a name="c274">\title</a></code>,
               <code class="command"><a name="c275">\author</a></code>, and <code class="command"><a name="c276">\date</a></code>
               commands in the document.
            </p>
            <p>This use of one command to store the information in
               another is a common way of gathering the information from the
               user. The use of macros containing the
               <code class="literal">@</code> character prevents their accidental
               misuse by the user: in fact to use them in your preamble we
               have to allow the <code class="literal">@</code> sign to become a
               &#8216;letter&#8217; so it can be recognised in a
               command name, and remember to turn it off again afterwards
               (see <a href="chapter9.html#makeat">item 1</a> below).
            </p>
            <blockquote><pre>
\makeatletter
\renewcommand{\maketitle}{%
   \begin{flushleft}%
      \sffamily
      {\Large\bfseries\color{red}\@title\par}%
      \medskip
      {\large\color{blue}\@author\par}%
      \medskip
      {\itshape\color{green}\@date\par}%
      \bigskip\hrule\vspace*{2pc}%
   \end{flushleft}%
}
\makeatother
      </pre></blockquote>
            <p>Insert this in the sample file on <a href="chapter5.html#oldtitle"></a> immediately before the
               <code class="literal">\begin{document}</code> and remove the
               <code class="literal">\color{...}</code> commands from the title,
               author, and date. Re-run the file through <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>, and you
               should get something like this:
            </p>
            <div align="center" style="margin:1cm"><img src="newtitle.png" width="75%"></div>
            <p>In this redefinition of <code class="command"><a name="c277">\maketitle</a></code>,
               we've done the following:
            </p>
            <ol type="1">
               <li>
                  <p><a name="makeat"></a>Enclosed the changes in
                     <code class="command"><a name="c278">\makeatletter</a></code> and
                     <code class="command"><a name="c279">\makeatother</a></code> to allow us to use the
                     <code class="literal">@</code> sign in command names;<sup><a href="#F51">1</a></sup></p>
               </li>
               <li>
                  <p>Used <code class="command"><a name="c280">\renewcommand</a></code> and put
                     <code class="command"><a name="c281">\maketitle</a></code> in curly braces after
                     it;
                  </p>
               </li>
               <li>
                  <p>Opened a pair of curly braces to hold the new
                     definition. The closing curly brace is immediately before
                     the <code class="command"><a name="c282">\makeatother</a></code>;
                  </p>
               </li>
               <li>
                  <p>Inserted a <span class="environment"><a name="e51">flushleft</a></span> environment
                     so the whole title block is left-aligned;
                  </p>
               </li>
               <li>
                  <p>Used <code class="command"><a name="c283">\sffamily</a></code> so the whole title
                     block is in the defined sans-serif typeface;
                  </p>
               </li>
               <li>
                  <p>For each of <code class="command"><a name="c284">\@title</a></code>,
                     <code class="command"><a name="c285">\@author</a></code>, and <code class="command"><a name="c286">\@date</a></code>,
                     we have used some font variation and colour, and enclosed
                     each one in curly braces to restrict the changes just to
                     each command. The closing <code class="command"><a name="c287">\par</a></code> makes
                     sure that multiline title and authors and dates get
                     typeset with the relevant line-spacing;
                  </p>
               </li>
               <li>
                  <p>Added some flexible space between the lines, and
                     around the <code class="command"><a name="c288">\hrule</a></code> (horizontal rule) at
                     the end;
                  </p>
               </li>
            </ol>
            <p>Note the <code class="literal">%</code> signs after any line ending
               in a curly brace, to make sure no intrusive white-space find
               its way into the output. These aren't needed after simple
               commands where there is no curly brace because excess
               white-space gets gobbled up there anyway.
            </p>
            <ol class="footnotes" start="1">
               <li><a name="F51">If you move all this preamble into a style file of
                     your own, you don't need these commands: the use
                     of <code class="literal">@</code> signs in command names is
                     allowed in style and class files.</a></li>
            </ol>
         </div>
         <div class="sect1">
            <h2><a href="#macros"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>9.3 <a name="macargs">Macros with arguments</a></h2>
            <p>But macros are not limited to text expansion. They can
               take arguments of their own, so you can define a command to do
               something with specific text you give it. This makes them much
               more powerful and generic, as you can write a macro to do
               something a certain way, and then use it hundreds of times
               with a different value each time.
            </p>
            <p>We looked earlier (<a href="chapter8.html#emph">the text in section 8.2.5</a>) at making new
               commands to put specific classes of words into certain fonts,
               such as product names into italics, keywords into bold, and so
               on. Here's an example for a command
               <code class="command"><a name="c289">\product</a></code>, which also indexes the product
               name and adds a trademark sign:
            </p>
            <blockquote><pre>
\newcommand{\product}[1]{%
        \textit{#1}\texttrademark%
        \index{#1@\textit{#1}}%
}
      </pre></blockquote>
            <p>If I now type <code class="literal">\tmproduct{Velcro}</code> then I
               get <i><a name="p226">Velcro</a></i>&#8482; typeset, and if
               you look in the index, you'll find this page referenced
               under &#8216;<span style="font-style:italic; ">Velcro</span>&#8217;. Let's
               examine what this does:
            </p>
            <ol type="1">
               <li>
                  <p>The macro is specified as having one argument
                     (that's the <code class="literal">[1]</code> in the
                     definition). This will
                     be the product name you type in curly braces when you use
                     <code class="command"><a name="c290">\product</a></code>. Macros can have up to nine
                     arguments.
                  </p>
               </li>
               <li>
                  <p>The expansion of the macro is contained in the second
                     set of curly braces, spread over several lines (see <a href="chapter9.html#macrolines">item 5</a> for why).
                  </p>
               </li>
               <li>
                  <p>It prints the value of the first argument (that's
                     the <code class="literal">#1</code>) in italics, which is
                     conventional for product names, and adds the
                     <code class="command"><a name="c291">\texttrademark</a></code> command.
                  </p>
               </li>
               <li>
                  <p>Finally, it creates an index entry using the same
                     value (<code class="literal">#1</code>), making sure that it's
                     italicised in the index (see <a href="chapter7.html#indextypo">the item &#8216;Font changes&#8217; in section 7.5</a> to remind yourself of how indexing
                     something in a different font works).
                  </p>
               </li>
               <li>
                  <p><a name="macrolines"></a>Typing this macro over several lines makes it easier
                     for humans to read. I could just as easily have
                     typed
                  </p>
                  <blockquote><pre class="footnotesize">
\newcommand{\product}[1]{\textit{#1}\index{#1@\textit{#1}}}
          </pre></blockquote>
                  <p><a name="macrolines"></a>but it wouldn't have been as clear what I was
                     doing.
                  </p>
                  <p><a name="macrolines"></a>One thing to notice is that to prevent unwanted spaces
                     creeping into the output when <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> reads the macro, I
                     ended each line with a comment character
                     (<code>%</code>). <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> normally treats
                     newlines as spaces when formatting (remember <a href="chapter2.html#comment">the first paragraph  in section 2.5.1</a>), so this stops the end of line
                     being turned into an unwanted space when the macro is
                     used. <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> always ignores spaces at the
                     <em>start</em> of macro lines anyway, so
                     indenting lines for readability is fine.
                  </p>
               </li>
            </ol>
            <p>In <a href="chapter2.html#hyph" title="sect2"></a> we mentioned the problem
               of frequent use of unbreakable text leading to poor
               justification or to hyphenation problems. A solution is to
               make a macro which puts the argument into an
               <code class="command"><a name="c292">\mbox</a></code> with the appropriate font change, but
               precedes it all with a conditional
               <code class="command"><a name="c293">\linebreak</a></code> which will make it more
               attractive to <span class="TEX">T<span class="E">E</span>X</span> to start a new line.
            </p>
            <blockquote><pre>
\newcommand{\var}[1]{\linebreak[3]\mbox{\ttfamily#1}}
      </pre></blockquote>
            <p>This only works effectively if you have a reasonably wide
               setting and paragraphs long enough for the differences in
               spacing elsewhere to get hidden. If you have to do this in
               narrow journal columns, you may have to adjust wording and
               spacing by hand occasionally.
            </p>
         </div>
         <div class="sect1">
            <h2><a href="#macros"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>9.4 <a name="macnest">Nested macros</a></h2>
            <p>Here's a slightly more complex example, where one
               macro calls another. It's common in normal text to refer
               to people by their forename and surname (in that order), for
               example <a name="N23">Don  Knuth</a>, but to have them indexed as <em>surname,
                  forename</em>. This pair of macros,
               <code class="command"><a name="c294">\person</a></code> and <code class="command"><a name="c295">\reindex</a></code>,
               automates that process to minimize typing and indexing.
            </p>
            <blockquote><pre>
\newcommand{\person}[1]{#1\reindex #1\sentinel}
\def\reindex #1 #2\sentinel{\index{#2, #1}}
      </pre></blockquote>
            <ol type="1">
               <li>
                  <p>The digit 1 in square brackets means that
                     <code class="command"><a name="c296">\person</a></code> has one argument, so you put the
                     whole name in a single set of curly braces, e.g.
                     <code class="literal">\person{Don Knuth}</code>.
                  </p>
               </li>
               <li>
                  <p>The first thing the macro does is output
                     <code class="literal">#1</code>, which is the value of what you typed,
                     just as it stands, so the whole name gets typeset exactly
                     as you typed it.
                  </p>
               </li>
               <li>
                  <p>But then it uses a special feature of Plain <span class="TEX">T<span class="E">E</span>X</span>
                     macros (which use <code class="command"><a name="c297">\def</a></code> instead of
                     <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>'s <code class="command"><a name="c298">\newcommand</a></code><sup><a href="#F52">2</a></sup>): they too can have multiple arguments but you
                     can separate them with other characters (here a space) to
                     form a pattern which <span class="TEX">T<span class="E">E</span>X</span> will recognise when reading the
                     arguments.
                  </p>
                  <p>In this example (<code class="command"><a name="c301">\reindex</a></code>) it's
                     expecting to see a string of characters
                     (<code class="literal">#1</code>) followed by a space, followed by
                     another string of characters (<code class="literal">#2</code>)
                     followed by a dummy command (<code class="command"><a name="c302">\sentinel</a></code>).
                     In effect this makes it a device for splitting a name into
                     two halves on the space between them, so the two halves
                     can be handled separately. The <code class="command"><a name="c303">\reindex</a></code>
                     command can now read the two halves of the name
                     separately.
                  </p>
               </li>
               <li>
                  <p>The <code class="command"><a name="c304">\person</a></code> command invokes
                     <code class="command"><a name="c305">\reindex</a></code> and follows it with the name
                     you typed plus the dummy command
                     <code class="command"><a name="c306">\sentinel</a></code> (which is just there to signal
                     the end of the name). Because <code class="command"><a name="c307">\reindex</a></code>
                     is expecting two arguments separated by a space and
                     terminated by a <code class="command"><a name="c308">\sentinel</a></code>, it sees
                     &#8216;<code class="literal">Don</code> and
                     <code class="literal">Knuth</code>&#8217; as two separate
                     arguments.
                  </p>
                  <p>It can therefore output them using
                     <code class="command"><a name="c309">\index</a></code> in reverse order, which is
                     exactly what we want.
                  </p>
               </li>
            </ol>
            <p>A book or report with a large number of personal names to
               print and index could make significant use of this to allow
               them to be typed as
               <code class="literal">\person{Leslie Lamport}</code> and printed as
               <a name="ll">Leslie Lamport</a>, but have them indexed as
               &#8216;Lamport,&nbsp;Leslie&#8217; with virtually no effort
               on the author's part at all.
            </p>
            <blockquote class="exercise">
               <hr>
               <h4><img src="kwrite.png" align="middle"> &nbsp; <i>Exercise 20</i>. Other names
               </h4>
               <p>Try to work out how to make this
                  <code class="command"><a name="c310">\person</a></code> feature work with names
                  like:
               </p>
               <dl>
                  <dd>Blanca Maria Bartosova de Paul</dd>
                  <dd>Patricia Maria Soria de Miguel</dd>
                  <dd>Arnaud de la Vill&egrave;sbrunne</dd>
                  <dd>Prince</dd>
                  <dd>Pope John Paul II</dd>
               </dl>
               <p>Hints: the command <code class="command"><a name="c311">\space</a></code> produces a
                  normal space, and one way around <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>'s requirements
                  on spaces after command names ending with a letter is to
                  follow such commands with an empty set of curly braces
                  <code class="literal">{}</code>.
               </p>
               <hr>
            </blockquote>
            <ol class="footnotes" start="2">
               <li><a name="F52">Don't try this at home alone, children! This
                     one is safe enough, but you should strictly avoid
                     <code class="command"><a name="c299">\def</a></code> for a couple of years. Stick to
                     <code class="command"><a name="c300">\newcommand</a></code> for now.</a></li>
            </ol>
         </div>
         <div class="sect1">
            <h2><a href="#macros"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>9.5 <a name="macenv">Macros and environments</a></h2>
            <p>As mentioned in <a href="chapter6.html#fancybox">section 6.7.3</a>, it is possible
               to define macros to capture text in an environment and reuse
               it afterwards. This avoids any features of the subsequent use
               affecting the formatting of the text.
            </p>
            <p>One example of this uses the facilities of the
               <span class="package"><a name="m88">fancybox</a></span> package, which defines a
               variety of framed boxes to highlight your text, and a special
               environment <span class="environment"><a name="e52">Sbox</a></span> which
               &#8216;captures&#8217; your text for use in these
               boxes.
            </p>
            <blockquote class="example"><pre>
\begin{Sbox}
\begin{minipage}{3in}
This text is formatted to the specifications 
of the minipage environment in which it 
occurs.

Having been typeset, it is held in the Sbox 
until it is needed, which is after the end 
of the minipage, where you can (for example) 
align it and put it in a special framed box.
\end{minipage}
\end{Sbox}
\begin{flushright}
\shadowbox{\theSbox}
\end{flushright}
        </pre><div align="center" class="sidebar">
                  <table width="75%">
                     <tr>
                        <td align="left" class="sidebar">
                           <p>This text is formatted to the specifications of the
                              minipage environment in which it occurs.
                           </p>
                           <p>Having been typeset, it is held in the Sbox until it
                              is needed, which is after the end of the minipage, where
                              you can (for example) centre it and put it in a special
                              framed box.
                           </p>
                        </td>
                     </tr>
                  </table>
               </div>
            </blockquote>
            <p>By putting the text (here in a
               <span class="environment"><a name="e53">minipage</a></span> environment because we want to
               change the width) inside the <span class="environment"><a name="e54">Sbox</a></span>
               environment, it is typeset into memory and stored in the macro
               <code class="command"><a name="c312">\theSbox</a></code>. It can then be used afterwards as
               the argument of the <code class="command"><a name="c313">\shadowbox</a></code> command (and
               in this example it has also been centred).
            </p>
         </div>
         <div class="sect1">
            <h2><a href="#macros"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>9.6 <a name="reprog">Reprogramming <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>'s internals</a></h2>
            <p><span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>'s internal macros can also be reprogrammed or
               even rewritten entirely, although doing this can require a
               considerable degree of expertise. Simple changes, however, are
               easily done.
            </p>
            <p>Recall that <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>'s default document structure for
               the Report document class uses Chapters as the main unit of
               text, whereas in reality most reports are divided into
               Sections, not Chapters (<a href="chapter3.html#repchap">footnote 24 in section 3.5</a>). The result
               of this is that if you start off your report with
               <code class="literal">\section{Introduction}</code>, it will print
               as
            </p>
            <p><span style="font-size:big; font-weight:bold; ">0.1&nbsp;&nbsp;Introduction</span></p>
            <p>which is not at all what you want. The zero is
               caused by it not being part of any chapter. But this numbering
               is controlled by macros, and you can redefine them. In this
               case it's a macro called <code class="literal">\thesection</code>
               which reproduces the current section number counter (see <a href="chapter6.html#thecounter">the last paragraph  in section 6.2.6</a>). It's redefined afresh in each
               document class file, using the command
               <code class="command"><a name="c314">\renewcommand</a></code> (in this case in
               <code>texmf/tex/latex/base/report.cls</code>):
            </p>
            <blockquote><pre>
\renewcommand \thesection 
   {\thechapter.\@arabic\c@section}
      </pre></blockquote>
            <p>You can see it invokes <code class="command"><a name="c315">\thechapter</a></code>
               (which is defined elsewhere to reproduce the value of the
               <tt><i><a name="l36">chapter</a></i></tt> counter), and it
               then prints a dot, followed by the Arabic value of the counter
               called <tt><i><a name="l37">section</a></i></tt> (that
               <code class="literal">\c@</code> notation is <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>'s internal way
               of referring to counters). You can redefine this in your
               preamble to simply leave out the reference to chapters:
            </p>
            <blockquote><pre>
\renewcommand{\thesection}{\arabic{section}}
      </pre></blockquote>
            <p>I've used the more formal method of enclosing the
               command being redefined in curly braces. For largely
               irrelevant historical reasons these braces are often omitted
               in <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>'s internal code (as you may have noticed in
               the example earlier). And I've also used the
               &#8216;public&#8217; macro
               <code class="command"><a name="c316">\arabic</a></code> to output the value of <tt><i><a name="l38">section</a></i></tt> (<span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>'s internals
               use a &#8216;private&#8217; set of control
               sequences containing <code class="literal">@</code>-signs, designed to
               protect
               them against being changed accidentally).
            </p>
            <p>Now the introduction to your report will start
               with:
            </p>
            <p><span style="font-size:big; font-weight:bold; ">1&nbsp;&nbsp;Introduction</span></p>
            <p>What's important is that you <em>don't
                  ever</em> need to alter the original document class
               file <code>report.cls</code>: you just copy the
               command you need to change into your own document preamble,
               and modify that instead. It will then override the
               default.
            </p>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>9.6.1 <a name="bullets">Changing list item bullets</a></h3>
               <p>As mentioned <a href="chapter6.html#labelitem" title="itemizedlist">earlier</a>,
                  here's how to redefine a bullet for an itemized list,
                  with a slight tweak:
               </p>
               <blockquote><pre>
\usepackage{bbding}
\renewcommand{\labelitemi}{%
        \raisebox{-.25ex}{\PencilRight}}
        </pre></blockquote>
               <p>Here we use the <span class="package"><a name="m89">bbding</a></span> package
                  which has a large selection of
                  &#8216;dingbats&#8217; or little icons, and we
                  make the label for top-level itemized lists print a
                  right-pointing pencil (the names for the icons are in the
                  package documentation: see <a href="chapter5.html#packagedoc">section 5.1.2</a> for
                  how to get it).
               </p>
               <p>In this case, we are using the
                  <code class="command"><a name="c317">\raisebox</a></code> command within the redefinition
                  because it turns out that the symbols in this font are
                  positioned slightly too high for the typeface we're
                  using. The <code class="command"><a name="c318">\raisebox</a></code> command takes two
                  arguments: the first is a dimension, how much to raise the
                  object by (and a negative value means
                  &#8216;lower&#8217;: there is no need for a
                  <code class="literal">\lowerbox</code> command); and the second is
                  the text you want to affect. Here, we are shifting the
                  symbol down by &frac14;ex (see <a href="chapter2.html#dimensions">section 2.8.1</a>
                  for a
                  list of dimensions <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> can use).
               </p>
               <p>There is a vast number of symbols available: see
                  <cite><a href="http://www.ctan.org/tex-archive/info/symbols/comprehensive/" name="C42">A comprehensive list of symbols in <span class="TEX">T<span class="E">E</span>X</span></a></cite> for a
                  comprehensive list.
               </p>
            </div>
         </div>
      </div>
      <hr>
      <table width="100%">
         <tr>
            <td align="left"><a href="chapter8.html"><img src="previous.png" alt="Previous" border="0"></a></td>
            <td align="center"><a href="#doctoc"><img src="top.png" alt="Top" border="0"></a></td>
            <td align="right"><a href="chapter10.html"><img src="next.png" alt="Next" border="0"></a></td>
         </tr>
      </table>
   </body>
</html>