Difference between revisions of "Registers"

From Wiki
Jump to navigation Jump to search
Line 9: Line 9:
 
If you need multiple levels (up to three), use "+" or "&" separators like in <cmd>index</cmd><tt>{beans+baked}</tt>.
 
If you need multiple levels (up to three), use "+" or "&" separators like in <cmd>index</cmd><tt>{beans+baked}</tt>.
  
'''Note: In MkIV (Sept.2010) & gives an error "Misplaced alignment tab character &" '''
+
'''Note: In MkIV (Sept.2010) "&" gives an error "Misplaced alignment tab character &" '''
  
'''So, just use "*" '''
+
'''So, just use "+" '''
  
 
You get a cross reference in your index with <cmd>seeindex</cmd> like in <cmd>seeindex</cmd><tt>[CONTEXT]{\ConTeXt}{\TeX}</tt> (ConTeXt: see TeX).
 
You get a cross reference in your index with <cmd>seeindex</cmd> like in <cmd>seeindex</cmd><tt>[CONTEXT]{\ConTeXt}{\TeX}</tt> (ConTeXt: see TeX).

Revision as of 19:40, 26 September 2010

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

Note: In MkIV (Sept.2010) "&" gives an error "Misplaced alignment tab character &"

So, just use "+"

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]{$\sqrt{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[index][mymouse]{mouse} ... \stopregister[index][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[index][mymouse1]{mouse} ... \stopregister[index][mymouse1] and then \startregister[index][mymouse2]{mouse} ... \stopregister[index][mymouse2] to get two independent ranges in the list. \startregister takes four arguments, of which two are mandatory: \startregister[NAME_OF_REGISTER]{ENTRY_NAME}. The other arguments are [KEY_FOR_RANGE] and [KEY_FOR_SORTING]. To give an example: \startregister[index][levi][Levi-Strauss]{Lévi|-|Strauss}. This will start a range with the key levi which will put the entry "Lévi-Strauss" in the register "index" (the "normal" register) and sort it under "Levi-Strauss." To mark the end of the range, you write \stopregister[index][levi].
  • Automatically collapse page ranges: \placeindex[compress=yes]
  • \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.!
  • The name that you will get in the head of \completeregister can be set with: \setupheadtext[register=My new index]
  • Get uppercase-letter heads: \setupregister[index][n=2,command=\Word,style=normal]

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.