Customizing the LaTeX Symbols Palette

All LaTeX symbols in the symbol palette are specified with the help XML files. The XML files reside under directories called conf/latex_symbols.d which are searched for:

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

All the symbol definitions are merged, and displayed in the symbols palette.

The default XML specification file is bundled with the application; it can be found in the source distribution as src/conf/latex_symbols.d/latexsymbols.xml. It is a good place to start if you’d like some examples.

XML File Syntax

The XML file syntax is relatively straightforward for simple symbols. Some additional XML tags allow for more advanced latex tricks syntax, e.g. delimiters and accents.

Every XML file should have the following base structure:

<?xml version='1.0' encoding='UTF-8'?>
<klf-symbol-list minklfversion="3.3.0a">
   <category name="...">
   ...
   </category>

   <category name="...">
   ...
   </category>

   ...
</klf-symbol-list>

The root node should be klf-symbol-list. The current XML file format is compatible with klatexformula 3.3.0a, so specify that as compatibility version. The root node may contain any number of category child nodes. Each category node must have a name attribute with an internal name for the category. The syntax inside a category node is:

<category name="...">
    <category-title>...</category-title>
    
    <sym>...</sym>
    <sym>...</sym>
    <sym>...</sym>
    ...
</category>

You may specify the category’s title with a category-title node; this will be displayed in the symbol’s palette selection box. You may then specify any number of LaTeX symbol definitions within <sym>...</sym> tags.

A LaTeX Symbol Specification

A symbol (or actually, any LaTeX piece of code, possibly even a macro with arguments) is specified within a <sym>...</sym> XML element. The sym element accepts the following child elements (the order of which are essentially irrelevant):

<latex>\partial</latex> specifies the LaTeX code for the symbol;

In case of a macro with arguments, specify the macro name only, and specify the number of arguments with the numargs attribute. If the symbol has an optional argument, set the optional attribute to "yes":
```
<latex numargs="2">\frac</latex> 
<latex optional="yes" numargs="1">\sqrt</latex> 
```
Specify additional required packages (to be included in the preamble) with the <usepackage name="..." /> element:
```
<usepackage name="amsmath" />
```
If the package requires arguments, use the syntax [options...]{name} inside the name attribute:
```
<usepackage name="[mathcal]{euscript}" />
```
Arbitrary preamble definitions may be included with the <preambleline> tag:
```
<preambleline>\DeclareMathOperator{\tr}{tr}</preambleline>
```
Separate independent declarations into different <preambleline> tags. When the symbol is included into a LaTeX expression, the preamble definitions are appended to the latex preamble only if they are not present; whether they are already present is determined by comparing each <preambleline> or <usepackage> with instructions in the existing preamble taken line by line.

(In particular, it is important that the <preambleline> contents is indeed a single line; otherwise the appended preamble line will not be detected as already present if you insert a second instance of the same symbol.)
<preview-latex>...</preview-latex> allows to specify some arbitrary LaTeX code which should be used for generating the symbol preview, instead of the code specified to <latex>. This should rarely be needed.
The <bb expand="TOP,RIGHT,BOTTOM,LEFT"/> XML element allows to adjust the bounding box when generating the symbol preview. This only has an effect when generating the symbol preview to display on the palette button, and has no effect when the symbol is inserted into an equation.

Values are given as integer postscript points on each edge by which the bounding box should be enlarged.
The optional attribute textmode="true" may be set on the <sym> element itself, to specify that the symbol should be used in text mode and not math mode.

Currently, this only has an effect when generating the LaTeX symbol preview to display on the symbols palette button.
Symbols that are marked <hidden/> won’t display in the symbols palette; however they will be recognized by the editor and a popup will suggest to insert missing packages when that symbol is typed.
Use foo bar to specify a space-separated list of tags/keywords to facilitate searching for symbols in the symbol palette.

Some examples, taken from the default symbol set:

<sym>
  <usepackage name="amssymb"/>
  <latex>\dotplus</latex>
</sym>

<sym>
  <latex numargs="2">\nicefrac</latex>
  <usepackage name="nicefrac"/>
  <keywords>slanted fraction bar over division</keywords>
</sym>

<sym>
  <usepackage name="[mathcal]{euscript}"/>
  <latex>\mathcal{A}</latex>
</sym>

<sym>
  <usepackage name="amsmath"/>
  <preambleline>\DeclareMathOperator{\tr}{tr}</preambleline>
  <latex>\tr</latex>
  <keywords>trace</keywords>
</sym>

<sym textmode="true">
  <preambleline>\usepackage[T1]{fontenc}</preambleline>
  <latex>\guillemotleft</latex>
</sym>