User scripts of the klf-backend-engine category define an alternative workflow for
generating an equation image from input latex code, altering the default latex
workflow for generating various formats from the
original LaTeX code.
See also general info on user scripts.
This page describes how “klf-backend-engine” user scripts interact with the workflow, what they can influence, how they are called, and what meta-information they should provide.
The user script is executed in every case immediately after having formed the LaTeX source file (i.e., immediately after Point 1 here).
The user script may do anything it likes (it may even choose to ignore the provided latex source completely and generate its own with the information provided in the environment variables). In the end, it should generate one or more of the formats listed in here.
Klatexformula will attempt to produce all the other formats it would normally produce,
using whatever steps of the workflow are needed to produce them, unless the format has
been explicitly disabled (“skipped”) by the user script. Which formats are to be skipped
is specified in the user script’s meta-information provided in its scriptinfo.xml file
(see below).
Note: For example, if the user script doesn’t generate DVI, then the workflow will
(re-)run latex as usual unless the user script explicitly asks to skip the DVI format.
Note: If you would like to override only later steps (and not the latex → dvi
step), then chances are you should be writing a klf-export-type category script instead. Those scripts may generate
additional formats starting from any of the base generated formats. [Note to self: the
dvipng-backend script should probably have been a klf-export-type, in retrospective.]
The user script is called with a single argument, the latex file name.
After the user script has terminated, the output is read from output files which must have
been generated by the user script. The file names are those provided in the KLF_FN_*
environment variables. The user script must create the files with those
exact names, or klatexformula won’t be able to retrieve the user script output.
For instance, if the user script spits out PNG data, it should create a file whose full
name is the contents of the KLF_FN_PNG environment variable.
When running a user script, some input settings may become irrelevant. For instance, there is no use setting the “math mode”, “font”, or “preamble” when using the user script “Custom Template”. In such cases, the user script may specify which input widgets should be grayed out to the user. This is done via the scriptinfo XML information (see below).
A user script may require additional input. For instance, the “Custom Template” should provide a text field for the custom template to be input.
User scripts may provide a custom Qt Designer UI form, which it can declare in its XML scriptinfo meta-information (see below).
Those widgets in the UI form named INPUT_fieldname are recognized as input widgets;
their value will be retrieved and passed on to the user script. The input fields are
provided to the user script as KLF_ARG_fieldname environment variables.
What exactly is achieved by the script is determined by additional configuration in the
scriptinfo.xml file, specified inside the <klf-backend-engine>
... </klf-backend-engine> XML element:
<spits-out>...</spits-out> specifies the format(s) which the user script provides.
The contents of the XML tag should be a space-separated list of formats chosen
from the list of possible formats given in the latex workflow.
These are: latex, dvi, eps-raw, eps-bbox, eps-processed, png, pdf,
svg.
<skip-formats>...</skip-formats> (optional) specifies a list of formats which we
should simply not attempt to generate. For example, if you provide a user scripts
which directly generates PNG or PDF data, it is probably useless to try to generate a
DVI file. (And worse, if you don’t explicitly skip the DVI format, klatexformula will
(re-)run latex to generate it.)
The value of this XML element should be a space-separated list of formats which the
klatexformula backend should not attempt to generate. The possible formats are the
same as for <spits-out>...</spits-out>.
Additionally, you may use the syntax <spits-out
selector="all-except">...</spits-out>, in which case all formats except those
specified are skipped.
<disable-inputs>...</disable-inputs> (optional) Specifies a list of widget names
which should be disabled when this user script is selected.
This should be a space-separated list of any of the following widget names, which should be self-explanatory:
FG_COLORBG_COLORMATHMODEPREAMBLEFONTFONTSIZEDPIVECTORSCALEMARGINSAdditionally, you may use the following selectors as shorthands (selectors are case-insensitive):
<disable-inputs selector="ALL"></disable-inputs> — disables all widgets
<disable-inputs selector="ALL EXCEPT">X Y Z</disable-inputs> — disables all
widgets except those specified
<disable-inputs selector="ALL_INPUT">...</disable-inputs> — disables all widgets
which influence the latex “input”, namely FG_COLOR, BG_COLOR, MATHMODE,
PREAMBLE, FONT, and FONTSIZE. Additional widget names may be specified, in
which case they are disabled as well.
<disable-inputs selector="ALL_INPUT EXCEPT">X Y Z</disable-inputs> — disables all widgets
which influence the latex “input” (as above), except for those specified widgets X, Y, Z.
<input-form-ui>...</input-form-ui> (optional) specify a Qt Designer UI file to be
used as interface for the user to specify additional input to the user script. This
interface is displayed under the “Script” tab in expanded mode. is selected.
Controls in the UI file which represent settings should be given a name starting with
INPUT_. When the user script is run, all settings are provided to the user script
as environment variables named KLF_ARG_<name> where <name> is the
widget name without the INPUT_ prefix.
KLF_INPUT_LATEX — The latex input, as entered by the user in the main text editor of
the application
KLF_INPUT_MATHMODE — The math mode to use, as entered by user (should contain ... to
be replaced with LaTeX code)
KLF_INPUT_PREAMBLE — The preamble specified by the user
KLF_INPUT_FONTSIZE — The requested font size, or -1 if the user selected “default”.
KLF_INPUT_FG_COLOR_WEB — The requested foreground color, in web format #000000
KLF_INPUT_FG_COLOR_RGBA — The requested foreground color as rgba(R, G, B, A) with
values 0..255
KLF_INPUT_BG_COLOR_TRANSPARENT — Boolean value (0 or 1) indicating whether the
background should be transparent.
KLF_INPUT_BG_COLOR_WEB — The requested background color, in web format #000000
KLF_INPUT_BG_COLOR_RGBA — The requested background color as rgba(R, G, B, A) with
values 0..255
KLF_INPUT_DPI — The requested DPI resolution
KLF_INPUT_USERSCRIPT — The user script being run
KLF_INPUT_VECTORSCALE — The vector scaling factor requested by the user. This is size
ratio, not in percent (i.e., original size is 1.0). (Note: this environment variable
is not set in KLF 4.0.0, fixed in KLF 4.0.1)
KLF_INPUT_BYPASS_TEMPLATE — Whether in the input, the bypassTemplate flag was set.
This is never the case in the KLatexFormula application (but may be the case if you’re
using the libklfbackend library directly).
KLF_TEMPDIR — The temporary directory set in klatexformula’s settings.
Note: the path in which the workflow is carried out will be different, and should be a
subdirectory of KLF_TEMPDIR. See KLF_TEMPFNAME below.
KLF_LATEX — The path to latex
KLF_DVIPS — The path to dvips
KLF_GS — The path to gs
KLF_GS_VERSION — The version of gs to which KLF_GS points
KLF_GS_DEVICES — A list of available devices of gs pointed to by KLF_GS, formatted
as a comma-separated list
KLF_SETTINGS_BORDEROFFSET — The border offset settings, formatted as
1.23,1.23,1.23,1.23 pt (using pt units regardless of user selection), where the
dimensions correspond to top, right, bottom, and left border offset, respectively.
KLF_SETTINGS_OUTLINEFONTS — klatexformula’s setting of whether to outline fonts in EPS
(0 or 1)
KLF_SETTINGS_CALCEPSBOUNDINGBOX — klatexformula’s setting of whether to recalculate
the precise bounding box fonts in EPS (0 or 1)
KLF_SETTINGS_WANT_RAW — Whether the backend settings has the wantRaw flag set (0
or 1); user scripts are not expected to honor this
KLF_SETTINGS_WANT_PDF — Whether the backend settings has the wantPdf flag set (0
or 1); user scripts are not expected to honor this
KLF_SETTINGS_WANT_SVG — Whether the backend settings has the wantSvg flag set (0
or 1); user scripts are not expected to honor this
KLF_TEMPFNAME — The temporary file base name. Each of the KLF_FN_* variables are
just different suffixes appended to this base name.
KLF_FN_LATEX — The source tex file after formatting with the default template, including
the user’s preamble, math mode, color settings etc. (format name latex)
KLF_FN_DVI — File name for the DVI output (format name dvi)
KLF_FN_EPS_RAW — File name for the raw EPS output (format name eps-raw)
KLF_FN_EPS_BBOX — File name for the processed EPS output (format name eps-bbox)
(Note: this environment variable is not set in KLF 4.0.0, fixed in KLF 4.0.1)
KLF_FN_EPS_PROCESSED — File name for the processed EPS output (format name eps-processed)
KLF_FN_PNG — File name for the PNG output (format name png)
KLF_FN_PDF — File name for the PDF output (format name pdf)
KLF_FN_SVG — File name for the SVG output (format name svg)