0
# References and Cross-References
1

2
Comprehensive cross-reference system providing footnotes, endnotes, table of contents, index generation, and internal linking capabilities. The reference system enables sophisticated document navigation and citation management with automatic numbering and formatting.
3

4
## Capabilities
5

6
### Cross-References
7

8
Core cross-reference system for linking to document elements with automatic text generation and formatting.
9

10
```python { .api }
11
class Reference(InlineFlowable):
12
    """
13
    Cross-reference to document elements with automatic text generation.
14
    
15
    Creates links to sections, figures, tables, and other document elements
16
    with automatically generated reference text based on element properties.
17
    
18
    Parameters:
19
    - target: str or DocumentElement, reference target (ID or element)
20
    - reference_type: str, type of reference text to generate
21
    - style: Style, styling for the reference text
22
    - parent: parent element
23
    - source: source location information
24
    """
25
    def __init__(self, target, reference_type='reference', style=None, parent=None, source=None): ...
26
    
27
    @property
28
    def target_element(self): ...  # Referenced element
29
    @property
30
    def reference_text(self): ...  # Generated reference text
31

32
class ReferenceField(Field):
33
    """Field that displays reference information for target element."""
34

35
class ReferenceText(StyledText):
36
    """Styled text for reference display with formatting options."""
37

38
# Reference types
39
REFERENCE_TYPES = {
40
    'reference': 'Full reference with number and title',
41
    'number': 'Reference number only', 
42
    'title': 'Reference title only',
43
    'page': 'Page number only',
44
    'custom': 'Custom reference format'
45
}
46
```
47

48
### Reference Paragraphs
49

50
Specialized paragraph types for content that contains references and needs special formatting.
51

52
```python { .api }
53
class ReferencingParagraph(Paragraph):
54
    """
55
    Paragraph that can contain and properly format cross-references.
56
    
57
    Provides enhanced handling for paragraphs containing references,
58
    ensuring proper spacing, alignment, and formatting of linked content.
59
    
60
    Parameters:
61
    - content: str or list, paragraph content including references
62
    - id: str, unique identifier
63
    - style: ReferencingParagraphStyle, specialized styling
64
    - parent: parent element
65
    - source: source location information
66
    """
67
    def __init__(self, content, id=None, style=None, parent=None, source=None): ...
68

69
class ReferencingParagraphStyle(ParagraphStyle):
70
    """Style configuration for paragraphs containing references."""
71
    
72
    reference_format = Attribute(str)  # Reference formatting pattern
73
    reference_separator = Attribute(str)  # Separator between references
74
```
75

76
### Footnotes and Endnotes
77

78
Comprehensive note system for footnotes, endnotes, and marginal annotations with automatic numbering and placement.
79

80
```python { .api }
81
class Note(GroupedFlowables):
82
    """
83
    Footnote or endnote with automatic numbering and placement.
84
    
85
    Creates numbered notes that are automatically positioned at page
86
    bottom (footnotes) or document end (endnotes) with proper formatting.
87
    
88
    Parameters:
89
    - note_flowables: list of Flowable objects for note content
90
    - id: str, unique identifier
91
    - style: Style, note content styling
92
    - parent: parent element
93
    - source: source location information
94
    """
95
    def __init__(self, note_flowables, id=None, style=None, parent=None, source=None): ...
96
    
97
    @property
98
    def number(self): ...  # Note number
99
    @property
100
    def formatted_number(self): ...  # Formatted note number
101

102
class NoteMarkerBase(InlineFlowable):
103
    """Base class for note markers in text."""
104

105
class NoteMarkerByID(NoteMarkerBase):
106
    """
107
    Note marker referencing note by ID.
108
    
109
    Creates clickable marker in text that links to note content,
110
    automatically formatted with note number.
111
    
112
    Parameters:
113
    - note_id: str, ID of referenced note
114
    - style: NoteMarkerStyle, marker appearance
115
    - parent: parent element
116
    """
117
    def __init__(self, note_id, style=None, parent=None): ...
118

119
class NoteMarkerWithNote(NoteMarkerBase):
120
    """
121
    Note marker with embedded note content.
122
    
123
    Combines marker and note content in single element for
124
    automatic note creation and numbering.
125
    
126
    Parameters:
127
    - note: Note, note content to reference
128
    - style: NoteMarkerStyle, marker appearance
129
    - parent: parent element
130
    """
131
    def __init__(self, note, style=None, parent=None): ...
132

133
class NoteMarkerStyle(Style):
134
    """Style configuration for note markers including numbering format."""
135
    
136
    number_format = Attribute(NumberFormat)  # Marker number format
137
    position = Attribute(str)  # Marker position ('superscript', 'baseline')
138
```
139

140
### Document Fields
141

142
Dynamic field system for inserting document metadata, page numbers, and other variable content.
143

144
```python { .api }
145
class Field(InlineFlowable):
146
    """
147
    Dynamic field that displays document information.
148
    
149
    Inserts automatically updated content like page numbers, section titles,
150
    document metadata, and other variable information.
151
    
152
    Parameters:
153
    - field_type: str, type of field content
154
    - style: Style, field text styling
155
    - parent: parent element
156
    - source: source location information
157
    """
158
    def __init__(self, field_type, style=None, parent=None, source=None): ...
159
    
160
    @property
161
    def field_value(self): ...  # Current field value
162

163
# Predefined field types
164
PAGE_NUMBER = 'page_number'           # Current page number
165
NUMBER_OF_PAGES = 'number_of_pages'   # Total page count
166
SECTION_NUMBER = 'section_number'     # Current section number
167
SECTION_TITLE = 'section_title'       # Current section title  
168
DOCUMENT_TITLE = 'document_title'     # Document title
169
DOCUMENT_SUBTITLE = 'document_subtitle'  # Document subtitle
170
DOCUMENT_AUTHOR = 'document_author'   # Document author
171
CURRENT_DATE = 'current_date'         # Current date
172
```
173

174
### Table of Contents
175

176
Automatic table of contents generation with customizable formatting and navigation links.
177

178
```python { .api }
179
class TableOfContents(Section):
180
    """
181
    Automatically generated table of contents.
182
    
183
    Creates navigable table of contents with section titles, numbers,
184
    and page references automatically extracted from document structure.
185
    
186
    Parameters:
187
    - local: bool, include only local sections if True
188
    - id: str, unique identifier
189
    - style: TableOfContentsStyle, TOC formatting
190
    - parent: parent element
191
    - source: source location information
192
    """
193
    def __init__(self, local=False, id=None, style=None, parent=None, source=None): ...
194

195
class TableOfContentsSection(Section):
196
    """Section wrapper for table of contents with proper formatting."""
197

198
class TableOfContentsEntry(Paragraph):
199
    """
200
    Individual entry in table of contents.
201
    
202
    Represents single TOC line with section title, number, and page
203
    reference with proper indentation and formatting.
204
    
205
    Parameters:
206
    - section: Section, referenced section
207
    - level: int, nesting level for indentation
208
    - style: Style, entry formatting
209
    - parent: parent element
210
    """
211
    def __init__(self, section, level=1, style=None, parent=None): ...
212

213
class TableOfContentsStyle(Style):
214
    """Style configuration for table of contents including indentation and leaders."""
215
    
216
    indent_increment = Attribute(Dimension)  # Indentation per level
217
    leader_pattern = Attribute(str)  # Leader dots pattern
218
    show_page_numbers = Attribute(bool)  # Include page numbers
219
```
220

221
### Index Generation
222

223
Comprehensive index system with term marking, cross-references, and automatic alphabetical organization.
224

225
```python { .api }
226
class Index(Section):
227
    """
228
    Automatically generated alphabetical index.
229
    
230
    Creates alphabetical index from marked terms throughout document
231
    with page references and cross-references between related terms.
232
    
233
    Parameters:
234
    - id: str, unique identifier
235
    - style: IndexStyle, index formatting
236
    - parent: parent element
237
    - source: source location information
238
    """
239
    def __init__(self, id=None, style=None, parent=None, source=None): ...
240

241
class IndexSection(Section):
242
    """Section wrapper for document index with proper formatting."""
243

244
class IndexTerm:
245
    """
246
    Multi-level index term specification.
247
    
248
    Represents hierarchical index terms with primary, secondary,
249
    and tertiary levels for detailed index organization.
250
    
251
    Parameters:
252
    - *levels: str, term levels from primary to tertiary
253
    """
254
    def __new__(cls, *levels): ...
255
    
256
    @property
257
    def primary(self): ...    # Primary term
258
    @property
259
    def secondary(self): ...  # Secondary term (if any)
260
    @property
261
    def tertiary(self): ...   # Tertiary term (if any)
262

263
class IndexTarget(InlineFlowable):
264
    """
265
    Index target marker for term references.
266
    
267
    Marks location in text where index terms should reference,
268
    automatically generating page numbers and cross-references.
269
    
270
    Parameters:
271
    - index_terms: list of IndexTerm objects
272
    - parent: parent element
273
    """
274
    def __init__(self, index_terms, parent=None): ...
275

276
class InlineIndexTarget(IndexTarget):
277
    """Inline version of index target marker."""
278

279
class IndexLabel(Label):
280
    """Label for index entries with proper formatting."""
281

282
class IndexStyle(Style):
283
    """Style configuration for index including spacing and indentation."""
284
```
285

286
### Lists of Tables and Figures
287

288
Automatic generation of lists for tables, figures, and other captioned elements.
289

290
```python { .api }
291
class ListOfStyle(Style):
292
    """Base style for lists of figures, tables, etc."""
293
    
294
    entry_spacing = Attribute(Dimension)  # Spacing between entries
295
    indent_increment = Attribute(Dimension)  # Indentation increment
296
    show_page_numbers = Attribute(bool)  # Include page numbers
297

298
class ListOfTables(Section):
299
    """
300
    Automatically generated list of all tables in document.
301
    
302
    Creates section containing links to all tables with their
303
    captions and page numbers.
304
    """
305
    def __init__(self, id=None, style=None, parent=None, source=None): ...
306

307
class ListOfTablesSection(Section):
308
    """Section wrapper for list of tables."""
309
```
310

311
## Usage Examples
312

313
### Basic Cross-References
314

315
```python
316
from rinohtype.reference import Reference
317
from rinohtype.structure import Section, Heading
318
from rinohtype.paragraph import Paragraph
319

320
# Create sections with IDs for referencing
321
intro_section = Section([
322
    Heading("Introduction")
323
], id='intro')
324

325
methods_section = Section([
326
    Heading("Methods"),
327
    Paragraph([
328
        "As discussed in ",
329
        Reference('intro', reference_type='title'),
330
        ", this approach provides..."
331
    ])
332
], id='methods')
333

334
# Reference by number only
335
number_ref = Reference('intro', reference_type='number') 
336

337
# Reference with page number
338
page_ref = Reference('intro', reference_type='page')
339
```
340

341
### Footnotes and Endnotes
342

343
```python
344
from rinohtype.reference import Note, NoteMarkerWithNote, NoteMarkerByID
345
from rinohtype.text import SingleStyledText
346

347
# Create footnote with marker
348
footnote_content = Note([
349
    Paragraph("This is additional information provided in a footnote.")
350
])
351

352
# Paragraph with footnote
353
paragraph_with_note = Paragraph([
354
    SingleStyledText("This is important information"),
355
    NoteMarkerWithNote(footnote_content),
356
    SingleStyledText(" that requires clarification.")
357
])
358

359
# Reference existing note by ID
360
existing_note = Note([
361
    Paragraph("Shared footnote content.")
362
], id='shared-note')
363

364
another_paragraph = Paragraph([
365
    SingleStyledText("Another reference"),
366
    NoteMarkerByID('shared-note'),
367
    SingleStyledText(" to the same note.")
368
])
369
```
370

371
### Document Fields
372

373
```python
374
from rinohtype.reference import Field, PAGE_NUMBER, SECTION_TITLE, DOCUMENT_TITLE
375
from rinohtype.structure import Header, Footer
376

377
# Page header with document title
378
header = Header([
379
    Paragraph([Field(DOCUMENT_TITLE)])
380
])
381

382
# Page footer with page numbers
383
footer = Footer([
384
    Paragraph([
385
        SingleStyledText("Page "),
386
        Field(PAGE_NUMBER),
387
        SingleStyledText(" of "),
388
        Field(NUMBER_OF_PAGES)
389
    ])
390
])
391

392
# Section header with current section
393
section_header = Header([
394
    Paragraph([
395
        Field(SECTION_NUMBER),
396
        SingleStyledText(". "),
397
        Field(SECTION_TITLE)
398
    ])
399
])
400
```
401

402
### Table of Contents
403

404
```python
405
from rinohtype.reference import TableOfContents, TableOfContentsSection
406
from rinohtype.structure import Heading
407

408
# Create table of contents section
409
toc_section = TableOfContentsSection([
410
    Heading("Table of Contents"),
411
    TableOfContents()
412
])
413

414
# Local table of contents for current section only
415
local_toc = TableOfContents(local=True)
416
```
417

418
### Index Creation
419

420
```python
421
from rinohtype.reference import Index, IndexTerm, IndexTarget, InlineIndexTarget
422

423
# Mark terms for indexing
424
important_paragraph = Paragraph([
425
    SingleStyledText("The concept of "),
426
    InlineIndexTarget([IndexTerm("machine learning")]),
427
    SingleStyledText("machine learning"),
428
    SingleStyledText(" involves "),
429
    InlineIndexTarget([IndexTerm("artificial intelligence", "neural networks")]),
430
    SingleStyledText("neural networks"),
431
    SingleStyledText(".")
432
])
433

434
# Multi-level index terms
435
complex_term = IndexTerm("algorithms", "sorting", "quicksort")
436
index_marker = IndexTarget([complex_term])
437

438
# Generate index section
439
index_section = Section([
440
    Heading("Index"),
441
    Index()
442
])
443
```
444

445
### Advanced Reference Formatting
446

447
```python
448
from rinohtype.reference import ReferencingParagraph, ReferencingParagraphStyle
449
from rinohtype.style import Style
450
from rinohtype.dimension import PT
451

452
# Custom reference styling
453
ref_style = ReferencingParagraphStyle(
454
    reference_format='({number})',  # Parenthetical references
455
    reference_separator=', ',       # Comma-separated multiple refs
456
    font_size=11*PT
457
)
458

459
# Paragraph with multiple references
460
multi_ref_paragraph = ReferencingParagraph([
461
    SingleStyledText("Previous studies "),
462
    Reference('study1', reference_type='number'),
463
    SingleStyledText(", "),
464
    Reference('study2', reference_type='number'), 
465
    SingleStyledText(", "),
466
    Reference('study3', reference_type='number'),
467
    SingleStyledText(" have shown...")
468
], style=ref_style)
469
```
470

471
### Custom Field Types
472

473
```python
474
from rinohtype.reference import Field
475

476
class CustomField(Field):
477
    """Custom field with specific formatting."""
478
    
479
    def __init__(self, custom_type, format_string=None, **kwargs):
480
        super().__init__(custom_type, **kwargs)
481
        self.format_string = format_string
482
    
483
    @property
484
    def field_value(self):
485
        # Custom field value calculation
486
        base_value = super().field_value
487
        if self.format_string:
488
            return self.format_string.format(base_value)
489
        return base_value
490

491
# Use custom field
492
custom_date = CustomField('current_date', format_string='Generated on {0}')
493
```
494

495
### Reference Error Handling
496

497
```python
498
from rinohtype.reference import ReferenceError
499

500
def safe_reference_creation(target_id, ref_type='reference'):
501
    """Create reference with error handling."""
502
    try:
503
        return Reference(target_id, reference_type=ref_type)
504
    except ReferenceError as e:
505
        print(f"Reference error: {e}")
506
        # Return placeholder text
507
        return SingleStyledText(f"[Missing reference: {target_id}]")
508

509
def validate_references(document):
510
    """Validate all references in document."""
511
    missing_refs = []
512
    
513
    # Collect all reference targets
514
    for element in document.get_elements(Reference):
515
        try:
516
            target = element.target_element
517
            if target is None:
518
                missing_refs.append(element.target)
519
        except ReferenceError:
520
            missing_refs.append(element.target)
521
    
522
    if missing_refs:
523
        print(f"Missing reference targets: {missing_refs}")
524
    
525
    return missing_refs
526
```
527

528
### List Generation
529

530
```python
531
from rinohtype.reference import ListOfTables, ListOfStyle
532
from rinohtype.image import ListOfFigures
533

534
# Custom list styling
535
list_style = ListOfStyle(
536
    entry_spacing=6*PT,
537
    show_page_numbers=True,
538
    indent_increment=12*PT
539
)
540

541
# Create lists section
542
lists_section = Section([
543
    Heading("Lists"),
544
    
545
    Section([
546
        Heading("List of Figures"),
547
        ListOfFigures(style=list_style)
548
    ]),
549
    
550
    Section([
551
        Heading("List of Tables"), 
552
        ListOfTables(style=list_style)
553
    ])
554
])
555
```
556

557
### Conditional References
558

559
```python
560
from rinohtype.text import ConditionalMixedStyledText
561

562
def conditional_reference(target_id, condition_func):
563
    """Create reference that appears conditionally."""
564
    ref = Reference(target_id)
565
    empty = SingleStyledText("")
566
    
567
    return ConditionalMixedStyledText(
568
        condition=condition_func,
569
        true_text=ref,
570
        false_text=empty
571
    )
572

573
# Only show reference if target exists
574
safe_ref = conditional_reference('optional-section', 
575
                                lambda doc: doc.get_element('optional-section') is not None)
576
```