[latexrefman-commits] [SCM] latexrefman updated: r635 - trunk
jimhefferon at gnu.org.ua
jimhefferon at gnu.org.ua
Thu May 31 18:43:51 CEST 2018
Author: jimhefferon
Date: 2018-05-31 19:43:51 +0300 (Thu, 31 May 2018)
New Revision: 635
Modified:
trunk/ChangeLog
trunk/latex2e.html
trunk/latex2e.info
trunk/latex2e.pdf
trunk/latex2e.texi
Log:
latex-info Lengths, including Definitions in current doc
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2018-05-31 16:05:41 UTC (rev 634)
+++ trunk/ChangeLog 2018-05-31 16:43:51 UTC (rev 635)
@@ -1,3 +1,12 @@
+2018-05-31 Jim Hefferon <jhefferon at smcvt.edu>
+
+ * latex2e.texi (Lengths) Next in latex-info is Lengths.
+ Adjust entries, adding examples and error messages.
+ (Definitions) \newlength adjusted, examples added. Make
+ synopses fit pattern elsewhere, including adding case of
+ no square brackets. Adjust wording of optargdefault in both
+ \newcommand and \newenvironment.
+
2018-05-30 Jim Hefferon <jhefferon at smcvt.edu>
* latex2e.texi (footnote) Next in latex-info is Footnotes.
Modified: trunk/latex2e.html
===================================================================
--- trunk/latex2e.html 2018-05-31 16:05:41 UTC (rev 634)
+++ trunk/latex2e.html 2018-05-31 16:43:51 UTC (rev 635)
@@ -8829,24 +8829,38 @@
<a name="index-defining-a-new-command"></a>
<a name="index-new-commands_002c-defining"></a>
-<p>Synopses:
+<p>Synopses, one of:
</p>
<div class="example">
-<pre class="example"> \newcommand{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>}
- \newcommand*{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>}
+<pre class="example">\newcommand{\<var>cmd</var>}{<var>defn</var>}
+\newcommand{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>}
+\newcommand{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>}
+\newcommand*{\<var>cmd</var>}{<var>defn</var>}
+\newcommand*{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>}
+\newcommand*{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>}
+</pre></div>
+
+<p>or one of:
+</p>
+<div class="example">
+<pre class="example">\renewcommand{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>}
+\renewcommand{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>}
\renewcommand{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>}
+\renewcommand*{\<var>cmd</var>}{<var>defn</var>}
+\renewcommand*{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>}
\renewcommand*{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>}
</pre></div>
<p>Define or redefine a command. See also the discussion of
<code>\DeclareRobustCommand</code> in <a href="#Class-and-package-commands">Class and package commands</a>.
-</p>
<a name="index-starred-form_002c-defining-new-commands"></a>
<a name="index-_002a_002dform_002c-defining-new-commands"></a>
-<p>The starred form of these two commands requires that the arguments not
-contain multiple paragraphs of text (not <code>\long</code>, in plain TeX
-terms).
+The starred form of these two requires that the arguments not contain
+multiple paragraphs of text (in plain TeX terms that it not be
+<code>\long</code>).
</p>
+<p>These are the parameters:
+</p>
<dl compact="compact">
<dt><var>cmd</var></dt>
<dd>
@@ -8858,9 +8872,9 @@
</dd>
<dt><var>nargs</var></dt>
<dd><p>Optional; an integer from 0 to 9, specifying the number of arguments
-that the command can take, including any optional argument. If this
-argument is not present, the default is for the command to have no
-arguments. When redefining a command, the new version can have a
+that the command can take, including any optional argument. Omitting
+this argument is the same as specifying 0, meaning that the command has
+no arguments. If you redefine a command, the new version can have a
different number of arguments than the old version.
</p>
</dd>
@@ -8871,38 +8885,38 @@
<code>\<var>cmd</var></code> does not take an optional argument.
</p>
<a name="index-positional-parameter"></a>
-<p>That is, if <code>\<var>cmd</var></code> is used with square brackets following,
-as in <code>\<var>cmd</var>[<var>myval</var>]</code>, then within <var>defn</var> the first
-<em>positional parameter</em> <code>#1</code> expands <var>myval</var>. On the
-other hand, if <code>\<var>cmd</var></code> is called without square brackets
-following, then within <var>defn</var> the positional parameter <code>#1</code>
-expands to the default <var>optargdefault</var>. In either case, any
-required arguments will be referred to starting with <code>#2</code>.
+<p>That is, if <code>\<var>cmd</var></code> is used with square brackets, as in
+<code>\<var>cmd</var>[<var>optval</var>]</code>, then within <var>defn</var> then <code>#1</code>
+is set to the value of <var>optval</var>. On the other hand, if
+<code>\<var>cmd</var></code> is called without the square brackets, then within
+<var>defn</var> the parameter <code>#1</code> is set to the value of
+<var>optargdefault</var>. In either case, the required arguments start with
+<code>#2</code>.
</p>
-<p>Omitting <code>[<var>myval</var>]</code> in a call is different from having the
-square brackets with no contents, as in <code>[]</code>. The former results
-in <code>#1</code> expanding to <var>optargdefault</var>; the latter results in
-<code>#1</code> expanding to the empty string.
+<p>Omitting <code>[<var>optargdefault</var>]</code> is different from having the
+square brackets with no contents, as in <code>[]</code>. The former sets
+<code>#1</code> to the value of <var>optargdefault</var>; the latter sets <code>#1</code>
+to the empty string.
</p>
</dd>
<dt><var>defn</var></dt>
-<dd><p>The text to be substituted for every occurrence of <code>\<var>cmd</var></code>; the
-positional parameter <code>#<var>n</var></code> in <var>defn</var> is replaced by
-the text of the <var>n</var>th argument.
+<dd><p>Required; the text to be substituted for every occurrence of
+<code>\<var>cmd</var></code>. The parameters <code>#1</code>, <code>#2</code>,
+... <code>#<var>nargs</var></code> are replaced by the values that you supply when
+you call the command (or by the default value if there is an optional
+argument and you don’t exercise the option).
</p>
</dd>
</dl>
<p>TeX ignores spaces in the source following an alphabetic control
sequence, as in ‘<samp>\cmd </samp>’. If you actually want a space there, one
-solution is to type <code>{}</code> after the command (‘<samp>\cmd{} </samp>’;
+solution is to type <code>{}</code> after the command (‘<samp>\cmd{} </samp>’, and
another solution is to use an explicit control space (‘<samp>\cmd\ </samp>’).
</p>
<p>A simple example of defining a new command:
-<code>\newcommand{\RS}{Robin Smith}</code> results in
-<code>\RS</code> being replaced by the longer text.
-</p>
-<p>Redefining an existing command is similar:
+<code>\newcommand{\RS}{Robin Smith}</code> results in <code>\RS</code> being
+replaced by the longer text. Redefining an existing command is similar:
<code>\renewcommand{\qedsymbol}{{\small QED}}</code>.
</p>
<p>If you try to define a command and the name has already been used then
@@ -8911,43 +8925,58 @@
to redefine a command and the name has not yet been used then you get
something like ‘<samp>LaTeX Error: \hank undefined</samp>’.
</p>
-<p>Here’s a command definition with one required argument:
+<p>Here the first command definition has no arguments, and the second has
+one required argument.
</p>
<div class="example">
-<pre class="example">\newcommand{\defref}[1]{Definition~\ref{#1}}
+<pre class="example">\newcommand{\student}{Ms~O'Leary}
+\newcommand{\defref}[1]{Definition~\ref{#1}}
</pre></div>
-<p>Then, <code>\defref{def:basis}</code> expands to
-<code>Definition~\ref{def:basis}</code>, which will ultimately expand to
+<p>Use the first as in <code>I highly recommend \student{} to you</code>.
+The second has a variable, so that <code>\defref{def:basis}</code> expands
+to <code>Definition~\ref{def:basis}</code>, which ultimately expands to
something like ‘<samp>Definition~3.14</samp>’.
</p>
-<p>An example with two required arguments:
+<p>Similarly, but with two required arguments:
<code>\newcommand{\nbym}[2]{$#1 \times #2$}</code> is invoked as
<code>\nbym{2}{k}</code>.
</p>
-<p>An example with an optional argument:
+<p>This example has an optional argument.
</p>
<div class="example">
<pre class="example">\newcommand{\salutation}[1][Sir or Madam]{Dear #1:}
</pre></div>
-<p>Then, <code>\salutation</code> gives ‘<samp>Dear Sir or Madam:</samp>’ while
+<p>Then <code>\salutation</code> gives ‘<samp>Dear Sir or Madam:</samp>’ while
<code>\salutation[John]</code> gives ‘<samp>Dear John:</samp>’. And
<code>\salutation[]</code> gives ‘<samp>Dear :</samp>’.
</p>
-<p>The braces around <var>defn</var> do not define a group, that is, they do
-not delimit the scope of the result of expanding <var>defn</var>. So
-<code>\newcommand{\shipname}[1]{\it #1}</code> is problematic; in this
-sentence,
+<p>This example has an optional argument and two required arguments.
</p>
<div class="example">
+<pre class="example">\newcommand{\lawyers}[3][company]{#2, #3, and~#1}
+I employ \lawyers[Howe]{Dewey}{Cheatem}.
+</pre></div>
+
+<p>The ouptut is ‘<samp>I employ Dewey, Cheatem, and Howe</samp>’. The optional
+argument, the <code>Howe</code>, is associated with <code>#1</code>, while
+<code>Dewey</code> and <code>Cheatem</code> are associated with <code>#2</code>
+and <code>#3</code>. Because of the optional argument,
+<code>\lawyers{Dewey}{Cheatem}</code> will give the output ‘<samp>I employ
+Dewey, Cheatem, and company</samp>’.
+</p>
+<p>The braces around <var>defn</var> do not define a group, that is, they do not
+delimit the scope of the result of expanding <var>defn</var>. For example,
+with <code>\newcommand{\shipname}[1]{\it #1}</code>, in this sentence,
+</p>
+<div class="example">
<pre class="example">The \shipname{Monitor} met the \shipname{Merrimac}.
</pre></div>
-<p>the words ‘<samp>met the</samp>’ would incorrectly be in italics. Another
-pair of braces in the definition is needed, like this:
-<code>\newcommand{\shipname}[1]{{\it #1}}</code>. Those braces are
-part of the definition and thus do define a group.
+<p>the words ‘<samp>met the</samp>’ would incorrectly be in italics. The
+solution is to put another pair of braces inside the definition:
+<code>\newcommand{\shipname}[1]{{\it #1}}</code>.
</p>
<hr>
@@ -8964,21 +8993,37 @@
<a name="index-defining-a-new-command-1"></a>
<a name="index-new-commands_002c-defining-1"></a>
-<p>Defines a command, as long as no command of this name already exists.
-Synopses:
+<p>Synopses, one of:
</p>
<div class="example">
-<pre class="example">\providecommand{<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>}
+<pre class="example">\providecommand{<var>cmd</var>}{<var>defn</var>}
+\providecommand{<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>}
+\providecommand{<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>}
+\providecommand*{<var>cmd</var>}{<var>defn</var>}
+\providecommand*{<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>}
\providecommand*{<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>}
</pre></div>
-<p>If no command of this name already exists then this has the same effect
-as <code>\newcommand</code> (see <a href="#g_t_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</a>). If a
-command of this name already exists then this definition does nothing.
-This is particularly useful in a style file, or other file that may be
-loaded more than once.
+<p>Defines a command, as long as no command of this name already exists.
+If no command of this name already exists then this has the same effect
+as <code>\newcommand</code>. If a command of this name already exists then
+this definition does nothing. This is particularly useful in a file
+that may be loaded more than once, such as a style file.
+See <a href="#g_t_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</a> for the description of the arguments.
</p>
+<p>This example
+</p>
+<div class="example">
+<pre class="example">\providecommand{\myaffiliation}{Saint Michael's College}
+\providecommand{\myaffiliation}{Saint Michael's College}
+From \myaffiliation.
+</pre></div>
+<p>outputs ‘<samp>From Saint Michael's College</samp>’. Unlike
+<code>\newcommand</code>, the repeated use of <code>\providecommand</code> does not
+give an error.
+</p>
+
<hr>
<a name="g_t_005cnewcounter"></a>
<div class="header">
@@ -8998,27 +9043,44 @@
\newcounter{<var>countername</var>}[<var>supercounter</var>]
</pre></div>
-<p>Globally defines a new counter named <var>countername</var> and initialize
-the new counter to zero.
+<p>Globally defines a new counter named <var>countername</var> and initialize it
+to zero (see <a href="#Counters">Counters</a>).
</p>
<p>The name <var>countername</var> must consist of letters only. It does not
begin with a backslash. This name must not already be in use by another
counter.
</p>
-<p>When you use the optional argument <code>[<var>supercounter</var>]</code> then
-<var>countername</var> the counter foo will be reset whenever the counter
+<p>When you use the optional argument <code>[<var>supercounter</var>]</code> then the
+counter <var>countername</var> will be reset to zero whenever
<var>supercounter</var> is incremented. For example, ordinarily
-<code>subsection</code> is numbered within <code>section</code> so that any time
-<var>supercounter</var> is incremented, either with <code>\stepcounter</code>
+<code>subsection</code> is numbered within <code>section</code> so that any time you
+increment <var>section</var>, either with <code>\stepcounter</code>
(see <a href="#g_t_005cstepcounter">\stepcounter</a>) or <code>\refstepcounter</code>
-(see <a href="#g_t_005crefstepcounter">\refstepcounter</a>), then <var>countername</var> is reset to zero.
+(see <a href="#g_t_005crefstepcounter">\refstepcounter</a>), then LaTeX will reset <var>subsection</var> to
+zero.
</p>
-<p>The super counter must already exist. If you enter
-<code>\newcounter{jh}[lh]</code> and <code>lh</code> is not a defined counter
-then you will get ‘<samp>LaTeX Error: No counter 'lh' defined.</samp>’
+<p>This example
</p>
-<p>See <a href="#Counters">Counters</a>, for more information about counters.
+<div class="example">
+<pre class="example">\newcounter{asuper} \setcounter{asuper}{1}
+\newcounter{asub}[asuper] \setcounter{asub}{3} % Note the optional `asuper'
+The value of asuper is \arabic{asuper} and that of asub is \arabic{asub}.
+\stepcounter{asuper}
+Now asuper is \arabic{asuper} while asub is \arabic{asub}.
+</pre></div>
+
+<p>produces ‘<samp>The value of asuper is 1 and that of asub is 3</samp>’ and
+‘<samp>Now asuper is 2 while asub is 0</samp>’.
</p>
+<p>If the counter already exists, for instance by entering <code>asuper</code>
+twice, then you get something like ‘<samp>LaTeX Error: Command \c at asuper
+already defined. Or name \end... illegal, see p.192 of the manual.</samp>’.
+</p>
+<p>If you use the optional argument then the super counter must already
+exist. Entering <code>\newcounter{jh}[lh]</code> when <code>lh</code> is not a
+defined counter will get you ‘<samp>LaTeX Error: No counter 'lh'
+defined.</samp>’
+</p>
<hr>
<a name="g_t_005cnewlength"></a>
@@ -9035,22 +9097,31 @@
<a name="index-skip-register_002c-plain-TeX"></a>
<a name="index-glue-register_002c-plain-TeX"></a>
-<p>Allocate a new <em>length</em> register. Synopsis:
+<p>Synopsis:
</p>
<div class="example">
<pre class="example">\newlength{\<var>arg</var>}
</pre></div>
-<p>This command takes one required argument, which must begin with a
-backslash, <code>\</code>. It creates a new length register named
-<code>\<var>arg</var></code>, which is a place to hold (rubber) lengths such as
-<code>1in plus.2in minus.1in</code> (what plain TeX calls a <code>skip</code>
-register). The register gets an initial value of zero. The control
-sequence <code>\<var>arg</var></code> must not already be defined.
+<p>Allocate a new length register (see <a href="#Lengths">Lengths</a>). The required argument
+must begin with a backslash, <code>\</code>. The new register hold rubber
+lengths such as <code>72.27pt</code> or <code>1in plus.2in minus.1in</code> (a
+LaTeX length register is what plain TeX calls a <code>skip</code>
+register). The initial value is zero. The control sequence
+<code>\<var>arg</var></code> must not be already defined.
</p>
-<p>See <a href="#Lengths">Lengths</a>, for more about lengths.
+<p>An example:
</p>
+<div class="example">
+<pre class="example">\newlength{\graphichgt}
+</pre></div>
+<p>If you forget the backslash then you get ‘<samp>Missing control sequence
+inserted</samp>’. If the command sequence already exists then you get
+something like ‘<samp>LaTeX Error: Command \graphichgt already defined.
+Or name \end... illegal, see p.192 of the manual</samp>’.
+</p>
+
<hr>
<a name="g_t_005cnewsavebox"></a>
<div class="header">
@@ -9063,17 +9134,31 @@
<a name="index-_005cnewsavebox"></a>
<a name="index-box_002c-allocating-new"></a>
-<p>Allocate a “bin” for holding a box. Synopsis:
+<p>Synopsis:
</p>
<div class="example">
<pre class="example">\newsavebox{\<var>cmd</var>}
</pre></div>
-<p>Defines <code>\<var>cmd</var></code> to refer to a new bin for storing boxes. Such
-a box is for holding typeset material, to use multiple times
-(see <a href="#Boxes">Boxes</a>) or to measure or manipulate. The name <code>\<var>cmd</var></code>
-must start with a backslash, <code>\</code>, and must not be already defined.
+<p>Define <code>\<var>cmd</var></code> to refer to a new “bin” for storing boxes.
+Such a box is for holding typeset material, to use multiple times or to
+measure or manipulate (see <a href="#Boxes">Boxes</a>). The name <code>\<var>cmd</var></code> must
+start with a backslash, <code>\</code>, and must not already be defined.
</p>
+<p>The first line here sets you up to save the material for later use.
+</p>
+<div class="example">
+<pre class="example">\newsavebox{\logobox}
+\savebox{\logobox}{LoGo}
+Our logo is \usebox{\logobox}.
+</pre></div>
+
+<p>The output is ‘<samp>Our logo is LoGo</samp>’.
+</p>
+<p>If there is an already defined box then you get something like
+‘<samp>LaTeX Error: Command \logobox already defined. Or name
+\end... illegal, see p.192 of the manual</samp>’.
+</p>
<p>The allocation of a box is global. This command is fragile
(see <a href="#g_t_005cprotect">\protect</a>).
</p>
@@ -9093,17 +9178,30 @@
<a name="index-defining-new-environments"></a>
<a name="index-redefining-environments"></a>
-<p>Synopses:
+<p>Synopses, one of:
</p>
<div class="example">
-<pre class="example"> \newenvironment{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>}
- \newenvironment*{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>}
- \renewenvironment{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>}
+<pre class="example">\newenvironment{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>}
+\newenvironment{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>}
+\newenvironment{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>}
+\newenvironment*{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>}
+\newenvironment*{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>}
+\newenvironment*{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>}
+</pre></div>
+
+<p>or one of:
+</p>
+<div class="example">
+<pre class="example">\renewenvironment{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>}
+\renewenvironment{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>}
+\renewenvironment{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>}
+\renewenvironment*{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>}
+\renewenvironment*{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>}
\renewenvironment*{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>}
</pre></div>
<p>Define or redefine the environment <var>env</var>, that is, create the
-construct <code>\begin{<var>env</var>} <var>body</var> \end{<var>env</var>}</code>.
+construct <code>\begin{<var>env</var>} ... <var>body</var> ... \end{<var>env</var>}</code>.
</p>
<a name="index-_002a_002dform-of-environment-commands"></a>
<p>The starred form of these commands requires that the arguments not
@@ -9123,31 +9221,30 @@
</dd>
<dt><var>nargs</var></dt>
<dd><p>Optional; an integer from 0 to 9 denoting the number of arguments of
-that the environment will take. When the environment is used these
+that the environment will take. When you use the environment these
arguments appear after the <code>\begin</code>, as in
-<code>\begin{<var>env</var>}{<var>arg1</var>} .... {<var>argn</var>}</code>. If this
-argument is not present then the default is for the environment to have
-no arguments. When redefining an environment, the new version can have
-a different number of arguments than the old version.
+<code>\begin{<var>env</var>}{<var>arg1</var>} .... {<var>argn</var>}</code>. Omiting
+this is equivalent to setting it to 0; the environment will have no
+arguments. When redefining an environment, the new version can have a
+different number of arguments than the old version.
</p>
</dd>
<dt><var>optargdefault</var></dt>
-<dd><p>Optional; if this argument is present then the first argument of the
-defined environment is optional, with default value <var>optargdefault</var>
-(which may be the empty string). If this argument is not present then
-the environment does not take an optional argument.
+<dd><p>Optional; if this is present then the first argument of the defined
+environment is optional, with default value <var>optargdefault</var> (which
+may be the empty string). If this is not in the definition then the
+environment does not take an optional argument.
</p>
-<p>That is, when <code>[<var>optargdefault</var>]</code> is present in the
-environment definition, if <code>\begin{<var>env</var>}</code> is used with
-square brackets following, as in
-<code>\begin{<var>env</var>}[<var>myval</var>]</code>, then, within <var>begdefn</var>,
-the positional parameter <code>#1</code> expands to <var>myval</var>. If
-<code>\begin{<var>env</var>}</code> is called without square brackets
-following, then, within within <var>begdefn</var>, the positional parameter
-<code>#1</code> expands to the default <var>optargdefault</var>. In either case,
-any required arguments will be referred to starting with <code>#2</code>.
+<p>That is, when this is present in the environment definition then you can
+start the environment with square brackets, as in
+<code>\begin{<var>env</var>}[<var>optval</var>] ... \end{<var>env</var>}</code>. In this
+case, within <var>begdefn</var> the parameter <code>#1</code> is set to the value
+of <var>optval</var>. If you call <code>\begin{<var>env</var>}</code> without square
+brackets, then within <var>begdefn</var> the parameter <code>#1</code> is set to
+the value of the default <var>optargdefault</var>. In either case, any
+required arguments start with <code>#2</code>.
</p>
-<p>Omitting <code>[<var>myval</var>]</code> in the call is different from having the
+<p>Omitting <code>[<var>myval</var>]</code> in the call is different than having the
square brackets with no contents, as in <code>[]</code>. The former results
in <code>#1</code> expanding to <var>optargdefault</var>; the latter results in
<code>#1</code> expanding to the empty string.
@@ -9155,16 +9252,17 @@
</dd>
<dt><var>begdef</var></dt>
<dd><p>Required; the text expanded at every occurrence of
-<code>\begin{<var>env</var>}</code>. Within <var>begdef</var>, the <var>n</var>th
-positional parameter (i.e., <code>#1</code>, <code>#2</code>, etc.) is replaced by
-the text of the <var>n</var>th argument.
+<code>\begin{<var>env</var>}</code>. Within <var>begdef</var>, the parameters
+<code>#1</code>, <code>#2</code>, ... <code>#<var>nargs</var></code>, are replaced by the
+values that you supply when you call the environment; see the examples
+below.
</p>
</dd>
<dt><var>enddef</var></dt>
<dd><p>Required; the text expanded at every occurrence of
-<code>\end{<var>env</var>}</code>. This may not contain any positional
-parameters, so you cannot use <code>#1</code>, <code>#2</code>, etc., here (but see
-the final example below).
+<code>\end{<var>env</var>}</code>. This may not contain any parameters, so you
+cannot use <code>#1</code>, <code>#2</code>, etc., here (but see the final example
+below).
</p>
</dd>
</dl>
@@ -9181,7 +9279,7 @@
get something like ‘<samp>LaTeX Error: Environment hank undefined.</samp>’.
</p>
<p>This example gives an environment like LaTeX’s <code>quotation</code>
-except that it will be set in smaller type:
+except that it will be set in smaller type.
</p>
<div class="example">
<pre class="example">\newenvironment{smallquote}{%
@@ -9192,7 +9290,7 @@
</pre></div>
<p>This one shows the use of arguments; it gives a quotation environment
-that cites the author:
+that cites the author.
</p>
<div class="example">
<pre class="example">\newenvironment{citequote}[1][Shakespeare]{%
@@ -9204,7 +9302,7 @@
</pre></div>
<p>The author’s name is optional, and defaults to ‘<samp>Shakespeare</samp>’.
-In the document, use the environment like this:
+In the document, use the environment like this.
</p>
<div class="example">
<pre class="example">\begin{citequote}[Lincoln]
@@ -9213,7 +9311,7 @@
</pre></div>
<p>The final example shows how to save the value of an argument to use in
-<var>enddef</var>, in this case in a box (see <a href="#g_t_005csbox">\sbox</a>):
+<var>enddef</var>, in this case in a box (see <a href="#g_t_005csbox">\sbox</a>).
</p>
<div class="example">
<pre class="example">\newsavebox{\quoteauthor}
@@ -9250,25 +9348,25 @@
\newtheorem{<var>name</var>}[<var>numbered_like</var>]{<var>title</var>}
</pre></div>
-<p>Define a new theorem-like environment. The first form,
-<code>\newtheorem{<var>name</var>}{<var>title</var>}</code>, creates an environment
-that will be labelled with <var>title</var>; see the first example below.
+<p>Define a new theorem-like environment. You can specify one of
+<var>numbered_within</var> and <var>numbered_like</var>, or neither, but not both.
</p>
+<p>The first form, <code>\newtheorem{<var>name</var>}{<var>title</var>}</code>, creates
+an environment that will be labelled with <var>title</var>; see the first
+example below.
+</p>
<p>The second form,
<code>\newtheorem{<var>name</var>}{<var>title</var>}[<var>numbered_within</var>]</code>,
creates an environment whose counter is subordinate to the existing
counter <var>numbered_within</var>, so this counter will be reset when
-<var>numbered_within</var> is reset.
+<var>numbered_within</var> is reset. See the second e3xample below.
</p>
<p>The third form
<code>\newtheorem{<var>name</var>}[<var>numbered_like</var>]{<var>title</var>}</code>,
with optional argument between the two required arguments, creates an
environment whose counter will share the previously defined counter
-<var>numbered_like</var>.
+<var>numbered_like</var>. See the third example.
</p>
-<p>You can specify one of <var>numbered_within</var> and <var>numbered_like</var>,
-or neither, but not both.
-</p>
<p>This command creates a counter named <var>name</var>. In addition, unless
the optional argument <var>numbered_like</var> is used, inside of the
theorem-like environment the current <code>\ref</code> value will be that of
@@ -9384,8 +9482,8 @@
<a name="index-defining-new-fonts"></a>
<p>This command is obsolete. This description is here only to help with old
-documents. New document should define fonts in families through the New
-Font Selection Scheme which allows you to, for example, associate a
+documents. New documents should define fonts in families through the
+New Font Selection Scheme which allows you to, for example, associate a
boldface with a roman (see <a href="#Fonts">Fonts</a>).
</p>
<p>Synopsis:
@@ -10110,16 +10208,28 @@
<p>Synopsis:
</p>
<div class="example">
-<pre class="example">\setlength{<var>\len</var>}{<var>amount</var>}
+<pre class="example">\setlength{<var>len</var>}{<var>amount</var>}
</pre></div>
-<p>The <code>\setlength</code> sets the value of <em>length command</em>
-<a name="index-length-command"></a>
-<code>\<var>len</var></code> to the <var>value</var> argument which can be expressed in any
-units that LaTeX understands, i.e., inches (<code>in</code>), millimeters
-(<code>mm</code>), points (<code>pt</code>), big points (<code>bp</code>), etc.
+<p>Set the length <var>len</var> to <var>amount</var>. The length name <var>len</var>
+must begin with a backslash, <code>\</code>. The <code>amount</code> can be a
+rubber length (see <a href="#Lengths">Lengths</a>). It can be positive, negative or zero,
+and can be in any units that LaTeX understands (see <a href="#Units-of-length">Units of length</a>).
</p>
+<p>Below, with LaTeX’s defaults the first paragraph will be indented
+while the second will not.
+</p>
+<div class="example">
+<pre class="example">I told the doctor I broke my leg in two places.
+\setlength{\parindent}{0em}
+He said stop going to those places.
+</pre></div>
+
+<p>If there is no such length <var>len</var> then you get something like
+‘<samp>Undefined control sequence. <argument> \praindent</samp>’.
+</p>
+
<hr>
<a name="g_t_005caddtolength"></a>
<div class="header">
@@ -10135,14 +10245,31 @@
<p>Synopsis:
</p>
<div class="example">
-<pre class="example">\addtolength{<var>\len</var>}{<var>amount</var>}
+<pre class="example">\addtolength{<var>len</var>}{<var>amount</var>}
</pre></div>
+<p>Increment the length <var>len</var> by <var>amount</var>. The length name
+<var>len</var> must begin with a backslash, <code>\</code>. The <code>amount</code> can
+be a rubber length (see <a href="#Lengths">Lengths</a>). It can be positive, negative or
+zero, and can be in any units that LaTeX understands (see <a href="#Units-of-length">Units of length</a>).
+</p>
+<p>Below, if <code>\parskip</code> starts with the value <code>0pt plus 1pt</code>
+</p>
+<div class="example">
+<pre class="example">\addtolength{\parskip}{1pt}
+Doctor: how is the boy who swallowed the silver dollar?
-<p>The <code>\addtolength</code> command increments a length command <code>\<var>len</var></code>
-by the amount specified in the <var>amount</var> argument, which may be
-negative.
+Nurse: no change.
+</pre></div>
+
+<p>then it has the value <code>1pt plus 1pt</code> for the second paragraph.
</p>
+<p>If there is no such length <var>len</var> then you get something like
+‘<samp>Undefined control sequence. <argument> \praindent</samp>’. If you leave
+off the backslash at the start of <var>len</var>, as in
+<code>\addtolength{parindent}{1pt}</code>, then you get something like
+‘<samp>You can't use `the letter p' after \advance</samp>’.
+</p>
<hr>
<a name="g_t_005csettodepth"></a>
@@ -10158,13 +10285,27 @@
<p>Synopsis:
</p>
<div class="example">
-<pre class="example">\settodepth{\<var>len</var>}{<var>text</var>}
+<pre class="example">\settodepth{<var>len</var>}{<var>text</var>}
</pre></div>
-<p>The <code>\settodepth</code> command sets the value of a length command
-<code>\<var>len</var></code> equal to the depth of the <var>text</var> argument.
+<p>Set the length <var>len</var> to the depth of the <var>text</var> argument. The
+length name <var>len</var> must begin with a backslash, <code>\</code>.
</p>
+<p>This will show how low the character descenders go.
+</p>
+<div class="example">
+<pre class="example">\newlength{\alphabetdepth}
+\settodepth{\alphabetdepth}{abcdefghijklmnopqrstuvwxyz}
+\the\alphabetdepth
+</pre></div>
+<p>If there is no such length <var>len</var> then you get something like
+‘<samp>Undefined control sequence. <argument> \alphabetdepth</samp>’. If you
+leave the backslash out of <var>len</var>, as in
+<code>\settodepth{alphabetdepth}{...}</code> then you get something like
+‘<samp>Missing number, treated as zero. <to be read again> \setbox</samp>’.
+</p>
+
<hr>
<a name="g_t_005csettoheight"></a>
<div class="header">
@@ -10179,13 +10320,27 @@
<p>Synopsis:
</p>
<div class="example">
-<pre class="example">\settoheight{\<var>len</var>}{text}
+<pre class="example">\settoheight{<var>len</var>}{text}
</pre></div>
-<p>The <code>\settoheight</code> command sets the value of a length command <code>\<var>len</var></code>
-equal to the height of the <code>text</code> argument.
+<p>Sets the length <var>len</var> to the height of the
+<code>text</code> argument. The length name <var>len</var> must begin with a
+backslash, <code>\</code>.
</p>
+<p>This will show how high the characters go.
+</p>
+<div class="example">
+<pre class="example">\newlength{\alphabetheight}
+\settoheight{\alphabetheight}{abcdefghijklmnopqrstuvwxyz}
+\the\alphabetheight
+</pre></div>
+<p>If there is no such length <var>len</var> then you get something like
+‘<samp>Undefined control sequence. <argument> \alphabetheight</samp>’. If you
+leave the backslash out of <var>len</var>, as in
+<code>\settoheight{alphabetheight}{...}</code> then you get something like
+‘<samp>Missing number, treated as zero. <to be read again> \setbox</samp>’.
+</p>
<hr>
<a name="g_t_005csettowidth"></a>
@@ -10201,13 +10356,27 @@
<p>Synopsis:
</p>
<div class="example">
-<pre class="example">\settowidth{\<var>len</var>}{<var>text</var>}
+<pre class="example">\settowidth{<var>len</var>}{<var>text</var>}
</pre></div>
-<p>The <code>\settowidth</code> command sets the value of the command <var>\len</var>
-to the width of the <var>text</var> argument.
+<p>Set the length <var>len</var> to the width of the <var>text</var>. The length
+name <var>len</var> must begin with a backslash, <code>\</code>.
</p>
+<p>This measures the width of the lower case ASCII alphabet.
+</p>
+<div class="example">
+<pre class="example">\newlength{\alphabetwidth}
+\settowidth{\alphabetwidth}{abcdefghijklmnopqrstuvwxyz}
+\the\alphabetwidth
+</pre></div>
+<p>If there is no such length <var>len</var> then you get something like
+‘<samp>Undefined control sequence. <argument> \alphabetwidth</samp>’. If you
+leave the backslash out of <var>len</var>, as in
+<code>\settoheight{alphabetwidth}{...}</code> then you get something like
+‘<samp>Missing number, treated as zero. <to be read again> \setbox</samp>’.
+</p>
+
<hr>
<a name="Predefined-lengths"></a>
<div class="header">
@@ -18052,7 +18221,6 @@
<tr><td></td><td valign="top"><a href="#index-left_002djustifying-text">left-justifying text</a>:</td><td> </td><td valign="top"><a href="#g_t_005craggedright">\raggedright</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-left_002djustifying-text_002c-environment-for">left-justifying text, environment for</a>:</td><td> </td><td valign="top"><a href="#flushleft">flushleft</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-left_002dto_002dright-mode">left-to-right mode</a>:</td><td> </td><td valign="top"><a href="#Modes">Modes</a></td></tr>
-<tr><td></td><td valign="top"><a href="#index-length-command">length command</a>:</td><td> </td><td valign="top"><a href="#g_t_005csetlength">\setlength</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-lengths_002c-adding-to">lengths, adding to</a>:</td><td> </td><td valign="top"><a href="#g_t_005caddtolength">\addtolength</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-lengths_002c-allocating-new">lengths, allocating new</a>:</td><td> </td><td valign="top"><a href="#g_t_005cnewlength">\newlength</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-lengths_002c-defining-and-using">lengths, defining and using</a>:</td><td> </td><td valign="top"><a href="#Lengths">Lengths</a></td></tr>
Modified: trunk/latex2e.info
===================================================================
--- trunk/latex2e.info 2018-05-31 16:05:41 UTC (rev 634)
+++ trunk/latex2e.info 2018-05-31 16:43:51 UTC (rev 635)
@@ -5908,19 +5908,30 @@
12.1 '\newcommand' & '\renewcommand'
====================================
-Synopses:
+Synopses, one of:
- \newcommand{\CMD}[NARGS][OPTARGDEFAULT]{DEFN}
- \newcommand*{\CMD}[NARGS][OPTARGDEFAULT]{DEFN}
+ \newcommand{\CMD}{DEFN}
+ \newcommand{\CMD}[NARGS]{DEFN}
+ \newcommand{\CMD}[NARGS][OPTARGDEFAULT]{DEFN}
+ \newcommand*{\CMD}{DEFN}
+ \newcommand*{\CMD}[NARGS]{DEFN}
+ \newcommand*{\CMD}[NARGS][OPTARGDEFAULT]{DEFN}
+
+ or one of:
+
+ \renewcommand{\CMD}[NARGS]{DEFN}
+ \renewcommand{\CMD}[NARGS]{DEFN}
\renewcommand{\CMD}[NARGS][OPTARGDEFAULT]{DEFN}
+ \renewcommand*{\CMD}{DEFN}
+ \renewcommand*{\CMD}[NARGS]{DEFN}
\renewcommand*{\CMD}[NARGS][OPTARGDEFAULT]{DEFN}
Define or redefine a command. See also the discussion of
-'\DeclareRobustCommand' in *note Class and package commands::.
+'\DeclareRobustCommand' in *note Class and package commands::. The
+starred form of these two requires that the arguments not contain
+multiple paragraphs of text (in plain TeX terms that it not be '\long').
- The starred form of these two commands requires that the arguments
-not contain multiple paragraphs of text (not '\long', in plain TeX
-terms).
+ These are the parameters:
CMD
@@ -5932,10 +5943,10 @@
NARGS
Optional; an integer from 0 to 9, specifying the number of
arguments that the command can take, including any optional
- argument. If this argument is not present, the default is for the
- command to have no arguments. When redefining a command, the new
- version can have a different number of arguments than the old
- version.
+ argument. Omitting this argument is the same as specifying 0,
+ meaning that the command has no arguments. If you redefine a
+ command, the new version can have a different number of arguments
+ than the old version.
OPTARGDEFAULT
Optional; if this argument is present then the first argument of
@@ -5943,68 +5954,81 @@
OPTARGDEFAULT (which may be the empty string). If this argument is
not present then '\CMD' does not take an optional argument.
- That is, if '\CMD' is used with square brackets following, as in
- '\CMD[MYVAL]', then within DEFN the first "positional parameter"
- '#1' expands MYVAL. On the other hand, if '\CMD' is called without
- square brackets following, then within DEFN the positional
- parameter '#1' expands to the default OPTARGDEFAULT. In either
- case, any required arguments will be referred to starting with
- '#2'.
+ That is, if '\CMD' is used with square brackets, as in
+ '\CMD[OPTVAL]', then within DEFN then '#1' is set to the value of
+ OPTVAL. On the other hand, if '\CMD' is called without the square
+ brackets, then within DEFN the parameter '#1' is set to the value
+ of OPTARGDEFAULT. In either case, the required arguments start
+ with '#2'.
- Omitting '[MYVAL]' in a call is different from having the square
- brackets with no contents, as in '[]'. The former results in '#1'
- expanding to OPTARGDEFAULT; the latter results in '#1' expanding to
- the empty string.
+ Omitting '[OPTARGDEFAULT]' is different from having the square
+ brackets with no contents, as in '[]'. The former sets '#1' to the
+ value of OPTARGDEFAULT; the latter sets '#1' to the empty string.
DEFN
- The text to be substituted for every occurrence of '\CMD'; the
- positional parameter '#N' in DEFN is replaced by the text of the
- Nth argument.
+ Required; the text to be substituted for every occurrence of
+ '\CMD'. The parameters '#1', '#2', ... '#NARGS' are replaced by
+ the values that you supply when you call the command (or by the
+ default value if there is an optional argument and you don't
+ exercise the option).
TeX ignores spaces in the source following an alphabetic control
sequence, as in '\cmd '. If you actually want a space there, one
-solution is to type '{}' after the command ('\cmd{} '; another solution
-is to use an explicit control space ('\cmd\ ').
+solution is to type '{}' after the command ('\cmd{} ', and another
+solution is to use an explicit control space ('\cmd\ ').
A simple example of defining a new command: '\newcommand{\RS}{Robin
-Smith}' results in '\RS' being replaced by the longer text.
+Smith}' results in '\RS' being replaced by the longer text. Redefining
+an existing command is similar: '\renewcommand{\qedsymbol}{{\small
+QED}}'.
- Redefining an existing command is similar:
-'\renewcommand{\qedsymbol}{{\small QED}}'.
-
If you try to define a command and the name has already been used
then you get something like 'LaTeX Error: Command \fred already defined.
Or name \end... illegal, see p.192 of the manual'. If you try to
redefine a command and the name has not yet been used then you get
something like 'LaTeX Error: \hank undefined'.
- Here's a command definition with one required argument:
+ Here the first command definition has no arguments, and the second
+has one required argument.
+ \newcommand{\student}{Ms~O'Leary}
\newcommand{\defref}[1]{Definition~\ref{#1}}
-Then, '\defref{def:basis}' expands to 'Definition~\ref{def:basis}',
-which will ultimately expand to something like 'Definition~3.14'.
+Use the first as in 'I highly recommend \student{} to you'. The second
+has a variable, so that '\defref{def:basis}' expands to
+'Definition~\ref{def:basis}', which ultimately expands to something like
+'Definition~3.14'.
- An example with two required arguments: '\newcommand{\nbym}[2]{$#1
-\times #2$}' is invoked as '\nbym{2}{k}'.
+ Similarly, but with two required arguments:
+'\newcommand{\nbym}[2]{$#1 \times #2$}' is invoked as '\nbym{2}{k}'.
- An example with an optional argument:
+ This example has an optional argument.
\newcommand{\salutation}[1][Sir or Madam]{Dear #1:}
-Then, '\salutation' gives 'Dear Sir or Madam:' while '\salutation[John]'
+Then '\salutation' gives 'Dear Sir or Madam:' while '\salutation[John]'
gives 'Dear John:'. And '\salutation[]' gives 'Dear :'.
+ This example has an optional argument and two required arguments.
+
+ \newcommand{\lawyers}[3][company]{#2, #3, and~#1}
+ I employ \lawyers[Howe]{Dewey}{Cheatem}.
+
+ The ouptut is 'I employ Dewey, Cheatem, and Howe'. The optional
+argument, the 'Howe', is associated with '#1', while 'Dewey' and
+'Cheatem' are associated with '#2' and '#3'. Because of the optional
+argument, '\lawyers{Dewey}{Cheatem}' will give the output 'I employ
+Dewey, Cheatem, and company'.
+
The braces around DEFN do not define a group, that is, they do not
-delimit the scope of the result of expanding DEFN. So
-'\newcommand{\shipname}[1]{\it #1}' is problematic; in this sentence,
+delimit the scope of the result of expanding DEFN. For example, with
+'\newcommand{\shipname}[1]{\it #1}', in this sentence,
The \shipname{Monitor} met the \shipname{Merrimac}.
-the words 'met the' would incorrectly be in italics. Another pair of
-braces in the definition is needed, like this:
-'\newcommand{\shipname}[1]{{\it #1}}'. Those braces are part of the
-definition and thus do define a group.
+the words 'met the' would incorrectly be in italics. The solution is to
+put another pair of braces inside the definition:
+'\newcommand{\shipname}[1]{{\it #1}}'.
File: latex2e.info, Node: \providecommand, Next: \newcounter, Prev: \newcommand & \renewcommand, Up: Definitions
@@ -6012,18 +6036,31 @@
12.2 '\providecommand'
======================
-Defines a command, as long as no command of this name already exists.
-Synopses:
+Synopses, one of:
+ \providecommand{CMD}{DEFN}
+ \providecommand{CMD}[NARGS]{DEFN}
\providecommand{CMD}[NARGS][OPTARGDEFAULT]{DEFN}
+ \providecommand*{CMD}{DEFN}
+ \providecommand*{CMD}[NARGS]{DEFN}
\providecommand*{CMD}[NARGS][OPTARGDEFAULT]{DEFN}
- If no command of this name already exists then this has the same
-effect as '\newcommand' (*note \newcommand & \renewcommand::). If a
-command of this name already exists then this definition does nothing.
-This is particularly useful in a style file, or other file that may be
-loaded more than once.
+ Defines a command, as long as no command of this name already exists.
+If no command of this name already exists then this has the same effect
+as '\newcommand'. If a command of this name already exists then this
+definition does nothing. This is particularly useful in a file that may
+be loaded more than once, such as a style file. *Note \newcommand &
+\renewcommand:: for the description of the arguments.
+ This example
+
+ \providecommand{\myaffiliation}{Saint Michael's College}
+ \providecommand{\myaffiliation}{Saint Michael's College}
+ From \myaffiliation.
+
+ outputs 'From Saint Michael's College'. Unlike '\newcommand', the
+repeated use of '\providecommand' does not give an error.
+
File: latex2e.info, Node: \newcounter, Next: \newlength, Prev: \providecommand, Up: Definitions
@@ -6035,59 +6072,91 @@
\newcounter{COUNTERNAME}
\newcounter{COUNTERNAME}[SUPERCOUNTER]
- Globally defines a new counter named COUNTERNAME and initialize the
-new counter to zero.
+ Globally defines a new counter named COUNTERNAME and initialize it to
+zero (*note Counters::).
The name COUNTERNAME must consist of letters only. It does not begin
with a backslash. This name must not already be in use by another
counter.
- When you use the optional argument '[SUPERCOUNTER]' then COUNTERNAME
-the counter foo will be reset whenever the counter SUPERCOUNTER is
-incremented. For example, ordinarily 'subsection' is numbered within
-'section' so that any time SUPERCOUNTER is incremented, either with
-'\stepcounter' (*note \stepcounter::) or '\refstepcounter' (*note
-\refstepcounter::), then COUNTERNAME is reset to zero.
+ When you use the optional argument '[SUPERCOUNTER]' then the counter
+COUNTERNAME will be reset to zero whenever SUPERCOUNTER is incremented.
+For example, ordinarily 'subsection' is numbered within 'section' so
+that any time you increment SECTION, either with '\stepcounter' (*note
+\stepcounter::) or '\refstepcounter' (*note \refstepcounter::), then
+LaTeX will reset SUBSECTION to zero.
- The super counter must already exist. If you enter
-'\newcounter{jh}[lh]' and 'lh' is not a defined counter then you will
-get 'LaTeX Error: No counter 'lh' defined.'
+ This example
- *Note Counters::, for more information about counters.
+ \newcounter{asuper} \setcounter{asuper}{1}
+ \newcounter{asub}[asuper] \setcounter{asub}{3} % Note the optional `asuper'
+ The value of asuper is \arabic{asuper} and that of asub is \arabic{asub}.
+ \stepcounter{asuper}
+ Now asuper is \arabic{asuper} while asub is \arabic{asub}.
+ produces 'The value of asuper is 1 and that of asub is 3' and 'Now
+asuper is 2 while asub is 0'.
+
+ If the counter already exists, for instance by entering 'asuper'
+twice, then you get something like 'LaTeX Error: Command \c at asuper
+already defined. Or name \end... illegal, see p.192 of the manual.'.
+
+ If you use the optional argument then the super counter must already
+exist. Entering '\newcounter{jh}[lh]' when 'lh' is not a defined
+counter will get you 'LaTeX Error: No counter 'lh' defined.'
+
File: latex2e.info, Node: \newlength, Next: \newsavebox, Prev: \newcounter, Up: Definitions
12.4 '\newlength': Allocating a length
======================================
-Allocate a new "length" register. Synopsis:
+Synopsis:
\newlength{\ARG}
- This command takes one required argument, which must begin with a
-backslash, '\'. It creates a new length register named '\ARG', which is
-a place to hold (rubber) lengths such as '1in plus.2in minus.1in' (what
-plain TeX calls a 'skip' register). The register gets an initial value
-of zero. The control sequence '\ARG' must not already be defined.
+ Allocate a new length register (*note Lengths::). The required
+argument must begin with a backslash, '\'. The new register hold rubber
+lengths such as '72.27pt' or '1in plus.2in minus.1in' (a LaTeX length
+register is what plain TeX calls a 'skip' register). The initial value
+is zero. The control sequence '\ARG' must not be already defined.
- *Note Lengths::, for more about lengths.
+ An example:
+ \newlength{\graphichgt}
+
+ If you forget the backslash then you get 'Missing control sequence
+inserted'. If the command sequence already exists then you get
+something like 'LaTeX Error: Command \graphichgt already defined. Or
+name \end... illegal, see p.192 of the manual'.
+
File: latex2e.info, Node: \newsavebox, Next: \newenvironment & \renewenvironment, Prev: \newlength, Up: Definitions
12.5 '\newsavebox': Allocating a box
====================================
-Allocate a "bin" for holding a box. Synopsis:
+Synopsis:
\newsavebox{\CMD}
- Defines '\CMD' to refer to a new bin for storing boxes. Such a box
-is for holding typeset material, to use multiple times (*note Boxes::)
-or to measure or manipulate. The name '\CMD' must start with a
-backslash, '\', and must not be already defined.
+ Define '\CMD' to refer to a new "bin" for storing boxes. Such a box
+is for holding typeset material, to use multiple times or to measure or
+manipulate (*note Boxes::). The name '\CMD' must start with a
+backslash, '\', and must not already be defined.
+ The first line here sets you up to save the material for later use.
+
+ \newsavebox{\logobox}
+ \savebox{\logobox}{LoGo}
+ Our logo is \usebox{\logobox}.
+
+ The output is 'Our logo is LoGo'.
+
+ If there is an already defined box then you get something like 'LaTeX
+Error: Command \logobox already defined. Or name \end... illegal, see
+p.192 of the manual'.
+
The allocation of a box is global. This command is fragile (*note
\protect::).
@@ -6097,15 +6166,26 @@
12.6 '\newenvironment' & '\renewenvironment'
============================================
-Synopses:
+Synopses, one of:
- \newenvironment{ENV}[NARGS][OPTARGDEFAULT]{BEGDEF}{ENDDEF}
- \newenvironment*{ENV}[NARGS][OPTARGDEFAULT]{BEGDEF}{ENDDEF}
- \renewenvironment{ENV}[NARGS][OPTARGDEFAULT]{BEGDEF}{ENDDEF}
+ \newenvironment{ENV}{BEGDEF}{ENDDEF}
+ \newenvironment{ENV}[NARGS]{BEGDEF}{ENDDEF}
+ \newenvironment{ENV}[NARGS][OPTARGDEFAULT]{BEGDEF}{ENDDEF}
+ \newenvironment*{ENV}{BEGDEF}{ENDDEF}
+ \newenvironment*{ENV}[NARGS]{BEGDEF}{ENDDEF}
+ \newenvironment*{ENV}[NARGS][OPTARGDEFAULT]{BEGDEF}{ENDDEF}
+
+ or one of:
+
+ \renewenvironment{ENV}{BEGDEF}{ENDDEF}
+ \renewenvironment{ENV}[NARGS]{BEGDEF}{ENDDEF}
+ \renewenvironment{ENV}[NARGS][OPTARGDEFAULT]{BEGDEF}{ENDDEF}
+ \renewenvironment*{ENV}{BEGDEF}{ENDDEF}
+ \renewenvironment*{ENV}[NARGS]{BEGDEF}{ENDDEF}
\renewenvironment*{ENV}[NARGS][OPTARGDEFAULT]{BEGDEF}{ENDDEF}
Define or redefine the environment ENV, that is, create the construct
-'\begin{ENV} BODY \end{ENV}'.
+'\begin{ENV} ... BODY ... \end{ENV}'.
The starred form of these commands requires that the arguments not
contain multiple paragraphs of text. The body of these environments can
@@ -6122,43 +6202,42 @@
NARGS
Optional; an integer from 0 to 9 denoting the number of arguments
- of that the environment will take. When the environment is used
+ of that the environment will take. When you use the environment
these arguments appear after the '\begin', as in '\begin{ENV}{ARG1}
- .... {ARGN}'. If this argument is not present then the default is
- for the environment to have no arguments. When redefining an
+ .... {ARGN}'. Omiting this is equivalent to setting it to 0; the
+ environment will have no arguments. When redefining an
environment, the new version can have a different number of
arguments than the old version.
OPTARGDEFAULT
- Optional; if this argument is present then the first argument of
- the defined environment is optional, with default value
- OPTARGDEFAULT (which may be the empty string). If this argument is
- not present then the environment does not take an optional
- argument.
+ Optional; if this is present then the first argument of the defined
+ environment is optional, with default value OPTARGDEFAULT (which
+ may be the empty string). If this is not in the definition then
+ the environment does not take an optional argument.
- That is, when '[OPTARGDEFAULT]' is present in the environment
- definition, if '\begin{ENV}' is used with square brackets
- following, as in '\begin{ENV}[MYVAL]', then, within BEGDEFN, the
- positional parameter '#1' expands to MYVAL. If '\begin{ENV}' is
- called without square brackets following, then, within within
- BEGDEFN, the positional parameter '#1' expands to the default
- OPTARGDEFAULT. In either case, any required arguments will be
- referred to starting with '#2'.
+ That is, when this is present in the environment definition then
+ you can start the environment with square brackets, as in
+ '\begin{ENV}[OPTVAL] ... \end{ENV}'. In this case, within BEGDEFN
+ the parameter '#1' is set to the value of OPTVAL. If you call
+ '\begin{ENV}' without square brackets, then within BEGDEFN the
+ parameter '#1' is set to the value of the default OPTARGDEFAULT.
+ In either case, any required arguments start with '#2'.
- Omitting '[MYVAL]' in the call is different from having the square
+ Omitting '[MYVAL]' in the call is different than having the square
brackets with no contents, as in '[]'. The former results in '#1'
expanding to OPTARGDEFAULT; the latter results in '#1' expanding to
the empty string.
BEGDEF
Required; the text expanded at every occurrence of '\begin{ENV}'.
- Within BEGDEF, the Nth positional parameter (i.e., '#1', '#2',
- etc.) is replaced by the text of the Nth argument.
+ Within BEGDEF, the parameters '#1', '#2', ... '#NARGS', are
+ replaced by the values that you supply when you call the
+ environment; see the examples below.
ENDDEF
Required; the text expanded at every occurrence of '\end{ENV}'.
- This may not contain any positional parameters, so you cannot use
- '#1', '#2', etc., here (but see the final example below).
+ This may not contain any parameters, so you cannot use '#1', '#2',
+ etc., here (but see the final example below).
All environments, that is to say the BEGDEF code, the environment
body, and the ENDDEF code, are processed within a group. Thus, in the
@@ -6172,7 +6251,7 @@
get something like 'LaTeX Error: Environment hank undefined.'.
This example gives an environment like LaTeX's 'quotation' except
-that it will be set in smaller type:
+that it will be set in smaller type.
\newenvironment{smallquote}{%
\small\begin{quotation}
@@ -6181,7 +6260,7 @@
}
This one shows the use of arguments; it gives a quotation environment
-that cites the author:
+that cites the author.
\newenvironment{citequote}[1][Shakespeare]{%
\begin{quotation}
@@ -6191,14 +6270,14 @@
}
The author's name is optional, and defaults to 'Shakespeare'. In the
-document, use the environment like this:
+document, use the environment like this.
\begin{citequote}[Lincoln]
...
\end{citequote}
The final example shows how to save the value of an argument to use
-in ENDDEF, in this case in a box (*note \sbox::):
+in ENDDEF, in this case in a box (*note \sbox::).
\newsavebox{\quoteauthor}
\newenvironment{citequote}[1][Shakespeare]{%
@@ -6221,23 +6300,22 @@
\newtheorem{NAME}{TITLE}[NUMBERED_WITHIN]
\newtheorem{NAME}[NUMBERED_LIKE]{TITLE}
- Define a new theorem-like environment. The first form,
-'\newtheorem{NAME}{TITLE}', creates an environment that will be labelled
-with TITLE; see the first example below.
+ Define a new theorem-like environment. You can specify one of
+NUMBERED_WITHIN and NUMBERED_LIKE, or neither, but not both.
+ The first form, '\newtheorem{NAME}{TITLE}', creates an environment
+that will be labelled with TITLE; see the first example below.
+
The second form, '\newtheorem{NAME}{TITLE}[NUMBERED_WITHIN]', creates
an environment whose counter is subordinate to the existing counter
NUMBERED_WITHIN, so this counter will be reset when NUMBERED_WITHIN is
-reset.
+reset. See the second e3xample below.
The third form '\newtheorem{NAME}[NUMBERED_LIKE]{TITLE}', with
optional argument between the two required arguments, creates an
environment whose counter will share the previously defined counter
-NUMBERED_LIKE.
+NUMBERED_LIKE. See the third example.
- You can specify one of NUMBERED_WITHIN and NUMBERED_LIKE, or neither,
-but not both.
-
This command creates a counter named NAME. In addition, unless the
optional argument NUMBERED_LIKE is used, inside of the theorem-like
environment the current '\ref' value will be that of
@@ -6331,9 +6409,9 @@
=============================================
This command is obsolete. This description is here only to help with
-old documents. New document should define fonts in families through the
-New Font Selection Scheme which allows you to, for example, associate a
-boldface with a roman (*note Fonts::).
+old documents. New documents should define fonts in families through
+the New Font Selection Scheme which allows you to, for example,
+associate a boldface with a roman (*note Fonts::).
Synopsis:
@@ -6830,13 +6908,24 @@
Synopsis:
- \setlength{\LEN}{AMOUNT}
+ \setlength{LEN}{AMOUNT}
- The '\setlength' sets the value of "length command" '\LEN' to the
-VALUE argument which can be expressed in any units that LaTeX
-understands, i.e., inches ('in'), millimeters ('mm'), points ('pt'), big
-points ('bp'), etc.
+ Set the length LEN to AMOUNT. The length name LEN must begin with a
+backslash, '\'. The 'amount' can be a rubber length (*note Lengths::).
+It can be positive, negative or zero, and can be in any units that LaTeX
+understands (*note Units of length::).
+ Below, with LaTeX's defaults the first paragraph will be indented
+while the second will not.
+
+ I told the doctor I broke my leg in two places.
+
+ \setlength{\parindent}{0em}
+ He said stop going to those places.
+
+ If there is no such length LEN then you get something like 'Undefined
+control sequence. <argument> \praindent'.
+
File: latex2e.info, Node: \addtolength, Next: \settodepth, Prev: \setlength, Up: Lengths
@@ -6845,11 +6934,28 @@
Synopsis:
- \addtolength{\LEN}{AMOUNT}
+ \addtolength{LEN}{AMOUNT}
- The '\addtolength' command increments a length command '\LEN' by the
-amount specified in the AMOUNT argument, which may be negative.
+ Increment the length LEN by AMOUNT. The length name LEN must begin
+with a backslash, '\'. The 'amount' can be a rubber length (*note
+Lengths::). It can be positive, negative or zero, and can be in any
+units that LaTeX understands (*note Units of length::).
+ Below, if '\parskip' starts with the value '0pt plus 1pt'
+
+ \addtolength{\parskip}{1pt}
+ Doctor: how is the boy who swallowed the silver dollar?
+
+ Nurse: no change.
+
+ then it has the value '1pt plus 1pt' for the second paragraph.
+
+ If there is no such length LEN then you get something like 'Undefined
+control sequence. <argument> \praindent'. If you leave off the
+backslash at the start of LEN, as in '\addtolength{parindent}{1pt}',
+then you get something like 'You can't use `the letter p' after
+\advance'.
+
File: latex2e.info, Node: \settodepth, Next: \settoheight, Prev: \addtolength, Up: Lengths
@@ -6858,11 +6964,23 @@
Synopsis:
- \settodepth{\LEN}{TEXT}
+ \settodepth{LEN}{TEXT}
- The '\settodepth' command sets the value of a length command '\LEN'
-equal to the depth of the TEXT argument.
+ Set the length LEN to the depth of the TEXT argument. The length
+name LEN must begin with a backslash, '\'.
+ This will show how low the character descenders go.
+
+ \newlength{\alphabetdepth}
+ \settodepth{\alphabetdepth}{abcdefghijklmnopqrstuvwxyz}
+ \the\alphabetdepth
+
+ If there is no such length LEN then you get something like 'Undefined
+control sequence. <argument> \alphabetdepth'. If you leave the
+backslash out of LEN, as in '\settodepth{alphabetdepth}{...}' then you
+get something like 'Missing number, treated as zero. <to be read again>
+\setbox'.
+
File: latex2e.info, Node: \settoheight, Next: \settowidth, Prev: \settodepth, Up: Lengths
@@ -6871,11 +6989,23 @@
Synopsis:
- \settoheight{\LEN}{text}
+ \settoheight{LEN}{text}
- The '\settoheight' command sets the value of a length command '\LEN'
-equal to the height of the 'text' argument.
+ Sets the length LEN to the height of the 'text' argument. The length
+name LEN must begin with a backslash, '\'.
+ This will show how high the characters go.
+
+ \newlength{\alphabetheight}
+ \settoheight{\alphabetheight}{abcdefghijklmnopqrstuvwxyz}
+ \the\alphabetheight
+
+ If there is no such length LEN then you get something like 'Undefined
+control sequence. <argument> \alphabetheight'. If you leave the
+backslash out of LEN, as in '\settoheight{alphabetheight}{...}' then you
+get something like 'Missing number, treated as zero. <to be read again>
+\setbox'.
+
File: latex2e.info, Node: \settowidth, Next: Predefined lengths, Prev: \settoheight, Up: Lengths
@@ -6884,11 +7014,23 @@
Synopsis:
- \settowidth{\LEN}{TEXT}
+ \settowidth{LEN}{TEXT}
- The '\settowidth' command sets the value of the command \LEN to the
-width of the TEXT argument.
+ Set the length LEN to the width of the TEXT. The length name LEN
+must begin with a backslash, '\'.
+ This measures the width of the lower case ASCII alphabet.
+
+ \newlength{\alphabetwidth}
+ \settowidth{\alphabetwidth}{abcdefghijklmnopqrstuvwxyz}
+ \the\alphabetwidth
+
+ If there is no such length LEN then you get something like 'Undefined
+control sequence. <argument> \alphabetwidth'. If you leave the
+backslash out of LEN, as in '\settoheight{alphabetwidth}{...}' then you
+get something like 'Missing number, treated as zero. <to be read again>
+\setbox'.
+
File: latex2e.info, Node: Predefined lengths, Prev: \settowidth, Up: Lengths
@@ -11551,10 +11693,10 @@
* * prompt: Command line. (line 18)
* *-form of environment commands: \newenvironment & \renewenvironment.
- (line 16)
+ (line 27)
* *-form of sectioning commands: Sectioning. (line 31)
* *-form, defining new commands: \newcommand & \renewcommand.
- (line 16)
+ (line 25)
* .glo file: Glossaries. (line 8)
* .idx file: Indexes. (line 9)
* .ind file: Indexes. (line 23)
@@ -11995,7 +12137,6 @@
* left-justifying text: \raggedright. (line 6)
* left-justifying text, environment for: flushleft. (line 6)
* left-to-right mode: Modes. (line 6)
-* length command: \setlength. (line 10)
* lengths, adding to: \addtolength. (line 6)
* lengths, allocating new: \newlength. (line 6)
* lengths, defining and using: Lengths. (line 6)
@@ -12230,7 +12371,7 @@
(line 60)
* position, in picture: picture. (line 77)
* positional parameter: \newcommand & \renewcommand.
- (line 41)
+ (line 52)
* postscript, in letters: \ps. (line 6)
* pounds symbol: Text symbols. (line 48)
* preamble, defined: Starting and ending. (line 19)
@@ -12333,7 +12474,7 @@
* splitting the input file: Splitting the input. (line 6)
* star-variants, commands: \@ifstar. (line 6)
* starred form, defining new commands: \newcommand & \renewcommand.
- (line 16)
+ (line 25)
* starting a new page: \newpage. (line 6)
* starting a new page and clearing floats: \clearpage. (line 6)
* starting and ending: Starting and ending. (line 6)
@@ -13807,137 +13948,137 @@
Node: Footnotes of footnotes223025
Node: Definitions223729
Node: \newcommand & \renewcommand224606
-Node: \providecommand228852
-Node: \newcounter229513
-Node: \newlength230664
-Node: \newsavebox231310
-Node: \newenvironment & \renewenvironment231920
-Node: \newtheorem236651
-Node: \newfont240124
-Node: \protect241419
-Node: \ignorespaces & \ignorespacesafterend243805
-Node: Counters246554
-Node: \alph \Alph \arabic \roman \Roman \fnsymbol248227
-Node: \usecounter251056
-Node: \value251919
-Node: \setcounter252848
-Node: \addtocounter253450
-Node: \refstepcounter253915
-Node: \stepcounter254573
-Node: \day \month \year254915
-Node: Lengths255460
-Node: Units of length257250
-Node: \setlength258744
-Node: \addtolength259148
-Node: \settodepth259466
-Node: \settoheight259757
-Node: \settowidth260054
-Node: Predefined lengths260362
-Node: Making paragraphs260877
-Node: \indent261449
-Node: \noindent261911
-Node: \parskip262420
-Node: Marginal notes262678
-Node: Math formulas264490
-Node: Subscripts & superscripts266274
-Node: Math symbols267612
-Node: Math functions292941
-Node: Math accents293884
-Node: Spacing in math mode294856
-Node: Math miscellany296323
-Node: Modes298873
-Node: \ensuremath300713
-Node: Page styles301629
-Node: \maketitle302123
-Node: \pagenumbering303193
-Node: \pagestyle303689
-Node: \thispagestyle304830
-Node: Spaces305136
-Node: \hspace306006
-Node: \hfill306961
-Node: \spacefactor307353
-Node: \(SPACE) and \@310065
-Ref: \AT310208
-Node: \frenchspacing311685
-Node: \normalsfcodes312301
-Node: \(SPACE) after control sequence312490
-Node: \thinspace313401
-Node: \/313721
-Node: \hrulefill \dotfill314903
-Node: \addvspace315896
-Node: \bigskip \medskip \smallskip316942
-Node: \vfill317834
-Node: \vspace318703
-Node: Boxes319696
-Node: \mbox320408
-Node: \fbox and \framebox320695
-Node: lrbox321499
-Node: \makebox321857
-Node: \parbox322577
-Node: \raisebox324688
-Node: \savebox325301
-Node: \sbox325716
-Node: \usebox326165
-Node: Color326426
-Node: Color package options327270
-Node: Color models328916
-Node: Commands for color331225
-Node: Define colors331640
-Node: Colored text332355
-Node: Colored boxes334730
-Node: Colored pages336169
-Node: Graphics336862
-Node: Graphics package options338989
-Node: Graphics package configuration341745
-Node: \graphicspath342547
-Node: \DeclareGraphicsExtensions345470
-Node: \DeclareGraphicsRule347267
-Node: Commands for graphics350456
-Node: \includegraphics350961
-Node: \rotatebox363930
-Node: \scalebox366725
-Node: \resizebox367777
-Node: Special insertions368969
-Node: Reserved characters369773
-Node: Upper and lower case370974
-Node: Symbols by font position372889
-Node: Text symbols373509
-Node: Accents376957
-Node: Additional Latin letters379499
-Ref: Non-English characters379670
-Node: \rule380687
-Node: \today381116
-Node: Splitting the input381870
-Node: \endinput383247
-Node: \include & \includeonly384514
-Node: \input388531
-Node: Front/back matter389239
-Node: Tables of contents389444
-Node: \addcontentsline390505
-Node: \addtocontents391523
-Node: Glossaries392056
-Node: Indexes392575
-Node: Letters394208
-Node: \address397886
-Node: \cc398756
-Node: \closing399174
-Node: \encl399485
-Node: \location399900
-Node: \makelabels400169
-Node: \name401170
-Node: \opening401400
-Node: \ps401740
-Node: \signature402029
-Node: \telephone403121
-Node: Terminal input/output403486
-Node: \typein403751
-Node: \typeout404336
-Node: Command line404959
-Node: Document templates405911
-Node: beamer template406318
-Node: book template406969
-Node: tugboat template407337
-Node: Concept Index409701
-Node: Command Index474259
+Node: \providecommand229817
+Node: \newcounter230966
+Node: \newlength232711
+Node: \newsavebox233571
+Node: \newenvironment & \renewenvironment234515
+Node: \newtheorem239625
+Node: \newfont243154
+Node: \protect244450
+Node: \ignorespaces & \ignorespacesafterend246836
+Node: Counters249585
+Node: \alph \Alph \arabic \roman \Roman \fnsymbol251258
+Node: \usecounter254087
+Node: \value254950
+Node: \setcounter255879
+Node: \addtocounter256481
+Node: \refstepcounter256946
+Node: \stepcounter257604
+Node: \day \month \year257946
+Node: Lengths258491
+Node: Units of length260281
+Node: \setlength261775
+Node: \addtolength262552
+Node: \settodepth263526
+Node: \settoheight264281
+Node: \settowidth265040
+Node: Predefined lengths265823
+Node: Making paragraphs266338
+Node: \indent266910
+Node: \noindent267372
+Node: \parskip267881
+Node: Marginal notes268139
+Node: Math formulas269951
+Node: Subscripts & superscripts271735
+Node: Math symbols273073
+Node: Math functions298402
+Node: Math accents299345
+Node: Spacing in math mode300317
+Node: Math miscellany301784
+Node: Modes304334
+Node: \ensuremath306174
+Node: Page styles307090
+Node: \maketitle307584
+Node: \pagenumbering308654
+Node: \pagestyle309150
+Node: \thispagestyle310291
+Node: Spaces310597
+Node: \hspace311467
+Node: \hfill312422
+Node: \spacefactor312814
+Node: \(SPACE) and \@315526
+Ref: \AT315669
+Node: \frenchspacing317146
+Node: \normalsfcodes317762
+Node: \(SPACE) after control sequence317951
+Node: \thinspace318862
+Node: \/319182
+Node: \hrulefill \dotfill320364
+Node: \addvspace321357
+Node: \bigskip \medskip \smallskip322403
+Node: \vfill323295
+Node: \vspace324164
+Node: Boxes325157
+Node: \mbox325869
+Node: \fbox and \framebox326156
+Node: lrbox326960
+Node: \makebox327318
+Node: \parbox328038
+Node: \raisebox330149
+Node: \savebox330762
+Node: \sbox331177
+Node: \usebox331626
+Node: Color331887
+Node: Color package options332731
+Node: Color models334377
+Node: Commands for color336686
+Node: Define colors337101
+Node: Colored text337816
+Node: Colored boxes340191
+Node: Colored pages341630
+Node: Graphics342323
+Node: Graphics package options344450
+Node: Graphics package configuration347206
+Node: \graphicspath348008
+Node: \DeclareGraphicsExtensions350931
+Node: \DeclareGraphicsRule352728
+Node: Commands for graphics355917
+Node: \includegraphics356422
+Node: \rotatebox369391
+Node: \scalebox372186
+Node: \resizebox373238
+Node: Special insertions374430
+Node: Reserved characters375234
+Node: Upper and lower case376435
+Node: Symbols by font position378350
+Node: Text symbols378970
+Node: Accents382418
+Node: Additional Latin letters384960
+Ref: Non-English characters385131
+Node: \rule386148
+Node: \today386577
+Node: Splitting the input387331
+Node: \endinput388708
+Node: \include & \includeonly389975
+Node: \input393992
+Node: Front/back matter394700
+Node: Tables of contents394905
+Node: \addcontentsline395966
+Node: \addtocontents396984
+Node: Glossaries397517
+Node: Indexes398036
+Node: Letters399669
+Node: \address403347
+Node: \cc404217
+Node: \closing404635
+Node: \encl404946
+Node: \location405361
+Node: \makelabels405630
+Node: \name406631
+Node: \opening406861
+Node: \ps407201
+Node: \signature407490
+Node: \telephone408582
+Node: Terminal input/output408947
+Node: \typein409212
+Node: \typeout409797
+Node: Command line410420
+Node: Document templates411372
+Node: beamer template411779
+Node: book template412430
+Node: tugboat template412798
+Node: Concept Index415162
+Node: Command Index479647
End Tag Table
Modified: trunk/latex2e.pdf
===================================================================
(Binary files differ)
Modified: trunk/latex2e.texi
===================================================================
--- trunk/latex2e.texi 2018-05-31 16:05:41 UTC (rev 634)
+++ trunk/latex2e.texi 2018-05-31 16:43:51 UTC (rev 635)
@@ -7265,24 +7265,38 @@
@cindex defining a new command
@cindex new commands, defining
-Synopses:
+Synopses, one of:
@example
- \newcommand@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
- \newcommand*@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
+\newcommand@{\@var{cmd}@}@{@var{defn}@}
+\newcommand@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@}
+\newcommand@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
+\newcommand*@{\@var{cmd}@}@{@var{defn}@}
+\newcommand*@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@}
+\newcommand*@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
+ at end example
+
+or one of:
+
+ at example
+\renewcommand@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@}
+\renewcommand@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@}
\renewcommand@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
+\renewcommand*@{\@var{cmd}@}@{@var{defn}@}
+\renewcommand*@{\@var{cmd}@}[@var{nargs}]@{@var{defn}@}
\renewcommand*@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
@end example
Define or redefine a command. See also the discussion of
@code{\DeclareRobustCommand} in @ref{Class and package commands}.
-
@cindex starred form, defining new commands
@cindex *-form, defining new commands
-The starred form of these two commands requires that the arguments not
-contain multiple paragraphs of text (not @code{\long}, in plain @TeX{}
-terms).
+The starred form of these two requires that the arguments not contain
+multiple paragraphs of text (in plain @TeX{} terms that it not be
+ at code{\long}).
+These are the parameters:
+
@table @var
@item cmd
@@ -7293,9 +7307,9 @@
@item nargs
Optional; an integer from 0 to 9, specifying the number of arguments
-that the command can take, including any optional argument. If this
-argument is not present, the default is for the command to have no
-arguments. When redefining a command, the new version can have a
+that the command can take, including any optional argument. Omitting
+this argument is the same as specifying 0, meaning that the command has
+no arguments. If you redefine a command, the new version can have a
different number of arguments than the old version.
@item optargdefault
@@ -7305,36 +7319,36 @@
@code{\@var{cmd}} does not take an optional argument.
@cindex positional parameter
-That is, if @code{\@var{cmd}} is used with square brackets following,
-as in @code{\@var{cmd}[@var{myval}]}, then within @var{defn} the first
- at dfn{positional parameter} @code{#1} expands @var{myval}. On the
-other hand, if @code{\@var{cmd}} is called without square brackets
-following, then within @var{defn} the positional parameter @code{#1}
-expands to the default @var{optargdefault}. In either case, any
-required arguments will be referred to starting with @code{#2}.
+That is, if @code{\@var{cmd}} is used with square brackets, as in
+ at code{\@var{cmd}[@var{optval}]}, then within @var{defn} then @code{#1}
+is set to the value of @var{optval}. On the other hand, if
+ at code{\@var{cmd}} is called without the square brackets, then within
+ at var{defn} the parameter @code{#1} is set to the value of
+ at var{optargdefault}. In either case, the required arguments start with
+ at code{#2}.
-Omitting @code{[@var{myval}]} in a call is different from having the
-square brackets with no contents, as in @code{[]}. The former results
-in @code{#1} expanding to @var{optargdefault}; the latter results in
- at code{#1} expanding to the empty string.
+Omitting @code{[@var{optargdefault}]} is different from having the
+square brackets with no contents, as in @code{[]}. The former sets
+ at code{#1} to the value of @var{optargdefault}; the latter sets @code{#1}
+to the empty string.
@item defn
-The text to be substituted for every occurrence of @code{\@var{cmd}}; the
-positional parameter @code{#@var{n}} in @var{defn} is replaced by
-the text of the @var{n}th argument.
+Required; the text to be substituted for every occurrence of
+ at code{\@var{cmd}}. The parameters @code{#1}, @code{#2},
+... @code{#@var{nargs}} are replaced by the values that you supply when
+you call the command (or by the default value if there is an optional
+argument and you don't exercise the option).
@end table
@TeX{} ignores spaces in the source following an alphabetic control
sequence, as in @samp{\cmd }. If you actually want a space there, one
-solution is to type @code{@{@}} after the command (@samp{\cmd@{@} };
+solution is to type @code{@{@}} after the command (@samp{\cmd@{@} }, and
another solution is to use an explicit control space (@samp{\cmd\ }).
A simple example of defining a new command:
- at code{\newcommand@{\RS@}@{Robin Smith@}} results in
- at code{\RS} being replaced by the longer text.
-
-Redefining an existing command is similar:
+ at code{\newcommand@{\RS@}@{Robin Smith@}} results in @code{\RS} being
+replaced by the longer text. Redefining an existing command is similar:
@code{\renewcommand@{\qedsymbol@}@{@{\small QED@}@}}.
If you try to define a command and the name has already been used then
@@ -7343,43 +7357,58 @@
to redefine a command and the name has not yet been used then you get
something like @samp{LaTeX Error: \hank undefined}.
-Here's a command definition with one required argument:
+Here the first command definition has no arguments, and the second has
+one required argument.
@example
+\newcommand@{\student@}@{Ms~O'Leary@}
\newcommand@{\defref@}[1]@{Definition~\ref@{#1@}@}
@end example
- at noindent Then, @code{\defref@{def:basis@}} expands to
- at code{Definition~\ref@{def:basis@}}, which will ultimately expand to
+ at noindent Use the first as in @code{I highly recommend \student@{@} to you}.
+The second has a variable, so that @code{\defref@{def:basis@}} expands
+to @code{Definition~\ref@{def:basis@}}, which ultimately expands to
something like @samp{Definition~3.14}.
-An example with two required arguments:
+Similarly, but with two required arguments:
@code{\newcommand@{\nbym@}[2]@{$#1 \times #2$@}} is invoked as
@code{\nbym@{2@}@{k@}}.
-An example with an optional argument:
+This example has an optional argument.
@example
\newcommand@{\salutation@}[1][Sir or Madam]@{Dear #1:@}
@end example
- at noindent Then, @code{\salutation} gives @samp{Dear Sir or Madam:} while
+ at noindent Then @code{\salutation} gives @samp{Dear Sir or Madam:} while
@code{\salutation[John]} gives @samp{Dear John:}. And
@code{\salutation[]} gives @samp{Dear :}.
-The braces around @var{defn} do not define a group, that is, they do
-not delimit the scope of the result of expanding @var{defn}. So
- at code{\newcommand@{\shipname@}[1]@{\it #1@}} is problematic; in this
-sentence,
+This example has an optional argument and two required arguments.
@example
+\newcommand@{\lawyers@}[3][company]@{#2, #3, and~#1@}
+I employ \lawyers[Howe]@{Dewey@}@{Cheatem@}.
+ at end example
+
+The ouptut is @samp{I employ Dewey, Cheatem, and Howe}. The optional
+argument, the @code{Howe}, is associated with @code{#1}, while
+ at code{Dewey} and @code{Cheatem} are associated with @code{#2}
+and at tie{}@code{#3}. Because of the optional argument,
+ at code{\lawyers@{Dewey@}@{Cheatem@}} will give the output @samp{I employ
+Dewey, Cheatem, and company}.
+
+The braces around @var{defn} do not define a group, that is, they do not
+delimit the scope of the result of expanding @var{defn}. For example,
+with @code{\newcommand@{\shipname@}[1]@{\it #1@}}, in this sentence,
+
+ at example
The \shipname@{Monitor@} met the \shipname@{Merrimac@}.
@end example
- at noindent the words @samp{met the} would incorrectly be in italics. Another
-pair of braces in the definition is needed, like this:
- at code{\newcommand@{\shipname@}[1]@{@{\it #1@}@}}. Those braces are
-part of the definition and thus do define a group.
+ at noindent the words @samp{met the} would incorrectly be in italics. The
+solution is to put another pair of braces inside the definition:
+ at code{\newcommand@{\shipname@}[1]@{@{\it #1@}@}}.
@node \providecommand
@@ -7390,21 +7419,37 @@
@cindex defining a new command
@cindex new commands, defining
-Defines a command, as long as no command of this name already exists.
-Synopses:
+Synopses, one of:
@example
+\providecommand@{@var{cmd}@}@{@var{defn}@}
+\providecommand@{@var{cmd}@}[@var{nargs}]@{@var{defn}@}
\providecommand@{@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
+\providecommand*@{@var{cmd}@}@{@var{defn}@}
+\providecommand*@{@var{cmd}@}[@var{nargs}]@{@var{defn}@}
\providecommand*@{@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
@end example
+Defines a command, as long as no command of this name already exists.
If no command of this name already exists then this has the same effect
-as @code{\newcommand} (@pxref{\newcommand & \renewcommand}). If a
-command of this name already exists then this definition does nothing.
-This is particularly useful in a style file, or other file that may be
-loaded more than once.
+as @code{\newcommand}. If a command of this name already exists then
+this definition does nothing. This is particularly useful in a file
+that may be loaded more than once, such as a style file.
+ at xref{\newcommand & \renewcommand} for the description of the arguments.
+This example
+ at example
+\providecommand@{\myaffiliation@}@{Saint Michael's College@}
+\providecommand@{\myaffiliation@}@{Saint Michael's College@}
+From \myaffiliation.
+ at end example
+
+outputs @samp{From Saint Michael's College}. Unlike
+ at code{\newcommand}, the repeated use of @code{\providecommand} does not
+give an error.
+
+
@node \newcounter
@section @code{\newcounter}: Allocating a counter
@@ -7418,28 +7463,45 @@
\newcounter@{@var{countername}@}[@var{supercounter}]
@end example
-Globally defines a new counter named @var{countername} and initialize
-the new counter to zero.
+Globally defines a new counter named @var{countername} and initialize it
+to zero (@pxref{Counters}).
The name @var{countername} must consist of letters only. It does not
begin with a backslash. This name must not already be in use by another
counter.
-When you use the optional argument @code{[@var{supercounter}]} then
- at var{countername} the counter foo will be reset whenever the counter
+When you use the optional argument @code{[@var{supercounter}]} then the
+counter @var{countername} will be reset to zero whenever
@var{supercounter} is incremented. For example, ordinarily
- at code{subsection} is numbered within @code{section} so that any time
- at var{supercounter} is incremented, either with @code{\stepcounter}
+ at code{subsection} is numbered within @code{section} so that any time you
+increment @var{section}, either with @code{\stepcounter}
(@pxref{\stepcounter}) or @code{\refstepcounter}
-(@pxref{\refstepcounter}), then @var{countername} is reset to zero.
+(@pxref{\refstepcounter}), then @LaTeX{} will reset @var{subsection} to
+zero.
-The super counter must already exist. If you enter
- at code{\newcounter@{jh@}[lh]} and @code{lh} is not a defined counter
-then you will get @samp{LaTeX Error: No counter 'lh' defined.}
+This example
- at xref{Counters}, for more information about counters.
+ at example
+\newcounter@{asuper@} \setcounter@{asuper@}@{1@}
+\newcounter@{asub@}[asuper] \setcounter@{asub@}@{3@} % Note the optional `asuper'
+The value of asuper is \arabic@{asuper@} and that of asub is \arabic@{asub@}.
+\stepcounter@{asuper@}
+Now asuper is \arabic@{asuper@} while asub is \arabic@{asub@}.
+ at end example
+produces @samp{The value of asuper is 1 and that of asub is 3} and
+ at samp{Now asuper is 2 while asub is 0}.
+If the counter already exists, for instance by entering @code{asuper}
+twice, then you get something like @samp{LaTeX Error: Command \c@@asuper
+already defined. Or name \end... illegal, see p.192 of the manual.}.
+
+If you use the optional argument then the super counter must already
+exist. Entering @code{\newcounter@{jh@}[lh]} when @code{lh} is not a
+defined counter will get you @samp{LaTeX Error: No counter 'lh'
+defined.}
+
+
@node \newlength
@section @code{\newlength}: Allocating a length
@@ -7449,39 +7511,62 @@
@cindex skip register, plain @TeX{}
@cindex glue register, plain @TeX{}
-Allocate a new @dfn{length} register. Synopsis:
+Synopsis:
@example
\newlength@{\@var{arg}@}
@end example
-This command takes one required argument, which must begin with a
-backslash, @code{\}. It creates a new length register named
- at code{\@var{arg}}, which is a place to hold (rubber) lengths such as
- at code{1in plus.2in minus.1in} (what plain @TeX{} calls a @code{skip}
-register). The register gets an initial value of zero. The control
-sequence @code{\@var{arg}} must not already be defined.
+Allocate a new length register (@pxref{Lengths}). The required argument
+must begin with a backslash, @code{\}. The new register hold rubber
+lengths such as @code{72.27pt} or @code{1in plus.2in minus.1in} (a
+ at LaTeX{} length register is what plain @TeX{} calls a @code{skip}
+register). The initial value is zero. The control sequence
+ at code{\@var{arg}} must not be already defined.
- at xref{Lengths}, for more about lengths.
+An example:
+ at example
+\newlength@{\graphichgt@}
+ at end example
+If you forget the backslash then you get @samp{Missing control sequence
+inserted}. If the command sequence already exists then you get
+something like @samp{LaTeX Error: Command \graphichgt already defined.
+Or name \end... illegal, see p.192 of the manual}.
+
+
@node \newsavebox
@section @code{\newsavebox}: Allocating a box
@findex \newsavebox
@cindex box, allocating new
-Allocate a ``bin'' for holding a box. Synopsis:
+Synopsis:
@example
\newsavebox@{\@var{cmd}@}
@end example
-Defines @code{\@var{cmd}} to refer to a new bin for storing boxes. Such
-a box is for holding typeset material, to use multiple times
-(@pxref{Boxes}) or to measure or manipulate. The name @code{\@var{cmd}}
-must start with a backslash, @code{\}, and must not be already defined.
+Define @code{\@var{cmd}} to refer to a new ``bin'' for storing boxes.
+Such a box is for holding typeset material, to use multiple times or to
+measure or manipulate (@pxref{Boxes}). The name @code{\@var{cmd}} must
+start with a backslash, @code{\}, and must not already be defined.
+The first line here sets you up to save the material for later use.
+
+ at example
+\newsavebox@{\logobox@}
+\savebox@{\logobox@}@{LoGo@}
+Our logo is \usebox@{\logobox@}.
+ at end example
+
+The output is @samp{Our logo is LoGo}.
+
+If there is an already defined box then you get something like
+ at samp{LaTeX Error: Command \logobox already defined. Or name
+\end... illegal, see p.192 of the manual}.
+
The allocation of a box is global. This command is fragile
(@pxref{\protect}).
@@ -7495,17 +7580,30 @@
@cindex defining new environments
@cindex redefining environments
-Synopses:
+Synopses, one of:
@example
- \newenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@}
- \newenvironment*@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@}
- \renewenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@}
+\newenvironment@{@var{env}@}@{@var{begdef}@}@{@var{enddef}@}
+\newenvironment@{@var{env}@}[@var{nargs}]@{@var{begdef}@}@{@var{enddef}@}
+\newenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@}
+\newenvironment*@{@var{env}@}@{@var{begdef}@}@{@var{enddef}@}
+\newenvironment*@{@var{env}@}[@var{nargs}]@{@var{begdef}@}@{@var{enddef}@}
+\newenvironment*@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@}
+ at end example
+
+or one of:
+
+ at example
+\renewenvironment@{@var{env}@}@{@var{begdef}@}@{@var{enddef}@}
+\renewenvironment@{@var{env}@}[@var{nargs}]@{@var{begdef}@}@{@var{enddef}@}
+\renewenvironment@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@}
+\renewenvironment*@{@var{env}@}@{@var{begdef}@}@{@var{enddef}@}
+\renewenvironment*@{@var{env}@}[@var{nargs}]@{@var{begdef}@}@{@var{enddef}@}
\renewenvironment*@{@var{env}@}[@var{nargs}][@var{optargdefault}]@{@var{begdef}@}@{@var{enddef}@}
@end example
Define or redefine the environment @var{env}, that is, create the
-construct @code{\begin@{@var{env}@} @var{body} \end@{@var{env}@}}.
+construct @code{\begin@{@var{env}@} ... @var{body} ... \end@{@var{env}@}}.
@cindex @code{*}-form of environment commands
The starred form of these commands requires that the arguments not
@@ -7524,45 +7622,45 @@
@item nargs
Optional; an integer from 0 to 9 denoting the number of arguments of
-that the environment will take. When the environment is used these
+that the environment will take. When you use the environment these
arguments appear after the @code{\begin}, as in
- at code{\begin@{@var{env}@}@{@var{arg1}@} .... @{@var{argn}@}}. If this
-argument is not present then the default is for the environment to have
-no arguments. When redefining an environment, the new version can have
-a different number of arguments than the old version.
+ at code{\begin@{@var{env}@}@{@var{arg1}@} .... @{@var{argn}@}}. Omiting
+this is equivalent to setting it to 0; the environment will have no
+arguments. When redefining an environment, the new version can have a
+different number of arguments than the old version.
@item optargdefault
-Optional; if this argument is present then the first argument of the
-defined environment is optional, with default value @var{optargdefault}
-(which may be the empty string). If this argument is not present then
-the environment does not take an optional argument.
+Optional; if this is present then the first argument of the defined
+environment is optional, with default value @var{optargdefault} (which
+may be the empty string). If this is not in the definition then the
+environment does not take an optional argument.
-That is, when @code{[@var{optargdefault}]} is present in the
-environment definition, if @code{\begin@{@var{env}@}} is used with
-square brackets following, as in
- at code{\begin@{@var{env}@}[@var{myval}]}, then, within @var{begdefn},
-the positional parameter @code{#1} expands to @var{myval}. If
- at code{\begin@{@var{env}@}} is called without square brackets
-following, then, within within @var{begdefn}, the positional parameter
- at code{#1} expands to the default @var{optargdefault}. In either case,
-any required arguments will be referred to starting with @code{#2}.
+That is, when this is present in the environment definition then you can
+start the environment with square brackets, as in
+ at code{\begin@{@var{env}@}[@var{optval}] ... \end@{@var{env}@}}. In this
+case, within @var{begdefn} the parameter @code{#1} is set to the value
+of @var{optval}. If you call @code{\begin@{@var{env}@}} without square
+brackets, then within @var{begdefn} the parameter @code{#1} is set to
+the value of the default @var{optargdefault}. In either case, any
+required arguments start with @code{#2}.
-Omitting @code{[@var{myval}]} in the call is different from having the
+Omitting @code{[@var{myval}]} in the call is different than having the
square brackets with no contents, as in @code{[]}. The former results
in @code{#1} expanding to @var{optargdefault}; the latter results in
@code{#1} expanding to the empty string.
@item begdef
Required; the text expanded at every occurrence of
- at code{\begin@{@var{env}@}}. Within @var{begdef}, the @var{n}th
-positional parameter (i.e., @code{#1}, @code{#2}, etc.) is replaced by
-the text of the @var{n}th argument.
+ at code{\begin@{@var{env}@}}. Within @var{begdef}, the parameters
+ at code{#1}, @code{#2}, ... @code{#@var{nargs}}, are replaced by the
+values that you supply when you call the environment; see the examples
+below.
@item enddef
Required; the text expanded at every occurrence of
- at code{\end@{@var{env}@}}. This may not contain any positional
-parameters, so you cannot use @code{#1}, @code{#2}, etc., here (but see
-the final example below).
+ at code{\end@{@var{env}@}}. This may not contain any parameters, so you
+cannot use @code{#1}, @code{#2}, etc., here (but see the final example
+below).
@end table
@@ -7578,7 +7676,7 @@
get something like @samp{LaTeX Error: Environment hank undefined.}.
This example gives an environment like @LaTeX{}'s @code{quotation}
-except that it will be set in smaller type:
+except that it will be set in smaller type.
@example
\newenvironment@{smallquote@}@{%
@@ -7589,7 +7687,7 @@
@end example
This one shows the use of arguments; it gives a quotation environment
-that cites the author:
+that cites the author.
@example
\newenvironment@{citequote@}[1][Shakespeare]@{%
@@ -7601,7 +7699,7 @@
@end example
@noindent The author's name is optional, and defaults to @samp{Shakespeare}.
-In the document, use the environment like this:
+In the document, use the environment like this.
@example
\begin@{citequote@}[Lincoln]
@@ -7610,7 +7708,7 @@
@end example
The final example shows how to save the value of an argument to use in
- at var{enddef}, in this case in a box (@pxref{\sbox}):
+ at var{enddef}, in this case in a box (@pxref{\sbox}).
@example
\newsavebox@{\quoteauthor@}
@@ -7641,25 +7739,25 @@
\newtheorem@{@var{name}@}[@var{numbered_like}]@{@var{title}@}
@end example
-Define a new theorem-like environment. The first form,
- at code{\newtheorem@{@var{name}@}@{@var{title}@}}, creates an environment
-that will be labelled with @var{title}; see the first example below.
+Define a new theorem-like environment. You can specify one of
+ at var{numbered_within} and @var{numbered_like}, or neither, but not both.
+The first form, @code{\newtheorem@{@var{name}@}@{@var{title}@}}, creates
+an environment that will be labelled with @var{title}; see the first
+example below.
+
The second form,
@code{\newtheorem@{@var{name}@}@{@var{title}@}[@var{numbered_within}]},
creates an environment whose counter is subordinate to the existing
counter @var{numbered_within}, so this counter will be reset when
- at var{numbered_within} is reset.
+ at var{numbered_within} is reset. See the second e3xample below.
The third form
@code{\newtheorem@{@var{name}@}[@var{numbered_like}]@{@var{title}@}},
with optional argument between the two required arguments, creates an
environment whose counter will share the previously defined counter
- at var{numbered_like}.
+ at var{numbered_like}. See the third example.
-You can specify one of @var{numbered_within} and @var{numbered_like},
-or neither, but not both.
-
This command creates a counter named @var{name}. In addition, unless
the optional argument @var{numbered_like} is used, inside of the
theorem-like environment the current @code{\ref} value will be that of
@@ -7766,8 +7864,8 @@
@c @findex .fd @r{file}
This command is obsolete. This description is here only to help with old
-documents. New document should define fonts in families through the New
-Font Selection Scheme which allows you to, for example, associate a
+documents. New documents should define fonts in families through the
+New Font Selection Scheme which allows you to, for example, associate a
boldface with a roman (@pxref{Fonts}).
@c This is done either by using
@c @file{.fd} files or through the use of an engine that can access system
@@ -8378,16 +8476,29 @@
Synopsis:
@example
-\setlength@{@var{\len}@}@{@var{amount}@}
+\setlength@{@var{len}@}@{@var{amount}@}
@end example
-The @code{\setlength} sets the value of @dfn{length command}
- at cindex length command
- at code{\@var{len}} to the @var{value} argument which can be expressed in any
-units that @LaTeX{} understands, i.e., inches (@code{in}), millimeters
-(@code{mm}), points (@code{pt}), big points (@code{bp}), etc.
+Set the length @var{len} to @var{amount}. The length name @var{len}
+must begin with a backslash, @code{\}. The @code{amount} can be a
+rubber length (@pxref{Lengths}). It can be positive, negative or zero,
+and can be in any units that @LaTeX{} understands (@pxref{Units of
+length}).
+Below, with @LaTeX{}'s defaults the first paragraph will be indented
+while the second will not.
+ at example
+I told the doctor I broke my leg in two places.
+
+\setlength@{\parindent@}@{0em@}
+He said stop going to those places.
+ at end example
+
+If there is no such length @var{len} then you get something like
+ at samp{Undefined control sequence. <argument> \praindent}.
+
+
@node \addtolength
@section @code{\addtolength}
@@ -8397,15 +8508,33 @@
Synopsis:
@example
-\addtolength@{@var{\len}@}@{@var{amount}@}
+\addtolength@{@var{len}@}@{@var{amount}@}
@end example
+Increment the length @var{len} by @var{amount}. The length name
+ at var{len} must begin with a backslash, @code{\}. The @code{amount} can
+be a rubber length (@pxref{Lengths}). It can be positive, negative or
+zero, and can be in any units that @LaTeX{} understands (@pxref{Units of
+length}).
-The @code{\addtolength} command increments a length command @code{\@var{len}}
-by the amount specified in the @var{amount} argument, which may be
-negative.
+Below, if @code{\parskip} starts with the value @code{0pt plus 1pt}
+ at example
+\addtolength@{\parskip@}@{1pt@}
+Doctor: how is the boy who swallowed the silver dollar?
+Nurse: no change.
+ at end example
+
+then it has the value @code{1pt plus 1pt} for the second paragraph.
+
+If there is no such length @var{len} then you get something like
+ at samp{Undefined control sequence. <argument> \praindent}. If you leave
+off the backslash at the start of @var{len}, as in
+ at code{\addtolength@{parindent@}@{1pt@}}, then you get something like
+ at samp{You can't use `the letter p' after \advance}.
+
+
@node \settodepth
@section @code{\settodepth}
@@ -8414,13 +8543,27 @@
Synopsis:
@example
-\settodepth@{\@var{len}@}@{@var{text}@}
+\settodepth@{@var{len}@}@{@var{text}@}
@end example
-The @code{\settodepth} command sets the value of a length command
- at code{\@var{len}} equal to the depth of the @var{text} argument.
+Set the length @var{len} to the depth of the @var{text} argument. The
+length name @var{len} must begin with a backslash, @code{\}.
+This will show how low the character descenders go.
+ at example
+\newlength@{\alphabetdepth@}
+\settodepth@{\alphabetdepth@}@{abcdefghijklmnopqrstuvwxyz@}
+\the\alphabetdepth
+ at end example
+
+If there is no such length @var{len} then you get something like
+ at samp{Undefined control sequence. <argument> \alphabetdepth}. If you
+leave the backslash out of @var{len}, as in
+ at code{\settodepth@{alphabetdepth@}@{...@}} then you get something like
+ at samp{Missing number, treated as zero. <to be read again> \setbox}.
+
+
@node \settoheight
@section @code{\settoheight}
@@ -8429,14 +8572,28 @@
Synopsis:
@example
-\settoheight@{\@var{len}@}@{text@}
+\settoheight@{@var{len}@}@{text@}
@end example
-The @code{\settoheight} command sets the value of a length command @code{\@var{len}}
-equal to the height of the @code{text} argument.
+Sets the length @var{len} to the height of the
+ at code{text} argument. The length name @var{len} must begin with a
+backslash, @code{\}.
+This will show how high the characters go.
+ at example
+\newlength@{\alphabetheight@}
+\settoheight@{\alphabetheight@}@{abcdefghijklmnopqrstuvwxyz@}
+\the\alphabetheight
+ at end example
+If there is no such length @var{len} then you get something like
+ at samp{Undefined control sequence. <argument> \alphabetheight}. If you
+leave the backslash out of @var{len}, as in
+ at code{\settoheight@{alphabetheight@}@{...@}} then you get something like
+ at samp{Missing number, treated as zero. <to be read again> \setbox}.
+
+
@node \settowidth
@section @code{\settowidth@{\@var{len}@}@{@var{text}@}}
@@ -8445,13 +8602,27 @@
Synopsis:
@example
-\settowidth@{\@var{len}@}@{@var{text}@}
+\settowidth@{@var{len}@}@{@var{text}@}
@end example
-The @code{\settowidth} command sets the value of the command @var{\len}
-to the width of the @var{text} argument.
+Set the length @var{len} to the width of the @var{text}. The length
+name @var{len} must begin with a backslash, @code{\}.
+This measures the width of the lower case ASCII alphabet.
+ at example
+\newlength@{\alphabetwidth@}
+\settowidth@{\alphabetwidth@}@{abcdefghijklmnopqrstuvwxyz@}
+\the\alphabetwidth
+ at end example
+
+If there is no such length @var{len} then you get something like
+ at samp{Undefined control sequence. <argument> \alphabetwidth}. If you
+leave the backslash out of @var{len}, as in
+ at code{\settoheight@{alphabetwidth@}@{...@}} then you get something like
+ at samp{Missing number, treated as zero. <to be read again> \setbox}.
+
+
@node Predefined lengths
@section Predefined lengths
More information about the latexrefman-commits
mailing list