Difference between revisions of "Indentation"

From ConTeXt wiki
Jump to navigationJump to search
m (Documenting toggle)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
< [[Visuals]]
 
< [[Visuals]]
  
In plain TeX, controlling indentation is simple: The user sets a value for
+
In plain TeX, controlling indentation is simple: The user sets a value for <tt>parindent</tt>, and each new paragraph is indented by that value, unless explicitly begun with <tt>noindent</tt>. Environments can provide a <tt>noindent</tt> at the end of their definitions, and if the user wants to overrule that, he can add an explicit <tt>indent</tt> at the beginning of the next paragraph. For the most part, LaTeX follows the same convention.
<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
+
Indentation in ConTeXt are a bit different: it mostly does not rely on the presence of blank lines, but uses {{cmd|setupindenting}} to manage general indentation, the <code>indentnext=yes/no/auto</code> key on environments to enable/disable indentation after them, and {{cmd|indentation}} and {{cmd|noindentation}} to manually force/disable an indentation.  
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
+
The commands {{cmd|indent}}, {{cmd|noindent}}, {{cmd|indenting}}, and {{cmd|noindenting}} are present for historical reasons, but should not be used. Especially, they should not be confused with {{cmd|indentation}} and {{cmd|noindentation}}
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 &mdash; surrounding each environment by empty lines
 
&mdash; 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 ==
 
== Setting up indentation for the whole document ==
  
Indentation involves two things: when to indent, and how much to indent. In
+
Indentation involves two things: when to indent, and how much to indent. In ConTeXt, these can be specified using {{cmd|setupindenting}}<tt>[...]</tt>. There are three types of keys for this command:
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>.
+
* <code>''no'' yes</code>: turn indentation on/off'
 
+
* <code>''none'' small medium big ''dimension''</code>: size of indents
* '''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.
+
* <code>''first'' next</code>: turn indentation of first paragraph on/off. Can be overridden by environments with <code>indentnext=yes/no/auto</code>.
 
+
* <code>odd even</code>: indent odd/even lines in \obeylines scopes
 
+
* <code>normal</code>: what does this do?
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). In particular, the most commonly
 
used keys are
 
 
 
* <code>yes</code> enable indenting
 
* <code>no</code> disable indenting
 
* <code>toggle</code> toggle the indenting state (if indenting was enabled, disable it and vice-versa)
 
* <code>odd</code> indents every odd paragraph
 
* <code>even</code> indents every even paragraph
 
* <code>first</code> indents the first paragraph
 
* <code>next</code> ''does not'' indent the first paragraph, but indents every subsequent paragrah
 
  
 
== Setting up indentation after an environment ==
 
== Setting up indentation after an environment ==
  
<cmd>setupindenting</cmd> does not take care of indenting after environments,
+
{{cmd|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.  
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
+
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:
itemize to be indented; then we can say
+
* <code>yes</code> declares the first paragraph following the environment should always be indented.
 +
* <code>no</code> declares the first paragraph following the environment should never be indented.
 +
* <code>auto</code> declares <code>indentnext=auto</code> the next paragraph should be 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.
  
 +
Some examples:
 
<texcode>
 
<texcode>
 +
% Do not indent paragraphs after \stopitemize
 
\setupitemgroup[itemize][indentnext=no]
 
\setupitemgroup[itemize][indentnext=no]
</texcode>
 
 
If we want paragraphs after section heads to be indented, we can say
 
  
<texcode>
+
% indent paragraphs after section heads
 
\setuphead[section][indentnext=yes]
 
\setuphead[section][indentnext=yes]
</texcode>
 
  
If we want the paragraphs after all sectioning heads to be
+
% indent the paragraphs after all sectioning heads  
indented, we can say
+
\setupheads[indentnext=yes]
  
<texcode>
+
% indent paragraphs after formulas if there is a blank space in between
\setupheads[indentnext=yes]
+
\setupformulas[indentnext=auto]  
</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>
 
</texcode>
  
 
== Setting up indentation inside environments ==
 
== Setting up indentation inside environments ==
  
There is one case that is not taken care of by <cmd>setupindenting</cmd> and the
+
There is one case that is not taken care of by {{cmd|setupindenting}} 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 arguments as the {{cmd|setupindenting}} command does. An example using {{cmd|setupitemgroup}}:
<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>
+
<context source="yes" text="gives">
\setupitemgroup[itemize][indenting={40pt,yes}]
+
\setuppapersize[A5]
</texcode>
 
  
then the following :
+
\setupindenting[medium,yes]
 
+
\setupitemgroup[itemize][indenting={40pt,next}]
<context source="yes" text="gives" scale="0.8">
 
\setupitemgroup[itemize][indenting={40pt,yes}]
 
 
\startitemize
 
\startitemize
 
\item This is an example of a multi|-|paragraph  
 
\item This is an example of a multi|-|paragraph  
Line 133: Line 59:
 
</context>
 
</context>
  
{{note|type=attention|1=Indentation inside itemize works differently in MkIV: <code>indenting={40pt,yes}</code> also indents the first line! To get the visual output shown above in MkIV, use <code>indenting={40pt,'''next'''}</code>.}}
+
== "indentnext=auto" demo ==
  
= Manual indentation =
+
<context source = "yes" text="gives:">
 +
\setupindenting[medium,yes]
 +
\setupitemize[indentnext=auto]
  
No matter how careful we are with all the settings, there are some cases which
+
  \startitemize
cannot be taken care of by automatic indentation, and we have to tell ConTeXt
+
    \item One
how to indent. Plain TeX (and LaTeX) provide the <cmd>indent</cmd> and <cmd>noindent</cmd>
+
  \stopitemize
commands for explicitly indenting and preventing indenting of a paragraph. These
+
 
commands are defined in ConTeXt but are not hooked into the ConTeXt
+
  This paragraph should be indented - due to the blank line after \type{\stopitemize}.
indentation mechanism. Instead, ConTeXt provides <cmd>indentation</cmd> and
+
 
<cmd>noindentation</cmd> which achieve the same effect.
+
  \startitemize
 +
    \item Two
 +
  \stopitemize
 +
  This paragraph should not be indented.
 +
</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. This is done with {{cmd|indentation}} and {{cmd|noindentation}}. The Plain TeX (and LaTeX) commands <tt>\indent</tt> and <tt>\noindent</tt> are defined in ConTeXt, but are not hooked into the indentation mechanism.
  
 
Suppose the default setup for an article is
 
Suppose the default setup for an article is
Line 150: Line 86:
 
</texcode>
 
</texcode>
  
Now, if we want to indent after an itemize, starting the next paragraph
+
Now, if we want to indent after an itemize, starting the next paragraph with {{cmd|indent}} does not work; to get indentation we have to say {{cmd|indentation}}. For example,
with <cmd>indent</cmd> does not work; to get indentation we have to say
+
 
<cmd>indentation</cmd>. For example,
+
<context source="yes" text="gives">
 +
\setuppapersize[A5]
  
<context source="yes" text="gives" scale="0.8">
 
 
\setupindenting [big,yes]
 
\setupindenting [big,yes]
 
\setupitemgroup [itemize] [indentnext=no]
 
\setupitemgroup [itemize] [indentnext=no]
 +
 
\startitemize[n]
 
\startitemize[n]
\item A dummy list
+
    \item A dummy list with \type{indentnext=no}...
\item To check \type{\indent}
+
    \item ...to test the \tex{indent} command
 
\stopitemize
 
\stopitemize
  
\indent This paragraph is not indented. The
+
\indent This paragraph is not indented, because \tex{indent} does not work.
\type{\indent} command does not work here.
 
  
 
\startitemize[n]
 
\startitemize[n]
\item Another dummy list
+
    \item Another dummy list with \type{indentnext=no}...
\item To check \type{\indentation}
+
    \item ...to test the \tex{indentation} command
 
\stopitemize
 
\stopitemize
  
\indentation This paragraph will be indented
+
\indentation This paragraph will be indented, because we used \tex{indentation}.
because we used \type{\indentation} instead.
 
 
</context>
 
</context>
  
= Beware of typos =
+
{{Getting started navbox}}
 
 
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.
 

Latest revision as of 08:11, 12 April 2019

< 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.

Indentation in ConTeXt are a bit different: it mostly does not rely on the presence of blank lines, but uses \setupindenting to manage general indentation, the indentnext=yes/no/auto key on environments to enable/disable indentation after them, and \indentation and \noindentation to manually force/disable an indentation.

The commands \indent, \noindent, \indenting, and \noindenting are present for historical reasons, but should not be used. Especially, they should not be confused with \indentation and \noindentation

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

"indentnext=auto" demo

\setupindenting[medium,yes]
\setupitemize[indentnext=auto]

  \startitemize
    \item One
  \stopitemize

  This paragraph should be indented - due to the blank line after \type{\stopitemize}.

  \startitemize
    \item Two
  \stopitemize
  This paragraph should not be indented.

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. This is done with \indentation and \noindentation. The Plain TeX (and LaTeX) commands \indent and \noindent are defined in ConTeXt, but are not hooked into the indentation mechanism.

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