869
edits
Changes
Wikified the tugboat article
In plain TeX, controlling indentation is simple: The user sets a value for
<cmd>parindent</cmd>, and each new paragraph is indented by that value, unless
explicitly begun with <cmd>noindent</cmd>. Environments can provide a
<cmd>noindent</cmd> at the end of their definitions, and if the user wants to
overrule that, he can add an explicit <cmd>indent</cmd> 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 <cmd>parindent</cmd>, 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 <code>indentfirst</code> 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 =
Indentation involves two things: when to indent, and how much to indent. In
ConTeXt, these can be specified using <cmd>setupindenting[...]</cmd>. There
are two types of keys for this command:
* '''To specify ''when to indent'':''' <code>never</code> or <code>always</code>, (equivalently, <code>no</code> or <code>yes</code>), <code>odd</code> or <code>even</code>, and <code>first</code> or <code>next</code>.
* '''To specify ''how much to indent'':''' <code>none</code>, <code>small</code>, <code>medium</code>, <code>big</code>, or a specific dimension. <code>small</code> corresponds to 1em, <code>medium</code> to 1.5em, and <code>big</code> to 2em.
Suppose we want to indent all paragraphs by 20pt: we can use
<texcode>
\setupindenting[20pt, yes]</texcode>
This is what one typically uses in a document. The other keys are needed only
for special cases (like typesetting quotations and verses).
<cmd>setupindenting</cmd> 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
'''<code>indentnext</code>''' key to configure the indentation behaviour after
the environment. The <code>indentnext</code> key can take one of three values:
<code>yes</code>, <code>no</code>, and <code>auto</code>. If
<code>indentnext=yes</code> then the paragraph after the end of the environment
is always indented; if <code>indentnext=no</code> then the next paragraph is
never indented; if <code>indentnext=auto</code> then the next paragraph is
indented only if there is a blank space after the environment. Setting
<code>indentnext=auto</code> is equivalent to the default plain TeX and LaTeX
behaviour.
Let us provide a couple of examples. Suppose we do not want paragraphs after
itemize to be indented; then we can say
<texcode>
\setupitemgroup[itemize][indentnext=no]
</texcode>
If we want paragraphs after section heads to be indented, we can say
<texcode>
\setuphead[section][indentnext=yes]
</texcode>
If we want the paragraphs after all sectioning heads to be
indented, we can say
<texcode>
\setupheads[indentnext=yes]
</texcode>
If we want paragraphs after formulas to be indented only if we
leave a blank space after them, we can say
<texcode>
\setupformulas[indentnext=auto]
</texcode>
There is one case that is not taken care of by <cmd>setupindenting</cmd> and the
<code>indentnext</code> 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 '''<code>indenting</code>''' key to configure the indentation
behaviour of paragraphs inside these environments. This key takes the same
values as the arguments of <cmd>setupindenting</cmd> command. For example, if we set
<texcode>
\setupitemgroup[itemize][indenting={40pt,yes}]
</texcode>
then the following :
<context source="yes" text="gives" scale="0.8">
\setupitemgroup[itemize][indenting={40pt,yes}]
\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
</context>
= 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 <cmd>indent</cmd> and <cmd>noindent</cmd>
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 <cmd>indentation</cmd> and
<cmd>noindentation</cmd> which achieve the same effect.
Suppose the default setup for an article is
<texcode>
\setupitemgroup [itemize] [indentnext=no]
</texcode>
Now, if we want to indent after an itemize, starting the next paragraph
with <cmd>indent</cmd> does not work; to get indentation we have to say
<cmd>indentation</cmd>. For example,
<context source="yes" text="gives" scale="0.8">
\setupindenting [big,yes]
\setupitemgroup [itemize] [indentnext=no]
\startitemize[n]
\item A dummy list
\item To check \type{\indent}
\stopitemize
\indent This paragraph is not indented. The
\type{\indent} command does not work here.
\startitemize[n]
\item Another dummy list
\item To check \type{\indentation}
\stopitemize
\indentation This paragraph will be indented
because we used \type{\indentation} instead.
</context>
= Beware of typos =
ConTeXt defines two more commands not commonly used:
<cmd>indenting</cmd> and <cmd>noindenting</cmd>. <cmd>indenting</cmd> is similar to
<cmd>setupindenting</cmd> and is provided for backward compatibility;
<cmd>noindenting</cmd> is equivalent to
<cmd>setupindenting[no]</cmd>. Unfortunately, these commands sound very
similar to <cmd>indentation</cmd> and <cmd>noindentation</cmd>, thus can be easily
used by mistake. If you happen to write <cmd>noindenting</cmd> instead of
<cmd>noindentation</cmd> in a document, it can take a while to debug.
<cmd>parindent</cmd>, and each new paragraph is indented by that value, unless
explicitly begun with <cmd>noindent</cmd>. Environments can provide a
<cmd>noindent</cmd> at the end of their definitions, and if the user wants to
overrule that, he can add an explicit <cmd>indent</cmd> 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 <cmd>parindent</cmd>, 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 <code>indentfirst</code> 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 =
Indentation involves two things: when to indent, and how much to indent. In
ConTeXt, these can be specified using <cmd>setupindenting[...]</cmd>. There
are two types of keys for this command:
* '''To specify ''when to indent'':''' <code>never</code> or <code>always</code>, (equivalently, <code>no</code> or <code>yes</code>), <code>odd</code> or <code>even</code>, and <code>first</code> or <code>next</code>.
* '''To specify ''how much to indent'':''' <code>none</code>, <code>small</code>, <code>medium</code>, <code>big</code>, or a specific dimension. <code>small</code> corresponds to 1em, <code>medium</code> to 1.5em, and <code>big</code> to 2em.
Suppose we want to indent all paragraphs by 20pt: we can use
<texcode>
\setupindenting[20pt, yes]</texcode>
This is what one typically uses in a document. The other keys are needed only
for special cases (like typesetting quotations and verses).
<cmd>setupindenting</cmd> 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
'''<code>indentnext</code>''' key to configure the indentation behaviour after
the environment. The <code>indentnext</code> key can take one of three values:
<code>yes</code>, <code>no</code>, and <code>auto</code>. If
<code>indentnext=yes</code> then the paragraph after the end of the environment
is always indented; if <code>indentnext=no</code> then the next paragraph is
never indented; if <code>indentnext=auto</code> then the next paragraph is
indented only if there is a blank space after the environment. Setting
<code>indentnext=auto</code> is equivalent to the default plain TeX and LaTeX
behaviour.
Let us provide a couple of examples. Suppose we do not want paragraphs after
itemize to be indented; then we can say
<texcode>
\setupitemgroup[itemize][indentnext=no]
</texcode>
If we want paragraphs after section heads to be indented, we can say
<texcode>
\setuphead[section][indentnext=yes]
</texcode>
If we want the paragraphs after all sectioning heads to be
indented, we can say
<texcode>
\setupheads[indentnext=yes]
</texcode>
If we want paragraphs after formulas to be indented only if we
leave a blank space after them, we can say
<texcode>
\setupformulas[indentnext=auto]
</texcode>
There is one case that is not taken care of by <cmd>setupindenting</cmd> and the
<code>indentnext</code> 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 '''<code>indenting</code>''' key to configure the indentation
behaviour of paragraphs inside these environments. This key takes the same
values as the arguments of <cmd>setupindenting</cmd> command. For example, if we set
<texcode>
\setupitemgroup[itemize][indenting={40pt,yes}]
</texcode>
then the following :
<context source="yes" text="gives" scale="0.8">
\setupitemgroup[itemize][indenting={40pt,yes}]
\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
</context>
= 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 <cmd>indent</cmd> and <cmd>noindent</cmd>
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 <cmd>indentation</cmd> and
<cmd>noindentation</cmd> which achieve the same effect.
Suppose the default setup for an article is
<texcode>
\setupitemgroup [itemize] [indentnext=no]
</texcode>
Now, if we want to indent after an itemize, starting the next paragraph
with <cmd>indent</cmd> does not work; to get indentation we have to say
<cmd>indentation</cmd>. For example,
<context source="yes" text="gives" scale="0.8">
\setupindenting [big,yes]
\setupitemgroup [itemize] [indentnext=no]
\startitemize[n]
\item A dummy list
\item To check \type{\indent}
\stopitemize
\indent This paragraph is not indented. The
\type{\indent} command does not work here.
\startitemize[n]
\item Another dummy list
\item To check \type{\indentation}
\stopitemize
\indentation This paragraph will be indented
because we used \type{\indentation} instead.
</context>
= Beware of typos =
ConTeXt defines two more commands not commonly used:
<cmd>indenting</cmd> and <cmd>noindenting</cmd>. <cmd>indenting</cmd> is similar to
<cmd>setupindenting</cmd> and is provided for backward compatibility;
<cmd>noindenting</cmd> is equivalent to
<cmd>setupindenting[no]</cmd>. Unfortunately, these commands sound very
similar to <cmd>indentation</cmd> and <cmd>noindentation</cmd>, thus can be easily
used by mistake. If you happen to write <cmd>noindenting</cmd> instead of
<cmd>noindentation</cmd> in a document, it can take a while to debug.