Difference between revisions of "Enumerations"

From Wiki
Jump to navigation Jump to search
(add \startitemize[text] explanation)
m (Text replacement - "</cmd>" to "}}")
(41 intermediate revisions by 17 users not shown)
Line 1: Line 1:
< [[Structurals]]
+
= Overview of commands =
 +
 
 +
== \startitemize ==
  
 
The most basic form of using enumerations in ConTeXt is
 
The most basic form of using enumerations in ConTeXt is
Line 10: Line 12:
 
</texcode>
 
</texcode>
  
The <cmd>startitemize</cmd> command takes optional parameters (see the documentation of <cmd>startitemgroup</cmd> for a complete list), for example a number conversion may be given, with the following predefined types:
+
The {{cmd|startitemize}} command takes optional parameters (see the documentation of {{cmd|startitemgroup}} for a complete list), for example a number conversion may be given, with the following predefined types:
  
 
<table>
 
<table>
Line 24: Line 26:
 
</table>
 
</table>
  
It is also possible to define your own number conversions; see [[User-Defined Enumerations]]. If you have loaded the [[Chinese]] module, you can also use <tt>c</tt> (and some more) for Chinese numbers.
+
It is also possible to define your own number conversions; see [[User-Defined Enumerations]]. If you have loaded the [[Chinese Japanese and Korean|Chinese]] module, you can also use <tt>c</tt> (and some more) for Chinese numbers.
 +
 
 +
When the selected language is Slovenian or Spanish, items are numbered using their proper alphabets (the Slovenian enumeration includes č, š and ž; the Spanish enumeration includes ñ). You can change to the international enumeration with <code>alphabetic</code>, <code>Alphabetic</code>.
  
 
Additional parameters include
 
Additional parameters include
 
* <tt>continue</tt> (start where the previous itemization  was finished, to allow text injections),
 
* <tt>continue</tt> (start where the previous itemization  was finished, to allow text injections),
 +
* <tt>reverse</tt> (numbers the items in reverse, i.e. descending, order),
 
* <tt>packed</tt> (less vertical space between items),  
 
* <tt>packed</tt> (less vertical space between items),  
 
* <tt>inmargin</tt> (place enumeration symbols into the margin), and
 
* <tt>inmargin</tt> (place enumeration symbols into the margin), and
 
* <tt>text</tt> (paragraph enumerations, formats the items as a running text).
 
* <tt>text</tt> (paragraph enumerations, formats the items as a running text).
  
To change the general layout of enumerations, there is <cmd>setupitemize</cmd>.  It accepts an integer as its first parameter to denote for which level of itemization the subsequent settings should apply.  There is an example below.
+
== \setupitemize ==
  
For finer control, it is advisable to create new types of itemization, using the command <cmd>defineitemgroup</cmd> (which unfortunately seems undocumented)For example, something similar to the LaTeX <tt>itemize</tt> environment can be defined as follows:
+
To change the general layout of enumerations, there is {{cmd|setupitemize}}.  It accepts an integer as its first parameter to denote for which level of itemization the subsequent settings should apply.   
  
<texcode>
+
You will find more about {{cmd|setupitemize}} at {{cmd|setupitemgroup}} and {{cmd|defineitemgroup}}.
 +
 
 +
== \defineitemgroup ==
 +
 +
For finer control, it is advisable to create new types of itemization, using the command {{cmd|defineitemgroup}}.  For example:
 +
 
 +
{|
 +
! width="45%"|
 +
! width="10%"|
 +
! width="45%"|
 +
|-
 +
| <texcode>
 
   \defineitemgroup[ltxitm][levels=5]
 
   \defineitemgroup[ltxitm][levels=5]
 
   %
 
   %
Line 66: Line 82:
 
   \stoptext
 
   \stoptext
 
</texcode>
 
</texcode>
 
+
|
gives
+
| <context>
 
 
<context>
 
 
   \defineitemgroup[ltxitm][levels=5]
 
   \defineitemgroup[ltxitm][levels=5]
 
   %
 
   %
Line 99: Line 113:
 
   \stoptext
 
   \stoptext
 
</context>
 
</context>
 +
|}
  
==Changing the Signs==
+
= Customization details and examples =
  
For a enumeration like this:
+
==Manual labels==
  
<context>
+
{|
 +
! width="50%"|
 +
! width="50%"|
 +
|-
 +
|<context>
 
\starttext
 
\starttext
 
\setupitemize[left=(, right=), margin=4em, stopper=]
 
\setupitemize[left=(, right=), margin=4em, stopper=]
Line 113: Line 132:
 
\stoptext
 
\stoptext
 
</context>
 
</context>
 +
| <texcode>
 +
\setupitemize[left=(, right=), margin=4em, stopper=]
 +
\startitemize[a]
 +
\item one item,
 +
\item next item.
 +
\stopitemize
 +
</texcode>
 +
* <tt>margin</tt> is from left margin to start of item text
 +
* <tt>stopper</tt> is the dot (or whatever) after the "number"
 +
|-
 +
|<context>
 +
\starttext
 +
\startitemize[R,fit][itemalign=flushright,stopper={ --- }]
 +
\dorecurse{5}{\item blablabla}
 +
\stopitemize
 +
\stoptext
 +
</context>
 +
|<texcode>
 +
\startitemize[R,fit][itemalign=flushright,stopper={ --- }]
 +
\dorecurse{5}{\item blablabla}
 +
\stopitemize
 +
</texcode>
 +
|-
 +
|<context>
 +
\starttext
 +
\startitemize[n,packed][start=42,stopper={\space}]
 +
\dorecurse{3}{\item Lorem ipsum}
 +
\stopitemize
 +
\stoptext
 +
</context>
 +
|
 +
You can tell ConTeXt to begin item numbering at given offset [http://thread.gmane.org/gmane.comp.tex.context/61728/focus=61729]:
 +
<texcode>
 +
\startitemize[n,fit][start=42,stopper={\space}]
 +
\dorecurse{3}{\item Lorem ipsum}
 +
\stopitemize
 +
</texcode>
 +
|-
 +
|<context>
 +
\starttext
 +
\startitemize[a,packed]
 +
\item bar
 +
\sym{1.}  foo
 +
\sym{2.}  bar
 +
\sym{3.}  foo
 +
\sym{5.}  bar
 +
\sym{8.}  foo
 +
\sym{13.} bar
 +
\item foo
 +
\stopitemize
 +
\stoptext
 +
</context>
 +
|Irregular item types can be inserted via {{cmd|sym}}: <tt>\sym{#1}</tt> [http://article.gmane.org/gmane.comp.tex.context/61731]:
 +
<texcode>
 +
\startitemize[a]
 +
\item bar
 +
\sym{1.}  foo
 +
\sym{2.}  bar
 +
\sym{3.}  foo
 +
\sym{5.}  bar
 +
\sym{8.}  foo
 +
\sym{13.} bar
 +
\item foo
 +
\stopitemize
 +
</texcode>
 +
Note that the original (alphabetically enumerated) order is not affected by
 +
these insertions: it continues after the last one as if they didn't exist.
 +
|}
 +
 +
== Expanded subnumbers ==
 +
 +
To specify that item numbers should also be leading numbers in any subitemizations, use the {{code|repeat}} keyword.
 +
 +
<context source=yes>
 +
% Indentation is a bit odd; cannot reproduce off-wiki.
 +
 +
\setupitemgroup[itemize][1][n,repeat]
 +
\setupitemgroup[itemize][2][a,repeat]
 +
\setupitemgroup[itemize][3][n]
 +
 +
This is our item list:
 +
 +
\startitemize
 +
    \item ...          % 1
 +
    \startitemize
 +
        \item ...      % 1.a
 +
        \startitemize
 +
            \item ...  % 1.a.1
 +
        \stopitemize
 +
        \item ...      % 1.b
 +
        \startitemize
 +
            \item ...  % 1.b.1
 +
            \item ...  % 1.b.2
 +
        \stopitemize
 +
    \stopitemize
 +
    \item ...          % 1
 +
\stopitemize
 +
</context>
 +
 +
To add change the separator mark, you have to setup the {{code|numberseparatorset}} key of the {{code|itemgroup:itemize}} counter. This example removes the separator mark entirely.
 +
 +
<context source=yes mode=mkiv>
 +
\setupitemgroup[itemize][1][n,repeat][width=1em]
 +
\setupitemgroup[itemize][2][a,repeat][width=2em]
 +
\setupitemgroup[itemize][3][n]      [width=3em]
 +
 +
\defineseparatorset[none][][]
 +
 +
\setupcounter[itemgroup:itemize][numberseparatorset=none]
 +
\startitemize
 +
    \item ...          % 1
 +
    \startitemize
 +
        \item ...      % 1a
 +
        \startitemize
 +
            \item ...  % 1a1
 +
        \stopitemize
 +
    \stopitemize
 +
\stopitemize
 +
</context>
 +
 +
== Vertical spacing ==
 +
 +
This is the way how you can set spacing before and after itemize when working with
 +
<texcode>
 +
\setupwhitespace[big]
 +
</texcode>
 +
 +
An option '''nowhite''' comes in handy:
 +
 +
<texcode>
 +
paragraph before
 +
 +
\startitemize[joinedup,nowhite,after]
 +
\item first
 +
\item second
 +
\stopitemize
 +
 +
paragraph after
 +
</texcode>
 +
 +
These are all the four possible combinations of whitespace settings that you might want to use:
 +
 +
 +
<context>
 +
\setuplayout[scale=0.8,width=9cm]
 +
\setupwhitespace[big]
 +
\definesymbol[1][$\triangleright$]
 +
\startcolumns
 +
{\bf joinedup:}                \par before \startitemize[joinedup]                \item test \item test \stopitemize after \par
 +
{\bf nowhite:}                \par before \startitemize[nowhite]                \item test \item test \stopitemize after \par
 +
{\bf joinedup,nowhite:}        \par before \startitemize[joinedup,nowhite]        \item test \item test \stopitemize after \column
 +
{\bf joinedup,nowhite,before:} \par before \startitemize[joinedup,nowhite,before] \item test \item test \stopitemize after \par
 +
{\bf joinedup,nowhite,after:}  \par before \startitemize[joinedup,nowhite,after]  \item test \item test \stopitemize after
 +
\stopcolumns
 +
</context>
 +
 +
  
you must fill <cmd>setupitemize</cmd> like this:
+
It is also (at least in mkiv) possible to do
 +
<texcode>
 +
Text before
 +
\startitemize[before={\blank[small]},after={\blank[small]},inbetween={\blank[medium]}]
 +
\item test
 +
\item test
 +
\stopitemize
 +
Text after
 +
</texcode>
 +
to control the vertical space.
 +
 
 +
 
 +
 
 +
To prevent an unwanted pagebreak before the list, there is an <tt>intro</tt> parameter :
 +
<texcode>
 +
The following list is on the same page as this paragraph :
 +
\startitemize[intro]
 +
  \startitem foo \stopitem
 +
  \startitem bar \stopitem
 +
\stopitemize
 +
</texcode>
  
* you get parentheses by <tt>left=(, right=)</tt>
+
==Horizontal spacing==
* <tt>margin</tt> is from left margin to start of item text
+
{|
* <tt>stopper</tt> is the dot (or whatever) after the "number"
+
! width="45%"|
 +
! width="10%"|
 +
! width="45%"|
 +
|-
 +
|To control the space between the item symbol (bullet) and the item text
  
 +
you can use eather the broad option
 
<texcode>
 
<texcode>
\setupitemize[left=(, right=), margin=4em, stopper=]
+
\startitemize[n*broad] %replace n with a number (e.g "3").
\startitemize[a]
+
\item Test
\item one item,
+
\stopitemize
\item next item.
+
</texcode>
 +
or you can use absolute values (for fine tuning):
 +
<texcode>
 +
\startitemize[width=1em,distance=0pt]
 +
\item Test
 
\stopitemize
 
\stopitemize
 
</texcode>
 
</texcode>
 +
|
 +
|<context>
 +
\startitemize[width=1em,distance=0pt]
 +
\item Using width=1em,distance=0pt
 +
\stopitemize\setuplayout[scale=0.8,width=9cm]
 +
\startitemize
 +
\item {\bf Default} (no arguments)
 +
\stopitemize
  
You find more about <cmd>setupitemize</cmd> at <cmd>defineitemgroup</cmd>.
+
\startitemize[1*broad]
 +
\item Using 1*broad
 +
\stopitemize
 +
\startitemize[3*broad]
 +
\item Using 2*broad
 +
\stopitemize
 +
</context>
 +
|}
  
 +
==Multicolumn==
  
==Alternate Multicolumn Format==
 
 
Hans posted a solution to the list for a multicolumn enumeration that counts across then down, instead of down then across. When he posted it (Dec 21, 2005), he said the joinedup option does not work, but he would fix that. This is a version without the tufte and zapf text
 
Hans posted a solution to the list for a multicolumn enumeration that counts across then down, instead of down then across. When he posted it (Dec 21, 2005), he said the joinedup option does not work, but he would fix that. This is a version without the tufte and zapf text
  
<texcode>
+
{|
 +
! width="45%"|
 +
! width="10%"|
 +
! width="45%"|
 +
|-
 +
| <texcode>
 
\starttext
 
\starttext
  
Line 156: Line 381:
 
\stoptext
 
\stoptext
 
</texcode>
 
</texcode>
 
+
|
<context>
+
|<context>
 
\starttext
 
\starttext
  
Line 180: Line 405:
  
 
</context>
 
</context>
 +
|}
 +
 +
From a discussion on the mailing list, the following was suggested (note that you have to enclose your items in {{cmd|startitem}} and {{cmd|stopitem}}, using  {{cmd|item}} only does not work):
 +
 +
{|
 +
! width="35%"|
 +
! width="5%"|
 +
! width="60%"|
 +
|-
 +
| <texcode>
 +
\starttext
 +
 +
Some previous sentence before the list
 +
 +
\startitemize[a,horizontal,three]
 +
\startitem first \stopitem
 +
\startitem second \stopitem
 +
\startitem third \stopitem
 +
\startitem fourth \stopitem
 +
\startitem fifth \stopitem
 +
\startitem sixth \stopitem
 +
\stopitemize
 +
 +
And the text continues after the list
 +
 +
\stoptext
 +
</texcode>
 +
|
 +
|<context>
 +
\starttext
 +
 +
Some previous sentence before the list
 +
 +
\startitemize[a,horizontal,two]
 +
\startitem first \stopitem
 +
\startitem second \stopitem
 +
\startitem third \stopitem
 +
\startitem fourth \stopitem
 +
\stopitemize
 +
 +
And the text continues after the list
 +
 +
\stoptext
 +
 +
</context>
 +
|}
 +
 +
= Other considerations =
 +
 +
== Randomizing items ==
 +
It is possible to make ConTeXt randomize the items in enumerations; this can come handy when, e.g., typesetting tests.  You have to add a <tt>random</tt> option to {{cmd|startitemize}}.  There are two caveats:
 +
# You have to say {{cmd|startitem}} ... {{cmd|stopitem}} instead of {{cmd|item}} ... .
 +
# Somehow the first item does not get randomized.  (I learned from the mailing list - thanks, Aditya! - that adding a {{cmd|nextrandom}} somewhere earlier helps.)
 +
Example:
 +
 +
{|
 +
! width="45%"|
 +
! width="10%"|
 +
! width="45%"|
 +
|-
 +
| <texcode>
 +
\nextrandom
 +
\startitemize[random]
 +
\startitem A \stopitem
 +
\startitem B \stopitem
 +
\startitem C \stopitem
 +
%\startitem F \stopitem
 +
\stopitemize
 +
</texcode>
 +
|
 +
| <context>
 +
\nextrandom
 +
\startitemize[random]
 +
\startitem A \stopitem
 +
\startitem B \stopitem
 +
\startitem C \stopitem
 +
%\startitem F \stopitem
 +
\stopitemize
 +
</context>
 +
|}
 +
 +
== Referring to items ==
 +
You can also use a reference to an item, just like a chapter or section. See also [[References]].
 +
 +
{|
 +
! width="45%"|
 +
! width="10%"|
 +
! width="45%"|
 +
|-
 +
| <texcode>
 +
\starttext
 +
\startitemize[n]
 +
\item A
 +
\item[foo] B
 +
\item C
 +
\stopitemize
 +
\dots
 +
As seen in \in{item}[foo] on page \at{page}[foo], B is teh shizzle.
 +
\stoptext
 +
</texcode>
 +
|
 +
| <context>
 +
\starttext
 +
\startitemize[n]
 +
\item A
 +
\item[foo] B
 +
\item C
 +
\stopitemize
 +
\dots
 +
As seen in \in{item}[foo] on page \at{page}[foo], B is teh shizzle.
 +
\stoptext
 +
</context>
 +
|}
 +
 +
=Further Reading=
 +
 +
* [[User-Defined Enumerations]]: Defining a new numbering scheme.
 +
* [[Command/startitemize]]
 +
* The source: {{src|strc-itm.mkvi}}
 +
* [[Description]] (definition lists)
 +
 +
[[Category:Basics]]

Revision as of 13:17, 9 August 2020

Overview of commands

\startitemize

The most basic form of using enumerations in ConTeXt is

 \startitemize
 \item here we list the points,
 \item one after the other.
 \stopitemize

The \startitemize command takes optional parameters (see the documentation of \startitemgroup for a complete list), for example a number conversion may be given, with the following predefined types:

n or NUsually the default: a numbered list
mA numbered list, with lowercase (“medieval”, aka “oldstyle”) numbers.
18Different kinds of bullets. All items get the same symbol.
aItems are numbered a., b., c., …
AItems are numbered A., B., C., …
AKItems are numbered A., B., C., …, in small caps.
rItems are numbered in lowercase Roman numerals.
RItems are numbered in uppercase Roman numerals.
KRItems are numbered in uppercase Roman numerals, small caps style.

It is also possible to define your own number conversions; see User-Defined Enumerations. If you have loaded the Chinese module, you can also use c (and some more) for Chinese numbers.

When the selected language is Slovenian or Spanish, items are numbered using their proper alphabets (the Slovenian enumeration includes č, š and ž; the Spanish enumeration includes ñ). You can change to the international enumeration with alphabetic, Alphabetic.

Additional parameters include

  • continue (start where the previous itemization was finished, to allow text injections),
  • reverse (numbers the items in reverse, i.e. descending, order),
  • packed (less vertical space between items),
  • inmargin (place enumeration symbols into the margin), and
  • text (paragraph enumerations, formats the items as a running text).

\setupitemize

To change the general layout of enumerations, there is \setupitemize. It accepts an integer as its first parameter to denote for which level of itemization the subsequent settings should apply.

You will find more about \setupitemize at \setupitemgroup and \defineitemgroup.

\defineitemgroup

For finer control, it is advisable to create new types of itemization, using the command \defineitemgroup. For example:

  \defineitemgroup[ltxitm][levels=5]
  %
  \setupitemgroup[ltxitm][1][1]
  \setupitemgroup[ltxitm][2][2]
  \setupitemgroup[ltxitm][3][3,packed]
  \setupitemgroup[ltxitm][4][4,packed]
  \setupitemgroup[ltxitm][5][5,packed]
  %
  \starttext
  %
  \startltxitm
    \item Consider
      \startltxitm
      \item this part
      \item and also these subpoints:
        \startltxitm
        \item one
        \item two
        \item three
          \startltxitm
            \item threeandahalf
          \stopltxitm
        \item four
        \stopltxitm
      \stopltxitm
  \stopltxitm
  %
  \stoptext

Customization details and examples

Manual labels

\setupitemize[left=(, right=), margin=4em, stopper=]
\startitemize[a]
\item one item,
\item next item.
\stopitemize
  • margin is from left margin to start of item text
  • stopper is the dot (or whatever) after the "number"
\startitemize[R,fit][itemalign=flushright,stopper={ --- }]
\dorecurse{5}{\item blablabla}
\stopitemize

You can tell ConTeXt to begin item numbering at given offset [1]:

\startitemize[n,fit][start=42,stopper={\space}]
\dorecurse{3}{\item Lorem ipsum}
\stopitemize
Irregular item types can be inserted via \sym: \sym{#1} [2]:
\startitemize[a]
\item bar
\sym{1.}  foo
\sym{2.}  bar
\sym{3.}  foo
\sym{5.}  bar
\sym{8.}  foo
\sym{13.} bar
\item foo
\stopitemize

Note that the original (alphabetically enumerated) order is not affected by these insertions: it continues after the last one as if they didn't exist.

Expanded subnumbers

To specify that item numbers should also be leading numbers in any subitemizations, use the repeat keyword.

% Indentation is a bit odd; cannot reproduce off-wiki.

\setupitemgroup[itemize][1][n,repeat]
\setupitemgroup[itemize][2][a,repeat]
\setupitemgroup[itemize][3][n]

This is our item list:

\startitemize
    \item ...          % 1
    \startitemize
        \item ...      % 1.a
        \startitemize
            \item ...  % 1.a.1
        \stopitemize
        \item ...      % 1.b
        \startitemize
            \item ...  % 1.b.1
            \item ...  % 1.b.2
        \stopitemize
    \stopitemize
    \item ...          % 1
\stopitemize

To add change the separator mark, you have to setup the numberseparatorset key of the itemgroup:itemize counter. This example removes the separator mark entirely.

\setupitemgroup[itemize][1][n,repeat][width=1em]
\setupitemgroup[itemize][2][a,repeat][width=2em]
\setupitemgroup[itemize][3][n]       [width=3em]

\defineseparatorset[none][][]

\setupcounter[itemgroup:itemize][numberseparatorset=none]
\startitemize
    \item ...          % 1
    \startitemize
        \item ...      % 1a
        \startitemize
            \item ...  % 1a1
        \stopitemize
    \stopitemize
\stopitemize

Vertical spacing

This is the way how you can set spacing before and after itemize when working with

\setupwhitespace[big]

An option nowhite comes in handy:

paragraph before

\startitemize[joinedup,nowhite,after]
\item first
\item second
\stopitemize

paragraph after

These are all the four possible combinations of whitespace settings that you might want to use:



It is also (at least in mkiv) possible to do

Text before
\startitemize[before={\blank[small]},after={\blank[small]},inbetween={\blank[medium]}]
\item test
\item test
\stopitemize
Text after

to control the vertical space.


To prevent an unwanted pagebreak before the list, there is an intro parameter :

The following list is on the same page as this paragraph :
\startitemize[intro]
  \startitem foo \stopitem
  \startitem bar \stopitem
\stopitemize

Horizontal spacing

To control the space between the item symbol (bullet) and the item text

you can use eather the broad option

\startitemize[n*broad] %replace n with a number (e.g "3").
	\item Test
\stopitemize

or you can use absolute values (for fine tuning):

\startitemize[width=1em,distance=0pt]
	\item Test
\stopitemize

Multicolumn

Hans posted a solution to the list for a multicolumn enumeration that counts across then down, instead of down then across. When he posted it (Dec 21, 2005), he said the joinedup option does not work, but he would fix that. This is a version without the tufte and zapf text

\starttext

Some previous sentence before the list

\startitemize[columns,n,joinedup]
\item one
\item two
\stopitemize
\startitemize[continue,columns,joinedup]
\item one
\item two
\stopitemize
\startitemize[continue,columns,joinedup]
\item one
\item two
\stopitemize

And the text continues after the list

\stoptext

From a discussion on the mailing list, the following was suggested (note that you have to enclose your items in \startitem and \stopitem, using \item only does not work):

\starttext

Some previous sentence before the list

\startitemize[a,horizontal,three]
\startitem first \stopitem
\startitem second \stopitem
\startitem third \stopitem
\startitem fourth \stopitem
\startitem fifth \stopitem
\startitem sixth \stopitem
\stopitemize

And the text continues after the list

\stoptext

Other considerations

Randomizing items

It is possible to make ConTeXt randomize the items in enumerations; this can come handy when, e.g., typesetting tests. You have to add a random option to \startitemize. There are two caveats:

  1. You have to say \startitem ... \stopitem instead of \item ... .
  2. Somehow the first item does not get randomized. (I learned from the mailing list - thanks, Aditya! - that adding a \nextrandom somewhere earlier helps.)

Example:

\nextrandom
\startitemize[random]
\startitem A \stopitem
\startitem B \stopitem
\startitem C \stopitem
%\startitem F \stopitem
\stopitemize

Referring to items

You can also use a reference to an item, just like a chapter or section. See also References.

\starttext
\startitemize[n]
\item A
\item[foo] B
\item C
\stopitemize
\dots
As seen in \in{item}[foo] on page \at{page}[foo], B is teh shizzle.
\stoptext

Further Reading