.. |TexText| replace:: **TexText 0.11**

.. role:: bash(code)
   :language: bash
   :class: highlight

.. role:: latex(code)
   :language: latex
   :class: highlight

.. _tt0x-troubleshooting:

Troubleshooting (TexText 0.11)
------------------------------

There are three main reasons why something may went wrong:

1. Your LaTeX code contains invalid commands or syntax errors.

2. The installed toolchain for the conversion of your code to a valid SVG element
   is for some reason broken.

3. |TexText| contains a bug and you are the person who discovers it!

|TexText| helps you to resolve such issues by offering detailed error and logging information.

This section is structured as follows:

.. contents:: :local:

.. _tt0x-trouble_latex:

LaTeX and toolchain errors
~~~~~~~~~~~~~~~~~~~~~~~~~~

If compilation of your LaTeX code fails |TexText| opens a dialog displaying the
cause of the failure. In most cases a syntax error in your code will be the reason.
|TexText| filters the relevant information from the compiler output and displays
it:

.. figure:: ../images/textext-error-dialog-simple.png
   :scale: 50 %
   :alt: Simple error dialog

If you would like to see the full output of the LaTeX processor, click on the ``+``
left to the ``stdout`` label:

.. figure:: ../images/textext-error-dialog-stdout.png
   :scale: 50 %
   :alt: Error dialog with stdout

Sometimes nothing meaningful can be stripped from the LaTeX processor output, or
nothing has been produced by LaTeX which can be parsed by |TexText|:

.. figure:: ../images/textext-error-dialog-empty.png
   :scale: 50 %
   :alt: empty error dialog

Most likely something serious failed during compilation and you may find additional
information under ``stderr`` , click on the ``+`` left to this label:

.. figure:: ../images/textext-error-dialog-stderr.png
   :scale: 50 %
   :alt: Error dialog with stderr

In that case follow the information given in the window (in the example given here:
open the pdflatex.log in the AppData path).

.. note::

   The ``stderr`` option is only available when errors have been piped by the
   failed command.

.. _tt0x-trouble_bugs:

Bugs in |TexText|
~~~~~~~~~~~~~~~~~

Of course, |TexText| may contain bugs which may crash the plugin. If this happens
an Inkscape error dialog is opened that will show something like this:

.. figure:: ../images/textext-error-dialog-python-error-1.png
    :scale: 50 %
    :alt: Error dialog after failed execution

Note the advice at the end of the text view: You should run the extension again.
Then, a logging mechanism is started which writes its result into the Inkscape
error dialog:

.. figure:: ../images/textext-error-dialog-python-error-2.png
    :scale: 50 %
    :alt: Error dialog after failed execution, second run

You can use this information to further analyze the problem or to
open an issue on GitHub asking for help: https://github.com/textext/textext/issues/new

.. important::
    Please carefully read the instructions in the issue template on GitHub so you
    pass all the required information to the developer team.

.. _tt0x-trouble_manual_compile:

Manual use of the toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~

For debugging purposes it may be required to manually process the steps usually done automatically
by |TexText|. This procedure is also helpful if the result generated by |TexText| does not match
your expectations at all and you are unsure if this is an error of |TexText| itself or of the
programs used in the toolchain. Here is what you have to do in such cases:

1. Create a LaTeX document ``test.tex`` with the following content:

    .. code-block:: latex

        \documentclass{article}
        \usepackage{amsmath,amsthm,amssymb,amsfonts}
        \usepackage{color}
        \pagestyle{empty}
        \begin{document}
        % ***Your code***
        \end{document}

    Replace ``% ***Your code***`` by the LaTeX code you want to compile and save the file to disk.

2. Open a Terminal (Linux, MacOS) or Command Window (Windows)

    - On Linux: Open a file manager (e.g. Nautilus, Dolphin), navigate to
      directory of ``test.tex``. Right click and select ``Open in Terminal`` (Nautilus)
      or simply press ``F4`` (Dolphin).

    - On Windows: Open the explorer, navigate to the directory of ``test.tex`` and press
      ``SHIFT + F10``, then select ``Open Command Window Here`` from the context menu.


3. Compile this file using the command

    .. code-block:: bash

        pdflatex test.tex -interaction=nonstopmode -halt-on-error

    .. note::

        On Windows it may be required to put the name of the directory in which ``pdflatex.exe``
        resides in front of ``pdflatex``, e.g. ``c:\Program Files\MiKTeX 2.9\miktex\bin\x64\``.

4. If compilation succeeds open the generated file ``test.pdf`` with a pdf viewer and
   check its content. If it is as expected proceed with the next step.

5. Check if the conversion from ``pdf`` to ``svg`` succeeds:

    - If you use ``pstoedit + ghostscript`` enter the command

        .. code-block:: bash

            pstoedit -f plot-svg test.pdf test.svg -dt -ssp -psarg -r9600x9600 -pta

        .. note::

            On Windows it may be required to put the name of the directory in which ``pstoedit.exe``
            resides in front of ``pstoedit``, e.g. ``c:\Program Files\pstoedit\``.

    - If you use ``pdf2svg`` enter the command

        .. code-block:: bash

            pdf2svg test.pdf test.svg

        .. note::

            On Windows it may be required to put the name of the directory in which ``pdf2svg.exe``
            resides in front of ``pdf2svg``, e.g. ``c:\Program Files\pdf2svg\``.

    - Open the generated file ``test.svg`` with Inkscape.

6. Check the generation from ``svg`` to ``png`` for the preview image succeeds

    - Enter the command

        .. code-block:: bash

            inkscape -f test.svg --export-png test.png  --export-id content --export-id-only --export-dpi=200

        .. note::

            On Windows it may be required to put the name of the directory in which ``inkscape.exe``
            resides in front of ``inkscape``, e.g. ``c:\Program Files\Inkscape\``.