enumitem horizontal spacing parameters

Question

I am still struggling with enumitem. I don't understand the horizontal spacing parameters at all. I have indeed read the documentation, and numerous answers to numerous questions, but despite all that I just don't get it! I have absolutely no idea what labelindent=* or labelindent=! are supposed to do. Could someone please explain in simple terms what the five parameters are and what these * and ! options do?

In particular, I want the second line of my list here to stack under the first line rather than start slightly over to the left. Here is my attempt to do that, but as you can see it's not working. (Incidentally, I am explicitly setting labelindent=0pt because it is globally set to \parindent for normal use in this document.)

\documentclass[12pt, a4paper, oneside, fleqn]{report}

\usepackage{enumitem}
\setlist[description]{leftmargin=\parindent,labelindent=\parindent,itemsep=1pt,parsep=0pt,topsep=0pt}

\begin{document}

\chapter*{Symbols list}

\begin{description}[labelindent=0pt,labelwidth=0.7cm,leftmargin=0.7cm]
%
\item[x] Text text text text more words. Here is a full sentence to use up some space. And yet another sentence. blah blah blah
\item[y] Text text text text more words. Here is a full sentence to use up some space. And yet another sentence. blah blah blah
\item[z] Text text text text more words. Here is a full sentence to use up some space. And yet another sentence. blah blah blah

\end{description}   

\end{document}

Update

I've tried the solution that @Bernard has put in his answer, but it is not working for me. I'm updating my code, because my label text is quite wide (I didn't include it at first because I feel like my entire thesis will be published in tex.se before I submit ;-).

Here is Bernard's suggestion with the labelwidth extended to 2.1cm to accommodate the wide text, and labelindent=0pt, which is a setting I wanted:

\documentclass[12pt, a4paper, oneside, fleqn]{report}

\usepackage{enumitem}
\setlist[description]{leftmargin=\parindent,labelindent=\parindent,itemsep=1pt,parsep=0pt,topsep=0pt}

\usepackage[showframe, top=2.5cm, left=3.5cm, bottom=2.5cm, right=2.5cm, includehead]{geometry}
\geometry{headheight=28pt, headsep=18pt}

\begin{document}

\chapter*{Symbols list}

\begin{description}[labelindent=0em ,labelwidth=2.1cm, labelsep*=1em, leftmargin =!, style = standard]%

\item[$\mathbf{H}$] Forward model Jacobian matrix
\item[$\mathbf{MoistCov}$] Background error covariance matrix calculated from an ensemble of forecast states and using a new moisture control variable designed to eliminate increments in the stratosphere.

\end{description}   

\end{document}

Here's what it looks like:

Here's what happens when in addition to that I comment out the \setlist command at the beginning, which is odd because there is clearly some interaction, though I don't know wny, because it looks like I should have overridden the horizontal settings. It looks like leftmargin=! is not calculating leftmargin from the other settings:

Answer 1

Enumitem introduces a new very useful length, labelsep*, such that labelsep* + itemindent = labelsep (see § 3.3 of the documentation). Setting labelindent + labelwidth + labelsep* = leftmargin gives what you want, while allowing label text to be longer than the default. If style=standard, a wider label changes the left margin of the list, while with style=sameline, it can go over the left margin:

\documentclass[12pt, a4paper, oneside, fleqn]{report}
\usepackage[showframe, nomarginpar]{geometry}

\usepackage{enumitem}

\begin{document}

\chapter*{Symbols list}

\begin{description}[labelindent=1em ,labelwidth=1.3cm, labelsep*=1em, leftmargin =!, style = standard]% 
\item[x text]Text text text text more words. Here is a full sentence to use up some space. And yet another sentence. blah blah blah
\item[y] Another text text text text more words. Here is a full sentence to use up some space. And yet another sentence. blah blah blah
\item[z] Text text text text more words. Here is a full sentence to use up some space. And yet another sentence. blah blah blah
\end{description}

\begin{description}[labelindent=1em ,labelwidth=1.2cm, labelsep*=1em, leftmargin =! , itemindent = 0pt, style = sameline]
\item[x text]Text text text text more words. Here is a full sentence to use up some space. And yet another sentence. blah blah blah
\item[y] Another text text text text more words. Here is a full sentence to use up some space. And yet another sentence. blah blah blah
\item[z] Text text text text more words. Here is a full sentence to use up some space. And yet another sentence. blah blah blah
\end{description}

\end{document}

To explain in more detail what happens, the label begins at label indent, the beginning of the lines that follow the label line is at leftmargin, which is equal to label indent + labelwidth +labelsep*. Setting the values of the first 3, and leftmargin=! make left margin be computed from the first three as indicated.

It works along the same lines for enumerate and itemize, except that label alignment in these cases is right, so that if label width is too small,the label can go into the (page) left margin. It behaves as a kind of \llap{label}.

Let me explain why your code does not work: the order in which you set the keys is important. Setting style=standard at the end, you overrode the previous values with those defined in standard style – just as the setlist{description}{…} values in the preamble can be overridden by the actual optional parameters in a description environment. If you change your code to the following, it works as you want:

\documentclass[12pt, a4paper, oneside, fleqn]{report}
\usepackage[utf8]{inputenc}

\usepackage{enumitem}

\usepackage[showframe, top=2.5cm, left=3.5cm, bottom=2.5cm, right=2.5cm, includehead]{geometry}
\geometry{headheight=28pt, headsep=18pt}

\begin{document}

\chapter*{Symbols list}

\begin{description}[style =standard, labelindent=0em , labelwidth=2cm, labelsep*=1em, leftmargin =!]%
\item[$\mathbf{H}$] Forward model Jacobian matrix
\item[$\mathbf{MoistCov}$] Background error covariance matrix calculated from an ensemble of forecast states and using a new moisture control variable designed to eliminate increments in the stratosphere.

\end{description}

\end{document} 

The leftmargin=! key means that left margin is computed from the other parameters as described in § 3.3, viz leftmargin=labelindent + labelwidth + labelsep*, which have all been chosen. Note that with almost the same keys, only deleting leftmargin=! gives a different result, as there must be a predefined value of leftmargin that is not overridden:

Writing parameterkey=! means that this parameter is computed in function of the others, whether you've set them explicitly or they're set by the environment, style, &. As far as I understand it, parameterkey=* means the same thing with the added feature that labelwidth is set to a conventional value (that of viii for a roman style enumeration for instance). I think it has a meaning for enumerate environments, although this is not very clear to me from the documentation.

Answer 2

\documentclass{article}
\usepackage{enumitem}
\usepackage{layouts}
\begin{document}
\listdiagram

\clearpage
\begin{enumerate}
\item The figure illustrates the layout of an \texttt{enumerate} list.
\currentlist
\listdesign
\end{enumerate}

\end{document}

Answer 3

You can see from this question How to draw this lines with tikzmark a scheme shows the different horizontal lengths in the enumirate environment

Answer 4

This is to address your update to the question.

The order of options is important. In particular, later options override earlier ones. Now hidden in style=standard is itemindent=!. If there is a previous leftmargin=! this will be overridden by the itemindent=!.

Below are examples to compare. The third is the same as yours without the horizontal spacing parts of your \setlist[description]. Notice it produces the same output as with itemindent=! as with leftmargin=!,style=standard. The second has leftindent=! instead of itemindent=! and produces different spacing. Thus the sytle=standard is overriding the leftmargin=!.

Examples 4, 5 and 6 demonstrate the same behaviour now in the presence of your \setlist options.

\documentclass[12pt, a4paper, oneside, fleqn]{report}

\usepackage{enumitem}
\setlist{itemsep=1pt,parsep=0pt,topsep=0pt}

\usepackage[showframe, top=2.5cm, left=3.5cm, bottom=2.5cm, right=2.5cm, includehead]{geometry}
\geometry{headheight=28pt, headsep=18pt}

\begin{document}

\chapter*{Symbols list}

\begin{description}[labelindent=0pt,labelwidth=2.1cm,labelsep*=1em,itemindent=!]
\item[$\mathbf{H}$] Forward model Jacobian matrix
\item[$\mathbf{MoistCov}$] Background error covariance matrix
  calculated from an ensemble of forecast states and using a new
  moisture control variable designed to eliminate increments in the
  stratosphere.
\end{description}

\begin{description}[labelindent=0pt,labelwidth=2.1cm,labelsep*=1em,leftmargin=!]
\item[$\mathbf{H}$] Forward model Jacobian matrix
\item[$\mathbf{MoistCov}$] Background error covariance matrix
  calculated from an ensemble of forecast states and using a new
  moisture control variable designed to eliminate increments in the
  stratosphere.
\end{description}

\begin{description}[labelindent=0em ,labelwidth=2.1cm, labelsep*=1em,
  leftmargin =!,style=standard]%
\item[$\mathbf{H}$] Forward model Jacobian matrix
\item[$\mathbf{MoistCov}$] Background error covariance matrix
  calculated from an ensemble of forecast states and using a new
  moisture control variable designed to eliminate increments in the
  stratosphere.
\end{description}

\setlist[description]{leftmargin=\parindent,labelindent=\parindent}
\begin{description}[labelindent=0pt,labelwidth=2.1cm,labelsep*=1em,itemindent=!]
\item[$\mathbf{H}$] Forward model Jacobian matrix
\item[$\mathbf{MoistCov}$] Background error covariance matrix
  calculated from an ensemble of forecast states and using a new
  moisture control variable designed to eliminate increments in the
  stratosphere.
\end{description}

\begin{description}[labelindent=0pt,labelwidth=2.1cm,labelsep*=1em,leftmargin=!]
\item[$\mathbf{H}$] Forward model Jacobian matrix
\item[$\mathbf{MoistCov}$] Background error covariance matrix
  calculated from an ensemble of forecast states and using a new
  moisture control variable designed to eliminate increments in the
  stratosphere.
\end{description}

\begin{description}[labelindent=0em ,labelwidth=2.1cm, labelsep*=1em,
  leftmargin =!,style=standard]%
\item[$\mathbf{H}$] Forward model Jacobian matrix
\item[$\mathbf{MoistCov}$] Background error covariance matrix
  calculated from an ensemble of forecast states and using a new
  moisture control variable designed to eliminate increments in the
  stratosphere.
\end{description}

\end{document}

Answer 5

I've found the following diagram, from § 8.16 list of LaTeX2e unofficial reference manual (October 2018) to be very helpful:

where:

• h0: \labelwidth
• h1: \labelsep
• h2: \listparindent
• h3: \leftmargin
• h4: \itemindent
• h5: \rightmargin

The critical equality is that the right edge of the bracket for h1 is the same horizontal location as the right edge of the bracket for h4, implying that the left edge of the label box is located at:

h3+h4-(h0+h1)

Answer 6

May be a little too late to solve the problem:

“In particular, I want the second line of my list here to stack under the first line rather than start slightly over to the left.”

This must be achieved with itemindent=0pt, always, in any list.

When you're ready with your description list, set widest item as the value of the key widest, in this case widest=$\mathbf{MoistCov}$.

Choose the indentation of the whole list by the value of the key labelindent, e.g., labelindent=\parindent or labelindent=0pt.

Now let the package enumitem do the calculations to evaluate the indentation of the second and all following lines so that these lines are flush with the first line by setting leftmargin = * .

Ready to go:

\begin{description}[itemindent=0pt ,labelindent=\parindent, 
          widest=$\mathbf{MoistCov}$, leftmargin =*]%

  \item[$\mathbf{H}$] Forward model Jacobian matrix
  \item[$\mathbf{MoistCov}$] Background error covariance matrix calculated from 
      an ensemble of forecast states and using a new moisture control variable 
      designed to eliminate increments in the stratosphere.

\end{description} 

Remark: If you want the second line to be flush with the label, do it the other way around. Select the indentation of the list using the labelindent key and give leftmargin the same value, e.g. give both the value 0pt or \parindent. You leave the calculation of the correct value of itemindent to the package by setting itemident=*.

\begin{description}[itemindent=* ,labelindent=0pt, 
    widest=$\mathbf{MoistCov}$, leftmargin=0pt]

I made a drawing showing the five horizontal keys of enumitem. As you can see, these are not independent, but rather linked by a linear equation. Therefore you can only give four keys a value, the fifth is given by the equation. The key whose value is to be calculated is given the value *. Keys for which no value is set get the default value, in my examples labelwidth and labelsep.

As you can see, the first and second lines are left justified if and only if itemindent=0pt. The label and the second line are left justified if and only if labelindent and leftmargin have the same value.

The drawing also shows that the margin of a sublist is determined by the left edge of the box from the second line of the parent list.