Where do I find out how a command/environment is defined?

Question

Say I want to redefine the itemize environment, or make a modified version of it. I want to know how it is currently defined. Where do I find this information? If it's some particular package command, I can just look at the .sty file for that package, but if it's something more basic, I don't know where to look...

Is there a reference manual of where all this stuff is explained? Or is there a file in the depths of my texmf tree I should poke around in?

Answer 1

LaTeX itself is documented in source2e.pdf (texdoc source2e) and the standard classes (article, book, report, etc) are documented in classes.pdf (texdoc classes).

Answer 2

To know how a command is defined, you can use the \show command:

\documentclass{article}
\begin{document}
\show\itemize
\end{document}

The log wfile will show:

> \itemize=macro:
->\ifnum \@itemdepth >\thr@@ \@toodeep \else \advance \@itemdepth \@ne \edef \@
itemitem {labelitem\romannumeral \the \@itemdepth }\expandafter \list \csname     @itemitem \endcsname {\def \makelabel ##1{\hss \llap {##1}}}\fi .
l.3 \show\itemize

To locate the file containing the definition the script texgrepis useful, which I posted answering this topic: Grepping through an entire texmf tree.

Answer 3

There is now the (la)texdef script on CTAN which can be used to display (La)TeX definitions. The current version also support to display the package which defines the macro, however you need to state a list of packages to be loaded. For itemize the usage would be

latexdef -f itemize

or, if only texdef was installed by your distro (latexdef is only a symlink to texdef which activates LaTeX mode):

texdef -t latex -f itemize

which prints:

\itemize is defined by (La)TeX.

\itemize:
macro:->\ifnum \@itemdepth >\thr@@ \@toodeep \else \advance \@itemdepth \@ne \edef \@itemitem {labelitem\romannumeral \the \@itemdepth }\expandafter \list \csname \@itemitem \endcsname {\def \makelabel ##1{\hss \llap {##1}}}\fi

To display the definition of any macro from any package use:

latexdef -p package macro

See latexdef --help for more information.

---

With v1.6 from 2012/05/02 you can also get the original source code for most macros using the -s/--source option:

$ latexdef -f itemize -s -E
% latex.ltx, line 4556:
\def\itemize{%
  \ifnum \@itemdepth >\thr@@\@toodeep\else
    \advance\@itemdepth\@ne
    \edef\@itemitem{labelitem\romannumeral\the\@itemdepth}%
    \expandafter
    \list
      \csname\@itemitem\endcsname
      {\def\makelabel##1{\hss\llap{##1}}}%
  \fi}

% latex.ltx, line 4565:
\let\enditemize =\endlist

% latex.ltx, line 4422:
\def\endlist{%
  \global\advance\@listdepth\m@ne
  \endtrivlist}

Here -E tells that itemize is an environment.

Answer 4

As a complement to Stefan's answer: If you don't want to peruse the logfile, but to typeset a command's definition directly in the document, use \meaning instead of \show:

\documentclass{article}

\usepackage[T1]{fontenc}

\begin{document}

\meaning\itemize

\end{document}

Note: \usepackage[T1]{fontenc} is necessary for correctly typesetting backslashes and braces.

Answer 5

None of the answers were as conveniently to use as I'd like, so I put together a small script that basically greps through the whole LaTeX (in my case, TeX Live, hence the name) installation and looks for a single command/environment name. It recognises some (not all) ways to define commands and environments (cf the comments).

This sounds like an awful amount of work, but it's indeed blazingly fast. Which makes you wonder why LaTeX "IDE"s don't do something similar.

For instance, on a full TeX Live installation, you'd get

~$ tlwhich todo
Files that define command todo:
    easy-todo.sty
    lilyglyphsStyle.sty
    todonotes.sty
    todo.sty
    tudscrdoc.cls
    udesoftec.cls

Files that define environment todo:
    ed.sty

Files that provide a package with similar name:
    easy-todo.sty
    fixmetodonotes.sty
    todonotes.sty
    todo.sty

Regular expressions (as compatible with grep) are possible:

~$ tlwhich "align(\*|ed)?"
Files that define command align(\*|ed)?:
    amstex.sty
    divers.sty
    dprogress.sty
    euro.sty

Files that define environment align(\*|ed)?:
    amsmath.sty
    amstex.sty

Files that provide a package with similar name:
    asyalign.sty

If it does not find something it should, please drop me a comment (or ticket on Github).

Answer 6

Environments are nearly always defined using either pairs \def\env..., \def\endenv... (used mainly in the Latex base code) or \newenvironment{env} (used mainly in the classes), so grepping the dtx source files might narrow you in to the code you want that bit faster, e.g., on a unixlike with TEXMF the root of a Texlive install, fgrep -e "\\itemize" $TEXMF/texmf-dist/source/latex/base/*.dtx shows the file and text where itemize is defined.

Answer 7

Reading source code is a great way to learn TeX programming but it's not for the weak of stomach. If you just want to modify an environment you can try the etoolbox package or some of the other answers on the TeX FAQ.

Oh, and one more thing: \show\cmd in a TeX file will interrupt processing to tell you the definition of \cmd.

Answer 8

Figure out where the command comes from

The easy way

Occasionally you can figure out which package contains the macro you're looking for directly with latexdef --find, find, grep, or simply searching on Google/Startpage (something I took a lot of time to figure out: DuckDuckGo is particularly bad at this, unfortunately)

See also

• Macro find tool
• Which latex editor is able to access all documentation of all packages?
• How to search a documentation about an tex-function in command-line way on linux?

The hard way

You should know where the command (macro, environment, control sequence) is defined.

For quick reference:

• If there's some \usepackage / nonstandard \documentclass at the top, read the documentation of that package. latexdef --find can handle this one.

  • Special case: for some packages like TikZ with massive documentation, there are some "quick introduction" such as What is the minimum one needs to know to use TikZ?.

• Otherwise, if a macro consist of @, read macros2e.pdf (short summary) or source2e.pdf (full documentation). (also read documentation of \makeatletter)

  See also Where can I find help files or documentation for commands like \@startsection for LaTeX?.

• If a macro consist of _ and/or :, read interface3 at CTAN documentation for l3kernel → The LaTeX3 interfaces. (also read expl3 before that)

• Otherwise, it should be in one of those

  • LaTeX2e unofficial reference manual or...

  • LaTeX Documentation (there are multiple PDF files! Remember to search through them all. E.g. \DeclareMathAlphabet is in fntguide.pdf, \NewHook is in lthooks-doc.pdf -- although this one can also be found in source2e.pdf)

    Note that reading this alone is most likely insufficient...

  • LaTeX books: "LaTeX: A document preparation system, User’s guide and reference manual" & "The LaTeX Companion" (etc.), which are basically the "official reference manual".

  • There are some packages that is merged into the format, e.g. xparse which contains \NewDocumentCommand.

  • source2e.pdf contains the documentation of some "new" commands as well, such as \MakeRobust.

  • ε-TeX manual (etex_man.pdf) for ε-TeX extensions, such as \detokenize, \currentiflevel, and \scantokens.

  • Documentation of TeX engines for engine-specific extensions (as well as "shared" extensions i.e. engine-specific extensions, but implemented in all engines, such as \expanded or \ifincsname):

    • LuaTeX documentation on CTAN (e.g. \lastnamedcs, \directlua, ^^^^)
    • XeTeX documentation on CTAN (e.g. \Ucharcat)
    • PDFTeX documentation on CTAN (e.g. \pdfescapestring)

  • The TeXBook (get at a bookstore. Source code is published on CTAN, but only for an example how TeX source looks like, it must not be compiled because of copyright reasons) -- cover both TeX primitives and plain TeX macros.

  • Alternatively there's TeX by Topic and TeX in a nutshell -- covers TeX primitives such as \mathsurround, but not necessarily plain TeX macros such as \mathpalette or \underbrace.

  • Some more obscure primitives are "documented" in the source code only. E.g.

    • \endwrite in TeX source code -- texdoc tex (see also Accessing TeX's internal tokens),
    • \synctex in PDFTeX/XeTeX being an extension added by TeX Live from the original PDFTeX/XeTeX program would be in texdoc pdftex-changes -- refer to
      • C/WEB programs in TeX Live 2022 (PDF format) or HINT format
      • or my question;
      • the one in LuaTeX is only documented in the source code which cannot be typesetted into PDF format.

Addition: What are all these layers?

Also read What is the difference between TeX and LaTeX? and the first comment there which points to https://www.tug.org/levels.html .

• First, there's the core, TeX, which has some 300 primitives.

  They're all documented in the TeXBook (you have to buy this one. See Is it actually illegal to TeX `texbook.tex`? for the legal details -- warning: users on this site are not necessarily lawyers!), and (mostly) TeX by Topic.

  (I remember seeing some command in the TeXBook but not in TeX by Topic, but perhaps it's in Plain TeX instead of a primitive.)

• There's also an engine extension (e-TeX).

• Then, there are the TeX engines (tex, pdftex, xetex, luatex).

  (analogy: gcc, clang, tcc, Microsoft Visual C++ compiler for C++; or CPython, PyPy, Jython for Python)

  It's fairly rare to see an engine-specific command/syntax (such as \directlua or ^^^^), but if it's then reading the documentation of the engine works.

• Then, there's a TeX format (set of macros predefined). The (not necessarily common) formats are "virgin" TeX, Plain TeX, LaTeX, ConTeXt, OpTeX.

  (analogy: legacy C headers/C++ standard library/Boost for C++. There isn't a good analogy, as most languages only have one "standard library")

  Now that the default format for LaTeX is LaTeX3, both LaTeX2e macros and LaTeX3 macros are automatically loaded.

Understanding how to use the command

Most of the time, you only need to know how to use the command.

For that, reading the documentation of the package is sufficient. See How to find the documentation for a package? .

Note: If you decide to be lazy and not read through the whole TeXBook/TeX by Topic first, you risk not understanding some concepts to make sense of the documentation. In that case search for the concepts recursively (for example, you can find those in The TeXBook: what is a token? What is category code (catcode)? What is a box's depth/height/width?)

Patch the command

Also most of the time, you don't need to know how the command is defined to patch it.

You can do something like this

\NewCommandCopy{\oldemph}{\emph}
\renewcommand{\emph}[1]{\textbf{\oldemph{#1}}}

(details in egreg's answer to "Can I redefine a command to contain itself?")

If you really need to know how the command is defined, it's usually beneficial to read through the command's source documentation (the .dtx file compiled to a .pdf file) if available, (otherwise read the source code, instead of the .sty file, which is a stripped-comment version) which usually contains explanation on how particular things are defined.

For instance, for the unicode-math package, it can be accessed at "Documentation of the source code" link in CTAN page.

Note

Also an answer to:

• How can I know how to use this command/macro/environment?
• Where can I look up LaTeX commands?
• How can I understand what this answer found on the site/snippet of code I found somewhere is doing?

Related questions:

• Is there a printable version of a reference manual for all TeX primitives?
• Dummies Guide to TeX as a programming language
• What is the best way to learn TeX?

Answer 9

Just concerning itemize: This is defined in the basic latex file latex.ltx. It is redefined,e.g. in the enumitem package, i.e, in enumitem.sty.

Answer 10

i would say that merely looking at the output of \show isn't going to get you very far: itemize is a refinement of trivlist so you need to read that definition too.

so, either read source2e.pdf (as others have recommended) or (if you're old and crumbly like me, and find typeset code confusing) read ltlists.dtx in the latex source distribution.