Difference between revisions of "Registers"

From ConTeXt wiki
(Styling the Index: tag mkii specific code)
(MkII: expand mkii instructions)
Line 36: Line 36:
  
 
== MkII ==
 
== MkII ==
<cmd>setupregister</cmd><tt>[index]</tt> is your friend. <cmd>placeindex</cmd> and <cmd>completeindex</cmd> take the same options.
 
  
You can also style single entries with the :: syntax like this (from the manual):
+
=== General Setup ===
 +
The interface for register styling is {{cmd|setupregister}}.
 +
For settings that apply to the register as a whole use the two-argument
 +
version:
  
 
<texcode>
 
<texcode>
\setupregister[index][form][pagestyle=bold,textstyle=slanted]
+
\defineregister[thing][stuff]
\setupregister[index][tb][textstyle=bold]
+
\setupregister[thing][
\setupregister[index][nb][pagestyle=bold]
+
  style=boldslanted,  %% headings
\setupregister[index][hm][pagestyle=slanted]
+
  textstyle=bold,    %% items
 +
  pagestyle=slanted,  %% page numbers
 +
]
 +
</texcode>
  
\index{tb::foot+squarefoot} % text in "tb" style
+
Here we first initialize a register ''thing''.
\index[nb::]{squareroot} % number in "nb" style
+
Then we assign a different
\index[hm::root]{$\sqrt{2}$} % number in "hm" style, sorted at "root"
+
[[Style_Alternatives|style]]
 +
to each of the three elements:
 +
the option ''style'' refers to index section headings (letters), which
 +
will be typeset in bold slanted;
 +
''textstyle'' means the item (indexed string, here bold);
 +
finally, ''pagestyle'' sets the page number references (slanted).
 +
 
 +
=== Individiual Entries ===
 +
Better granularity regarding the formatting of individual entries can
 +
be achieved through the ''three-argument'' version of
 +
{{cmd|setupregister}}.
 +
Its second argument is an identifier by means of which a sub-style can
 +
be applied later.
 +
 
 +
<texcode>
 +
\setupregister[thing][important] [textstyle=bold,  pagestyle=boldslanted]
 +
\setupregister[thing][nonsense]  [textstyle=\tfxx, pagestyle=\tfd]
 +
</texcode>
 +
 
 +
This creates the substyles ''important'' and ''nonsense'' for the
 +
register ''thing''.
 +
To apply a sub-style, it has to be specified when an entry is added to
 +
the register.
 +
If we wanted to highlight an entry as important, we would call the
 +
macro {{cmd|thing|link=no}} as follows:
 +
 
 +
<texcode>
 +
text before \thing{important::entry} text after
 +
</texcode>
 +
 
 +
Note the double colon (<tt>::</tt>) that serves as delimiter between
 +
style directive (left hand side) and entry text (right).
 +
To highlight the page number instead:
 +
 
 +
<texcode>
 +
text before \thing[important::]{entry} text after
 +
</texcode>
 +
 
 +
Note that the '''<tt>::</tt> is non-optional'''!
 +
If the double colon is omitted, ''important'' would instead refer to
 +
the string used for register sorting.
 +
Of course, both elements can be styled at once:
 +
 
 +
<texcode>
 +
text before \thing[important::]{nonsense::entry} text after
 +
</texcode>
 +
 
 +
This produces an entry whose text is highlighted according to the
 +
definition of ''nonsense'' with a pagenumber styled as ''important''.
 +
 
 +
The syntax for an MkII-style register entry has the schematic:
 +
 
 +
<pre>
 +
\<registercmd> [<pagestyle>::<sortkey>] {<textstyle>::<category>+<entry>}
 +
</pre>
 +
 
 +
where only <code><entry></code> is mandatory.
 +
 
 +
=== Example ===
 +
 
 +
A complete working example demonstrating the highlighting capabilities:
 +
 
 +
<texcode>
 +
\defineregister[thing][things]
 +
%%% 2-arg
 +
\setupregister[thing][
 +
  style=boldslanted,
 +
  textstyle=normal,
 +
  pagestyle=slanted,
 +
]
 +
 
 +
%%% 3-arg
 +
\setupregister[thing][important] [textstyle=bold,  pagestyle=boldslanted]
 +
\setupregister[thing][nonsense]  [textstyle=\tfxx, pagestyle=\tfd]
 +
 
 +
 
 +
\starttext
 +
  Ordinary entries: \thing{one}\thing{two}
 +
 
 +
  Just a                \thing              {important::three}test.  %% text -> “important”
 +
  Yet another          \thing              {nonsense::four}test.    %% text -> “nonsense”
 +
  Again, nothing but a  \thing [important::] {five}test.              %% page -> “important”
 +
  Old story: this is a  \thing [important::] {important::five}test.  %% both -> “important”
 +
  Get it? A            \thing [important::] {important::six}test.    %% both -> “important”
 +
  Plain and simple:    \thing [nonsense::]  {nonsense::seven}test.  %% both -> “nonsense”
 +
 
 +
  \placething
 +
\stoptext
 
</texcode>
 
</texcode>
  

Revision as of 17:38, 2 April 2013

< 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

MkII

General Setup

The interface for register styling is \setupregister. For settings that apply to the register as a whole use the two-argument version:

\defineregister[thing][stuff]
\setupregister[thing][
  style=boldslanted,  %% headings
  textstyle=bold,     %% items
  pagestyle=slanted,  %% page numbers
]

Here we first initialize a register thing. Then we assign a different style to each of the three elements: the option style refers to index section headings (letters), which will be typeset in bold slanted; textstyle means the item (indexed string, here bold); finally, pagestyle sets the page number references (slanted).

Individiual Entries

Better granularity regarding the formatting of individual entries can be achieved through the three-argument version of \setupregister. Its second argument is an identifier by means of which a sub-style can be applied later.

\setupregister[thing][important] [textstyle=bold,  pagestyle=boldslanted]
\setupregister[thing][nonsense]  [textstyle=\tfxx, pagestyle=\tfd]

This creates the substyles important and nonsense for the register thing. To apply a sub-style, it has to be specified when an entry is added to the register. If we wanted to highlight an entry as important, we would call the macro \thing as follows:

text before \thing{important::entry} text after

Note the double colon (::) that serves as delimiter between style directive (left hand side) and entry text (right). To highlight the page number instead:

text before \thing[important::]{entry} text after

Note that the :: is non-optional! If the double colon is omitted, important would instead refer to the string used for register sorting. Of course, both elements can be styled at once:

text before \thing[important::]{nonsense::entry} text after

This produces an entry whose text is highlighted according to the definition of nonsense with a pagenumber styled as important.

The syntax for an MkII-style register entry has the schematic:

\<registercmd> [<pagestyle>::<sortkey>] {<textstyle>::<category>+<entry>}

where only <entry> is mandatory.

Example

A complete working example demonstrating the highlighting capabilities:

\defineregister[thing][things]
%%% 2-arg
\setupregister[thing][
  style=boldslanted,
  textstyle=normal,
  pagestyle=slanted,
]

%%% 3-arg
\setupregister[thing][important] [textstyle=bold,  pagestyle=boldslanted]
\setupregister[thing][nonsense]  [textstyle=\tfxx, pagestyle=\tfd]


\starttext
  Ordinary entries: \thing{one}\thing{two}

  Just a                \thing               {important::three}test.  %% text -> “important”
  Yet another           \thing               {nonsense::four}test.    %% text -> “nonsense”
  Again, nothing but a  \thing [important::] {five}test.              %% page -> “important”
  Old story: this is a  \thing [important::] {important::five}test.   %% both -> “important”
  Get it? A             \thing [important::] {important::six}test.    %% both -> “important”
  Plain and simple:     \thing [nonsense::]  {nonsense::seven}test.   %% both -> “nonsense”

  \placething
\stoptext

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.