FLM Feature flm.feature.refs

Provides cross-referencing support via \ref and \hyperref macros, including label registration, counter-based reference formatting, and resolution through external ref resolvers.

class flm.feature.refs.ReferenceableInfo(kind, formatted_ref_flm_text, labels)

Bases: object

Arguments:

• kind - The type of the thing being referenced (e.g. ‘heading’, ‘defterm’)

• formatted_ref_flm_text - should be a string (standalone FLM code) or an FLMFragment instance

• labels - a list of pairs (ref_type, ref_label) to attach to this referenceable object.

get_target_id()

Derive a safe HTML-anchor id from the first label.

Uses get_safe_target_id() on the first (ref_type, ref_label) pair in labels.

Returns:

A string suitable for use as an HTML id attribute, or None if labels is empty.

asdict()

Return a dictionary of this object’s public fields.

The returned dict has keys 'kind', 'formatted_ref_flm_text', and 'labels'.

class flm.feature.refs.RefInstance(ref_type, ref_label, formatted_ref_flm_text, target_href, counter_value, counter_numprefix, counter_formatter_id)

Bases: object

A resolved reference target, holding all information needed to render a cross-reference link.

asdict()

flm.feature.refs.get_safe_target_id(ref_type, ref_label)

Build an HTML-safe anchor id from a reference type and label.

Characters outside [a-zA-Z0-9-] are escaped as _<hex>X. The resulting string has the form <safe_type>-<safe_label>.

Parameters:

• ref_type – The reference type prefix string.

• ref_label – The reference label string.

Returns:

A string safe for use as an HTML id attribute.

class flm.feature.refs.FeatureRefsRenderManager(feature_document_manager, render_context, **kwargs)

Bases: FeatureRenderManagerBase

initialize(add_external_ref_resolvers: Sequence[Any] | None = None)

register_reference_referenceable(*, node, referenceable_info)

register_counter_formatter(*, counter_formatter_id=None, counter_formatter)

register_reference_step_counter(*, node, counter_iface, ref_type=None, ref_label=None, target_href_fn=None, counter_with_prefix=True, counter_prefix_variant=None, counter_with_delimiters=True)

register_reference(ref_type, ref_label, *, node, formatted_ref_flm_text, target_href, counter_value=None, counter_numprefix=None, counter_formatter_id=None)

Doc todo……..

If you call this method a second time on the same render context with the same node instance and the same (ref_type, ref_label), then the additional arguments are ignored and the earlier registered reference refinstance is returned instead.

formatted_ref_flm_text is FLM code given as a string or as a FLMFragment instance.

counter_value can be a ValueWithSubNums instance! …….

get_ref(ref_type, ref_label, resource_info)

render_ref(ref_type, ref_label, display_content_flm, resource_info, *, counter_prefix_variant=None, counter_with_prefix=True, counter_with_delimiters=True)

render_ref_instance(ref_instance, display_content_flm, *, counter_prefix_variant=None, counter_with_prefix=True, counter_with_delimiters=True)

ref_many_use_flm_hyperref = True

render_ref_many(ref_type_label_list, resource_info, *, counter_prefix_variant=None, counter_with_delimiters=True, counter_with_prefix=True)

class flm.feature.refs.RefMacro(macroname, *, ref_type='ref', command_arguments=('ref_label', 'display_text'), counter_prefix_variant=None)

Bases: FLMMacroSpecBase

delayed_render: bool | Callable[[LatexNode, TypeRenderContext], bool] = True

Whether this node needs to be rendered at the delayed rendering stage, i.e., after a first pass through the document. This is the case, for instance, for \ref commands etc. for which the entire document needs to have been traversed at least once beforehand. See the delayed render mechanism in the documentation for the flmdocument.FLMDocument class.

Set to True or False to determine whether or not the node needs a delayed render. Set to a callable func(node, render_context) -> bool to compute at render time whether the node should be delayed or not.

postprocess_parsed_node(node)

prepare_delayed_render(node, render_context)

render(node, render_context)

recompose_pure_latex(node, recomposer, **kwargs)

class flm.feature.refs.FeatureRefs(external_ref_resolvers: Sequence[Any] | None = None, allow_unresolved_refs: bool | TypeAllowUnresolvedRefsDef = False)

Bases: Feature

Feature plugin for labels and cross-references. Registers \ref and \hyperref macros, manages reference resolution within a document, and supports external ref resolvers for cross-document links. Optionally allows unresolved references to render gracefully instead of raising errors.

feature_name: str | None = 'refs'

A name that should uniquely identify this feature.

feature_title: str | None = 'Labels and cross-references'

Descriptive name or title for this feature.

RenderManager

alias of FeatureRefsRenderManager

set_external_ref_resolvers(external_ref_resolvers)

add_external_ref_resolver(external_ref_resolver)

add_latex_context_definitions()

RefMacroCls

alias of RefMacro

flm.feature.refs.FeatureClass = <class 'flm.feature.refs.FeatureRefs'>

Feature plugin for labels and cross-references. Registers \ref and \hyperref macros, manages reference resolution within a document, and supports external ref resolvers for cross-document links. Optionally allows unresolved references to render gracefully instead of raising errors.