# Changes

,  21:12, 18 August 2019
< [[Structurals]] | [[Bibliography]] >
==General Use==
If you want to refer to any text element, you must first define the target's reference label. All titling commands and a lot of others take one as optional parameter, e.g.
<texcode>
That will typeset the text in braces and add the number of the refered element, e.g. "chapter 1 on page 1".
To define a reference label anywhere you can also use <{{cmd>|pagereference</cmd><tt>|[reference]</tt> }} and <{{cmd>|textreference</cmd><tt>|[reference]{text}</tt>}}. Everwhere where you can define one label, you can also define more at once, if you separate them with commas. It's also possible to use "namespaces" like <ttcode>[fig:cow]</ttcode>.
If you activated interaction, references become links automatically.
Starting with ConTeXt 2012.06.22, there is a third command: <{{cmd>|contentreference</cmd><tt>|[reference][framedsettings]{text}</tt> }} which wraps the <ttcode>text</ttcode> argument inside a <{{cmd>|framed</cmd>}}. The main difference with <{{cmd>|textreference</cmd> }} where the <ttcode>text</ttcode> contains a <{{cmd>|framed</cmd> }} itself is that, when interaction is enabled, <{{cmd>|contentreference</cmd> }} places the top left of the target area at the top left of the framed box whereas <{{cmd>|textreference</cmd> }} uses its baseline.
===Example===
When the default chapter and section prefixes are used, the chapters are
prefixed by a number, so are the sections. When referring to a section using
the command <{{cmd>|in|{section}[sec:foo]</cmd> }} the chapter number is prefixed
following by a dot and the according section number.
However, some styles do not show the chapter prefix while displaying the
sections. In this case the referencing commands, like <{{cmd>|in</cmd> }} just output the
section number, which is of course ambiguous.
To fix this problem, the command <{{cmd>|setupreferencestructureprefix</cmd> }} can be
incorporated to adjust the prefixes displayed by the referencing commands.
===Example===
Given that <{{cmd>|start}}/{{cmd|stopchapter</cmd> }} output <ttcode>Romannumerals</ttcode> prefixes (<tt>I,II, III, …</tt>) and <{{cmd>|start}}/{{cmd|stopsection</cmd> }} output <ttcode>Character</ttcode> prefixes (<tt>A,B, C, …</tt>), the following commands give the results provided in the comments.
<texcode>
To adjust the separator between the different structure
levels in the referencing commands, like <{{cmd>|in</cmd>}}, the command<{{cmd>|definestructureseparatorset</cmd> }} is used.
===Example===
To change the separator between chapter and section from a dot to a hyphen use
<{{cmd>|definestructureseparatorset</cmd> }} as follows.
<texcode>
\definestructureseparatorset [default] [,,-]
</texcode>

==Putting a separator in the heading but not the reference==

Sometimes you want to have a separator in the heading but not the reference. For example, you want section heading to look like "3. This is a new section" (with a dot after the section number), but references to the section should not have the dot (they should be like "In section 3 we found..."). Wolfgang Schuster gave a solution (for MkIV) [http://www.ntg.nl/pipermail/ntg-context/2013/072650.html on the list]:

<texcode>
\defineprocessor[dostopper][right=.]
\defineprocessor[nostopper][right=]

\defineconversionset[stopperconversionyes][][dostopper->n]
\defineconversionset[stopperconversionnop][][nostopper->n]

%\setupreferencestructureprefix[chapter][default][prefixconversionset=stopperconversionnop]
\setupreferencestructureprefix[default][prefixconversionset=stopperconversionnop]

\starttext

\input knuth

In \in{Chapter}[one] we learn.

\stoptext

</texcode>

==References to an external file==

You can refer to referenced elements in an external file. MkIV requires for this the presence of the '''tuc-file''' of the referenced file. ConTeXt will catch the information to be included from this file.

===Example===
External files: hasseltbook.tex/pdf/'''tuc'''

The contents of hasseltbook.tex could be:

<texcode>
\starttext

\startstandardmakeup
\midaligned{\tfd Festivities in Hasselt}
\stopstandardmakeup

\startchapter[title=Euifeest,reference=euifeest]
Something about the Euifeest.\index{Euifeest}
\stopchapter

\stoptext
</texcode>

In your document you can say:

<texcode>
\setupinteraction
[state=start]

\useexternaldocument
[hia][hasseltbook][Festivities in Hasselt]

\setupinteraction
[state=start,
color=green,
style=bold]

\starttext
Most tourist attractions are described in \from[hia].\crlf
A description of the \about[hia::euifeest] is found in \from[hia].\crlf
The eui||feest is described on \at{page}[hia::euifeest] in \from[hia].\crlf
See for more information \in{chapter}[hia::euifeest] in \from[hia].
\stoptext
</texcode>

Note how the link is established to the externalfile:
<texcode>\command[symbolic-name::reference]</texcode>

==Related Modules==

* [[Cross Referencing]]: Cross references in a (academic) text are either internal (linking to an other point inside the same document) or external (linking to a entity of the bibliography that points to a different document).
* [[Paragraph Referencing]]: The pararef module understands a paragraph as a full closed block of one thought.
{{todo|Describe what the arguments of the commands do and how the commands work}}
{{Getting started navbox}}` ==Putting a separator in the heading but not the reference==
40

edits