A user script is a directory with an extension [...].klfuserscript. It should contain
at least two files: one named scriptinfo.xml, and the script itself.
The scriptinfo.xml file contains information about the user script. It specifies the
script name, its category, the file to execute, as well as meta-information such as a
description/author names/copyright. It may also be used to specify additional info which
depends on the script category.
The script category defines what it is useful for. Currently, there are two possible user
script categories: klf-backend-engine and klf-export-type.
User scripts which are globally installed are located in a directory userscripts under
KLatexFormula’s shared data directory, usually /usr/share/klatexformula/userscripts (or
on Mac, in the application bundle in klatexformula.app/Contents/Resources/userscripts).
You may also place user scripts under in the userscripts directory in your home config
directory $HOME/.klatexformula/userscripts.
The script is typically an interpreted script; the best support is provided for python
scripts.
KLatexFormula will attempt to identify the correct interpreter from the script’s filename
extension. The config entry in klatexformula.conf › [BackendSettings] ›
userscriptinterpreters contains a string of the form {py=/usr/bin/python;sh=/bin/bash}
with a mapping from filename extensions to interpreter paths. As a last resort, for the
py extension some standard paths are searched for a Python interpreter, while for the
extensions sh and rb we look for bash and ruby in the system $PATH.
The script file does not have to be interpreted and may also be a binary executable. Compiling an executable is however not ideal as it will not be portable (and it definitely requires more work).
The output of the script is collected in the “User Script Log”, which can be inspected in expanded mode → “Script” → “View user script log”
User scripts of the klf-backend-engine category define an alternative workflow for
generating an equation image from input latex code.
The way these user scripts work are documented on this separate page.
User scripts of the klf-export-type category define a new export format for processed
equations. They typically consist of converting one of the generated formats (PNG, EPS,
PDF, …) into further formats (e.g., GIF, EMF, …).
The way these user scritps work are documented on this separate page.
The scriptinfo.xml should have the following structure:
<?xml version="1.0"?>
<klfuserscript-info klf-compat-version="4">
<exe-script>...</exe-script>
<category>klf-export-type</category>
<name>...</name>
<author>...</author>
<version>...</version>
<license>...</license>
...
</klfuserscript-info>
The following tags are allowed and/or expected within the root klfuserscript-info
element:
<exe-script>...</exe-script> the actual script to run. Specify a file name relative
to the user script directory including extension.
<category>...</category> specifies the user script category. Currently this is
expected to be one of klf-backend-engine or klf-export-type.
<name>...</name> specifies the display name for this user script. This may be used
for example in a selection box displayed to the user.
<author>...</author>, <version>...</version>, <license>...</license> may be used
to specify meta-data for the script. The meta-data is displayed in the settings
dialog in the “user script settings”. The <author> tag may be repeated several
times if several authors are present.
<settings-form-ui>[...].ui</settings-form-ui> (optional) specify a Qt Designer UI
file to be used as interface for the user to specify the user script settings. This
interface is displayed in the settings dialog, under “Scripts”, when the given script
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_USCONFIG_<name> where <name> is the
widget name without the INPUT_ prefix.
The value is given as a string, encoded with klfSaveVariantToText() (see
src/klftools/klfdatautil.cpp).
<can-provide-default-settings>true|false</can-provide-default-settings> (optional)
specifies whether the script is capable of auto-detecting default values for the
settings.
See detecting default settings below.
an XML element with the same name as the script category, i.e. either
<klf-backend-engine> ... </klf-backend-engine> or <klf-export-type>
... </klf-export-type>, specifies any configuration which is specific to this
category (see below).
If the scriptinfo specifies
<can-provide-default-settings>true</can-provide-default-settings>, then the script is
capable of detecting default values for the script settings. This is useful, for example,
to search for a 3rd party program.
At klatexformula’s start-up, the user script will be executed with the argument
--query-default-settings. The script should output the default (possibly auto-detected)
configuration on its standard output. Two possibilities:
output may consist of lines of the form VARNAME=<value>. The <value> may
not have line breaks. Choose the XML variant if you need to specify values with
several lines or anything more special.
output may be given as XML. The output should start as a valid XML file, i.e. with
<?xml .... The root element node must be <klfuserscript-default-settings>. The
contents is parsed by klfLoadVariantFromMap() (see
src/klftools/klfdatautil.cpp): it is essentially a list of
<pair><key>...</key><value type="...">...</value></pair>, where the type is the Qt
metatype name and where the value is encoded with klfSaveVariantToText().
In each case, the settings with the given names are set to the given corresponding values.
The name for each setting is expected to correspond to a widget in the UI file (if given)
without the INPUT_ prefix.
For user scripts written in Python, some utilities are provided in the pyklfuserscript
package provided in the root user scripts directory.
The PYTHONPATH is automatically set to be able to load that package.