Difference between revisions of "Registers"

From Wiki
Jump to navigation Jump to search
(Last edit was me too - forgot to log in.)
(Added note on vertical space problems)
Line 69: Line 69:
 
* Place a word in text ''and'' index: <tt>\def\Tindex#1{\index{#1}#1}</tt>  -- Please someone enhance this to get space correction, [] sorting etc.!
 
* Place a word in text ''and'' index: <tt>\def\Tindex#1{\index{#1}#1}</tt>  -- Please someone enhance this to get space correction, [] sorting etc.!
  
==Coupled Registers==
+
=Coupled Registers=
  
 
This is a special feature for documents that are only used on screen: Make a word clickable to jump to the index, the first or last occurrence.
 
This is a special feature for documents that are only used on screen: Make a word clickable to jump to the index, the first or last occurrence.
Line 75: Line 75:
 
Enable it with <cmd>setupregister</cmd><tt>[index][coupling=yes]</tt>.
 
Enable it with <cmd>setupregister</cmd><tt>[index][coupling=yes]</tt>.
 
Substitute <cmd>index</cmd> with <cmd>coupledindex</cmd> and enjoy!
 
Substitute <cmd>index</cmd> with <cmd>coupledindex</cmd> and enjoy!
 +
 +
=Impact on vertical spacing=
 +
 +
In some situations, placing an <cmd>index</cmd> (or related command) might affect vertical spacing and the page-breaking mechanism. In those situations it is advisable to wrap the command in a <cmd>doflushatpar</cmd> as shown below (needs a ConTeXt version dated after 14th Dec 2005):
 +
 +
<texcode>
 +
\starttext
 +
\section{Tufte}
 +
\dorecurse{4}{\input tufte \par}
 +
\section{Knuth}
 +
\doflushatpar{\index{Knuth}}
 +
\input knuth \par
 +
\stoptext
 +
</texcode>
 +
 +
This will stop bad-page breaking between the section title and the following para, for example.
 +
 +
==Technical note==
 +
 +
The above command is defined as follows:
 +
 +
<texcode>
 +
\long\def\doflushatpar#1%
 +
% {\dogotopar{\dontleavehmode#1}}  % this one can introduce empty lines
 +
{\dogotopar{#1\ifvmode\nobreak\fi}} % while this one can mess up vertical space
 +
</texcode>
 +
 +
Note the two possible definitions, and the pitfalls with each one. If you are still having trouble with specific <cmd>index</cmd> commands, try using the alternative definition. When they are used in the right context, these three possible ways of placing an index term (the plain <cmd>index</cmd>, or it wrapped in one of the two possible <cmd>doflushatpar</cmd>s, should solve any problem.

Revision as of 18:11, 14 December 2005

< Structurals | References > (It's also in the manual at "Registers")

Basics

Putting a word into the index as simple as \index{word}. (Always type \index before the word you refer to!)

To sort e.g. \ConTeXt under "C", you write \index[CONTEXT]{\ConTeXt}.

If you need multiple levels (up to three), use "+" or "&" separators like in \index{beans+baked}.

You get a cross reference in your index with \seeindex like in \seeindex[CONTEXT]{\ConTeXt}{\TeX} (ConTeXt: see TeX).

To typeset the index, use \placeindex (without title) or \completeindex (with titling).

Example

My \index{dog}dog is a \index{dog+bullterrier}bullterrier named \seeindex{Dolly}{Underware}Dolly.
He doesn't like \index{cat}cats.
There are a lot of \index{cat+stray}stray cats, but only a few of them are \index{cat+Siamese}Siamese.

\placeindex

Styling the Index

\setupregister[index] is your friend. \placeindex and \completeindex take the same options.

You can also style single entries with the :: syntax like this (from the manual):

\setupregister[index][form][pagestyle=bold,textstyle=slanted]
\setupregister[index][tb][textstyle=bold]
\setupregister[index][nb][pagestyle=bold]
\setupregister[index][hm][pagestyle=slanted]

\index{tb::foot+squarefoot} % text in "tb" style
\index[nb::]{squareroot} % number in "nb" style
\index[hm::root]{$\srqt{2}$} % number in "hm" style, sorted at "root"

More Registers

\index is only one special case of \register. You can define as much different registers as you like:

\defineregister[singular name][plural name], e.g.

\defineregister[mouse][mice]
\setupregister[mouse][style=\ss]

\mouse{rat}

\placemouse

(Don't know if the plural form is used anywhere...)

Tricks

  • \startregister[mymouse]{mouse} ... \stopregister[mymouse]: to mark several pages for the same entry; becomes e.g. "mouse 12--16". Note that if you have two or more of these ranges, you need them to have different [key] values to stop the system treating them as part of a great big range. So, use \startregister[mymouse1]{mouse} ... \stopregister[mymouse1] and then \startregister[mymouse2]{mouse} ... \stopregister[mymouse2] to get two independent ranges in the list.
  • \writetoregister (sometimes needed to avoid macro expansion issues)
  • A register per chapter: \placeregister[index][criterium=chapter]
  • Place a word in text and index: \def\Tindex#1{\index{#1}#1} -- Please someone enhance this to get space correction, [] sorting etc.!

Coupled Registers

This is a special feature for documents that are only used on screen: Make a word clickable to jump to the index, the first or last occurrence.

Enable it with \setupregister[index][coupling=yes]. Substitute \index with \coupledindex and enjoy!

Impact on vertical spacing

In some situations, placing an \index (or related command) might affect vertical spacing and the page-breaking mechanism. In those situations it is advisable to wrap the command in a \doflushatpar as shown below (needs a ConTeXt version dated after 14th Dec 2005):

\starttext
\section{Tufte}
\dorecurse{4}{\input tufte \par}
\section{Knuth}
\doflushatpar{\index{Knuth}}
\input knuth \par
\stoptext

This will stop bad-page breaking between the section title and the following para, for example.

Technical note

The above command is defined as follows:

\long\def\doflushatpar#1%
% {\dogotopar{\dontleavehmode#1}}   % this one can introduce empty lines
{\dogotopar{#1\ifvmode\nobreak\fi}} % while this one can mess up vertical space

Note the two possible definitions, and the pitfalls with each one. If you are still having trouble with specific \index commands, try using the alternative definition. When they are used in the right context, these three possible ways of placing an index term (the plain \index, or it wrapped in one of the two possible \doflushatpars, should solve any problem.