[latexrefman-commits] r342 - in /trunk: ChangeLog latex2e.texi

[jhefferon at domain.hid]

Author: jhefferon
Date: Mon May 25 21:21:37 2015
New Revision: 342

URL: http://svn.gna.org/viewcvs/latexrefman?rev=342&view=rev
Log:
expand newcommand

Modified:
    trunk/ChangeLog
    trunk/latex2e.texi

Modified: trunk/ChangeLog
URL: http://svn.gna.org/viewcvs/latexrefman/trunk/ChangeLog?rev=342&r1=341&r2=342&view=diff
==============================================================================
--- trunk/ChangeLog	(original)
+++ trunk/ChangeLog	Mon May 25 21:21:37 2015
@@ -1,3 +1,8 @@
+2015-05-25  Jim Hefferon  <jhefferon at domain.hid>
+
+	* latex2e.texi (\newcommand & \renewcommand): Add examples.  Drop
+	square brackets around * since square brackets are significant.
+
 2015-05-22  Jim Hefferon  <jhefferon at domain.hid>
 
 	* latex2e.texi (\label): Add example of \label picking up

Modified: trunk/latex2e.texi
URL: http://svn.gna.org/viewcvs/latexrefman/trunk/latex2e.texi?rev=342&r1=341&r2=342&view=diff
==============================================================================
--- trunk/latex2e.texi	(original)
+++ trunk/latex2e.texi	Mon May 25 21:21:37 2015
@@ -1320,7 +1320,7 @@
 punctuation characters.  Upper and lowercase letters are distinguished,
 as usual.
 
-A common convention to use labels consisting of a prefix and a suffix
+A common convention is to use labels consisting of a prefix and a suffix
 separated by a colon or period. One advantage is that it helps avoid
 accidentally creating two labels with the same name.  Some commonly-used
 prefixes:
@@ -3713,6 +3713,7 @@
 @section @code{\newcommand} & @code{\renewcommand}
 @findex \newcommand
 @cindex commands, defining new ones
+ at cindex commands, redefining
 @cindex defining a new command
 @cindex new commands, defining
 
@@ -3720,34 +3721,37 @@
 command, respectively.  Synopses:
 
 @example
-  \newcommand[*]@{@var{cmd}@}[@var{nargs}][@var{optargval}]@{@var{defn}@}
-\renewcommand[*]@{@var{cmd}@}[@var{nargs}][@var{optargval}]@{@var{defn}@}
- at domain.hid example
+  \newcommand at domain.hid}@}
+  \newcommand*@{@var{cmd}@}[@var{nargs}][@var{optargval}]@{@var{defn}@}
+\renewcommand at domain.hid}@}
+\renewcommand*@{@var{cmd}@}[@var{nargs}][@var{optargval}]@{@var{defn}@}
+ at end example
+
+The *-form of these two commands requires that the arguments not contain
+multiple paragraphs of text (not @code{\long}, in plain @TeX{} terms).
 
 @table @var
- at domain.hid @code{*}
- at domain.hid *-form of defining new commands
-The *-form of these commands requires that the arguments not contain
-multiple paragraphs of text (not @code{\long}, in plain @TeX{} terms).
 
 @item cmd
-The command name, beginning with @code{\}.  For @code{\newcommand}, it
-must not be already defined and must not begin with @code{\end}; for
+The command name.  It must begin with @code{\}.  For @code{\newcommand},
+it must not be already defined and must not begin with @code{\end}; for
 @code{\renewcommand}, it must already be defined.
 
 @item nargs
-An optional integer from 1 to 9 specifying the number of arguments
-that the command will take.  The default is for the command to have no
-arguments.
+An integer from 0 to 9, specifying the number of arguments that the
+command will take.  The default is for the command to have no arguments;
+this is what you get if you omit the @code{[@var{nargs}]}.
 
 @item optargval
-If this optional parameter is present, it means that the first
-argument of command @var{cmd} is optional and its default value (i.e.,
-if it is not specified in the call) is @var{optarg}.  In otherwise,
-when calling the macro, if no @code{[@var{value}]} is given after
- at domain.hid is different from having @code{[]} for an
-empty @var{value}---then string @samp{@var{optargval}} becomes the
-value of @code{#1} within @var{defn} when the macro is expanded.
+If this parameter is present then the first argument of command
+ at var{\cmd} is optional, with the default value @var{optarg}.  That is,
+if the macro is called with the command name followed by square brackets
+ at code{@var{\cmd}[@var{value}]} then within @var{defn} the @code{#1}
+expands to the contents of the square brackets @var{value}.  If the
+macro is called not followed by square brackets then within @var{defn}
+the @code{#1} expands to the default @var{optargval}.  (Note that
+omitting @code{[@var{value}]} is different from having the square
+brackets with no contents @code{[]}, which is an empty @var{value}.)
 
 @item defn
 The text to be substituted for every occurrence of @code{cmd}; a
@@ -3756,6 +3760,28 @@
 
 @end table
 
+A simple example of defining a new command is that
+ at code{\newcommand at domain.hid Hef at domain.hid@}} will cause the
+abbreviation @code{\JH} to be replaced by the longer text.  Redefining a
+command is basically the same:
+ at code{\renewcommand at domain.hid QED@}@}}.  When redefining a
+command, the new version can have a different number of arguments than
+the old version.
+
+
+This command definition uses arguments
+ at code{\newcommand at domain.hid@}@}}, so that
+ at code{\defreference at domain.hid@}} will expand to something like
+ at samp{Definition~3.14}.  You can use up to nine arguments so this
+command @code{\newcommand at domain.hid@}} is invoked as
+ at code{\nbym at domain.hid@}}.
+
+An example of the use of optional arguments is that with this definition
+ at code{\newcommand at domain.hid or Madam]@{Dear #1:@}}
+then @code{\salutation} will give @samp{Dear Sir or Madam:} while
+ at code{\salutation[John]} gives @samp{Dear John:}.
+
+ at c xx \ensuremath, ?xspace or at least some comment about swallowing a space.
 @c xx \providecommand, * form (non-\long)
 
 @node \newcounter