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, …).
See also general info on user scripts and information on developing user scripts.
You might wish to start by looking at the simple “Noise Effect” which is documented and explained here.
When the user wishes to produce data in a format provided by a specific export type user script, then KLatexFormula executes the user script in order to generate the correct format. KLatexFormula passes some options and sets some environment variables so that the script has all the required information to produce the requested output.
An export type user script is capable of producing one or more export formats, given an
input data type. These are specified in the scriptinfo.xml user script description.
The user script is invoked as follows:
user-script.py inputfile.ext --format fmt
The inputfile.ext depends on the input formats accepted by the script, and has a corresponding filename extension.
The script is expected to produce the format fmt, which is one among the internal format
names declared in the scriptinfo.xml file.
How the output is supplied by the script may be specified in the scriptinfo.xml. If
<has-stdout-output> is set to true, then the output is read from the script’s standard
output. The script may still produce debugging or logging messages on its standard error
output. If <has-stdout-output> is set to false, then the output is expected to be
provided in a file with the same base name as the input file, but with the corresponding
output format extension as declared in the format’s XML description (if several file
extensions are declared, the first one is expected to be used).
The script should exit with exit code zero to indicate success or non-zero to indicate failure.
Recall that for Python scripts, the library pyklfuserscript provides some helpful
utilities for user scripts (such as finding an executable and an arguments parser for
export types. Check the svg-dvisvgm, gif-convert and inkscapeformats scripts for
examples.
Beyond the XML definitions common to all user scripts, the scriptinfo.xml should contain a <klf-export-type>...</klf-export-type>
node with information about your export type. The info should be specified with the help
of the following XML elements:
<input-data-type exporter="...">...</input-data-type> a data type accepted by the
user script at its input. This must be a format name which can be produced using the
given exporter specified using the exporter attribute. If the exporter attribute is
not specified, then the KLFBackendFormatsExporter is used, which can provide the
following format names: PDF, PNG, SVG, PS, EPS, DVI, JPEG, and all image
formats natively supported by Qt. (Note: SVG is available only if ghostscript
supports SVG.)
The <input-data-type> tag may be repeated several times, in which cases
the first available format is generated and passed on to the user script.
The actual exporter and format used to generate the data to the user script
may be accessed via the KLF_INPUTDATA_*** environment
variables.
It is up to the user script to ensure that there are no cyclic dependencies. These could make the application hang due to infinite recursion.
<has-stdout-output>true|false</has-stdout-output> specifies whether the script will
produce output on its standard output, or whether it prefers to write output to a
file.
<mime-export-profiles-xml-file>[...].xml</mime-export-profiles-xml-file> specifies
an XML file containing export
profiles which can be used for copy/paste and drag/drop. These will be automatically
added to the export profiles menu.
You need to provide this if you want to be able to copy/paste or drag/drop using your export format.
the script should declare all available output formats it can produce with the following syntax:
<format name="internal-format-name">
<title>Format Display Name...</title>
<file-name-extension>ext</file-name-extension>
</format>
The <format> tag may be repeated as necessary to declare all possible output formats
of the user script.
Notes:
The internal-format-name may be anything which uniquely identifies the format
among the available formats of this specific user script. This is provided to the
userscript as argument to --format. See also exporters and export profiles.
The title is what will be displayed to the user, for example in the file save
dialog. The title should make clear how the format is produced, to disambiguate
with other user scripts or export types providing the same format (e.g.: "SVG
Vector Format (via dvisvgm)").
The ext file name extension is the filename extension to be used if the user
chooses this export format to save to file. The
<file-name-extension>...</file-name-extension> tag may be repeated several times
if there are several acceptable file name extensions for this data format.
Some useful information is carried by the following environment variables when the user script is run.
KLF_OUTPUT_WIDTH_PT: the width of the klatexformula-generated graphics, in
postscript points;
KLF_OUTPUT_HEIGHT_PT: the height of the klatexformula-generated graphics, in
postscript points;
KLF_OUTPUT_WIDTH_PX: the width of the klatexformula-generated image in
pixels — this is the defined as the width of the PNG output format;
KLF_OUTPUT_HEIGHT_PX: the height of the klatexformula-generated image in
pixels — this is the defined as the height of the PNG output format;
KLF_INPUTDATA_EXPORTER_NAME: the name of the exporter used to generate the
input data to the user script;
KLF_INPUTDATA_FORMAT: the format used to generate the input data to the user
script;
KLF_INPUT_***: In addition, all variables describing the KLF input (prefixed
with KLF_INPUT_ and listed here) are available.