Difference between revisions of "Indentation"
m (typo) |
m (Narrower examples, no more <cmd> tags) |
||
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. |
− | < | ||
− | explicitly begun with < | ||
− | < | ||
− | overrule that, he can add an explicit < | ||
− | paragraph. For the most part, LaTeX follows the same convention. | ||
− | So, understanding indentation in plain TeX and LaTeX boils down to this: set a | + | So, understanding indentation in plain TeX and LaTeX boils down to this: set a value for <tt>parindent</tt>, 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. |
− | value for < | ||
− | 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 | + | 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. |
− | 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 = | = 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 <tt>{{cmd|setupindenting}}[...]</tt>. There are three types of keys for this command: |
− | ConTeXt, these can be specified using <cmd | ||
− | are three types of keys for this command: | ||
* '''To enable indenting:''' <code>never</code> or <code>always</code>, (equivalently, <code>no</code> or <code>yes</code>), The default is '''<code>never</code>''' | * '''To enable indenting:''' <code>never</code> or <code>always</code>, (equivalently, <code>no</code> or <code>yes</code>), The default is '''<code>never</code>''' | ||
Line 55: | Line 27: | ||
<texcode>\setupindenting[20pt, yes, first]</texcode> | <texcode>\setupindenting[20pt, yes, first]</texcode> | ||
− | This is what one typically uses in a document. The other keys are needed only | + | 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 |
− | for special cases (like typesetting quotations and verses). In particular, the most commonly | ||
− | used keys are | ||
* <code>yes</code> enable indenting | * <code>yes</code> enable indenting | ||
Line 70: | Line 40: | ||
== Setting up indentation after an environment == | == Setting up indentation after an environment == | ||
− | + | {{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 | + | 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. |
− | '''<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> | <texcode> | ||
\setupitemgroup[itemize][indentnext=no] | \setupitemgroup[itemize][indentnext=no] | ||
Line 99: | Line 55: | ||
</texcode> | </texcode> | ||
− | If we want the paragraphs after all sectioning heads to be | + | If we want the paragraphs after all sectioning heads to be indented, we can say |
− | indented, we can say | ||
<texcode> | <texcode> | ||
Line 106: | Line 61: | ||
</texcode> | </texcode> | ||
− | If we want paragraphs after formulas to be indented only if we | + | If we want paragraphs after formulas to be indented only if we leave a blank space after them, we can say |
− | leave a blank space after them, we can say | ||
<texcode> | <texcode> | ||
Line 115: | Line 69: | ||
== Setting up indentation inside environments == | == Setting up indentation inside environments == | ||
− | There is one case that is not taken care of by | + | 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 values as the arguments of {{cmd|setupindenting}} command. For example, if we set |
− | <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 | ||
− | |||
<texcode> | <texcode> | ||
\setupitemgroup[itemize][indenting={40pt,next}] | \setupitemgroup[itemize][indenting={40pt,next}] | ||
Line 129: | Line 76: | ||
then the following : | then the following : | ||
− | <context source="yes" text="gives | + | <context source="yes" text="gives"> |
+ | \setuppapersize[A5] | ||
+ | |||
\setupindenting[medium,yes] | \setupindenting[medium,yes] | ||
\setupitemgroup[itemize][indenting={40pt,next}] | \setupitemgroup[itemize][indenting={40pt,next}] | ||
Line 140: | Line 89: | ||
\stopitemize | \stopitemize | ||
</context> | </context> | ||
− | |||
− | |||
= Manual indentation = | = Manual indentation = | ||
− | No matter how careful we are with all the settings, there are some cases which | + | 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}} and {{cmd|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 {{cmd|indentation}} and {{cmd|noindentation}} which achieve the same effect. |
− | cannot be taken care of by automatic indentation, and we have to tell ConTeXt | ||
− | how to indent. Plain TeX (and LaTeX) provide the | ||
− | 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 | ||
− | |||
Suppose the default setup for an article is | Suppose the default setup for an article is | ||
Line 158: | Line 99: | ||
</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 | + | |
− | + | <context source="yes" text="gives"> | |
+ | \setuppapersize[A5] | ||
− | |||
\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 |
− | \item To check \type{\indent} | + | \item To check \type{\indent} |
\stopitemize | \stopitemize | ||
\indent This paragraph is not indented. The | \indent This paragraph is not indented. The | ||
− | \type{\indent} command does not work here. | + | \type{\indent} command does not work here. |
\startitemize[n] | \startitemize[n] | ||
− | \item Another dummy list | + | \item Another dummy list |
− | \item To check \type{\indentation} | + | \item To check \type{\indentation} |
\stopitemize | \stopitemize | ||
\indentation This paragraph will be indented | \indentation This paragraph will be indented | ||
− | because we used \type{\indentation} instead. | + | because we used \type{\indentation} instead. |
</context> | </context> | ||
= Beware of typos = | = Beware of typos = | ||
− | ConTeXt defines two more commands not commonly used: | + | ConTeXt defines two more commands not commonly used: {{cmd|indenting}} and {{cmd|noindenting}}. {{cmd|indenting}} is similar to {{cmd|setupindenting}} and is provided for backward compatibility; {{cmd|noindenting}} is equivalent to {{cmd|setupindenting[no]}}. Unfortunately, these commands sound very similar to {{cmd|indentation}} and {{cmd|noindentation}}, thus can be easily used by mistake. If you happen to write {{cmd|noindenting}} instead of {{cmd|noindentation}} in a document, it can take a while to debug. |
− | |||
− | |||
− | |||
− | |||
− | similar to | ||
− | used by mistake. If you happen to write | ||
− |
Revision as of 12:03, 11 June 2012
< 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.
Contents
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:
- To enable indenting:
never
oralways
, (equivalently,no
oryes
), The default isnever
- To specify when to indent::
odd
oreven
, andfirst
ornext
. The default isfirst
- To specify how much to indent:
none
,small
,medium
,big
, or a specific dimension.small
corresponds to 1em,medium
to 1.5em, andbig
to 2em. The default isnone
.
Suppose we want to indent all paragraphs by 20pt: we can use
\setupindenting[20pt, yes]
which is equivalent ot
\setupindenting[20pt, yes, first]
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
yes
enable indentingno
disable indentingtoggle
toggle the indenting state (if indenting was enabled, disable it and vice-versa)odd
indents every odd paragrapheven
indents every even paragraphfirst
indents all paragraphs, including the first paragraphnext
does not indent the first paragraph, but indents every subsequent paragraphreset
reset all settings to their default values. This disable indenting, sets the indenting amount tonone
, disablesodd
oreven
indenting, and sets indenting method tofirst
.
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
, no
, and auto
. If indentnext=yes
then the paragraph after the end of the environment is always indented; if indentnext=no
then the next paragraph is never indented; if indentnext=auto
then the next paragraph is indented only if there is a blank space after the environment. Setting indentnext=auto
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
\setupitemgroup[itemize][indentnext=no]
If we want paragraphs after section heads to be indented, we can say
\setuphead[section][indentnext=yes]
If we want the paragraphs after all sectioning heads to be indented, we can say
\setupheads[indentnext=yes]
If we want paragraphs after formulas to be indented only if we leave a blank space after them, we can say
\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 values as the arguments of \setupindenting command. For example, if we set
\setupitemgroup[itemize][indenting={40pt,next}]
then the following :
\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 \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.
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 [[Command/setupindenting[no]|\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.