8

Consider the following code listing from p. 82 of the TikZ & PGF manual for version 3.0.1a:

A code listing from the TikZ & PGF manual

\def\lecture#1#2#3#4#5#6{
  \node [annotation, #3, scale=0.65, text width=4cm, inner sep=2mm] at (#4) {
    Lecture #1: \textcolor{orange}{\textbf{#2}}
    \list{--}{\topsep=2pt\itemsep=0pt\parsep=0pt
              \parskip=0pt\labelwidth=8pt\leftmargin=8pt
              \itemindent=0pt\labelsep=2pt}
    #5
    \endlist
  };
}

The listing uses a pair of commands: \list and \endlist. The \list command takes two arguments: {--} and {\topset...=2pt}.

The \list command is not listed in the TikZ manual's index, nor in the indices of Knuth's The TeX Book or Lamport's LaTeX.

To which system/package does this command belong?
What is its syntax?
What are its semantics?

  • 1
    \list and \endlist are the commands corresponding to the start and end of the list environment. – karlkoeller Jun 18 '17 at 9:09
  • @karlkoeller: Thanks. Can you speculate why the TikZ manual avoided using the list environment in the above code listing? – Evan Aad Jun 18 '17 at 9:13
  • 2
    See also texdoc source2e, search for \def\list. – Torbjørn T. Jun 18 '17 at 9:13
  • 1
    Well, it's there. I don't know which version you have, but look in the table of contents for "Lists, and related environments", it's in that chapter. (Chapter 54, page 286 on my system, TeX Live 2016.) – Torbjørn T. Jun 18 '17 at 9:38
  • 1
    @EvanAad In texdoc source2e included with TeX Live 2017, look for \def\list at the bottom of page 290, numbered line 34 — the chapter this occurs in is "File A: ltlists.dtx" aka "Lists, and related environments". (You can find this by looking in the index under L for \list, and following the underlined index entry, which stands for where it's defined.) – ShreevatsaR Jun 18 '17 at 15:20
9

The code above is not particularly instructive for beginners and should be accompanied by explicatory notes.

It takes advantage of two facts:

  1. the code in the main argument to \node is executed in a \parbox, due to setting of text width, which forms a (TeX) group;

  2. code such as \begin{env}...\end{env} is essentially equivalent to

    \begingroup
    <some bookkeeping>
    \env
    ...
    \endenv
    <some bookkeeping>
    \endgroup
    

The bookkeeping is, in this case, irrelevant, because the whole construction is performed in the group provided by \parbox.

Never use \list...\endlist in the wild, because not doing the bookkeeping will almost certainly have adverse effects.

The code should better be, from a teacher’s point of view,

\newcommand{\lecture}[6]{%
  \node [annotation, #3, scale=0.65, text width=4cm, inner sep=2mm] at (#4) {
    Lecture #1: \textcolor{orange}{\textbf{#2}}
    \begin{list}{--}{%
      \setlength{\topsep}{2pt}%
      \setlength{\itemsep}{0pt}%
      \setlength{\parsep}{0pt}%
      \setlength{\parskip}{0pt}%
      \setlength{\labelwidth}{8pt}%
      \setlength{\leftmargin}{8pt}%
      \setlength{\itemindent}{0pt}%
      \setlength{\labelsep}{2pt}%
    }%
    #5
    \end{list}
  };
}

Optimizations such as those require experience and actually don't gain much.

Better yet, one could do

\newenvironment{lecturelist}
 {\begin{list}{--}{%
    \setlength{\topsep}{2pt}%
    \setlength{\itemsep}{0pt}%
    \setlength{\parsep}{0pt}%
    \setlength{\parskip}{0pt}%
    \setlength{\labelwidth}{8pt}%
    \setlength{\leftmargin}{8pt}%
    \setlength{\itemindent}{0pt}%
    \setlength{\labelsep}{2pt}%
  }%
  {\end{list}}

and then

\newcommand{\lecture}[6]{%
  \node [annotation, #3, scale=0.65, text width=4cm, inner sep=2mm] at (#4) {
    Lecture #1: \textcolor{orange}{\textbf{#2}}
    \begin{lecturelist}
    #5
    \end{lecturelist}
  };
}

In the code for lecturelist it would be good to change \begin{list} and \end{list} with \list and \endlist respectively: the bookkeeping will be taken care of by \begin{lecturelist} and \end{lecturelist}, so it doesn't need to be done in the inner part. It would also give better error messages in case one doesn't properly close the lecturelist package.

  • Thanks. Can you speculate why the TikZ manual avoided using the list environment in the above code listing? Is it possible to replace the \list...\endlist in the manual's code listing by \begin{list}...\end{list} with no (ill) effect? – Evan Aad Jun 18 '17 at 9:32
  • 1
    @EvanAad I'd say that \begin{list}...\end{list} ought to be used, along with \newcommand{\lecture}[6]{...}. – egreg Jun 18 '17 at 9:35
  • 1
    @EvanAad I added some more comments – egreg Jun 18 '17 at 9:43
  • Thanks. This is much clearer, except for the last sentence, where you seem to contradict your former exhortation not to use \list and \endlist. – Evan Aad Jun 18 '17 at 9:48
  • 1
    @EvanAad No contradiction! That's not using \list and \endlist in the wild, but in the definition of a new environment: the bookkeeping is taken care of by the lecturelist outer environment. – egreg Jun 18 '17 at 10:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.