Indentation

From Wiki
Revision as of 15:25, 11 June 2012 by Esteis (talk | contribs) (Clearer examples (one terser, one more verbose), and better description of \setupitemize keys.)
Jump to navigation Jump to search

< Visuals

In plain TeX, controlling indentation is simple: The user sets a value for parindent, and each new paragraph is indented by that value, unless explicitly begun with noindent. Environments can provide a noindent at the end of their definitions, and if the user wants to overrule that, he can add an explicit indent at the beginning of the next paragraph. For the most part, LaTeX follows the same convention.

So, understanding indentation in plain TeX and LaTeX boils down to this: set a value for parindent, and start a new paragraph (i.e., leave an empty line) whenever you want indentation. For example, LaTeX usually does not indent the first line after a sectioning command. If you want to indent the first line after a sectioning command you use the indentfirst package (which is part of the required LaTeX bundle). If you want to indent the paragraph after an environment, you leave a blank line after the end of the environment; if you do not want to indent after the end of an environment, you do not leave a blank line. It takes a while to get used to, but the rules are easy to remember and eventually you do not need to even think about indentation; it becomes a matter of habit.

Indentations in ConTeXt are a bit different; and sometimes difficult to understand. In this article I hope to explain how ConTeXt does indentations. First, let's understand why ConTeXt does indentations differently; why does it not simply follow the time-tested approach of plain TeX and LaTeX? The way I understand it, the reason is that Hans Hagen, the author of ConTeXt, prefers spaced out markup — surrounding each environment by empty lines — which makes it easy to see where an environment starts and ends while reading the source file. However, this style means that the 'indentation after empty lines' paradigm of plain TeX and LaTeX cannot be used for indentations. So, ConTeXt provides an alternative. As with other things in ConTeXt, this alternative is consistent and easy to configure; but if you are used to other TeX formats it takes some time to get comfortable with it.

The basics

Setting up indentation for the whole document

Indentation involves two things: when to indent, and how much to indent. In ConTeXt, these can be specified using \setupindenting[...]. There are three types of keys for this command:

  • no yes: turn indentation on/off'
  • none small medium big dimension: size of indents
  • first next: turn indentation of first paragraph on/off. Can be overridden by environments with indentnext=yes/no/auto.
  • odd even: indent odd/even lines in \obeylines scopes
  • normal: what does this do?

Setting up indentation after an environment

\setupindenting does not take care of indenting after environments, such as ConTeXt's itemizes, enumerations, definitions, formulas and floats. It also does not take care of indenting after heads such as chapters, sections, and subsections.

The setup command of these environments provides an indentnext key to configure the indentation behaviour after the environment. The indentnext key can take one of three values:

  • yes declares the first paragraph following the environment should always be indented.
  • no declares the first paragraph following the environment should never be indented.
  • auto declares indentnext=auto the next paragraph should be indented only if there is a blank space after the environment. Setting indentnext=auto is equivalent to the default plain TeX and LaTeX behaviour.

Some examples:

% Do not indent paragraphs after \stopitemize
\setupitemgroup[itemize][indentnext=no]

% indent paragraphs after section heads
\setuphead[section][indentnext=yes]

% indent the paragraphs after all sectioning heads 
\setupheads[indentnext=yes] 

% indent paragraphs after formulas if there is a blank space in between
\setupformulas[indentnext=auto] 

Setting up indentation inside environments

There is one case that is not taken care of by \setupindenting and the indentnext key: indentation of paragraphs inside multi-paragraph environments such as itemizes, descriptions, and enumerations. By default ConTeXt does not indent such paragraphs. The setup commands of these environments provides an indenting= key to configure the indentation behaviour of paragraphs inside these environments. This key takes the same arguments as the \setupindenting command does. An example using \setupitemgroup:

\setuppapersize[A5]

\setupindenting[medium,yes]
\setupitemgroup[itemize][indenting={40pt,next}]
\startitemize
\item This is an example of a multi|-|paragraph 
      item inside an itemize environment.

      This second paragraph is indented by 40pt
      (double the normal indentation).
\stopitemize

gives

Manual indentation

No matter how careful we are with all the settings, there are some cases which cannot be taken care of by automatic indentation, and we have to tell ConTeXt how to indent. Plain TeX (and LaTeX) provide the \indent and \noindent commands for explicitly indenting and preventing indenting of a paragraph. These commands are defined in ConTeXt but are not hooked into the ConTeXt indentation mechanism. Instead, ConTeXt provides \indentation and \noindentation which achieve the same effect.

Suppose the default setup for an article is

\setupitemgroup [itemize] [indentnext=no]

Now, if we want to indent after an itemize, starting the next paragraph with \indent does not work; to get indentation we have to say \indentation. For example,

\setuppapersize[A5]

\setupindenting [big,yes]
\setupitemgroup [itemize] [indentnext=no]

\startitemize[n]
    \item A dummy list with \type{indentnext=no}...
    \item ...to test the \tex{indent} command
\stopitemize

\indent This paragraph is not indented, because \tex{indent} does not work.

\startitemize[n]
    \item Another dummy list with \type{indentnext=no}...
    \item ...to test the \tex{indentation} command
\stopitemize

\indentation This paragraph will be indented, because we used \tex{indentation}.

gives

Beware of typos

ConTeXt defines two more commands not commonly used: \indenting and \noindenting. \indenting is similar to \setupindenting and is provided for backward compatibility; \noindenting is equivalent to \setupindenting[no]. Unfortunately, these commands sound very similar to \indentation and \noindentation, thus can be easily used by mistake. If you happen to write \noindenting instead of \noindentation in a document, it can take a while to debug.