References and Cross-References

class Reference(InlineFlowable):
    """
    Cross-reference to document elements with automatic text generation.
    
    Creates links to sections, figures, tables, and other document elements
    with automatically generated reference text based on element properties.
    
    Parameters:
    - target: str or DocumentElement, reference target (ID or element)
    - reference_type: str, type of reference text to generate
    - style: Style, styling for the reference text
    - parent: parent element
    - source: source location information
    """
    def __init__(self, target, reference_type='reference', style=None, parent=None, source=None): ...
    
    @property
    def target_element(self): ...  # Referenced element
    @property
    def reference_text(self): ...  # Generated reference text

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

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

# Reference types
REFERENCE_TYPES = {
    'reference': 'Full reference with number and title',
    'number': 'Reference number only', 
    'title': 'Reference title only',
    'page': 'Page number only',
    'custom': 'Custom reference format'
}

class ReferencingParagraph(Paragraph):
    """
    Paragraph that can contain and properly format cross-references.
    
    Provides enhanced handling for paragraphs containing references,
    ensuring proper spacing, alignment, and formatting of linked content.
    
    Parameters:
    - content: str or list, paragraph content including references
    - id: str, unique identifier
    - style: ReferencingParagraphStyle, specialized styling
    - parent: parent element
    - source: source location information
    """
    def __init__(self, content, id=None, style=None, parent=None, source=None): ...

class ReferencingParagraphStyle(ParagraphStyle):
    """Style configuration for paragraphs containing references."""
    
    reference_format = Attribute(str)  # Reference formatting pattern
    reference_separator = Attribute(str)  # Separator between references

class Note(GroupedFlowables):
    """
    Footnote or endnote with automatic numbering and placement.
    
    Creates numbered notes that are automatically positioned at page
    bottom (footnotes) or document end (endnotes) with proper formatting.
    
    Parameters:
    - note_flowables: list of Flowable objects for note content
    - id: str, unique identifier
    - style: Style, note content styling
    - parent: parent element
    - source: source location information
    """
    def __init__(self, note_flowables, id=None, style=None, parent=None, source=None): ...
    
    @property
    def number(self): ...  # Note number
    @property
    def formatted_number(self): ...  # Formatted note number

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

class NoteMarkerByID(NoteMarkerBase):
    """
    Note marker referencing note by ID.
    
    Creates clickable marker in text that links to note content,
    automatically formatted with note number.
    
    Parameters:
    - note_id: str, ID of referenced note
    - style: NoteMarkerStyle, marker appearance
    - parent: parent element
    """
    def __init__(self, note_id, style=None, parent=None): ...

class NoteMarkerWithNote(NoteMarkerBase):
    """
    Note marker with embedded note content.
    
    Combines marker and note content in single element for
    automatic note creation and numbering.
    
    Parameters:
    - note: Note, note content to reference
    - style: NoteMarkerStyle, marker appearance
    - parent: parent element
    """
    def __init__(self, note, style=None, parent=None): ...

class NoteMarkerStyle(Style):
    """Style configuration for note markers including numbering format."""
    
    number_format = Attribute(NumberFormat)  # Marker number format
    position = Attribute(str)  # Marker position ('superscript', 'baseline')

class Field(InlineFlowable):
    """
    Dynamic field that displays document information.
    
    Inserts automatically updated content like page numbers, section titles,
    document metadata, and other variable information.
    
    Parameters:
    - field_type: str, type of field content
    - style: Style, field text styling
    - parent: parent element
    - source: source location information
    """
    def __init__(self, field_type, style=None, parent=None, source=None): ...
    
    @property
    def field_value(self): ...  # Current field value

# Predefined field types
PAGE_NUMBER = 'page_number'           # Current page number
NUMBER_OF_PAGES = 'number_of_pages'   # Total page count
SECTION_NUMBER = 'section_number'     # Current section number
SECTION_TITLE = 'section_title'       # Current section title  
DOCUMENT_TITLE = 'document_title'     # Document title
DOCUMENT_SUBTITLE = 'document_subtitle'  # Document subtitle
DOCUMENT_AUTHOR = 'document_author'   # Document author
CURRENT_DATE = 'current_date'         # Current date

class TableOfContents(Section):
    """
    Automatically generated table of contents.
    
    Creates navigable table of contents with section titles, numbers,
    and page references automatically extracted from document structure.
    
    Parameters:
    - local: bool, include only local sections if True
    - id: str, unique identifier
    - style: TableOfContentsStyle, TOC formatting
    - parent: parent element
    - source: source location information
    """
    def __init__(self, local=False, id=None, style=None, parent=None, source=None): ...

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

class TableOfContentsEntry(Paragraph):
    """
    Individual entry in table of contents.
    
    Represents single TOC line with section title, number, and page
    reference with proper indentation and formatting.
    
    Parameters:
    - section: Section, referenced section
    - level: int, nesting level for indentation
    - style: Style, entry formatting
    - parent: parent element
    """
    def __init__(self, section, level=1, style=None, parent=None): ...

class TableOfContentsStyle(Style):
    """Style configuration for table of contents including indentation and leaders."""
    
    indent_increment = Attribute(Dimension)  # Indentation per level
    leader_pattern = Attribute(str)  # Leader dots pattern
    show_page_numbers = Attribute(bool)  # Include page numbers

class Index(Section):
    """
    Automatically generated alphabetical index.
    
    Creates alphabetical index from marked terms throughout document
    with page references and cross-references between related terms.
    
    Parameters:
    - id: str, unique identifier
    - style: IndexStyle, index formatting
    - parent: parent element
    - source: source location information
    """
    def __init__(self, id=None, style=None, parent=None, source=None): ...

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

class IndexTerm:
    """
    Multi-level index term specification.
    
    Represents hierarchical index terms with primary, secondary,
    and tertiary levels for detailed index organization.
    
    Parameters:
    - *levels: str, term levels from primary to tertiary
    """
    def __new__(cls, *levels): ...
    
    @property
    def primary(self): ...    # Primary term
    @property
    def secondary(self): ...  # Secondary term (if any)
    @property
    def tertiary(self): ...   # Tertiary term (if any)

class IndexTarget(InlineFlowable):
    """
    Index target marker for term references.
    
    Marks location in text where index terms should reference,
    automatically generating page numbers and cross-references.
    
    Parameters:
    - index_terms: list of IndexTerm objects
    - parent: parent element
    """
    def __init__(self, index_terms, parent=None): ...

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

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

class IndexStyle(Style):
    """Style configuration for index including spacing and indentation."""

class ListOfStyle(Style):
    """Base style for lists of figures, tables, etc."""
    
    entry_spacing = Attribute(Dimension)  # Spacing between entries
    indent_increment = Attribute(Dimension)  # Indentation increment
    show_page_numbers = Attribute(bool)  # Include page numbers

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

class ListOfTablesSection(Section):
    """Section wrapper for list of tables."""

from rinohtype.reference import Reference
from rinohtype.structure import Section, Heading
from rinohtype.paragraph import Paragraph

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

methods_section = Section([
    Heading("Methods"),
    Paragraph([
        "As discussed in ",
        Reference('intro', reference_type='title'),
        ", this approach provides..."
    ])
], id='methods')

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

# Reference with page number
page_ref = Reference('intro', reference_type='page')

from rinohtype.reference import Note, NoteMarkerWithNote, NoteMarkerByID
from rinohtype.text import SingleStyledText

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

# Paragraph with footnote
paragraph_with_note = Paragraph([
    SingleStyledText("This is important information"),
    NoteMarkerWithNote(footnote_content),
    SingleStyledText(" that requires clarification.")
])

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

another_paragraph = Paragraph([
    SingleStyledText("Another reference"),
    NoteMarkerByID('shared-note'),
    SingleStyledText(" to the same note.")
])

from rinohtype.reference import Field, PAGE_NUMBER, SECTION_TITLE, DOCUMENT_TITLE
from rinohtype.structure import Header, Footer

# Page header with document title
header = Header([
    Paragraph([Field(DOCUMENT_TITLE)])
])

# Page footer with page numbers
footer = Footer([
    Paragraph([
        SingleStyledText("Page "),
        Field(PAGE_NUMBER),
        SingleStyledText(" of "),
        Field(NUMBER_OF_PAGES)
    ])
])

# Section header with current section
section_header = Header([
    Paragraph([
        Field(SECTION_NUMBER),
        SingleStyledText(". "),
        Field(SECTION_TITLE)
    ])
])

from rinohtype.reference import TableOfContents, TableOfContentsSection
from rinohtype.structure import Heading

# Create table of contents section
toc_section = TableOfContentsSection([
    Heading("Table of Contents"),
    TableOfContents()
])

# Local table of contents for current section only
local_toc = TableOfContents(local=True)

from rinohtype.reference import Index, IndexTerm, IndexTarget, InlineIndexTarget

# Mark terms for indexing
important_paragraph = Paragraph([
    SingleStyledText("The concept of "),
    InlineIndexTarget([IndexTerm("machine learning")]),
    SingleStyledText("machine learning"),
    SingleStyledText(" involves "),
    InlineIndexTarget([IndexTerm("artificial intelligence", "neural networks")]),
    SingleStyledText("neural networks"),
    SingleStyledText(".")
])

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

# Generate index section
index_section = Section([
    Heading("Index"),
    Index()
])

from rinohtype.reference import ReferencingParagraph, ReferencingParagraphStyle
from rinohtype.style import Style
from rinohtype.dimension import PT

# Custom reference styling
ref_style = ReferencingParagraphStyle(
    reference_format='({number})',  # Parenthetical references
    reference_separator=', ',       # Comma-separated multiple refs
    font_size=11*PT
)

# Paragraph with multiple references
multi_ref_paragraph = ReferencingParagraph([
    SingleStyledText("Previous studies "),
    Reference('study1', reference_type='number'),
    SingleStyledText(", "),
    Reference('study2', reference_type='number'), 
    SingleStyledText(", "),
    Reference('study3', reference_type='number'),
    SingleStyledText(" have shown...")
], style=ref_style)

from rinohtype.reference import Field

class CustomField(Field):
    """Custom field with specific formatting."""
    
    def __init__(self, custom_type, format_string=None, **kwargs):
        super().__init__(custom_type, **kwargs)
        self.format_string = format_string
    
    @property
    def field_value(self):
        # Custom field value calculation
        base_value = super().field_value
        if self.format_string:
            return self.format_string.format(base_value)
        return base_value

# Use custom field
custom_date = CustomField('current_date', format_string='Generated on {0}')

from rinohtype.reference import ReferenceError

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

def validate_references(document):
    """Validate all references in document."""
    missing_refs = []
    
    # Collect all reference targets
    for element in document.get_elements(Reference):
        try:
            target = element.target_element
            if target is None:
                missing_refs.append(element.target)
        except ReferenceError:
            missing_refs.append(element.target)
    
    if missing_refs:
        print(f"Missing reference targets: {missing_refs}")
    
    return missing_refs

from rinohtype.reference import ListOfTables, ListOfStyle
from rinohtype.image import ListOfFigures

# Custom list styling
list_style = ListOfStyle(
    entry_spacing=6*PT,
    show_page_numbers=True,
    indent_increment=12*PT
)

# Create lists section
lists_section = Section([
    Heading("Lists"),
    
    Section([
        Heading("List of Figures"),
        ListOfFigures(style=list_style)
    ]),
    
    Section([
        Heading("List of Tables"), 
        ListOfTables(style=list_style)
    ])
])

from rinohtype.text import ConditionalMixedStyledText

def conditional_reference(target_id, condition_func):
    """Create reference that appears conditionally."""
    ref = Reference(target_id)
    empty = SingleStyledText("")
    
    return ConditionalMixedStyledText(
        condition=condition_func,
        true_text=ref,
        false_text=empty
    )

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