\startcomponent co-en-10

\project manual
\product cont-en

\chapter[references]{References}

\section[toc]{Table of contents}
\index{references}
\index{table of contents}
\index{combined list}
\index{lists}
\macro[placecombined]{\tex{place<<combinedlist>>}}
\macro[completecombined]{\tex{complete<<combinedlist>>}}
\macro{\tex{definecombinedlist}}
\macro{\tex{setupcombinedlist}}
\macro{\tex{definelist}}
\macro{\tex{setuplist}}
\macro{\tex{placelist}}
\macro{\tex{writetolist}}
\macro{\tex{writebetweenlist}}
\macro{\tex{nolist}}

The table of contents is very common in books and is used
to refer to the text that lies ahead. Tables of content are
generated automatically by:

\startexample
\starttyping
\placecontent
\stoptyping
\stopexample

The table of contents shows a list of chapters and sections
but this depends also on the location where the table of
contents is summoned. Just in front of a chapter we will
obtain a complete table. But just after the chapter we will
only obtain a list of relevant sections or subsections. The
same mechanism also works with sections and subsections.

\startexample
\starttyping
\chapter{Mammals}
\placecontent
\section{Horses}
\stoptyping
\stopexample

A table of contents is an example of a combined list. Before
discussing combined lists we go into single lists. A single
list is defined with:

\showsetup{definelist}

An example of such a definition is:

\startexample
\starttyping
\definelist[firstlevel]
\stoptyping
\stopexample

Such a list is recalled with:

\startexample
\starttyping
\placelist[firstlevel]
\stoptyping
\stopexample

Each list may have its own set up:

\startexample
\starttyping
\setuplist[firstlevel][width=2em]
\stoptyping
\stopexample

Lists can be set up simultaneously, for example:

\startexample
\starttyping
\setuplist[firstlevel,secondlevel][width=2em]
\stoptyping
\stopexample

To generate a list you type:

\showsetup{placelist}

\startpostponing
\showsetup{setuplist}
\stoppostponing

The layout of a list is determined by the values of \type
{alternative} (see \in {table} [tab:setupcombinedlist]),
\type{margin}, \type{width} and \type{distance}. The
alternatives \type{a}, \type{b} and \type{c} are line
oriented. A line has the following construct:

\startlinecorrection
\hbox
  {\vbox to 3em{\framed[width=.1\hsize,rightframe=off]{\strut margin}\vss}%
   \vbox to 3em{\framed[width=.2\hsize,rightframe=off]{\strut width}\vss}%
   \vbox to 3em{\framed[width=.1\hsize,rightframe=off]{\strut distance}\vss}%
   \vbox to 3em{\framed[width=.6\hsize,height=3em]{}}}
\stoplinecorrection

\startlinecorrection
\hbox
  {\vbox to 3em{\framed[width=.1\hsize,rightframe=off]{}\vss}%
   \vbox to 3em{\framed[width=.2\hsize,rightframe=off]{headnumber}\vss}%
   \vbox to 3em{\framed[width=.1\hsize,rightframe=off]{}\vss}%
   \vbox to 3em{\framed[width=.6\hsize,height=3em]{head and pagenumber}}}
\stoplinecorrection

In a paper document it is sufficient to set up \type
{width}. In an interactive document however the \type
{width} determines the clickable area. \footnote {This also
depends on the value assigned to \type {interaction}.}

In alternative \type{d} the titles in the table will be type
set as a continuous paragraph. In that case the \type{before}
and \type{after} have no meaning. The \type{distance}, that is
1em at a minimum, relates to the distance to the next element
in the list. The next set up generates a compact table of
contents:

\startbuffer
\setuplist
  [chapter]
  [before=\blank,after=\blank,style=bold]
\setuplist
  [section]
  [alternative=d,left=(,right=),pagestyle=slanted,prefix=no]
\stopbuffer

\startexample
\typebuffer
\stopexample

Since both lists are defined already when defining the
sectioning command, we do not define them here. The
parameter \type{prefix} indicates whether the preceding
level indicator numbering is used. In this alternative the
prefix is not used. Alternative~\type{d} looks like this:

\startnarrower
\getbuffer\placelist[section][criterium=chapter]
\stopnarrower

When \type {alternative} is set to \type {d}, an element in
the list has the following construction:

\startlinecorrection
\hbox
  {\framed[rightframe=off]{left}%
   \framed[rightframe=off]{headnumber}%
   \framed[rightframe=off]{right}%
   \framed[rightframe=off,width=.3\hsize]{head}%
   \framed[rightframe=off]{page}%
   \framed{distance}}
\stoplinecorrection

When you define a title you also define a list. This means
that there are standard lists for chapters, sections and
subsections, etc. available.

These (sub)sections can be combined into one combined list.
The default table of contents is such a combined list:

\startexample
\starttyping
\definecombinedlist
  [content]
  [part,
   chapter,section,subsection,subsubsection,
   subsubsubsection,subsubsubsubsection]
  [level=subsubsubsubsection,
   criterium=local]
\stoptyping
\stopexample

The alternative setups equals that of the separate lists.

\showsetup{definecombinedlist}

\showsetup{setupcombinedlist}

These commands themselves generate the commands:

\showsetup{complete<<combinedlist>>}

\showsetup{place<<combinedlist>>}

The first command places a title at the top of the list.
This title is unnumbered because we do not want the table of
contents as an element in the list. In the next section we will
discuss lists where the numbered title \type {\chapter} is
used.

\placetable
  [here][tab:setupcombinedlist]
  {Alternatives in combined lists.}
\starttable[|c|l|]
\HL
\VL \bf alternative                            \VL
    \bf display                                \VL\SR
\HL
\VL \type{a}                                   \VL
    number -- title -- pagenumber              \VL\FR
\VL \type{b}                                   \VL
    number -- title -- spaces -- pagenumber    \VL\MR
\VL \type{c}                                   \VL
    number -- title -- dots -- pagenumber   \VL\MR
\VL \type{d}                                   \VL
    number -- title -- pagenumber (continuous) \VL\MR
\VL \type{e}                                   \VL
    title (framed)                             \VL\MR
\VL \type{f}                                   \VL
    title (left, middle or right aligned)     \VL\MR
\VL \type{g}                                   \VL
    title (centered)                           \VL\LR
\HL
\stoptable

Possible alternatives are summed up in \in {table}
[tab:setupcombinedlist]. There are a number of possible
variations and we advise you to do some experimenting when
you have specific wishes. The three parameters \type
{width}, \type {margin} and \type {style} are specified for
all levels \`or for all five levels separately.

\startexample
\starttyping
\setupcombinedlist
  [content]
  [alternative=c,
   aligntitle=no,
   width=2.5em]
\stoptyping
\setuplist
  [chapter]
  [style=bold,
   before=\blank,
   after=\blank]
\stopexample

The parameter \type {aligntitle} forces entries with no
section number (like titles, subjects and alike) to be
typeset onto the left margin. Otherwise the title is aligned
to the numbered counterparts (like chapter, section and
alike). Compare:

\startpacked
\hphantom{12\quad}title \crlf 12\quad chapter
\stoppacked

with:

\startpacked
title\crlf 12\quad chapter
\stoppacked

You can also pass setup parameters to the \type {\place...}
commands. For example:

\startexample
\starttyping
\placecontent[level=part]
\stoptyping
\stopexample

In this situation only the parts are used in the displayed
list. Instead of an identifier, like part or chapter, you
can also use a number. However this suggests that you have
some insight in the level of the separate sections (part=1,
chapter=2 etc.)

A table of contents may cross the page boundaries at an
undesired location in the list. Pagebreaking in tables of
content can hardly be automated. Therefore it is possible to
adjust the pagebreaking manually. The next example
illustrates this.

\startexample
\starttyping
\completecontent[pageboundaries={2.2,8.5,12.3.3}]
\stoptyping
\stopexample

This kind of \quote {fine||tuning} should be done at the end
of the production proces. When the document is revised you
have to evaluate the pagebreaking location. \CONTEXT\
produces terminal feedback to remind you when these kind of
commands are in effect.

Before a list can be generated the text should be processed
twice. When a combined list is not placed after the text is
processed twice you probably have asked for a local list.

There are two commands to write something directly to a
list. The first command is used to add an element and the
second to add a command:

\showsetup{writetolist}

\showsetup{writebetweenlist}

We supply a simple example:

\startexample
\starttyping
\writebetweenlist [section] {\blank}
\writetolist      [section] {---} {from here temporary}
\writebetweenlist [section] {\blank}
\stoptyping
\stopexample

The next command is used in situations where information goes
into the title but should not go into the list.

\showsetup{nolist}

Consider for example the following example:

\startexample
\starttyping
\definehead[function][ownnumber=yes]
\function{A-45}{manager logistics \nolist{(outdated)}}
\placelist[function][criterium=all]
\stoptyping
\stopexample

When we call for a list of functions, we will get (\unknown)
instead of (outdated). This can be handy for long titles.
Keep in mind that each head has a corresponding list.

In an interactive document it is common practice to use more
lists than in a paper document. The reason is that the
tables of content is also a navigational tool. The user of
the interactive document arrives faster at the desired
location when many subtables are used, because clicking is
the only way to get to that location.

In designing an interactive document you can consider the
following setup (probably in a different arrangement):

\starttyping
\setuplayout[rightedge=3cm]
\setupinteraction[state=start,menu=on]
\setupinteractionmenu[right][state=start]
\startinteractionmenu[right]
  \placecontent
    [level=current, criterium=previous,
     alternative=f, align=right,
     interaction=all,
     before=, after=]
\stopinteractionmenu
\stoptyping

These definitions make sure that a table of contents is
typeset at every page (screen) in the right edge. The table
displays the sections one level deeper than the actual
level. So, for each section we get a list of subsections.

When you produce an interactive document with a table of
contents at every level you can make a (standard) button
that refers to \type {[previouscontent]}. This reference is
generated automatically.

The list elements that are written to a list are not
expanded (that is, commands remain commands). When expansion
is needed you can set the parameter \type{expansion}.
Expansion is needed in situations where you write variable
data to the list. This is seldom the case.

In a more extensive document there may occur situations
where at some levels there are no deeper levels available.
Then the table of contents at that level is not available
either. In that case you need more information on the list
so you can act upon it. You can have access to:

\starttabulate[|l|l|]
\NC \type{\listlength} \NC the number of items                  \NC\NR
\NC \type{\listwidth}  \NC the maximum width of a list element  \NC\NR
\NC \type{\listheight} \NC the maximum height of a list element \NC\NR
\stoptabulate

These values are determined by:

\showsetup{determinelistcharacteristics}

We end this section with an overview of the available
alternatives. The first three alternatives are primarily
meant for paper documents. The \type {criterium} parameter
determines what lists are typeset, so in the next example,
the sections belonging to the current chapter are typeset.

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=a]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\setuplabeltext[en][section={ugh }]
\placelist
  [section]
  [criterium=chapter,alternative=a,
   label=yes,width=2cm]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=b]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=b,
   pagenumber=no,width=fit,distance=1em]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=c]
\stopbuffer

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=c,
   chapternumber=yes,margin=1.5cm]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist % note the spaces on each side of the colon
  [section]
  [criterium=chapter,alternative=c,
   chapternumber=yes,separator={ : },width=fit]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=d]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=d,
   distance=2cm]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=d,
   left={(},right={)}]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=e]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=e,
   width=\textwidth,background=screen]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=e,
   width=4cm]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=f]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=g]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

Within a list entry, each element can be made interactive.
In most cases, in screen documents, the option all is the
most convenient one. Alternative~e is rather well suited for
screen documents and accepts nearly all parameters of
\type {\framed}. In the next example we use a symbol
instead of a sectionnumber. The parameter \type {depth}
applies to this symbol.

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=a,
   pagenumber=no,distance=1em,
   symbol=3,height=1.75ex,depth=.25ex,numbercolor=gray]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

When using color, don't forget to enable it. In the last
example, All alternatives provide the means to hook in
commands for the section number, text and pagenumber. Real
complete freedom is provided by alternative \type {none}.

\startbuffer
\placelist
  [section]
  [criterium=chapter,alternative=none,
   numbercommand=\framed,
   textcommand=\framed,pagecommand=\framed]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

\startbuffer
\def\ListCommand#1#2#3%
  {at page {\bf #3} we discuss {\bf #2}}

\placelist
  [section]
  [criterium=chapter,alternative=none,
   command=\ListCommand]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

This alternative still provides much of the built||in
functionality. Alternative \type {command} leaves nearly
everything to the macro writer.

\startbuffer
\def\ListCommand#1#2#3%
  {At p~#3 we discuss {\em #2}; }

\placelist
  [section]
  [criterium=chapter,alternative=command,
   command=\ListCommand]
\stopbuffer

\typebuffer \blank {\getbuffer} \blank

As an alternative for \type {none}, we can use \type
{horizontal} and \type {vertical}. Both commands have their
spacing tuned for typesetting lists in for instance menus.

\section[synonyms]{Synonyms}
\index{abbreviations}
\index{synonyms}
\macro{\tex{definesynonyms}}
\macro{\tex{setupsynonyms}}
\macro[completelistofsy]{\tex{completelistof<<synonyms>>}}
\macro[placelistofsy]{\tex{placelistof<<synonyms>>}}
\macro[synonym]{\tex{<<synonym>>}}
\macro[loadsynonyms]{\tex{load<<synonyms>>}}
\macro{\tex{abbreviation}}

In many texts we use abbreviations. An abbreviation has a
meaning. The abbreviation and its meaning have to be used
and typeset consistently throughout the text. We do not like
to see ABC and in the next line an \kap{abc}. For this
reason it is possible to define a list with the used
abbreviations and their meanings. This list can be recalled
and placed at the beginning or end of a book for the
convenience of the reader.

The use of abbreviations is an example of the synonym
mechanism. A new category of synonyms is defined with the
command:

\showsetup{definesynonyms}

The way the list is displayed can be influenced by:

\showsetup{setupsynonyms}

Abbreviations are defined with the command:

\startexample
\starttyping
\definesynonyms[abbreviation][abbreviations][\infull]
\stoptyping
\stopexample

We will explain the optional fourth argument later. After
this definition a new command \type{\abbreviation} is
available. An example of the use of abbreviations is:

\startexample
\starttyping
\abbreviation {UN}  {United Nations}
\abbreviation {UK}  {United Kingdom}
\abbreviation {USA} {United States of America}
\stoptyping
\stopexample

The meaning can be used in the text by:

\startexample
\starttyping
\infull{abbreviation}
\stoptyping
\stopexample

It is also possible to add commands in the abbreviation. In
that case the command must be typed literally between the
\setchars:

\startexample
\starttyping
\abbreviation [TEX] {\TeX} {The \TeX\ Typesetting System}
\stoptyping
\stopexample

Recalling such an abbreviation is done with \type {\TEX} and
the meaning can be fetched with \type {\infull {TEX}}. In a
running text we type \type{\TEX\} and in front of punctuation
\type{\TEX}.

A synonym is only added to a list when it is used. When you
want to display all defined synonyms (used and not used) you
have to set the parameter \type{criterium} at \type{all}.
By setting \type{state} at \type{stop} you will prevent
list elements to be the added to the list even when they are
used. This can be a temporary measure:

\startexample
\starttyping
\setupsynonyms[abbreviation][state=stop]
\abbreviation {NIL} {Not In List}
\setupsynonyms[abbreviation][state=start]
\stoptyping
\stopexample

Here we left out the optional first argument, in which case
the abbreviation itself becomes the command (\type {\NIL}).
So, in this case the next two definitions are equivalent:

\starttyping
\abbreviation [NIL] {NIL} {Not In List}
\abbreviation {NIL} {Not In List}
\stoptyping

The formal definition of a synonym looks like this:

\showsetup{<<synonym>>}

A list of synonyms is generated by:

\showsetup{placelistof<<synonyms>>}

The next command generates a list with a title
(\type{\chapter}):

\showsetup{completelistof<<synonyms>>}

Here we see why we typed the plural form during the
definition of the synonym. The plural is also used as the
title of the list and the first character is capitalized. The
title can be altered with \type{\setuphead} (see
\in{section}[titles]).

Synonyms are only available after they are used. There are
instances when the underlying mechanism cannot preload
the definitions. When you run into such troubles, you can
try to load the meaning of the synonyms with the command:

\showsetup{load<<synonyms>>}

For instance, the meaning of abbreviations can be loaded
with \type {\loadabbreviations}. In order to succeed, the
text has to be processed at least once. Don't use this
command if things run smoothly.

Next to the predefined abbreviations we also defined the
\SI||units as synonyms. These must be loaded as a separate
module. We will discuss this in \in {section} [units].

The attentive reader has seen that the command \type
{\definesynonyms} has four arguments. The fourth argument is
reserved for a command with which you can recall the
synonym. In this way the synonyms are protected from the
rest of the \CONTEXT\ commands and there will be no
conflicts using them.

\startexample
\starttyping
\definesynonyms[Function][Functions][\FunctionName][\FunctionNumber]
\stoptyping
\stopexample

We could define some functions like:

\startexample
\starttyping
\Function [0001] {0001a} {Lithographer}
\Function [0002] {0002x} {Typesetter}
\stoptyping
\stopexample

Than we can recall number and name by \type {\FunctionName}
(Lithographer and Typesetter) and \type {\FunctionNumber}
(0001a and 0002x), so:

\starttyping
The \FunctionName{0001} has functionnumber \FunctionNumber{0001}.
\stoptyping

\section[sorting]{Sorting}
\index{sorting}
\index{lists+sorting}
\index{logos}
\macro{\tex{definesorting}}
\macro{\tex{setupsorting}}
\macro[completelistofso]{\tex{completelistof<<sorts>>}}
\macro[placelistofso]{\tex{placelistof<<sorts>>}}
\macro[sort]{\tex{<<sorteer>>}}
\macro[loadsorts]{\tex{load<<sorts>>}}
\macro{\tex{logo}}

Another instance of lists with synonyms
is the sorted list. A sorted list is defined with:

\showsetup{definesorting}

The list is set up with:

\showsetup{setupsorting}

After the definition the next command is available. The
\type{<<sort>>} indicates the name for the list you
defined.

\showsetup{<<sort>>}

In accordance to lists there are two other commands
available:

\showsetup{placelistof<<sorts>>}

The title can be set up with \type{\setuphead}:

\showsetup{completelistof<<sorts>>}

An example of sorting is:

\startbuffer
\definesorting[city][cities]
\setupsorting[city][criterium=all]

\city {London}
\city {Berlin}
\city {New York}
\city {Paris}
\city {Hasselt}

\placelistofcities
\stopbuffer

\startexample
\typebuffer
\stopexample

The definition is typed in the setup area of your file or
in an environment file. The cities can be typed anywhere in
your text and the list can be recalled anywhere.

\startreality
\getbuffer
\stopreality

Another instance of the sorting command is that where we
must type the literal text of the synonym in order to be
able to sort the list. For example if you want a sorted list
of commands you should use that instance. The predefined
command \type {\logo} is an example of such a list.

\startexample
\starttyping
\logo [TEX]   {\TeX}
\logo [TABLE] {\TaBlE}
\stoptyping
\stopexample

When you use the alternative with the \setchars\ \CONTEXT\
automatically defines a command that is available throughout
your document. In the example above we have \type{\TABLE}
and \type{\TEX} for recalling the logo. For punctuation
we use \type{\TABLE}.

We advise you to use capital letters to prevent interference
with existing \CONTEXT\ and|/|or \TEX\ commands.

Like in synonyms, a sorted list is only available after an
entry is used. When sorting leads to any problems you can
load the list yourself:

\showsetup{load<<sorts>>}

When we add a command in the third argument during the
definition of the sorted list we may recall sorted list with
this command. In this way the sorted lists can not interfere
with existing commands (see \in{section}[synonyms]).

\section[marking]{Marking}
\index{marking}
\index{headers+marking}
\index{footers+marking}
\macro{\tex{marking}}
\macro{\tex{definemarking}}
\macro{\tex{couplemarking}}
\macro{\tex{decouplemarking}}
\macro{\tex{resetmarking}}
\macro{\tex{getmarking}}
\macro{\tex{setupmarking}}

There is a feature to add \quote {invisible} marks to your
text that can be used at a later stage. Marks can be used to
place chapter or section titles in page headers or footers.

A mark is defined with:

\showsetup{definemarking}

The second optional argument will be discussed at the end of
this section. After the definition texts can be marked by:

\showsetup{marking}

and recalled by:

\showsetup{getmarking}

In analogy with the \TEX||command \type{\mark}, we keep
record of three other marks per mark (see
\in{table}[tab:marks]).

\placetable
  [hier][tab:marks]
  {Recorded marks, completed with some combinations.}
\starttable[|l|l|]
\HL
\VL \bf marks       \VL \bf location                  \VL\SR
\HL
\VL \type{previous} \VL the last of the previous page \VL\FR
\VL \type{first}    \VL the first of the actual page  \VL\MR
\VL \type{last}     \VL the last of the actual page   \VL\LR
\HL
\VL \type{both}     \VL first --- last                \VL\FR
\VL \type{all}      \VL previous --- first --- last   \VL\LR
\HL
\stoptable

When you use a combination of marks (\type {both} and \type
{all}) marks are separated by an ---. This separator can be
set up with:

\showsetup{setupmarking}

\pagereference[expansion]The use of marks can be blocked
with the parameter \type {state}. The parameter \type
{expansion} relates to the expansion mechanism. By default
expansion is inactive. This means that a command is stored
as a command. This suits most situations and is memory
effective. When you use altering commands in the mark you
should activate the expansion mechanism.

Marks are initialised by:

\showsetup{resetmarking}

At the beginning of a chapter the marks of sections,
subsections, etc. are reset. If we do not reset those marks
would be active upto the next section or subsection.

Assume that a word list is defined as follows (we enforce
some pagebreaks on purpose):

\startexample
\starttyping
\definemarking[words]

\marking[words]{first}first word ...
\marking[words]{second}second word ...
\page
\marking[words]{third}third word ...
\marking[words]{fourth}fourth word ...
\page
\marking[words]{fifth}fifth word ...
\page
\stoptyping
\stopexample

The results are shown in \in{table}[tab:example marks].

\placetable
  []
  [tab:example marks]
  {The reordering of marks.}
\starttable[|c|c|c|c|]
\HL
\VL \bf page \VL \bf previous \VL \bf first \VL \bf last \VL\SR
\HL
\VL  1       \VL ---          \VL first     \VL second   \VL\FR
\VL  2       \VL second       \VL third     \VL fourth   \VL\MR
\VL  3       \VL fourth       \VL fifth     \VL fifth    \VL\LR
\HL
\stoptable

While generating the title of chapters and sections
\type{first} is used. The content of the marks can be checked
easily by placing the mark in a footer:

\startexample
\starttyping
\setupfootertexts
  [{\getmarking[words][first]}]
  []
\stoptyping
\stopexample

or all at once:

\startexample
\starttyping
\setupfootertexts
  [{\getmarking[words][previous]} --
   {\getmarking[words][first]} --
   {\getmarking[words][last]}]
  []
\stoptyping
\stopexample

A more convenient way of achieving this goal, is the
following command. The next method also takes care of empty
markings.

\startexample
\starttyping
\setupfootertexts[{\getmarking[words][all]}][]
\stoptyping
\stopexample

Commands like \type {\chapter} generate marks automatically.
When the title is too long you can use the command \type
{\nomarking} (see \in{section}[subdivision]) or pose limits
to the length. In \CONTEXT\ the standard method to place
marks in footers is:

\startexample
\starttyping
\setupfootertexts[chapter][sectionnumber]
\stoptyping
\stopexample

In case you defined your own title with \type {\definehead},
the new title inherits the mark from the existing title. For
example when we define \type{\category} as follows:

\startexample
\starttyping
\definehead[category][subsection]
\stoptyping
\stopexample

After this command it does not matter whether we recall the
mark by \type {category} or \type {subsection}.
In this way we can also set up the footer:

\startexample
\starttyping
\setupfootertexts[chapter][category]
\stoptyping
\stopexample

There are situations where you really want a separate mark
mechanism \type{category}. We could define such a mark with:

\startexample
\starttyping
\definemarking[category]
\stoptyping
\stopexample

However, we do want to reset marks so we have to have some
information on the level at which the mark is active.
The complete series of commands would look something like
this:

\startexample
\starttyping
\definehead[category][subsection]
\definemarking[category]
\couplemarking[category][subsection]
\stoptyping
\stopexample

Note that we do this only when we both use category and
subsection! After these commands it is possible to say:

\startexample
\starttyping
\setupfootertexts[subsection][category]
\stoptyping
\stopexample

The command \type {\couplemarking} is formally defined as:

\showsetup{couplemarking}

Its counterpart is:

\showsetup{decouplemarking}

It is obvious that you can couple marks any way you want,
but it does require some insight in the ways \CONTEXT\
works.

\section[cross references]{Cross references}
\index{cross references}
\index{references}
\index{linenumbers}
\macro{\tex{in}}
\macro{\tex{at}}
\macro{\tex{about}}
\macro{\tex{somwhere}}
\macro{\tex{atpage}}
\macro{\tex{reference}}
\macro{\tex{ref}}
\macro{\tex{pagereference}}
\macro{\tex{textreference}}
\macro{\tex{setupreferencing}}
\macro{\tex{startline}}
\macro{\tex{someline}}
\macro{\tex{inline}}

We can add reference points to our text for cross
referencing. For example we can add reference points at
chapter titles, section titles, figures and tables. These
reference points are typed between \setchars. It is even
allowed to type a list of reference points separated by a
comma. We refer to these reference points with the commands:

\showsetup{in}

\showsetup{at}

\showsetup{about}

A cross reference to a page, text (number) or both can
be made with:

\showsetup{pagereference}

\showsetup{textreference}

\showsetup{reference}

The command \type {\in} provides the number of a chapter,
section, figure, table, etc. The command \type {\at} produces
a pagenumber and \type {\about} produces a complete title.
In the first two calls, the second argument is optional, and
when given, is put after the number or title.

In the example below we refer to sections and pages
that possess reference points:

\startbuffer
In section~\in[cross references], titled \about[cross references], we
describe how a cross reference can be defined. This section starts
at page~\at[cross references] and is part of chapter~\in[references].
\stopbuffer

\startexample
\typebuffer
\stopexample

This becomes:

\startreality
\getbuffer
\stopreality

Here is another variation of the same idea:

\startexample
\starttyping
In \in{section}[cross references], titled \about[cross references], we
describe how a cross reference can be defined. This section starts
at \at{page}[cross references] and is part of \in{chapter}[references].
\stoptyping
\stopexample

We prefer this way of typing the cross references,
especially in interactive documents. The clickable area is
in this case not limited to the number, but also includes
the preceding word, which is more convenient, especially
when the numbering is disabled. In the first example you
would have obtained a symbol like\high {\symbol
[previouspage]} that is clickable. This symbol indicates the
direction of the cross reference: forward\high {\symbol
[nextpage]} or backward\high {\symbol [previouspage]}.

\startbuffer
The direction of a hyperlink can also be summoned by the command
\type {\somewhere}. In this way we find chapters or other text elements
\somewhere {before} {after} [text elements] and discuss somewhere
\somewhere {previous} {later} [descriptions] the descriptions.
\stopbuffer

\getbuffer

\showsetup{somewhere}

This command gets two texts. The paragraph will be typed like
this:

\typebuffer

The next command does not need any text but will generate it
itself. The generated texts can be defined with \type
{\setuplabeltext} (see \at {page} [labels]).

\showsetup{atpage}

At the locations where we make reference points we can also
type a complete list of reference points in a comma
delimited list:

\startexample
\starttyping
\chapter[first,second,third]{First, second and third}
\stoptyping
\stopexample

Now you can cross reference to this chapter with \type
{\in[first]}, \type {\in[second]} or \type {\in[third]}. In
a large document it is difficult to avoid the duplication of
labels. Therefore it is advisable to bring some order to
your reference point definitions. For example, in this
manual we use: \type {[fig:first]}, \type {[int:first]},
\type {[tab:first]} etc. for figures, intermezzos and tables
respectively.

\CONTEXT\ can do this for you automatically. Using the
command \type {\setupreferencing}, you can set for instance
\type {prefix=alfa}, in which case all references will be
preceded by the word \type{alfa}. A more memory efficient
approach would be to let \CONTEXT\ generate a prefix itself:
\type {prefix=+}. Prefixing can be stopped with \type
{prefix=-}.

In many cases, changing the prefix in many places in the
document is not an example of clearness and beauty. For that
reason, \CONTEXT\ is able to set the prefix automatically
for each section. When for instance you want a new prefix at
the start of each new chapter, you can use the command \type
{\setuphead} to set the parameter \type {prefix} to \type
{+}. The chapter reference itself is not prefixed, so you
can refer to them in a natural way. The references within
that chapter are automatically prefixed, and thereby local.
When a chapter reference if given, this one is used as
prefix, otherwise a number is used. Say that we have
defined:

\starttyping
\setuphead[chapter][prefix=+]

\chapter[texworld]{The world of \TeX}
\stoptyping

In this chapter, we can safely use references, without the
danger of clashing with references in other chapters. If we
have a figure:

\starttyping
\placefigure[here][fig:worldmap]{A map of the \TeX\ world}{...}
\stoptyping

In the chapter itself we can refer to this figure with:

\starttyping
\in {figure} [fig:worldmap]
\stoptyping

but from another chapter, we should use:

\starttyping
\in {figure} [texworld:fig:worldmap]
\stoptyping

In general, when \CONTEXT\ tries to resolve a reference in
\type {\in}, \type {\at} etc., it first looks to see whether
it is a local reference (with prefix). If such a reference
is not available, \CONTEXT\ will look for a global reference
(without prefix). If you have some trouble understanding the
mechanism during document production you can visualize the
reference with the command \type {\version[temporary]}.

There are situations where you want to make a global
reference in the middle of document. For example when you
want to refer to a table of contents or a register. In that
case you can type \type {-:} in the reference point label
that {\em no} prefix is needed: you type \type
{[-:content]}. Especially in interactive documents the
prefix||mechanism is of use, since it enables you to have
documents with thousands of references, with little danger
for clashes. In the previous example, we would have got a
global reference by saying:

\starttyping
\placefigure[here][-:fig:worldmap]{A map of the \TeX\ world}{...}
\stoptyping

The generation of references can be started, stopped and
influenced with the command:

\showsetup{setupreferencing}

In this command the parameter \type{\<<section>>number}
relates to the way the page numbers must be displayed. In
interactive documents, we can refer to other documents. In
that case, when the parameter \type {convertfile} is set to
\type {yes}, external filenames are automatically converted
to uppercase, which is sometimes needed for \CDROM\
distributions. We will go into details later.

References from another document can be loaded with the
command:

\showsetup{usereferences}

With \type {left} and \type {right} you can define what is
written around a reference generated by \type {\about}.
Default these are quotes. The parameter \type {interaction}
indicates whether you want references to be displayed like
{\em section~1.2}, {\em section}, {\em 1.2} or as a symbol,
like~\symbol [somewhere].

What exactly is a cross reference? Earlier we saw that we
can define a reference point by typing a logical label at
the titles of chapters, sections, figures, etc. Then we can
summon the numbers of chapters, sections, figures, etc. or
even complete titles at another location in the document.
For some internal purposes the real pagenumber is also
available. In the background real pagenumbers play an
important role in the reference mechanism.

% Er is ook nog een extra verwijzing mogelijk, maar die
% wordt vooralsnog niet gebruikt in de standaard||commando's.

In the examples below we discuss in detail how the reference
point definitions and cross referencing works in \CONTEXT.

\startbuffer
\reference[my reference]{{Look}{at}{this}}
\stopbuffer

\typebuffer

\getbuffer

The separate elements can be recalled by \type{\ref}:

\starttabulate[|lT|l|l|l|]
\NC p \NC the typeset pagenumber   \NC \type{\ref[p][my reference]}
                                   \NC \ref[p][my reference] \NC \NR
\NC t \NC the text reference       \NC \type{\ref[t][my reference]}
                                   \NC \ref[t][my reference] \NC \NR
\NC r \NC the real pagenumber      \NC \type{\ref[r][my reference]}
                                   \NC \ref[r][my reference] \NC \NR
\NC s \NC the subtext reference    \NC \type{\ref[s][my reference]}
                                   \NC \ref[s][my reference] \NC \NR
\NC e \NC the extra text reference \NC \type{\ref[e][my reference]}
                                   \NC \ref[e][my reference] \NC \NR
\stoptabulate

In a paper document the reference is static: a number or a
text. In an interactive document a reference may carry
functionality like hyperlinks. In addition to the commands
\type {\in} and \type {\at} that we discussed earlier we
have the command \type {\goto}, which allows us to jump.
This command does not generate a number or a text because
this has no meaning in a paper version.

\CONTEXT\ supports interactivity which is integrated into
the reference mechanism. This integration saved us the
trouble of programming a complete new set of interactivity
commands and the user learns how to cope with these
non||paper features in a natural way. In fact there is no
fundamental difference in referring to chapter~3, the
activation of a \JAVASCRIPT, referring to another document
or the submitting of a completed form.

A direct advantage of this integration is the fact that we
are not bound to one reference, but we can define complete
lists of references.
This next reference is legal:

\starttyping
... see \in{section}[flywheel,StartVideo{flywheel 1}] ...
\stoptyping

As expected this command generates a section number. And in
an interactive document you can click on {\em section~nr}
and jump to the correct location. At the moment that
location is reached a video titled {\em flywheel~1} is
started. In order to reach this kind of comfortable
referencing we cannot escape a fully integrated reference
mechanism.

Assume that you want to make a cross reference for a general
purpose. The name of the reference point is not known yet.
In the next example we want to start a video from a general
purpose menu:

\starttyping
\startinteractionmenu[right]
  \but [previouspage]  previous \\
  \but [nextpage]      next     \\
  \but [ShowAVideo]    video    \\
  \but [CloseDocument] stop     \\
\stopinteractionmenu
\stoptyping

Now we can activate a video at any given moment by
defining \type {ShowAVideo}:

\starttyping
\definerreference[ShowAVideo][StartVideo{a real nice video reel}]
\stoptyping

This reference can be redefined or erased at any moment:

\starttyping
\definereference[ShowAVideo][]
\stoptyping

\showsetup{definereference}

\startbuffer
\startlinenumbering
A special case of referencing is that of referring to linenumbers.
\startline [line:a] Different line numbering mechanism can be used
interchangeably. \startline [line:b] This leads to confusing input.
\stopline [line:a] \startline [line:c] Doesn't it? \stopline [line:c]
\stopline [line:b] A cross reference to a line can result in one line
number or a range of lines. \someline[line:d] {A cross reference is
specified by \type {\inline} where the word {\em line(s)} is
automatically added.} Here we have three cross references: \inline
[line:a], \inline [line:b], \inline[line:c] and \inline {as the last
reference} [line:d].
\stoplinenumbering
\stopbuffer

\typebuffer

With \type {\startlines..\stoplines} you will obtain the
range of lines in a cross reference and in case of \type
{\someline} you will get the first line number. In this
example we see that we can either let \CONTEXT\ generate a
label automatically, or privide our own text between braces.

\getbuffer

\showsetup{startlines}

\showsetup{someline}

\showsetup{inline}

\section{Predefined references}
\index{labels}
\macro{\tex{definereferenceformat}}

One can imagine that it can be cumbersome and even dangerous
for consistency when one has many references which the same
label, like {\bf figure} in \type {\in{figure}[somefig]}.
For example, you may want to change each {\bf figure} into
\type {Figure} afterwards. The next command can both save
time and force consistency:

\showsetup{definereferenceformat}

\textreference[demo:b]{BB}\textreference[demo:c]{CC}Given
the following definitions:

\startbuffer
\definereferenceformat [indemo]  [left=(,right=),text=demo]
\definereferenceformat [indemos] [left=(,right=),text=demos]
\definereferenceformat [anddemo] [left=(,right=),text=and]
\stopbuffer

\getbuffer

\typebuffer

we will have three new commands:

\startbuffer
\indemo [demo:b]
\indemo {some text} [demo:b]
\indemos {some text} [demo:b] \indemo {and more text} [demo:c]
\indemos [demo:b] \anddemo [demo:c]
\stopbuffer

\typebuffer

These will show up as:

\startlines
\getbuffer
\stoplines

Instead of using the \type {text} parameter, one can use
\type {label} and recall a predefined label. The parameter
\type {command} can be used to specify the command to use
(\type {\in} by default).

% \section[lijsten]{Referentie--lijsten}
% \index{verwijzingen+overzichten}
% \index{overzichten+verwijzingen}
% \macro{\tex{reflijst}}
% \macro{\tex{stelreferentielijstin}}
%
% Het is mogelijk een met een index vergelijkbare lijst te
% genereren, bijvoorbeeld een lijst met subjecten en
% paginanummers. Het commando luidt:
%
% \showsetup{reflijst}
%
% Referentielijsten worden vooralsnog niet gesorteerd. Mocht
% daar behoefte aan bestaan dan zal dan in de toekomst alsnog
% gebeuren.
%
% De referentie die wordt opgegeven verwijst naar een elders
% aangemaakte referentie, bijvoorbeeld een chapter of een
% section. Een voorbeeld van een lijst is:
%
% \startbuffer
% \startpacked
% \reflijst [startstop]  {Afsluiten}
% \reflijst [lijsten]    {Referentie||lijsten}
% \reflijst [definities] {Definities}
% \stoppacked
% \stopbuffer
%
% \startexample
% \typebuffer
% \stopexample
%
% Hierbij zorgt \type{\...packed} ervoor dat tussen de
% verschillende elementen van de lijst geen witbroadte wordt
% opgenomen. Dit wordt dus:
%
% \startreality
% \getbuffer
% \stopreality
%
% Het lettertype waarin de tekst wordt gezet, kan worden
% ingesteld met:
%
% \showsetup{stelreferentielijstin}

\section[registers]{Registers}
\index{index}
\index{registers}
\index{registers+interaction}
\index{interaction+registers}
\macro[register]{\tex{<<register>>}}
\macro{\tex{startregister}}
\macro{\tex{defineregister}}
\macro{\tex{setupregister}}
\macro{\tex{coupleregister}}
\macro[writetorgister]{\tex{writeto<<register>>}}
\macro[placeregister]{\tex{place<<register>>}}
\macro[completeregister]{\tex{complete<<register>>}}
\macro[seeregister]{\tex{see<<register>>}}
\macro[nextregister]{\tex{next<<register>>}}

A book without a register is not likely to be taken
seriously. Therefore we can define and generate one or more
registers in \CONTEXT. The index entries are written to a
separate file. The \PERL\ script \TEXUTIL\ converts this
file into a format \TEX\ can typeset.

A register is defined with the command:

\showsetup{defineregister}

There are a number of commands to create register entries and
to place registers. One register is available by default:

\startexample
\starttyping
\defineregister[index][indices]
\stoptyping
\stopexample

An entry is created by:

\showsetup{<<register>>}

An entry has a maximum of three levels. The subentries are
separated by a \type{+} or \type {&}. We illustrate this
with an example.

\startexample
\starttyping
\index{car}
\index{car+wheel}
\index{car+engine}
\stoptyping
\stopexample

When index entries require special typesetting, for example
\type{\sl} and \type{\kap} we have to take some measures,
because these kind of commands are ignored during list
generation and sorting. In those cases we can use the
extended version. Between \setchars\ we type the literal
\ASCII||string which will determine the alphabetical order.

For example we have defined logos or abbreviations like \kap
{UN}, \kap {UK} and \kap {USA} (see \in {section}
[synonyms]), then an index entry must look like this:

\startexample
\starttyping
\index[UN]{\UN}
\index[UK]{\UK}
\index[USA]{\USA}
\stoptyping
\stopexample

If we do not do it this way \kap {UN}, \kap {UK} and \kap
{USA} will be placed under the \texescape.

A cross reference within a register is created with:

\showsetup{see<<register>>}

This command has an extended version also with which we
can input a \quote {pure} literal \ASCII\ string.

A register is generated and placed in your document with:

\showsetup{place<<register>>}

The next command results in register with title:

\showsetup{complete<<register>>}

The register can be set up with the command \type
{\setupregister}. When you use the command \type
{\version[temporary]} during processing, the entries and
their locations will appear in the margin (see
\in{section}[version]).

\showsetup{setupregister}

By default a complete register is generated. However it is
possible te generate partial registers. In that case the
parameter \type{criterium} must be set. With \type
{indicator} we indicate that we want a letter in the
alphabetical ordering of the entries. When \type
{referencing=on} is a pagereference is generated for every
letter indicator, for example \type {index:a} or \type
{index:w}. We can use these automatically generated
references to refer to the page where for instance the
a||entries start.

The commands we have mentioned thus far allow us to use a
spacious layout in our source file. This means we can
type the entries like this:

\startexample
\starttyping
\chapter{Here we are}

\section{Where we are}
\index{here}
\index{where}

Wherever you are ...
\stoptyping
\stopexample

Between \type{\chapter} and \type{\section} we should not
type any text because the vertical spacing might be
disturbed by the index entries. The empty line after the
entry has no consequences. In case there are problems we
always have the option to write index entries to the list by
the more direct command:

\showsetup{writeto<<register>>}

There the \type{expansion} mechanism can be activated.
Default expansion is inactive (see \at{page}[expansion]).

In this reference manual there is a register with commands.
This register is defined and initialised with:

\startexample
\starttyping
\defineregister [macro] [macros]
\setupregister  [macro] [indicator=no]
\stoptyping
\stopexample

And we can find entries like:

\startexample
\starttyping
\macro{\tex{chapter}}
\macro{\tex{section}}
\stoptyping
\stopexample

In case we want a register per chapter we can summon the
accompanying register with the command below (the command
\type{\tex} will place a \tex{} in front of a word, but is
ignored during sorting): \footnote {Of course, \type
{\placemacro} and \type {\completemacros} are also
available.}

\startbuffer
\placeregister[macro]
  [criterium=chapter,n=2,before=,after=]
\stopbuffer

\startexample
\typebuffer
\stopexample

and we will obtain:

\start % dit moet, anders krijgen we dubbele letter-referenties
\defineregister[macro]
\setupregister[macro][referencing=off]
\getbuffer
\stop  % register macro wordt immers ook aan het eind opgeroepen

A warning is due. The quality of the content of a register
is completely in your hands. A bad selection of index
entries leads to an inadequate register that is of no use to
the reader.

Every entry shows one or more pagenumbers. With \type
{symbol} we can define some alternatives. With \type
{distance} the horizontal spacing between word and number or
symbol is set.

\placetable{Alternatives for pagenumbers in registers.}
\starttable[|c|c|]
\HL
\VL \bf symbol \VL \bf display                        \VL\SR
\HL
\VL \type{a} \VL a b c d                              \VL\FR
\VL \type{n} \VL 1 2 3 4                              \VL\MR
\VL \type{1} \VL $\bullet\ \bullet\ \bullet\ \bullet$ \VL\MR
\VL \type{2} \VL \setbox0=\hbox{\vrule width 1em height 1ex}%
                 \copy0\ \copy0\ \copy0\ \copy0       \VL\LR
\HL
\stoptable

% nog eens een apartt handleiding van maken
%
% Een voorbeeld van een uitermate slecht register is de index
% bij de reeks \quote {Opleiders in Organisaties}. Na een
% pretentieuze inleiding volgen ongeveer 50~bladzijden met
% verwijzingen. Het betreft een index bij 22~specials met
% meerdere artikelen over eenzelfde subject. Achter ieder
% (sub)woord in de cumulatieve index staat (enkele
% uitzonderingen daargelaten) slechts \'e\'en bladzijdenummer,
% wat de suggestie wekt dat er nauwelijks overlap in de
% artikelen zit. Zo is er slechts ‚‚n nummer vermeld achter
% \quote {opleidingsafdeling}, terwijl dit begrip in veel
% artikelen terugkomt. Verder staat ieder woord wat maar te
% bedenken valt in het register, en krijgen verschillende
% verschijningsvormen van een woord een eigen ingang.
%
% Bestudering van deze index leidt al snel tot een aantal
% aanbevelingen met betrekking tot registers. Vaak is controle
% op de volgende punten al voldoende. Het genoemde register is
% waarschijnlijk nooit gecontroleerd.
%
% \startitemize[n]
%
% \item  Gebruik geen ingangen waar geen normaal denkend mens
%       op komt. broad de helft van de ingangen in de genoemde
%       index lijkt zinloos: {\em controle}, {\em consistent},
%       {\em getal}. Niemand zal hierop gaan zoeken.
%
% \item  Gebruik geen subingangen als het hoofdwoord niet ook
%       voor de hand ligt. In iedere kolom van de beruchte
%       index staat wel zo'n onnodig dubbele ingang.
%
% \item  Gebruik subingangen consistent, en dus niet {\em
%       assessment + model} naast {\em assessment||component},
%       om over het engelse woord maar niet te spreken.
%
% \item  Controleer op enkelvoud en meervoud en gebruik dus niet
%       {\em assessment} naast {\em assessments}.
%
% \item  Gebruik geen subingangen die naar dezelfde bladzijde
%       verwijzen, terwijl er geen andere subingangen zijn. De
%       genoemde index toont er vele, zoals: {\em
%       consistent + extern}, {\em consistent + intern} en verder
%       niets onder {\em consistent}.
%
% \item  Ga na of sommige ingangen niet beter achterwege kunnen
%       blijven, bijvoorbeeld omdat de hele tekst er over
%       gaat. Het heeft geen zin om {\em docenten + instructie}
%       en {\em docenten + selectie} op te nemen (die bovendien
%       naar dezelfde bladzijde verwijzen), terwijl in veel
%       meer artikelen docenten aan de orde komen. Suggereer
%       niet ten onrechte volledigheid.
%
% \item  Ga na of verschillende ingangen niet eigenlijk
%       hetzelfde verwoorden. In het genoemde register is het
%       subject mentor bijzonder slecht geordend. We vinden
%       er {\em mentor en coach} naast (enkele ingangen
%       verderop) {\em mentor of coach}. Los van het vermeende
%       onderscheid is het beter om van {\em mentor} te
%       spreken en onder {\em coach} te verwijzen naar dit
%       woord.
%
% \stopitemize
%
% Misschien wel de belangrijkste tip die we hier kunnen geven
% is de volgende:
%
% \startitemize[verder]
% \item  Laat slechts ‚‚n persoon de index samenstellen en
%       controleren. Iedere auteur zijn eigen ingangen laten
%       aanleveren leidt gegarandeerd tot de genoemde problemen.
% \stopitemize

Most of the time the layout of a register is rather simple.
Some manuals may need some form of differentiating between
entries. The definition of several registers may be a
solution. However the layout can contribute to a better use
of the register:

\starttyping
\index           {entry}
\index[key]      {entry}
\index[form::]   {entry}
\index[form::key]{entry}
\index           {form::entry}
\index[key]      {form::entry}
\index[form::]   {form::entry}
\index[form::key]{form::entry}
\stoptyping

The first two alternatives are known, but the rest is new and
offers some control over the way the entry itself is
typeset. The specification between
\setchars\ relates to the pagenumber, the specification
in front of the entry relates to the entry itself.

\starttyping
\setupregister[index][form][pagestyle=bold,textstyle=slanted]
\stoptyping

Without any problems we can use different appearances
for pagenumber and entry.

\starttyping
\setupregister[index][nb][pagestyle=bold]
\setupregister[index][hm][pagestyle=slanted]
\stoptyping

With for example:

\starttyping
\index[nb::]{squareroot}
\index[hm::root]{$\srqt{2}$}
\stoptyping

The index entries we have discussed so far indicate the one
page where the entry is made, but we can also indicate
complete ranges of pages using:

\showsetup{<<start>>register}

The entries in between, which are of the same order, are not
placed in the register.

\starttyping
\startregister[endless]{endless}
...... an endless story ......
\stopregister[endless]
\stoptyping

An extensive index entry, i.e.\ an entry with a large number
of appearances, may have an uncomfortably long list of
pagenumbers. Especially in interactive documents this leads
to endless back and forth clicking. For this purpose we
designed the feature of linked index entries. This means
that you can couple identical entries into a list that
enables the user to jump from entry to (identical) entry
without returning to the register. The coupling mechanism is
activated by:

\startexample
\starttyping
\setupregister[index][coupling=yes]
\stoptyping
\stopexample

In this way a mechanism is activated that places references
in the register (\hbox {\symbol [previous]\ \symbol
[somewhere]\ \symbol [next]}) as well as in the text (\hbox
{\symbol [previous]\ {\bf word}\ \symbol [next]}) depending
on the availability of alternatives. A jump from the
register will bring you to the first, the middle or the last
appearance of the entry.

This mechanism is only working at the first level;
subentries are ignored. Clicking on the word itself will
bring you back to the register. Because we need the
clickable word in the text we use the following command for
the index entry itself:

\showsetup{coupled<<register>>}

For example \type {\coupledindex{where}}. The couplings
must be loaded with the command:

\showsetup{coupleregister}

Normally this command is executed automatically when needed,
so it's only needed in emergencies.

\stopcomponent
