References notes and floats/Footnotes/Explanation

1. Purpose

This page explains the conceptual structure of notes in ConTeXt.

It does not aim to list every command or provide a complete step-by-step procedure. Instead, it explains why ConTeXt distinguishes:

• the note mark from the note entry;
• the note series from its typographical notation;
• the creation of a note from its placement;
• the logical identity of a note from its printed number;
• document-wide note collection from local note scopes;
• note structure from interaction, directionality, and parsing.

Understanding these distinctions makes complex note layouts easier to design, maintain, and diagnose.

This page presents a conceptual model of the note mechanism. It does not attempt to describe every internal implementation detail.

2. The structure of a note

2.1. Note mark and note entry

Every ordinary footnote connects two visible locations:

1. a note mark in the running text;
2. a note entry placed elsewhere.

In the simplest case:

\footnote{note text}

creates both at once.

Conceptually, however, the two elements remain distinct.

Element	Function
Note mark	Signals that supplementary information is associated with a point in the running text.
Note entry	Contains the supplementary information and is placed in a note area.

The mark belongs to the sentence, word, passage, line, or object being annotated.

The entry may be placed:

• at the bottom of the page;
• after a section or chapter;
• at the end of the document;
• in a margin;
• near a table, figure, or framed passage;
• in a separately placed block.

2.2. Why mark and entry can be separated

The command \footnote is convenient because it creates the mark and entry together.

More complex documents may need to create them separately:

\note[reference]

\setnotetext
  [footnote]
  [reference]
  {note text}

This separation is useful when:

• several marks refer to one entry;
• the note text must be registered later;
• nested or deferred-note situations require explicit control;
• a macro creates the mark and text in different stages;
• note data is imported from another structured source.

The separation is not an exceptional trick. It exposes a relation already present in every ordinary note.

For practical procedures, see:

• Separating a note mark from its text .

2.3. Several marks may refer to one entry

A named note may be called more than once:

\footnote[foot:shared]{note text}

...

\note[foot:shared]

This produces:

• one logical note;
• one note entry;
• several visible note marks;
• one stable internal reference.

The relation is therefore not always one mark to one entry.

one logical note
    |
    +--> several visible marks
    |
    +--> one visible entry

This is useful when the same explanation applies to several passages.

For detailed examples, see:

• Referring to a footnote more than once .

3. Series, counters, and references

3.1. A note series is an editorial category

ConTeXt does not require all notes to belong to one undifferentiated stream.

A document may define several note series:

\definenote[EdNote][footnote]
\definenote[TradNote][footnote]
\definenote[SourceNote][footnote]

Names such as EdNote, TradNote, and SourceNote are project-defined conventions.

Each series may represent a distinct editorial function.

Series	Possible editorial function
footnote	General commentary, clarification, or bibliography
EdNote	Editorial intervention
TradNote	Translator's explanation
SourceNote	Identification of a source or quotation

3.2. Independent counters

A note series normally maintains its own counter.

If ordinary footnotes use numbers and editorial notes use letters, the sequences may develop independently:

footnote:  1, 2, 3, ...
EdNote:    a, b, c, ...

Adding an editorial note does not normally advance the ordinary footnote counter.

This independence allows different series to be configured with different:

• number conversions;
• reset levels;
• placement policies;
• typographical forms;
• inclusion or exclusion rules.

The counter belongs to the organization of the series. Its printed form is a separate typographical choice.

3.3. Stable internal references and printed numbers

A note may receive a stable internal reference:

\footnote[foot:source]{note text}

Its printed number may later change because another note is inserted earlier in the document.

The reference foot:source remains unchanged.

Element	Example	Stability
Stable internal reference	foot:source	Intended to remain stable in the source
Printed number	3	May change when the document changes

4. Note series and notation

ConTeXt distinguishes a note series from the notation used to present its entries.

This distinction is reflected in two principal setup commands:

\setupnote[series][...]
\setupnotation[series][...]

4.1. The note-series layer

Conceptually, \setupnote configures properties of the note series, including its placement and composition.

In the documentation, it is used for settings such as:

• automatic or postponed placement;
• the body font used for note entries;
• paragraph or column composition;
• series-level setups.

4.2. The notation layer

Conceptually, \setupnotation configures the numbering and typographical presentation of note entries.

It is used for settings such as:

• number conversion;
• counter reset level;
• number position;
• width and distance around the number;
• entry alignment;
• interaction.

For exact syntax and representative keys, see:

• Configuring note series and notation .

4.3. Why the distinction matters

A series can retain the same editorial meaning while its:

• numbering;
• layout;
• placement;
• interaction settings;

change between different versions of a publication.

5. Creation, placement, and scope

5.1. Creation and placement are separate operations

By default, an ordinary footnote is created and placed automatically at the bottom of the page.

With:

\setupnote
  [footnote]
  [location=text]

the note is still created, but its entry is not placed automatically.

It must later be placed with:

\placefootnotes

For a custom series:

\placenotes[EdNote]

This reveals a fundamental distinction.

Operation	Meaning
Creation	The logical note, its mark, text, stable reference, and counter value are established.
Placement	The stored entry is inserted into a visible note block.

A note may therefore exist without yet being visible in its final location.

5.2. Postponed footnotes and endnotes

The setting location=text postpones entries from the footnote series until an explicit placement command is used.

Postponed footnotes may be placed:

• after a paragraph;
• after a section;
• after a chapter;
• at the end of a document.

They may therefore visually resemble chapter notes or endnotes.

They nevertheless remain entries of the footnote series unless a distinct endnote series is used.

For related procedures and distinctions, see:

• Placing footnotes at the end of a section or chapter ;
• Endnotes .

5.3. Local notes create a temporary scope

A local note context isolates the collection and placement of notes associated with a particular object or passage.

For example:

\startlocalfootnotes
  ...
  \placelocalfootnotes
\stoplocalfootnotes

A local note scope is useful in:

• tables;
• figures;
• captions;
• framed texts;
• independent examples.

Locality concerns the structural domain in which notes are collected and placed. It is not merely a different visual style.

5.4. Migration and locality are different mechanisms

Migration is the process by which material created inside a box or another restricted context is moved to a page-level area.

A note created inside a box may therefore migrate to the ordinary page footnote area.

A local note, by contrast, remains associated with the local scope and is placed explicitly there.

Mechanism	Result
Migration	A note originating inside a restricted context joins a page-level note area.
Local scope	A note remains attached to the table, figure, box, or other local structure.

The question is not only where the note command occurs, but where the note editorially belongs.

6. Presentation and output layers

6.1. Interaction adds navigation, not structure

Interactive PDF notes may add links between note marks and entries.

Interaction does not change:

• the logical identity of the note;
• its series;
• its counter;
• its editorial role;
• its placement policy.

It is an additional presentation and navigation layer.

A printed document contains the same note structure even though interactive links have no function on paper.

For a practical procedure, see:

• Creating interactive footnotes .

6.2. One source may produce several note configurations

Because note series are structurally distinct, one source can produce several outputs.

For example:

• a scholarly edition with all note layers;
• a reading edition without editorial notes;
• a translation edition with translator's notes only;
• a print edition without interactive links;
• a screen edition with interactive marks.

The source may use semantic commands:

\EdNote{...}
\TradNote{...}
\SourceNote{...}

Conditional wrappers or project settings can then determine which series are active in a particular output.

For a practical workflow, see:

• Producing annotated and unannotated versions .

6.3. Bidirectional notes coordinate several systems

In right-to-left or mixed-direction documents, note composition depends on several coordinated layers:

• font coverage;
• script shaping;
• paragraph direction;
• note-entry alignment;
• number direction;
• punctuation;
• note-series structure.

A failure in one layer may appear to be a failure in another.

For example:

• missing glyphs usually indicate a font-coverage problem;
• disconnected Arabic letters indicate a shaping problem;
• misplaced punctuation may indicate a direction problem;
• misplaced entries may indicate a placement or alignment problem.

For a detailed procedure, see:

• Typesetting notes in bidirectional documents .

6.4. Verbatim material reveals the importance of parsing

A footnote argument is read as ordinary TeX input.

True verbatim material requires a different parsing regime.

That is why a block such as:

\starttyping
...
\stoptyping

should not normally begin directly inside \footnote{...}.

The material should instead be prepared before the note argument is read, for example in a buffer.

This illustrates a broader distinction:

• note structure concerns logical relations;
• parsing concerns how source text is read;
• formatting concerns how the resulting material is displayed.

These layers must not be confused.

For practical examples, see:

• Including verbatim material in footnotes .

7. A conceptual model

The ConTeXt note mechanism can be represented conceptually as follows:

source passage
    |
    v
note command
    |
    +--> visible note mark
    |
    +--> logical note
            |
            +--> note series
            +--> stable internal reference
            +--> counter value
            +--> note text
                    |
                    +--> formatted by notation settings
                    |
                    +--> placed according to series settings
                            |
                            v
                       visible note entry

For postponed notes:

logical note
    |
    v
stored entry
    |
    v
explicit placement command
    |
    v
visible note block

For local notes:

local scope
    |
    +--> local marks
    +--> locally collected entries
    +--> local placement

These diagrams are conceptual. They show the principal relationships without attempting to reproduce the internal implementation.

8. Why complex note systems remain manageable

ConTeXt's note mechanism may initially appear more complex than a single footnote command.

The complexity comes from separating concerns that simple documents can safely combine:

• logical identity;
• numbering;
• mark creation;
• text registration;
• placement;
• formatting;
• scope;
• interaction;
• output selection.

This separation becomes valuable when producing:

• scholarly editions;
• multilingual books;
• critical apparatuses;
• textbooks;
• parallel texts;
• heavily annotated documents;
• several outputs from one source.

9. Common conceptual confusions

9.1. A note is not its printed number

The printed number may change. The stable internal reference identifies the note in the source.

9.2. A note series is not merely a visual style

A series represents an editorial category with its own configuration and normally its own counter.

9.3. Postponed notes are not suppressed notes

Their entries remain registered and must be placed later.

9.4. Postponed footnotes are not automatically a distinct endnote series

They may appear at the end of a structural division while still belonging to the footnote series.

9.5. Local notes are not ordinary notes in smaller type

They belong to a temporary structural scope associated with an object or passage.

9.6. Interaction is not the note mechanism itself

Interaction adds navigation to a note structure that already exists.

9.7. Direction is not alignment

Right-to-left processing and right alignment solve different typographical problems.

9.8. A valid command may still be applied at the wrong level

Some settings belong to the note series; others belong to notation, directionality, fonts, or interaction.

10. What this explanation has established

The ConTeXt note mechanism is built from coordinated but distinct layers:

1. a note mark signals supplementary material;
2. a note entry contains that material;
3. a note series expresses editorial function;
4. a counter determines sequence;
5. a stable internal reference identifies the logical note;
6. notation determines numerical and typographical presentation;
7. placement determines where the entry appears;
8. local scopes isolate note collection and placement structurally;
9. migration moves material from a restricted context to another area;
10. interaction adds navigation;
11. conditional mechanisms support selective output.

The central principle is that a footnote is a structured logical object whose mark, text, numbering, placement, and presentation can be controlled independently.

11. Related pages

• Learn the basic footnote workflow
• Solve specific note-related problems
• Consult the command and setting reference
• Consult the glossary of note terminology
• Understand endnotes
• Understand margin notes