I want to start learning how to use \newcommand \newenvironment and \def any suggestions where to start?

Question

I have been using LaTeX for a long time now, and I find myself often going to this website to solve my problems. This often includes copy pasting codes which include \newcommand, \newenvironment and \def. I think it is time I start to learn how to use them so I can solve my problems myself! It is always better if you actually know what is going on inside your code.

I am wondering if there is any turtorial or book out there that handles how to use those commands. Or is the best way to learn to just mess with a random file?

Thanks in advance!

(Also this is my first time I post here after using this website for so long, I really appreciate everyone who posts and tries to help other people here!)

Answer 1

LaTeX macros for defining custom commands and environments include:

• \newcommand
• \newcommand*
• \renewcommand
• \renewcommand*
• \providecommand
• \providecommand*
• \newenvironment
• \newenvironment*
• \renewenvironment
• \renewenvironment*

It is best to start with these since you should prefer them to TeX macros such as \def. However, sometimes only the TeX macros will work. It is easier to understand when and why \def and friends are needed once you have a good understanding of how the LaTeX macros work.

Defining, redefining and providing commands

\newcommand[<n>][<default>]{<definition>}

where <n> is the total number of arguments and <definition> is the definition of the command. If <n> is not specified, LaTeX assumes the command cannot take arguments. If <default> is given, the first argument is optional and, if missing, <default> is used.

For example, this is how \tableofcontents is defined in article.cls:

\newcommand\tableofcontents{%
    \section*{\contentsname
        \@mkboth{%
           \MakeUppercase\contentsname}{\MakeUppercase\contentsname}}%
    \@starttoc{toc}%
    }

The command takes no arguments, either mandatory or optional, so only the macro name, \tableofcontents and the definition of the macro are given.

Here is an example with a single, mandatory argument from \ltnews.cls:

\newcommand\cs[1]{\texttt{\textbackslash#1}}

The #1 refers to the first argument.

This is an example from latex.ltx defining a new command which takes 2 arguments, one mandatory and one optional. If the optional argument is not given, the default value of 0 will be used as #1:

\newcommand\qbezier[2][0]{\bezier{#1}#2}

The number of arguments may not exceed 9 and no more than one optional argument may be specified using \newcommand. All other arguments must be mandatory. Moreover, if an optional argument is available, it must be specified first and the syntax of the defined command is always \mycommand[optional]{mandatory}{mandatory}{mand....

\newcommand checks for an existing command of the same name and produces an error if it finds one. So there is a built-in check to prevent accidentally overwriting an existing command.

\newcommand* is just like \newcommand but its arguments cannot contain paragraph breaks.

To redefine an existing command, you can use \renewcommand or \renewcommand*. In this case, LaTeX checks whether or not the command already exists and produces an error if it does not.

If you want to define a command only if it does not exist already, you can use \providecommand or \providecommand*.

Defining and redefining environments

\newenvironment{<env name>}[<n>][<default>]{<begin env>}{<end env>}

where <env name> is the name of the new environment, <n> is the number of arguments (0 if not specified) and <default> is the default value of the first argument if the first argument is optional (all arguments are mandatory if this is not specified). <begin env> and <end env> specify the code to be executed at the beginning and end of the environment.

This is very like \newcommand. <n> cannot exceed 9, only one argument may be optional and it must be the first argument, and LaTeX will complain if an environment of the same name already exists. #1,... #9 refer to the arguments given to the environment if applicable.

Here is an example from cuisine.sty with 3 arguments, all mandatory:

\newenvironment{recipe}[3]{%
  \stepcounter{r@cipenumber}
  \let\newstep\m@thodend
  \let\recipen@wpage\newpage
  \let\newpage\r@cipen@wpage
  \let\0\d@grees
  \let\degrees\d@grees
  \let\fr\fr@ction
  \let\ing\ingr@dient
  \let\ingredient\ingr@dient
  \let\freeform\fr@eform
  \n@wpagingfalse%
  \setlength{\parindent}{0pt}
  \savebox{\st@pingrbox}[\R@cipeIQUWidth]{}
  \savebox{\st@pmethodbox}[\R@cipeMethodWidth]{}
  \ifind@xing
     \addcontentsline{toc}{subsection}{#1}
  \fi
  \r@cipetitle{#1}{#2}{#3}
  \vskip0.2cm%
  \p@stingred%
}%
{%
  \pr@ingred%
  \ifnum\value{st@pnumber}=0%  then complain!
    \PackageWarning{cuisine}{The recipe did not have any steps}%
  \fi%

  \pagebreak[0]%
  \medskip%
  \@endpetrue%
}%

\newenvironment* is just like \newenvironment but its arguments cannot contain paragraph breaks.

To redefine an existing environment, use \renewenvironment or \renewenvironment*. Again, LaTeX will complain in this case if the environment does not already exist.

Beyond LaTeX 2e

When you are comfortable with these methods of customisation, you will find that there are limitations on what you can do. At this point, start to look at \def and friends. At this stage, you should probably also take a look at xparse which provides much more powerful and flexible options from the work developing LaTeX 3. But these methods will make more sense once you are familiar with the possibilities offered by the LaTeX 2e macros.