Dave Jarvis' Repositories

git clone https://repo.autonoma.ca/repo/keenwrite.git
# Troubleshooting

This chapter addresses common issues that may arise while using {{app.title}}.
When problems occur, the status bar displays a brief summary of a problem.
Detailed information is available through the log viewer.

## Log

The application maintains a list of error messages to help diagnose issues.

Click **View → Log** (or press [F12]{.kbd}) to open the log view.

The log window shows various types of information:

* Error messages that indicate specific problems
* Warning messages about potential issues
* Information about file operations and processing
* System events and application state changes

When reporting issues or seeking help, the log information can provide valuable
context about what the application was doing when problems occurred.

## Container

If you encounter the following error (or similar) on Windows:

> Error: unable to load machine config file: "json: cannot unmarshal
> string into Go struct field MachineConfig.ImagePath of type define.VMFile"

Complete the following steps to remove obsolete containers:

1. Stop {{app.title}}.
1. Uninstall podman.
1. Delete `C:\Users\%USERNAME%\.config\containers\`.
1. Delete `C:\Users\%USERNAME%\AppData\Roaming\containers\`.
1. Open a command prompt.
1. Run:
   ``` dos
   wsl -l -v
   wsl --unregister podman-machine-default
   podman -v
   podman machine reset -f
   ```
1. Reboot.
1. Start {{app.title}}.
1. Retry exporting as a PDF file.

Note that downloading the typesetter image can take several minutes and does
not show a progress indicator. Be patient.

## SVG compatibility

Vector graphics files created in certain applications may encounter
compatibility issues when embedded in documents. These problems typically
manifest as rendering failures, missing content, or incorrectly displayed
graphics.

When referencing a vector graphic using Markdown, the status bar may show the
following error:

> The current document is unable to create an element of the requested type (namespace: http://www.w3.org/2000/svg, name: flowRoot).

This error occurs due to a version mismatch of the `flowRoot` element that
Inkscape creates. Resolve the issue by changing the SVG version number as
follows:

1. Edit the vector graphics file using any text editor.
1. Find `version="1.1"`.
1. Change the version to: `version="1.2"`.
1. Save the file.

The SVG will now appear inside the application; however, the text may appear as black blocks.

### Black blocks

Depending on how text is added to a vector graphic in Inkscape, the text may be
inserted within an element called a `flowRoot`. Although `flowRoot` is
recognized, the contents may not be fully interpreted, resulting in black
blocks being drawn instead of text, as shown in [@fig:blocked-text].

![Black text](images/blocked-text)

:: Blocked text {#fig:blocked-text}

Resolve the issue by "unflowing" all text elements as follows:

1. Start Inkscape.
1. Load the SVG file.
1. Select all the text elements.
1. Click **Text → Unflow**.

The text may change size and position; recreate the text without dragging using
the text tool. After all the text areas have been recreated, continue as
follows:

1. Click **Edit → XML Editor**.
1. Expand the **XML Editor** to see more elements.
1. Delete all elements named `svg:flowRoot`.
1. Save the file.

When the illustration is reloaded, the black blocks will have disappeared, but
the text elements may ignore any assigned colour.

### Blackened text

When an SVG `style` attribute contains a reference to `-inkscape-font-specification`, all values that follow said reference are ignored. This results in black text, shown in [@fig:black-text].

![Black text](images/black-text)

:: Blackened text {#fig:black-text}

Resolve the issue of colourless text as follows:

1. Open the SVG file in a plain-text editor.
1. Remove all references `-inkscape-font-specification:'<FONT>';`, including the trailing (or leading) semicolon.
1. Save the file.

[@fig:resolved-text] shows colours having reappeared after reloading.

![Resolved text](images/resolved-text)

:: Resolved text {#fig:resolved-text}