Why is there an extra space when I create a reference location in a document in ConTeXt?

Question

I am trying to create a simple cross-reference from one page to another, e.g., in part of the document, it says, "see bears, p. 3." From the ConTeXt manual, p. 170, I was able to determine that a method for this is with \reference, in the place which is referenced to, and \at, in the place where the text refers to the place.

When I use \reference in my document, it is giving me an extra space, e.g.:

\starttext
    \section{This is a section}
        \reference[1]{This is a reference}
        This is some text.
    \section{This is another section}
        This is some more text.
\stoptext

This displays as:

1 This is a section

This is some text.

2 This is another section
This is some more text.

Notice, there is an added space between the first section and the text, while this extra space is not there.

• Am I creating references properly? Why are there so many different commands in the manual, but all seem to do the same thing, e.g. \ref, \at, \in, etc.?
• Why is \reference creating an extra space? How can I remove this extra space?
• Why do I need to place some text inside curly braces in \reference[]{Some text here}?

Answer 1

This is explained in the manual chapter 12.5 - Cross references

The command \in provides the number of a chapter, section, figure, table, etc. The command \at produces a pagenumber and \about produces a complete title. In the first two calls, the second argument is optional, and when given, is put after the number or title.

Example:

\startchapter [title=foo, reference=sec:foo]
\stopchapter

% Output: chapter 1
\in{chapter}[sec:foo]

% Output: page 42
\at{page}[sec:foo]

% Output: “Foo”
\about[sec:foo]

Note: \in and \at take optional arguments in braces, \about does not.

You can also refer to items in itemize lists:

\startitemize [n]
    \startitem [item:first]
        First
    \stopitem
    \startitem [item:second]
        Second
    \stopitem
\stopitemize

% Outputs: As in item 2.
As in \in{item}[item:second].

Answer 2

The usual way to create references in ConTeXt is:

\startsection[title={This is a section}, reference=sec:one]
....
\stopsection

or

\section[sec:one]{This is a section}

Although \reference is similar to LaTeX's \label, yet unlike LaTeX, you almost never use a manual \reference in ConTeXt. All commands provide some means of specifying a reference.