.. |TexText| replace:: **TexText**
.. |Lin| replace:: **Linux/ MacOS**
.. |Win| replace:: **Windows**

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

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

.. _troubleshooting:

Troubleshooting
---------------

.. contents:: :local:
    :depth: 1

.. _trouble_installation:

Installation problems
=====================

The setup script offers several command line options which may help to fix the
most common problems during the installation process. For this purpose open a
Terminal or Windows Command Prompt and enter one of the commands listed below:

- Inkscape is not found by the installation script -> specify the path to the executable:

    - |Lin|

    .. code-block:: bash

        python setup.py --inkscape-executable '/path/to/my Inkscape/inkscape'

    - |Win| (note the double quotes!)

    .. code-block:: bash

        setup_win.bat --inkscape-executable "C:\My\Installation Location\bin\inkscape.exe"

- Inkscape does not find |TexText| although it has been installed -> notify the setup script
  about a user-defined (non-standard) installation location for the Inkscape extensions

    - |Lin|

    .. code-block:: bash

        python setup.py --inkscape-extensions-path '/path/to/user defined/location'

    - |Win| (note the double quotes!)

    .. code-block:: bash

        setup_win.bat --inkscape-extensions-path "C:\Users\My extension location"

- The LaTeX engines are not found in the system path by the setup script -> specify the
  path to the executables:

    - |Lin|

    .. code-block:: bash

        python setup.py --pdflatex-executable '/path/to/my latex/pdflatex'

    also available: ``--lualatex-executable`` and ``--xelatex-executable`` for the LuaLaTex and
    XeLaTeX executables, respectively.

    - |Win| (note the double quotes!)

    .. code-block:: bash

        setup_win.bat --pdflatex-executable "C:\Program Files\My Latex\pdflatex.exe"

    also available: ``--lualatex-executable`` and ``--xelatex-executable`` for the LuaLaTex and
    XeLaTeX executables, respectively.

- The typst engine ist not found in the system path by the setup script -> specify the
  path to the executables:

    - |Lin|

    .. code-block:: bash

        python setup.py --typst-executable '/path/to/my typst/typst'

    - |Win| (note the double quotes!)

    .. code-block:: bash

        setup_win.bat --typst-executable "C:\Program Files\My Typst\typst.exe"

- Completely skip all requirement checks during installation and just copy the |TexText| files into
  the extension directory:

    - |Lin|

    .. code-block:: bash

        python setup.py --skip-requirements-check

    - |Win|

    .. code-block:: bash

        setup_win.bat --skip-requirements-check

- General help:

    - |Lin|

    .. code-block:: bash

        python setup.py --help

    - |Win|

    .. code-block:: bash

        setup_win.bat --help

.. important::

    Do not hesitate to file a report if you cannot solve your installation problems:
    `github <https://github.com/textext/textext/issues/new/choose>`_

Problems running |TexText|
==========================

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 discovered it!

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

This section is structured as follows:

.. contents:: :local:

.. _trouble_latex:

TexText does not show up at all
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the |TexText| dialog does not open after having clicked on the TexText entry in
the extension menu try the following:

- If you are using TexLive and you updated TexLive recently the path to the TexLive
  executables may have changed. You can address this by thw following two methods:

  - Delete the file (if it exists) ``~/.config/textext/.cache.json`` (Linux) or
    ``C:\Users\[Your UserName]\AppData\Roaming\textext\.cache.json`` (Windows) or
    ``~/Library/Preferences/textext/.cache.json`` and try to open
    |TexText| again

  - Determine the path of your pdflatex executable and install |TexText| again using
    the ``--pdflatex-executable`` command line option:

    - Linux, Mac: ``python3 setup.py --pdflatex-executable /path/to/your/pdflatex-executable``
    - Windows:  ``setup_win.bat --pdflatex-executable /path/to/your/pdflatex-executable``

- Have a look for the file ``textext.log`` in the directory
  ``~/.cache/textext`` (Linux), ``C:\Users\[Your UserName]\AppData\Roaming\textext`` (Windows) or
  ``~/Library/Preferences/textext`` (Mac) and see if any useful error messages are logged into that
  file. 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


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).

Additionally, you have the possibility to display the full Python code traceback. This
may help to locate more tricky errors in the Python code of the extension.

.. note::

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

.. _trouble_bugs:

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

Of course, |TexText| may contain bugs which may crash the plugin. If this happens
information about the error can be either found in the TexText error dialog

.. figure:: ../images/textext-error-dialog-traceback.png
    :scale: 50 %
    :alt: TexText error dialog after failed execution

or (hopefully) in an Inkscape error dialog that will show something like this:

.. figure:: ../images/textext-error-dialog-python-error-1.png
    :scale: 50 %
    :alt: Inkscape 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.

.. _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:

    .. code-block:: bash

        inkscape --pdf-poppler --pages=1 --export-type=svg --export-text-to-path --export-area-drawing --export-filename test.svg test.pdf

    .. 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\bin\``.

    Open the generated file ``test.svg`` with Inkscape and check the result.

6. Check if the conversion of the strokes to paths in the ``svg`` succeeds:

    .. code-block:: bash

        inkscape -g --batch-process --actions="EditSelectAll;StrokeToPath;export-filename:test.svg;export-do;EditUndo;FileClose" test.svg

    .. 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\bin\``.

    Open the generated file ``test.svg`` with Inkscape and check the result (Visually there will
    be no difference between the svg generated in this step and that from step 5).

7. Check if the conversion from ``svg`` to ``png`` for the preview image succeeds

    .. code-block:: bash

        inkscape --pdf-poppler --pdf-page=1 --export-type=png --export-area-drawing --export-dpi=300 --export-filename test.png test.pdf

    .. 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\bin\``.

    Open the generated file ``test.png`` with an image viewer and check the result.