Difference between revisions of "Registers"

From Wiki
Jump to navigation Jump to search
m (fix link to register command)
(36 intermediate revisions by 12 users not shown)
Line 1: Line 1:
< [[Structurals]] | [[References]] > (It's also in the manual at "Registers")
 
 
 
=Basics=
 
=Basics=
  
Putting a word into the index as simple as <cmd>index</cmd><tt>{word}</tt>. (Always type <cmd>index</cmd> ''before'' the word you refer to!)
+
Use indexes as follows:
  
To sort e.g. <cmd>ConTeXt</cmd> under "C", you write <cmd>index</cmd><tt>[CONTEXT]{\ConTeXt}</tt>.
+
* To add the word "word", use: {{cmd|index}}<tt>{word}</tt>
 +
* To sort a word (such as "ConTeXt" under "C"), use: {{cmd|index}}<tt>[CONTEXT]{\ConTeXt}</tt>
 +
* To use multi-levels (up to three), use a plus symbol: {{cmd|index}}<tt>{beans+baked}</tt>
 +
* To cross-reference items, use {{cmd|seeindex}}: {{cmd|seeindex}}<tt>[CONTEXT]{\ConTeXt}{\TeX}</tt>
 +
* To include the index without a title, use: {{cmd|placeindex}}
 +
* To include the index with a title, use: {{cmd|completeindex}}
  
If you need multiple levels (up to three), use "+" or "&" separators like in <cmd>index</cmd><tt>{beans+baked}</tt>.
+
Note that the {{cmd|completeindex}} command might not work correctly. In such situations you can use: {{cmd|subject}}<tt>{Index}</tt> {{cmd|placeindex}}
  
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).
+
==Example==
 
 
To typeset the index, use <cmd>placeindex</cmd> (without title) or <cmd>completeindex</cmd> (with titling).
 
  
==Example==
 
 
<texcode>
 
<texcode>
 
My \index{dog}dog is a \index{dog+bullterrier}bullterrier named \seeindex{Dolly}{Underware}Dolly.
 
My \index{dog}dog is a \index{dog+bullterrier}bullterrier named \seeindex{Dolly}{Underware}Dolly.
Line 31: Line 31:
 
=Styling the Index=
 
=Styling the Index=
  
<cmd>setupregister</cmd><tt>[index]</tt> is your friend. <cmd>placeindex</cmd> and <cmd>completeindex</cmd> take the same options.
+
Registers consist of three text elements that can be styled
 +
independently:
 +
the sections headings, the entry text, and a page number (reference).
 +
For formatting purposes each has its own key so it can be referred to
 +
consistently:
 +
 
 +
* <tt>style</tt> refers to the style of ''headings''; ordinarily these are the letters of the alphabet.
 +
* <tt>textstyle</tt> refers to the typeset content of an entry;
 +
* <tt>pagestyle</tt> refers to the typeset page number of an entry;
 +
* page numbers are references so their appearance depends on the [[Interaction|interaction]] settings as well.
 +
 
 +
== MkIV ==
 +
 
 +
=== General Setup ===
 +
The appearance of a register can be configured with {{cmd|setupregister}}.
 +
An example setup for the register ''entity'' could look like:
 +
 
 +
<texcode>
 +
\defineregister [entity]
 +
\setupregister  [entity] [
 +
      style=sansbold,  %% headings
 +
  textstyle=slanted,    %% entries
 +
  pagestyle=bolditalic, %% page refs
 +
          n=1,          %% columns
 +
]
 +
</texcode>
 +
 
 +
This typesets sections in bold face sans serif, entries with slant, and
 +
page references in italic.
 +
Also, the register will use a single column.
 +
 
 +
In MkIV {{cmd|setupregister}} is consistent with the common interface
 +
to [[Style_Alternatives|text style]].
 +
Thus for every <tt>style</tt> there is a corresponding <tt>color</tt>
 +
option (''color'', ''textcolor'', and ''pagecolor''):
 +
 
 +
<texcode>
 +
\setupregister [entity] [
 +
      color=red,
 +
  textcolor=green,
 +
  pagecolor=blue,
 +
]
 +
</texcode>
 +
 
 +
Naturally, self-defined alternatives are valid as well:
 +
 
 +
<texcode>
 +
\definefontfeature [textfigures] [onum=yes]
 +
 
 +
\definealternativestyle [reg:bigbold]  [\bfc]                    []
 +
\definealternativestyle [reg:tinybold] [\bfxx]                  []
 +
\definealternativestyle [reg:bignum]  [\tfc\addff{textfigures}] []
 +
 
 +
\defineregister [entity]
 +
\setupregister  [entity] [
 +
      style=reg:bigbold,
 +
  textstyle=reg:tinybold,
 +
  pagestyle=reg:bignum,
 +
]
 +
</texcode>
 +
 
 +
Use with care!
 +
 
 +
=== Processors ===
 +
 
 +
The [[Registers#Individiual_Entries|traditional approach]] to
 +
fine-tuning entries has not (yet?) been implemented in MkIV
 +
[http://www.ntg.nl/pipermail/ntg-context/2013/070961.html].
 +
Instead, there is a new mechanism called ''processors'' available that
 +
has a similar effect
 +
[http://www.ntg.nl/pipermail/ntg-context/2010/049493.html].
 +
 
 +
Processors are created via {{cmd|defineprocessor}}:
 +
 
 +
<texcode>
 +
\defineprocessor [relevant] [style=italic]
 +
</texcode>
 +
 
 +
To apply it to a register entry, we employ the <tt>-&gt;</tt> operator:
 +
<texcode>
 +
Text \entity{foo}text.
 +
Text \entity{relevant->bar}text.
 +
Text \entity{baz}text.
 +
</texcode>
 +
 
 +
This will render ''bar''’s entry in the register ''entity'' in italic
 +
font, while the other two entries remain unchanged.
 +
 
 +
<context mode=mkiv source=no>
 +
\defineregister [entity]
 +
\setupregister  [entity] [
 +
      style=sansbold,
 +
  textstyle=normal,
 +
  pagestyle=bolditalic,
 +
  n=1,
 +
]
 +
 
 +
\defineprocessor [relevant] [style=italic]
 +
 
 +
\starttext
 +
  \placeentity \page
 +
 
 +
  Text before.
 +
  Text \entity{foo}text.
 +
  Text \entity{relevant->bar}text.
 +
  Text \entity{baz}text.
 +
  Text after.
 +
\stoptext
 +
</context>
 +
 
 +
A processor is not local to a specific register (as it was in MkII).
 +
Once defined it can be applied to different registers, yielding the
 +
same effect:
 +
 
 +
<texcode>
 +
\defineregister [first]
 +
\defineregister [second]
 +
\defineregister [third]
 +
\defineprocessor [relevant] [style=italic,color=blue]
 +
\starttext %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 +
  \placefirst  \placesecond \placethird \page
 +
  Text before.
 +
  Text \first {foo} \first {relevant->bar 1} \first {baz}text.
 +
  Text \second{foo} \second{relevant->bar 2} \second{baz}text.
 +
  Text \third {foo} \third {relevant->bar 3} \third {baz}text.
 +
  Text after.
 +
\stoptext %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 +
</texcode>
 +
 
 +
The same processor can be applied to to both entries and page numbers.
 +
(Another difference from MkII.)
 +
For page numbers, apply the <tt>-&gt;</tt> operator on the optional
 +
first argument:
 +
 
 +
<texcode>
 +
\entity[relevant->]{foo}
 +
</texcode>
 +
 
 +
Note that <code>\entity[weird]{foo}</code> is not enough.
 +
Without the <tt>-&gt;</tt>, the first argument is interpreted as sort
 +
key.
 +
However, if in addition to the page number processor you wish to supply
 +
a custom sort key, then the sort key must follow the processor:
 +
 
 +
<texcode>
 +
\entity[relevant->baz]{foo}
 +
</texcode>
 +
 
 +
In this example, the page number will be displayed using the processor
 +
''relevant'' and the entity ''foo'' will be treated like the string
 +
''baz'' for sorting purposes.
 +
Of course, page number and text formatting can be combined:
 +
 
 +
<texcode>
 +
\entity[relevant->]{relevant->foo}
 +
</texcode>
 +
 
 +
Processors work well with multi-level indices:
 +
 
 +
<texcode>
 +
\entity {relevant->foo}
 +
\entity {relevant->foo+bar}
 +
\entity {relevant->foo+bar+baz}
 +
</texcode>
 +
 
 +
''Applying multiple processors to a single entry has no effect.''
 +
Context will ignore any other processor after the first.
 +
(This is probably a feature, as there is no need to repeat the
 +
processor with every entry.)
 +
However, different entries in the page reference list can be formatted
 +
differently:
 +
 
 +
<context mode=mkiv source=yes>
 +
\setupcolor[rgb]
 +
\defineregister  [stuff] [style=sansbold,pagestyle=italic,n=1]
 +
\defineprocessor [relevant]  [style=bold,color=red]
 +
\defineprocessor [irrelevant] [color=darkgray]
 +
 
 +
\starttext
 +
  \placestuff
 +
 
 +
  \page Text \stuff                {relevant->foo}  text.
 +
  \page Text \stuff                {foo}            text.
 +
  \page Text \stuff [relevant->]  {foo}            text.
 +
  \page Text \stuff                {irrelevant->foo} text. %% no effect!
 +
  \page Text \stuff [irrelevant->] {foo}            text.
 +
\stoptext
 +
</context>
 +
 
 +
=== Examples ===
 +
==== Simple Setup ====
 +
 
 +
<context mode=mkiv source=yes>
 +
\defineregister [entity]
 +
\setupregister  [entity] [
 +
    style=sansbold,
 +
textstyle=slanted,
 +
pagestyle=bolditalic,
 +
        n=1,
 +
]
 +
 
 +
\starttext
 +
 
 +
  \placeentity \page
 +
 
 +
  Text before.
 +
  Text \entity{foo} \entity{bar}  text.\page
 +
  Text \entity{foo} \entity{baz}  text.\page
 +
  Text \entity{foo} \entity{bar}  text.\page
 +
  Text \entity{foo} \entity{xyzzy} text.\page
 +
  Text after.
 +
 
 +
\stoptext
 +
</context>
 +
 
 +
==== Colorful Setup ====
 +
 
 +
<context mode=mkiv source=yes>
 +
\defineregister [entity]
 +
\setupregister  [entity] [
 +
      color=red,
 +
  textcolor=green,
 +
  pagecolor=blue,
 +
        n=1,
 +
]
 +
 
 +
\starttext
 +
 
 +
  \placeentity \page
 +
 
 +
  Text before.
 +
  Text \entity{foo} \entity{bar}  text.\page
 +
  Text \entity{foo} \entity{baz}  text.\page
 +
  Text \entity{foo} \entity{bar}  text.\page
 +
  Text \entity{foo} \entity{xyzzy} text.\page
 +
  Text after.
 +
 
 +
\stoptext
 +
</context>
 +
 
 +
==== Setup with Alternatives ====
 +
 
 +
<context mode=mkiv source=yes>
 +
\setuppapersize[A10][A7,landscape]
 +
 
 +
\setuppaper[nx=4, ny=2]
 +
\setuplayout[location=middle,marking=on]
 +
\setuparranging [XY]
 +
 
 +
\definefontfeature [textfigures] [onum=yes]
 +
 
 +
\definealternativestyle [reg:bigbold]  [\bfc]                    []
 +
\definealternativestyle [reg:tinybold] [\bfxx]                  []
 +
\definealternativestyle [reg:bignum]  [\tfc\addff{textfigures}] []
 +
 
 +
\defineregister [entity]
 +
\setupregister  [entity] [
 +
      style=reg:bigbold,
 +
  textstyle=reg:tinybold,
 +
  pagestyle=reg:bignum,
 +
]
 +
 
 +
\starttext
 +
 
 +
  \placeentity \page
 +
 
 +
  Text before.
 +
  Text \entity{foo} \entity{bar}  text.\page
 +
  Text \entity{foo} \entity{baz}  text.\page
 +
  Text \entity{foo} \entity{bar}  text.\page
 +
  Text \entity{foo} \entity{xyzzy} text.\page
 +
  Text after.
 +
 
 +
\stoptext
 +
</context>
 +
 
 +
==== Complex Setup ====
 +
 
 +
<texcode>
 +
\definefontfeature [textfigures] [onum=yes]
 +
 
 +
\definealternativestyle [reg:heada]  [\WORD\ssa\bold]
 +
\definealternativestyle [reg:headb]  [\word\tfb\sc]
 +
\definealternativestyle [reg:pageno] [\addff{textfigures}\italic]
 +
 
 +
\defineregister [entity] [style=reg:heada,pagestyle=normal,n=3]
 +
\defineregister [object] [style=reg:headb,pagestyle=reg:pageno,n=2]
 +
 
 +
\defineprocessor [relevant] [style=italic]
 +
\defineprocessor [weird]    [style=italic,color=red]
 +
\defineprocessor [striking] [style=bold,color=blue]
 +
 
 +
\starttext
 +
 
 +
  \placeentity \blank[3*big] \placeobject \page
 +
 
 +
  \dorecurse{3}{
 +
    Text before.
 +
    \page Text \entity            {foo}          text.
 +
          Text \object            {striking->bar} text.
 +
          Text \entity            {baz+foo}      text.
 +
          Text \object            {foo+bar}      text.
 +
    \page Text \entity[relevant->] {weird->foo}    text.
 +
    \page Text \entity            {weird->bar}    text.
 +
          Text \object[weird->]    {foo}          text.
 +
          Text \object            {baz}          text.
 +
    \page Text \entity[weird->foo] {foo}          text.
 +
    \page Text \entity[weird->]    {baz}          text.
 +
          Text \object            {baz}          text.
 +
          Text \object            {bar+baz}      text.
 +
          Text \entity[weird->]    {baz}          text.
 +
          Text \entity            {baz+miranda}  text.
 +
          Text \entity            {baz+xyzzy}    text.
 +
          Text \object            {foo}          text.
 +
    \page Text \entity            {weird->foo}    text.
 +
          Text \object[striking->] {bar+baz}      text.
 +
          Text \object            {foo}          text.
 +
          Text \entity[relevant->] {baz+xyzzy}    text.
 +
    \page Text \entity[weird->foo] {foo}          text.
 +
          Text \object            {bar+xyzzy}    text.
 +
          Text \object            {baz}          text.
 +
          Text \object            {foo}          text.
 +
          Text \entity[weird->]    {baz+xyzzy+meh} text.
 +
    \page Text \entity[weird->]    {weird->foo}    text.
 +
          Text \object[striking->] {foo}          text.
 +
          Text \object            {xyzzy}        text.
 +
          Text \entity            {baz+xyzzy}    text.
 +
    Text after.
 +
  }
 +
 
 +
\stoptext
 +
</texcode>
 +
 
 +
 
 +
== MkII ==
 +
 
 +
=== 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>
 +
\defineregister[thing][stuff]
 +
\setupregister[thing][
 +
  style=boldslanted,  %% headings
 +
  textstyle=bold,    %% items
 +
  pagestyle=slanted,  %% page numbers
 +
]
 +
</texcode>
 +
 
 +
Here we first initialize a register ''thing''.
 +
Then we assign a different
 +
[[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).
  
You can also style single entries with the :: syntax like this (from the manual):
+
=== Individual 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>
 
<texcode>
\setupregister[index][form][pagestyle=bold,textstyle=slanted]
+
\setupregister[thing][important] [textstyle=bold, pagestyle=boldslanted]
\setupregister[index][tb][textstyle=bold]
+
\setupregister[thing][nonsense] [textstyle=\tfxx, pagestyle=\tfd]
\setupregister[index][nb][pagestyle=bold]
+
</texcode>
\setupregister[index][hm][pagestyle=slanted]
 
  
\index{tb::foot+squarefoot} % text in "tb" style
+
This creates the substyles ''important'' and ''nonsense'' for the
\index[nb::]{squareroot} % number in "nb" style
+
register ''thing''.
\index[hm::root]{$\sqrt{2}$} % number in "hm" style, sorted at "root"
+
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>
 
</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>
 +
category>+
 +
/context>
 +
 +
==== Colorful Setup ====
  
 
=More Registers=
 
=More Registers=
  
<cmd>index</cmd> is only one special case of <cmd>register</cmd>. You can define as much different registers as you like:
+
{{cmd|index}} is only one special case of {{gen|register}}. You can define as much different registers as you like:
  
<cmd>defineregister</cmd><tt>[singular name][plural name]</tt>, e.g.  
+
{{cmd|defineregister}}<tt>[singular name][plural name]</tt>, e.g.  
 
<texcode>
 
<texcode>
 
\defineregister[mouse][mice]
 
\defineregister[mouse][mice]
Line 64: Line 495:
 
=Tricks=
 
=Tricks=
  
* <cmd>startregister</cmd><tt>[mymouse]{mouse}</tt> ... <cmd>stopregister</cmd><tt>[mymouse]</tt>: 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 <tt>[key]</tt> values to stop the system treating them as part of a great big range. So, use <cmd>startregister</cmd><tt>[mymouse1]{mouse}</tt> ... <cmd>stopregister</cmd><tt>[mymouse1]</tt> and then <cmd>startregister</cmd><tt>[mymouse2]{mouse}</tt> ... <cmd>stopregister</cmd><tt>[mymouse2]</tt> to get two independent ranges in the list. <cmd>startregister</cmd> takes four arguments, of which two are mandatory: <cmd>startregister</cmd><tt>[NAME_OF_REGISTER]{ENTRY_NAME}</tt>. The other arguments are <tt>[KEY_FOR_RANGE}</tt> and <tt>[KEY_FOR_SORTING]</tt>. To give an example: <cmd>startregister</cmd><tt>[index][levi][Levi-Strauss]{Lévi|-|Strauss}</tt>. This will start a range with the key <tt>levi</tt> 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 <cmd>stopregister</cmd><tt>[index][levi]</tt>.
+
* A register per chapter: {{cmd|placeregister}}<tt>[index][criterium=chapter]</tt>
* <cmd>writetoregister</cmd> (sometimes needed to avoid macro expansion issues)
+
* Uppercase-letter index heads: {{cmd|setupregister}}<tt>[index][n=2,command=\Word,style=normal]</tt>
* A register per chapter: <cmd>placeregister</cmd><tt>[index][criterium=chapter]</tt>
 
 
* 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.!
* The name that you will get in the head of \completeregister can be set with: \setupheadtext[register=My new index]
+
* {{cmd|writetoregister}} (sometimes needed to avoid macro expansion issues, '''MkII only''')
 +
 
 +
 
 +
== Collapse Page Numbers ==
 +
 
 +
Often index entries like "mouse 2,3,4,5" aren’t desired, instead ConTeXt should shorten it to "mouse 2–5". This is called collapsing.
 +
There are two ways to collapse page numbers:
 +
 
 +
# {{cmd|setupregister}}[compress=yes]
 +
 
 +
# Enclose several pages in {{cmd|startregister}} … {{cmd|stopregister}}:
 +
 
 +
<texcode>
 +
\startregister[index][Keycode1]{Keyword}
 +
% lots of text
 +
\stopregister[index][Keycode1]
 +
</texcode>
 +
 
 +
The first parameter of {{cmd|startregister}} is the name of the index – "index" is the default index, but you might use your self defined registers as well.
 +
 
 +
The second parameter is a keyword to distinguish several overlapping range-entries.
 +
 
 +
It’s also possible to use the sorting parameter:
 +
 
 +
<texcode>
 +
\startregister[index][levi][Levi-Strauss]{Lévi|-|Strauss}
 +
% lots of text
 +
\stopregister[index][levi]
 +
</texcode>
 +
 
 +
This will create a range with the key <tt>levi</tt> which will put the entry "Lévi-Strauss" in the register "index" (the "normal" register) and sort it under "Levi-Strauss."
 +
 
 +
== Rename Register Heading ==
 +
 
 +
Change the {{cmd|completeregister}} heading using the {{cmd|setupheadtext}} command. For example:
 +
 
 +
<context source="yes">
 +
\defineregister[photographer][]
 +
 
 +
\setupregister[photographer][
 +
  indicator=no,
 +
]
 +
 
 +
\setupheadtext[photographer=Credits]
 +
 
 +
\starttext
 +
  \photographer{Yousuf Karsh}
 +
 
 +
  \completephotographer
 +
\stoptext
 +
</context>
 +
 
 +
== Alphabetical Headers ==
 +
 
 +
The letters of the alphabet can be disabled by {{cmd|setupregister}}<tt>[register][indicator=no]</tt>.
 +
 
 +
The vertical spaces between the entry groups for subsequent letters is governed by the parameter <tt>before</tt> in the same command (default: <tt>\blank</tt>, change to <tt>before={}</tt> to get no additional space).
 +
 
 +
=Sorting=
 +
 
 +
The sorting of the index is influenced by the current [[Languages#Language_tags|language tag]]. You can override that with the {{key|language}} key of {{cmd|setupregister}}.
 +
There are a few additional "languages" for sorting, as defined in {{src|sort-lan.mkiv}}:
 +
* <tt>DIN 5007-1</tt> (German) normal sorting, ß = ss
 +
* <tt>DIN 5007-2</tt> (German) phonebook sorting, ä = ae, ö = oe, ü = ue, ß = ss
 +
* <tt>Duden</tt> (German) ß = s
 +
* <tt>de-AT</tt> (Austrian German) phonebook sorting; umlauts after base vocal (a, ä, o, ö, u, ü)
 +
* <tt>cu</tt> (Church Slavonic)
 +
* <tt>ocs-scn</tt> (Scientific Old Slavonic transcription)
 +
* <tt>ru-iso9</tt> (Russian transcription)
 +
 
 +
Additionally, there’s the {{key|method}} key that influences the order of upper-/lowercase and diacritics:
 +
 
 +
The details lay in a rather obscure set of methods (see {{src|sort-ini.lua|source}}), for which the following presets are defined:
 +
 
 +
* {{key|default}} = {{key|"zc,pc,zm,pm,uc"}} (uppercase like lowercase, diacritics separate)
 +
* {{key|before}}  = {{key|"mm,mc,uc"}} (upper before lower, diacritics ignored)
 +
* {{key|after}}    = {{key|"pm,mc,uc}} (lower before upper, diacritics ignored)
 +
* {{key|first}}  = {{key|"pc,mm,uc"}} (lower before upper, diacritics separate)
 +
* {{key|last}}    = {{key|"mc,mm,uc"}} (upper before lower, diacritics separate)
 +
* If you don’t set the sorting method, the preset "first" ist used (and not "default").
 +
* There’s no preset for the combination "uppercase like lowercase, diacritics ignored", try {{key|"zm,pm,zc,zm,uc"}}.
 +
* The sorting is also influenced by the current language or the language setting in {{cmd|setupregister}}.
 +
 
 +
e.g.
 +
<texcode>
 +
\setupregister[index][
 +
  n=1,
 +
  language=Duden,
 +
  method={zm,pm,zc,zm,uc},
 +
]
 +
</texcode>
  
 
=Coupled Registers=
 
=Coupled Registers=
Line 74: Line 594:
 
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.
  
Enable it with <cmd>setupregister</cmd><tt>[index][coupling=yes]</tt>.
+
Enable it with {{cmd|setupregister}}<tt>[index][coupling=yes]</tt>.
Substitute <cmd>index</cmd> with <cmd>coupledindex</cmd> and enjoy!
+
Substitute {{cmd|index}} with {{cmd|coupledindex}} and enjoy!
  
 
=Impact on vertical spacing=
 
=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):
+
In some situations, placing an {{cmd|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 {{cmd|doflushatpar}} as shown below (needs a ConTeXt version dated after 14th Dec 2005):
  
 
<texcode>
 
<texcode>
Line 103: Line 623:
 
</texcode>
 
</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.
+
Note the two possible definitions, and the pitfalls with each one. If you are still having trouble with specific {{cmd|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 {{cmd|index}}, or it wrapped in one of the two possible {{cmd|doflushatpar}}s, should solve any problem.
 +
 
 +
=Impact on hyphenation, and on line breaking as a consequence=
 +
 
 +
{{cmd|index}} is attached to a word, so it modifies the word boundaries. That influences its hyphenation and likely the paragraph's line breaking. To prevent that, you can write:
 +
 
 +
<texcode>
 +
This is an indexed term\wordboundary\index{Term}. % instead of simply ... term\index{Term}.
 +
</texcode>
 +
 
 +
That way, ConTeXt knows that the word "term" is ended by the "m" and not by something attached to it by {{cmd|index}}, and the effect on hyphenation and line breaking is the same as if we wrote:
 +
 
 +
<texcode>
 +
This is an indexed term.
 +
</texcode>
 +
 
 +
[[Category:Basics]]

Revision as of 11:28, 30 August 2020

Basics

Use indexes as follows:

  • To add the word "word", use: \index{word}
  • To sort a word (such as "ConTeXt" under "C"), use: \index[CONTEXT]{\ConTeXt}
  • To use multi-levels (up to three), use a plus symbol: \index{beans+baked}
  • To cross-reference items, use \seeindex: \seeindex[CONTEXT]{\ConTeXt}{\TeX}
  • To include the index without a title, use: \placeindex
  • To include the index with a title, use: \completeindex

Note that the \completeindex command might not work correctly. In such situations you can use: \subject{Index} \placeindex

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

Registers consist of three text elements that can be styled independently: the sections headings, the entry text, and a page number (reference). For formatting purposes each has its own key so it can be referred to consistently:

  • style refers to the style of headings; ordinarily these are the letters of the alphabet.
  • textstyle refers to the typeset content of an entry;
  • pagestyle refers to the typeset page number of an entry;
  • page numbers are references so their appearance depends on the interaction settings as well.

MkIV

General Setup

The appearance of a register can be configured with \setupregister. An example setup for the register entity could look like:

\defineregister [entity]
\setupregister  [entity] [
      style=sansbold,   %% headings
  textstyle=slanted,    %% entries
  pagestyle=bolditalic, %% page refs
          n=1,          %% columns
]

This typesets sections in bold face sans serif, entries with slant, and page references in italic. Also, the register will use a single column.

In MkIV \setupregister is consistent with the common interface to text style. Thus for every style there is a corresponding color option (color, textcolor, and pagecolor):

\setupregister  [entity] [
      color=red,
  textcolor=green,
  pagecolor=blue,
]

Naturally, self-defined alternatives are valid as well:

\definefontfeature [textfigures] [onum=yes]

\definealternativestyle [reg:bigbold]  [\bfc]                    []
\definealternativestyle [reg:tinybold] [\bfxx]                   []
\definealternativestyle [reg:bignum]   [\tfc\addff{textfigures}] []

\defineregister [entity]
\setupregister  [entity] [
      style=reg:bigbold,
  textstyle=reg:tinybold,
  pagestyle=reg:bignum,
]

Use with care!

Processors

The traditional approach to fine-tuning entries has not (yet?) been implemented in MkIV [1]. Instead, there is a new mechanism called processors available that has a similar effect [2].

Processors are created via \defineprocessor:

\defineprocessor [relevant] [style=italic]

To apply it to a register entry, we employ the -> operator:

Text \entity{foo}text.
Text \entity{relevant->bar}text.
Text \entity{baz}text.

This will render bar’s entry in the register entity in italic font, while the other two entries remain unchanged.

A processor is not local to a specific register (as it was in MkII). Once defined it can be applied to different registers, yielding the same effect:

\defineregister [first]
\defineregister [second]
\defineregister [third]
\defineprocessor [relevant] [style=italic,color=blue]
\starttext %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \placefirst  \placesecond \placethird \page
  Text before.
  Text \first {foo} \first {relevant->bar 1} \first {baz}text.
  Text \second{foo} \second{relevant->bar 2} \second{baz}text.
  Text \third {foo} \third {relevant->bar 3} \third {baz}text.
  Text after.
\stoptext %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The same processor can be applied to to both entries and page numbers. (Another difference from MkII.) For page numbers, apply the -> operator on the optional first argument:

\entity[relevant->]{foo}

Note that \entity[weird]{foo} is not enough. Without the ->, the first argument is interpreted as sort key. However, if in addition to the page number processor you wish to supply a custom sort key, then the sort key must follow the processor:

\entity[relevant->baz]{foo}

In this example, the page number will be displayed using the processor relevant and the entity foo will be treated like the string baz for sorting purposes. Of course, page number and text formatting can be combined:

\entity[relevant->]{relevant->foo}

Processors work well with multi-level indices:

\entity {relevant->foo}
\entity {relevant->foo+bar}
\entity {relevant->foo+bar+baz}

Applying multiple processors to a single entry has no effect. Context will ignore any other processor after the first. (This is probably a feature, as there is no need to repeat the processor with every entry.) However, different entries in the page reference list can be formatted differently:

\setupcolor[rgb]
\defineregister  [stuff] [style=sansbold,pagestyle=italic,n=1]
\defineprocessor [relevant]   [style=bold,color=red]
\defineprocessor [irrelevant] [color=darkgray]

\starttext
  \placestuff

  \page Text \stuff                {relevant->foo}   text.
  \page Text \stuff                {foo}             text.
  \page Text \stuff [relevant->]   {foo}             text.
  \page Text \stuff                {irrelevant->foo} text. %% no effect!
  \page Text \stuff [irrelevant->] {foo}             text.
\stoptext

Examples

Simple Setup

\defineregister [entity]
\setupregister  [entity] [
     style=sansbold,
 textstyle=slanted,
 pagestyle=bolditalic,
         n=1,
]

\starttext

  \placeentity \page

  Text before.
  Text \entity{foo} \entity{bar}   text.\page
  Text \entity{foo} \entity{baz}   text.\page
  Text \entity{foo} \entity{bar}   text.\page
  Text \entity{foo} \entity{xyzzy} text.\page
  Text after.
  
\stoptext

Colorful Setup

\defineregister [entity]
\setupregister  [entity] [
      color=red,
  textcolor=green,
  pagecolor=blue,
         n=1,
]

\starttext

  \placeentity \page

  Text before.
  Text \entity{foo} \entity{bar}   text.\page
  Text \entity{foo} \entity{baz}   text.\page
  Text \entity{foo} \entity{bar}   text.\page
  Text \entity{foo} \entity{xyzzy} text.\page
  Text after.
  
\stoptext

Setup with Alternatives

\setuppapersize[A10][A7,landscape]

\setuppaper[nx=4, ny=2]
\setuplayout[location=middle,marking=on]
\setuparranging [XY]

\definefontfeature [textfigures] [onum=yes]

\definealternativestyle [reg:bigbold]  [\bfc]                    []
\definealternativestyle [reg:tinybold] [\bfxx]                   []
\definealternativestyle [reg:bignum]   [\tfc\addff{textfigures}] []

\defineregister [entity]
\setupregister  [entity] [
      style=reg:bigbold,
  textstyle=reg:tinybold,
  pagestyle=reg:bignum,
]

\starttext

  \placeentity \page

  Text before.
  Text \entity{foo} \entity{bar}   text.\page
  Text \entity{foo} \entity{baz}   text.\page
  Text \entity{foo} \entity{bar}   text.\page
  Text \entity{foo} \entity{xyzzy} text.\page
  Text after.
  
\stoptext

Complex Setup

\definefontfeature [textfigures] [onum=yes]

\definealternativestyle [reg:heada]  [\WORD\ssa\bold]
\definealternativestyle [reg:headb]  [\word\tfb\sc]
\definealternativestyle [reg:pageno] [\addff{textfigures}\italic]

\defineregister [entity] [style=reg:heada,pagestyle=normal,n=3]
\defineregister [object] [style=reg:headb,pagestyle=reg:pageno,n=2]

\defineprocessor [relevant] [style=italic]
\defineprocessor [weird]    [style=italic,color=red]
\defineprocessor [striking] [style=bold,color=blue]

\starttext

  \placeentity \blank[3*big] \placeobject \page

  \dorecurse{3}{
    Text before.
    \page Text \entity             {foo}           text.
          Text \object             {striking->bar} text.
          Text \entity             {baz+foo}       text.
          Text \object             {foo+bar}       text.
    \page Text \entity[relevant->] {weird->foo}    text.
    \page Text \entity             {weird->bar}    text.
          Text \object[weird->]    {foo}           text.
          Text \object             {baz}           text.
    \page Text \entity[weird->foo] {foo}           text.
    \page Text \entity[weird->]    {baz}           text.
          Text \object             {baz}           text.
          Text \object             {bar+baz}       text.
          Text \entity[weird->]    {baz}           text.
          Text \entity             {baz+miranda}   text.
          Text \entity             {baz+xyzzy}     text.
          Text \object             {foo}           text.
    \page Text \entity             {weird->foo}    text.
          Text \object[striking->] {bar+baz}       text.
          Text \object             {foo}           text.
          Text \entity[relevant->] {baz+xyzzy}     text.
    \page Text \entity[weird->foo] {foo}           text.
          Text \object             {bar+xyzzy}     text.
          Text \object             {baz}           text.
          Text \object             {foo}           text.
          Text \entity[weird->]    {baz+xyzzy+meh} text.
    \page Text \entity[weird->]    {weird->foo}    text.
          Text \object[striking->] {foo}           text.
          Text \object             {xyzzy}         text.
          Text \entity             {baz+xyzzy}     text.
    Text after.
  }

\stoptext


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

Individual 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

category>+ /context>

Colorful Setup

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

  • A register per chapter: \placeregister[index][criterium=chapter]
  • Uppercase-letter index heads: \setupregister[index][n=2,command=\Word,style=normal]
  • Place a word in text and index: \def\Tindex#1{\index{#1}#1} -- Please someone enhance this to get space correction, [] sorting etc.!
  • \writetoregister (sometimes needed to avoid macro expansion issues, MkII only)


Collapse Page Numbers

Often index entries like "mouse 2,3,4,5" aren’t desired, instead ConTeXt should shorten it to "mouse 2–5". This is called collapsing. There are two ways to collapse page numbers:

  1. \setupregister[compress=yes]
  1. Enclose several pages in \startregister\stopregister:
\startregister[index][Keycode1]{Keyword}
 % lots of text
\stopregister[index][Keycode1]

The first parameter of \startregister is the name of the index – "index" is the default index, but you might use your self defined registers as well.

The second parameter is a keyword to distinguish several overlapping range-entries.

It’s also possible to use the sorting parameter:

\startregister[index][levi][Levi-Strauss]{Lévi|-|Strauss}
 % lots of text
\stopregister[index][levi]

This will create 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."

Rename Register Heading

Change the \completeregister heading using the \setupheadtext command. For example:

\defineregister[photographer][]

\setupregister[photographer][
  indicator=no,
]

\setupheadtext[photographer=Credits]

\starttext 
  \photographer{Yousuf Karsh}

  \completephotographer
\stoptext 

Alphabetical Headers

The letters of the alphabet can be disabled by \setupregister[register][indicator=no].

The vertical spaces between the entry groups for subsequent letters is governed by the parameter before in the same command (default: \blank, change to before={} to get no additional space).

Sorting

The sorting of the index is influenced by the current language tag. You can override that with the language key of \setupregister. There are a few additional "languages" for sorting, as defined in sort-lan.mkiv:

  • DIN 5007-1 (German) normal sorting, ß = ss
  • DIN 5007-2 (German) phonebook sorting, ä = ae, ö = oe, ü = ue, ß = ss
  • Duden (German) ß = s
  • de-AT (Austrian German) phonebook sorting; umlauts after base vocal (a, ä, o, ö, u, ü)
  • cu (Church Slavonic)
  • ocs-scn (Scientific Old Slavonic transcription)
  • ru-iso9 (Russian transcription)

Additionally, there’s the method key that influences the order of upper-/lowercase and diacritics:

The details lay in a rather obscure set of methods (see source), for which the following presets are defined:

  • default = "zc,pc,zm,pm,uc" (uppercase like lowercase, diacritics separate)
  • before = "mm,mc,uc" (upper before lower, diacritics ignored)
  • after = "pm,mc,uc (lower before upper, diacritics ignored)
  • first = "pc,mm,uc" (lower before upper, diacritics separate)
  • last = "mc,mm,uc" (upper before lower, diacritics separate)
  • If you don’t set the sorting method, the preset "first" ist used (and not "default").
  • There’s no preset for the combination "uppercase like lowercase, diacritics ignored", try "zm,pm,zc,zm,uc".
  • The sorting is also influenced by the current language or the language setting in \setupregister.

e.g.

\setupregister[index][
  n=1,
  language=Duden,
  method={zm,pm,zc,zm,uc},
]

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.

Impact on hyphenation, and on line breaking as a consequence

\index is attached to a word, so it modifies the word boundaries. That influences its hyphenation and likely the paragraph's line breaking. To prevent that, you can write:

This is an indexed term\wordboundary\index{Term}. % instead of simply ... term\index{Term}.

That way, ConTeXt knows that the word "term" is ended by the "m" and not by something attached to it by \index, and the effect on hyphenation and line breaking is the same as if we wrote:

This is an indexed term.