summaryrefslogtreecommitdiff
path: root/info/beginlatex/html/chapter9.html
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /info/beginlatex/html/chapter9.html
Initial commit
Diffstat (limited to 'info/beginlatex/html/chapter9.html')
-rw-r--r--info/beginlatex/html/chapter9.html692
1 files changed, 692 insertions, 0 deletions
diff --git a/info/beginlatex/html/chapter9.html b/info/beginlatex/html/chapter9.html
new file mode 100644
index 0000000000..537a26a7fc
--- /dev/null
+++ b/info/beginlatex/html/chapter9.html
@@ -0,0 +1,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> \ No newline at end of file