..
   This file is part of Logtalk <https://logtalk.org/>
   SPDX-FileCopyrightText: 1998-2025 Paulo Moura <pmoura@logtalk.org>
   SPDX-License-Identifier: Apache-2.0

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


.. _faq_troubleshooting:

Troubleshooting
===============

* :ref:`faq_troubleshooting_options`
* :ref:`faq_troubleshooting_gecko`
* :ref:`faq_troubleshooting_warnings`

.. _faq_troubleshooting_options:

Using compiler options on calls to the Logtalk compiling and loading predicates does not work!
----------------------------------------------------------------------------------------------

Using compiler options on calls to the Logtalk :ref:`predicates_logtalk_compile_2`
and :ref:`predicates_logtalk_load_2` built-in predicates only apply to the
file being compiled. If the first argument is a :term:`loader file`, the
compiler options will only be used in the compilation of the loader file
itself, not in the compilation of the files loaded by the loader file.
The solution is to edit the loader file and add the compiler options to
the calls that compile/load the individual files.

.. _faq_troubleshooting_gecko:

Gecko-based browsers (e.g., Firefox) show non-rendered HTML entities when browsing XML documenting files!
---------------------------------------------------------------------------------------------------------

Using Gecko-based browsers (e.g., Firefox) show non-rendered HTML
entities (e.g., ``&ndash;``) when browsing XML documenting files after
running the ``lgt2xml`` shell script in the directory containing the
XML documenting files. This is a consequence of the lack of support
for the ``disable-output-escaping`` attribute in the browser XSLT
processor. The workaround is to use another browser (e.g., Safari or
Opera) or to use instead the ``lgt2html`` shell script in the
directory containing the XML documenting files to convert them to
(X)HTML files for browsing.

.. _faq_troubleshooting_warnings:

Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!
---------------------------------------------------------------------------------------------------------------------------------------------------

This may happen when your Prolog compiler implementation of the ISO
Prolog standard ``write_canonical/2`` built-in predicate is buggy and
writes terms that cannot be read back when consulting the
intermediate Prolog files generated by the Logtalk compiler. Often,
syntax errors found when consulting result in error messages but not
in exceptions as the Prolog compiler tries to continue the
compilation despite the problems found. As the Logtalk compiler
relies on the exception mechanisms to catch compilation problems, it
may report zero errors and zero warnings despite the error messages.
Send a bug report to the Prolog compiler developers asking them to
fix the ``write_canonical/2`` buggy implementation.
