diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /info/beginlatex/html/chapter9.html |
Initial commit
Diffstat (limited to 'info/beginlatex/html/chapter9.html')
-rw-r--r-- | info/beginlatex/html/chapter9.html | 692 |
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 — 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 — 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. ¶ 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 — as well as other online + documents — 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. ¶ 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. ¶ 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 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 © 1999–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> </p> + <h1>Programmability (macros)</h1> + </td> + <td class="toc"> + <p> </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 — rather a big collection — 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>) the name you want to give the new command; and <i>b</i>) 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 + ‘letter’ 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>™ typeset, and if + you look in the index, you'll find this page referenced + under ‘<span style="font-style:italic; ">Velcro</span>’. 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 ‘Font changes’ 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 + ‘<code class="literal">Don</code> and + <code class="literal">Knuth</code>’ 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 + ‘Lamport, Leslie’ with virtually no effort + on the author's part at all. + </p> + <blockquote class="exercise"> + <hr> + <h4><img src="kwrite.png" align="middle"> <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è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 + ‘captures’ 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 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 + ‘public’ 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 ‘private’ 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 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 + ‘dingbats’ 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 + ‘lower’: 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 ¼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 |