FLM content compiling and rendering

Provides an interface to the python-based FLM library. The library is transpiled to Javascript using Transcrypt and some important entry points are exposed in the modules described here.

The python-transpiled interface

This part of the ZooDb library incorporates the FLM python sources transpiled into JavaScript using Transcrypt. While this detail shouldn’t matter for most uses, there are some important differences to keep in mind:

• You can’t use JavaScript class (prototype) inheritance with the python-based classes. (Callbacks won’t work, the parent class won’t call the child method, etc.) If you really need to subclass one of the classes from python’s interface (or further derived classes like ZooFLMEnvironment()), you need to do it the Transcrypt way.

• To pass keyword arguments, use the syntax function(arg1, arg2, $$kw( { keyword_arg1: ..., keyword_arg2: ... } )). The $kw(...) argument should be the last argument in the call.

• You cannot use the JS syntax x instanceof y with python-transcrypted classes. Instead, you can import the isinstance() utility to check instances the python way, isinstance(x, y). To check whether an object is a FLM fragment instance, use is_flm_fragment().

• You can convert objects to some representative string using the repr() function.

The relevant functions can be imported as follows:

import {
    $$kw, repr, __class__, __super__, __get__, isinstance
} from '@phfaist/zoodb/zooflm';

• explain how to create subclasses……….

FLM environment

import {
    ZooFLMResourceInfo,
    FeatureZooGraphicsCollection,

    ZooFLMEnvironment,
    zooflm_default_options,

    is_flm_fragment,

    RefResolver,
    CitationsProvider,

    // expose FLM classes
    FLMParsingState, // flm.flmenvironment.FLMParsingState
    ParsingStateDelta, // pylatexenc.latexnodes.ParsingStateDelta
    FLMParsingStateDeltaSetBlockLevel,
    SectionCommandInfo, // flm.feature.headings.FeatureHeadings.SectionCommandInfo
    EndnoteCategory, // flm.feature.endnotes.EndnoteCategory
    ReferenceableInfo, // flm.feature.refs.ReferenceableInfo
    RefInstance, // flm.feature.refs.RefInstance
    FloatType, // flm.feature.floats.FloatType
    GraphicsResource, // flm.feature.graphics.GraphicsResource

} from '@phfaist/zoodb';

class ZooFLMEnvironment(options)

The ZooFLMEnvironment class is the main FLM environment class in the context of the ZooDb library. Consider using the “standard” zoodb interface to create an environment instance, as this is likely to be simpler and more features will be handled under the hood (see Setting up a “Standard” ZooDb).

class FeatureZooGraphicsCollection()

Implements a graphics resource provider feature for FLM, enabling the use of \includegraphics{}.

The graphics resources must have been detected (e.g., using a ZooFLMScanner(), perhaps handled via a ZooFLMProcessor()), and the relevant graphics resource objects must have been compiled/fetched (see flm.feature.graphics.GraphicsResource). You then set those graphics resource instances here to make them visible to the FLM renderers.

You may set the src_url_resolver property to a function/lambda with signature callback(graphics_resource, render_context) and returning a URL specifying where the graphics resource should be linked to in the rendered output. (This property is set e.g. in use_flm_environment().)

FeatureZooGraphicsCollection.add_graphics(source_path, graphics_resource)

Register the given graphics_resource object associated with the given source_path.

FeatureZooGraphicsCollection.set_collection(collection)

Combines multiple calls to add_graphics(). The collection is an array of pairs [source_path, graphics_resource]. The add_graphics() method will be called for each pair.

class ZooFLMResourceInfo()

Store information about which source file an FLM fragment was encountered in. Useful to find resources (eg. graphics files) with relative paths as well as to track errors. Objects of this type will be set in the resource_info fields of FLM fragments.

ZooFLMResourceInfo.object_type

ZooFLMResourceInfo.object_id

ZooFLMResourceInfo.source_path

ZooFLMResourceInfo.ZooFLMResourceInfo

is_flm_fragment(obj)

Test whether or not obj is an instance of an FLM fragment.

We expose this function because the standard JS inheritance test instanceof does not work for Python/Transcrypt-based classes. This strategy avoids having to expose both “isinstance” and “FLMFragment”. We thus avoid having to use Transcrypt interface tools to check if an object is a FLM fragment instance.

zooflm_default_options(footnote_counter_formatter)

Return a default set of options for an FLM environment.

class RefResolver()

Manager for cross-references.

Doc……….. & doc members…….!

RefResolver.target_href_resolver

You can set this attribute to a custom function that will be called when get_ref() is called to override the target href URL of the returned reference isntance. The value of this attribute should be a function with signature callback(ref_instance, render_context) and should return a string, the new URL to use for the target_href attribute of the returned RefInstance().

RefResolver.RefResolver

class CitationsProvider()

Simple citations provider (for flm interface) that looks up a citation in a given citation database. A convenient way to set up the database is to use a CitationManager().

Doc………..

CitationsProvider.CitationsProvider

CitationsProvider.set_citations(iterable)

Equivalent to calling clear_citations() followed by update_citations(iterable).

CitationsProvider.update_citations(iterable)

Add the given citations to the database, updating any existing citations with the coinciding prefix/key.

The iterable should be a list or iterable of objects of the form {cite_prefix:..., cite_key:..., citation_text:....}.

Rendering content

import {
    ZooHtmlFragmentRenderer, ZooTextFragmentRenderer,
    html_fragmentrenderer_get_style_information,
    render_html_standalone, render_text_standalone
} from '@phfaist/zoodb/zooflm';

class ZooHtmlFragmentRenderer()

Subclass of FLM’s flm.fragmentrenderer.html.HtmlRenderer with some options tweaked.

html_fragmentrenderer_get_style_information(fragment_renderer)

Helper to get the default CSS definitions that is necessary in order to display HTML-rendered FLM content.

Returns a dictionary with the keys ‘css_global’, ‘css_content’, ‘js’, and ‘body_end_js_scripts’, set to corresponding reasonable definitions and that can be used in an HTML template.

class ZooTextFragmentRenderer()

Subclass of FLM’s flm.fragmentrenderer.text.TextRenderer with some options tweaked.

render_html_standalone(fragment)

Utility to render a standalone fragment to HTML. No document instance or render context is required. This function will create a ZooHtmlFragmentRenderer() instance under the hood.

render_text_standalone(fragment)

Utility to render a standalone fragment to HTML. No document instance or render context is required. This function will create a ZooTextFragmentRenderer() instance under the hood.

Scanning fragments

import {
    ZooFLMScanner, visitor_scan_object, visitor_scan_zoo,
} from '@phfaist/zoodb/zooflm/scanner';

class ZooFLMScanner()

Visitor object that registers any encountered definitions of referenceable things (labels), references to external resources, and bibliographic citations.

Interface-wise, this class can be thought of as extending pylatexenc.latexnodes.nodes.LatexNodesVisitor.

ZooFLMScanner.ZooFLMScanner

visitor_scan_object(visitor, obj, schema, what)

Run a ZooFLMScanner() object on all FLM fields of a given object

Arguments:

• visitor – the ZooFLMScanner() object instance

• obj – the object with the data fields; it should conform to the given schema

• schema – the object schema, accessible for instance in a ZooDb object instance as zoodb_instance.schema(object_type)

• what – brief label/description of object this is, only used for debug messages

visitor_scan_zoo(visitor, zoodbdata, options)

Run a ZooFLMScanner() object on all FLM fields of a zoo instance.

The (optional) options argument is of the form { object_types: ..., }. The option object_types is an array of object types to which the scanner will be applied; if false or null then all existing object types are used.

Arguments:

• visitor – the ZooFLMScanner() object instance

• zoodbdata – the ZooDb instance or database content. Schemas and objects for a given object_type are accessed as .schemas[object_type] and .objects[object_type].

• options – an object, see above

Compiling citations

import {
    CitationCompiler, install_csl_flm_output_format,
} from '@phfaist/zoodb/zooflm/citationcompiler';

class CitationCompiler()

Format citations into FLM code using a citation manager.

Options:

• citation_manager, locales, csl_style, add_cite_links, output_format, flm_compile_fragments, flm_environment, format_link_text, - ….

• cache_fs - a ‘fs’-compatible module object providing filesystem access for the cache.

• cache_file - the filesystem path where we should store a cache of the compiled citations.

• cache_entry_duration_ms - Specify for how long (in milliseconds) to keep entries in the cache.

CitationCompiler.CitationCompiler

CitationCompiler.compile_citations(compile_citations)

The argument compile_citations is a list of citation keys to compile. If set to non-null, we’ll only compile these citations and not all the citations of the database. An empty list signifies to compile nothing. Each list element should be an object that provides the keys ‘cite_prefix’ and ‘cite_key’. (E.g., as returned by ZooFLMScanner() via scanner.get_encountered(‘citations’))

CitationCompiler.get_compiled_citation(cite_prefix, cite_key)

Retrieve the citation text associated with the given cite_prefix:cite_key.

CitationCompiler.has_compiled_citation(cite_prefix, cite_key)

Return true if we have a compiled citation that is associated with the given cite_prefix:cite_key, and false otherwise.

CitationCompiler.load_cache()

Load citation information from the cache file. Does nothing if the cache file does not exist. This method is automatically called by the constructor.

CitationCompiler.save_cache()

Save the current citation information database to the cache file. Automatically done after compiling citations.

install_csl_flm_output_format(zooflmenviron)

Extend the global CSL object (the citation formatter library) to enable FLM code output.

If you use the ZooFLMProcessor() (in most cases you should), then this function is called automatically and you shouldn’t worry about it.