Output Export Profiles

An important functionality of KLatexFormula is its ability to provide the rendered equation in a variety of different formats for copying and pasting or dragging and dropping into other applications.

By default, KLatexFormula provides a selection of common formats in its default data format list; however, some applications can be quite picky on how and in which form the data is provided. For instance, vector formats typically render better than a PNG image, but an application may give precedence to pasting PNG over PDF. In those cases, it is possible to instruct KLatexFormula to only provide PDF data. Furthermore, different applications may not always use the same name for the same data format, not to mention wild differences in the schemes used between Linux/X11, Windows and Mac OS X platforms.

Exporters, Formats and Export Profiles

KLatexFormula solves this issue with a powerful and flexible export profile system, involving the following components:

An exporter (or export type) is capable of providing the LaTeX equation in one or more data formats.

The formats provided in KLatexFormula’s save dialog reflect (essentially) the available exporters. An exporter is furthermore capable of suggesting a file name extension to use with the corresponding data type.
a format refers to a data type, such as PNG data, PDF data, etc. Formats of a given exporter are identified by a name which is unique within the exporter.
a MIME type, Windows format or Mac flavor (or UTI) refers to a name which conventionally identifies a format for a given operating system. For example, the pdf format is usually identified on Linux/X11 systems with the MIME type application/pdf.
an export profile is a list of combinations of an exporter, a format, and one or more MIME types, Windows formats and/or Mac flavors. The role of an export profile is to define which combination of data formats are provided by KLatexFormula when the equation is copied or dragged, and which system names these data formats are advertized as.

Formats are usually grouped into exporters by common generation processes. For example, all formats supported directly by the KLatexFormula backend are grouped in one exporter. Or, an exporter may invoke a 3rd-party tool and may output to several formats that the 3rd-party tool can export as. The same format may be provided by different exporters. For example, SVG may be generated directly by gs (for some gs versions and/or configurations) or via dvisvgm.

Available Exporters

The available built-in exporters are defined in src/klfexporter_p.h as classes deriving from KLFExporter. Custom exporters may be defined using user scripts.

The built-in exporters are:

KLFBackendFormatsExporter is capable of providing all formats the KLFBackend can handle.

Available formats: PDF, PNG, SVG, PS, EPS, DVI, JPEG, and all image formats natively supported by Qt.
KLFTexExporter is capable of exporting a (La)TeX fragment with the equation by itself, possibly along with TeX comments which allows the data to be read back in KLatexFormula.

Available formats: tex-with-klf-metainfo, tex (the former is (La)TeX code with meta information as TeX comments, while the latter is just the (La)TeX code)
KLFOpenOfficeDrawExporter can generate OpenOffice.org Drawing (ODG) data.

Available formats: odg
KLFHtmlDataExporter provides an HTML fragment with an <img> tag containing the image data inline.

Available formats: html
KLFTempFileUriExporter writes one of the backend formats to a temporary file, and provides the URL to that file. This is useful for some applications which, for example, can’t directly paste PDF data but can paste the image if the path to a temporary file is provided (typically as MIME type text/uri-list).

Available formats: the same as for KLFBackendFormatsExporter. These formats are not available for saving to file (it doesn’t make sense to save a temporary file name into a file!!).

User script defined export formats are given the name UserScript:user-script-base-name, for example, UserScript:svg-dvisvgm.

Export Profiles XML Definitions

All export profiles are defined with the help XML files. The XML files reside under directories called conf/export_mime_profiles.d which are searched for:

in the shared data directory (e.g., /usr/share/klatexformula/conf/export_mime_profiles.d/);
under the user’s .klatexformula directory ($HOME/.klatexformula/conf/export_mime_profiles.d/).

In addition, export type user scripts may specify an XML file with additional export profile definitions in their script meta-information.

All the discovered export profiles are displayed in the export profile menu, which allows the user to decide which export profile to use when copying or dragging a rendered equation.

KLatexFormula’s basic export types are bundled with the application; they can be found in the source distribution in the directory src/conf/export_mime_profiles.d/. It is a good place to start if you’d like some examples.

XML Syntax

Each XML file should have the following basic structure:

<?xml version='1.0' encoding='UTF-8'?>
<export-profile-list version="4.0">
  <profile name="...">
    <description>...</description>
    <export-type exporter="..." format="...">
      ...
    </export-type>
    [...]
  </profile>
  [...]
</export-profile-list>

The root XML element should be export-profile-list and should specify the compatibility version (currently 4.0).

The contents of the <export-profile-list> is a list of profiles, each specified with a <profile> tag.

The <profile> tag requires a mandatory name="..." attribute, setting an internal name of the export profile. The contents of the <profile> tag is:

a <description> tag which specifies the human-readable name for this export profile, which is e.g. displayed in the export profile menu;
any number of <export-type> specifications, specifying all the export types to include in this export profile.

An <export-type> tag requires the mandatory attributes exporter="..." and format="..." which specify the exporter and format to use (see above). An <export-type> tag may contain any number (if at all) of the following elements, in any order:

<mime-type>...</mime-type> a MIME type under which to advertize this format under Linux/X11. You may specify several <mime-type>...</mime-type> tags to advertize the same data under different MIME types.
<mac-flavor>...</mac-flavor> a Mac OS X “flavor” or UTI under which to advertize this format on Mac OS X. This is the dot-organized-name such as com.adobe.pdf. You may specify several <mac-flavor>...</mac-flavor> tags in order to advertize the same data under different Mac OS X flavors/UTIs.
<win-format>...</win-format> a Windows format name under which to advertize this format on MS Windows. As far as I can tell there is no convention on how the name is formed, and is sometimes the same as the MIME type. You may specify several <win-format>...</win-format> tags to advertize the same data under different Windows formats.
<default-qt-formats type="..."/>: Qt itself is able to handle some data types and translate them to native clipboard formats (for example, image formats, HTML, or plain text). This tag instructs KLatexFormula to let Qt provide the default native types associated with the given type. Possible types are:
- image: image format(s). The data should be understandable by Qt (e.g. PNG data).
- text: plain text. The data is assumed to be encoded as UTF-8.
- html: HTML (or HTML fragment). The data is assumed to be encoded as UTF-8.
- urls: list of URLs (or a single URL). The data should indeed be a list of URLs separated by a newline (\n) (or a single URL).
An optional only-on attribute may be set to a comma-separated list of x11, mac and/or win, in which case this instruction only takes effect on the corresponding platform:
```
<default-qt-formats type="image" only-on="x11,mac" />
```
By default, this instruction applies to all platforms.