Logs and troubleshooting

The application log

The log button, at the right of the editor header, shows the application log:

• loading of dictionaries and entities;
• compilation errors;
• the results of imports and exports.

It turns red when there are errors. Errors in the shorthand are also underlined in the editor, at the place where they occur.

When reporting a problem, include the relevant log entries. They usually identify the failing stage immediately.

The performance log

If Saga-Scribe becomes slow, start it with the option --perf-log:

saga-scribe --perf-log
# or, for the Flatpak:
flatpak run app.sagascribe.Sagascribe --perf-log

It then records how long each step takes — compiling, previewing, validating, and frames where the window stalled — in a file perf-<time>.jsonl in its log directory. The file helps locate the cause of a slowdown, especially in a large manuscript.

With the --perf-log=<file> form you can choose the file. In development, set SAGA_SCRIBE_PERF_LOG=1 before bun run tauri dev.

Common situations

The system warns me when I open the application

The builds are not code-signed yet. See Installation for the steps on your platform.

Export is refused

The shorthand contains an error. Check the underlined text in the editor and the application log. Saga-Scribe refuses to save or export an incomplete document on purpose.

The ONP lookup does not answer

ONP may be unreachable, or you may be offline. The word panel says so; enter the analysis by hand. Known analyses from earlier work are still available.

A word cannot be clicked in the preview

The template may not have word wrapping enabled. Word wrapping is what creates <w> elements, and lemmas and annotations attach to them. Switch to a template with word wrapping (the built-in Menota template has it) and check the preview again.

The preview lags behind my typing

The preview updates after a pause in typing, and large manuscripts take longer. If the lag is seconds rather than a moment:

• check whether the XSLT view is open with a stylesheet that does not declare <?saga-scribe render="page"?>;
• turn on the performance log and include it in a bug report;
• if you use your own stylesheet, follow the rules for page-by-page rendering.

My imported file looks different after saving

An imported file is only rewritten where you edited it. If a passage changed unexpectedly, check:

• whether the shorthand edit changed the encoding, not just the whitespace;
• whether a lemma was confirmed on a word in that passage;
• whether the document was compiled with a different template than the one it was imported with.

When in doubt, compare the saved file with the original using a diff tool. Reading an imported file must never change it; if it does, that is a bug worth reporting.

Reporting a problem

Problems can be reported on GitHub.

A useful report includes:

• what you did, what you expected, and what happened;
• the application version (shown in the toolbar and the help dialog);
• your operating system;
• the relevant log entries;
• if the problem involves a document, a minimal transcription that reproduces it — remove anything you do not want to publish;
• for a slowdown, the performance log.