This page describes how to report a problem you found when using retawq. Before you write a report, please make sure that you use the most recent version of retawq which is available on the project home page and that the problem does not occur with other web browsers. To report a bug or other problem, you can send an e-mail to the maintainer. Your report should include at least the following information:

• a short, precise description of the problem
• the version of retawq you use
• operating system, possibly relevant libraries, C compiler
• if compiling/linking failed: the complete, verbatim error messages
• if the problem might be related to (or might depend on) the compile-time configuration: the file ".config" which was generated by the configure script resp. by "make"; if you don't have this file anymore: the output of a shell command like "retawq --dump=about:ctconfig"
• if the problem might be related to (or might depend on) the run-time configuration: the file /home/your_home/.retawq/config or the relevant parts from it and the built-in run-time configuration (if any; cf. the compile-time configuration option OPTION_BIRTCFG); please make sure that you don't send passwords

Some parts of this information can be collected by simply running "./configure --report" (if you use the configure script) resp. "make report" (if you use the classical Makefile).

Debugging Mode

When a problem can't be solved otherwise, you might want to enable retawq's debugging mode to find out whether the resulting debugging messages show the cause of the problem. The debugging mode is realized by the special, internal compile-time configuration option CONFIG_DEBUG. To enable it, do the following:

• if you use the configure script: run the script as usual; then open the file ".config" (which was generated by the script) with a text editor and change the value of CONFIG_DEBUG from 0 to 1
• if you use the "classical" Makefile: open the Makefile in a text editor and change the value of CONFIG_DEBUG from 0 to 1
• run "make" to build the program

The resulting program generates a file called "debug.txt" in the current directory. Old contents of this file are overwritten whenever the program is started. The file contains lots of cryptic debugging messages, most of which aren't related to a particular problem. Please note that the file might also contain passwords (e.g. from the run-time configuration handling) or confidential documents (e.g. when you received something via TLS/SSL). So you should remove old debugging files as soon as you don't need them anymore, and you should remove any passwords and other confidential stuff from the file or replace them with "[snipped]" markers or similar before sending the file.

Enabling the debugging mode has many more consequences than just the generation of the debugging file. For example, the program becomes bigger and slower, it might create an HTML parser debugging file ("htmldebug.txt"), and the status line at the bottom of the screen shows cryptic additional information. In short: use this mode only if necessary; it's only intended to solve problems which can't be solved otherwise.

Debugging with gdb

If retawq crashes, it's very useful to find out where exactly the crash happened. A debugger catches the crash and allows you to get the information. The following description shows how to do this with GNU gdb, but much of it applies to any debugger similarly.

• If you use the configure script: make sure that LDFLAGS doesn't contain the option "-s" which would cause important symbols to be deleted from the binary. For example, run the configure script like so: "./configure LDFLAGS=' '". (That is, set the LDFLAGS to a "dummy" space character.) After this, build the program with "make".
• If you use the "classical" Makefile: use "make devel" instead of "make", or remove the target "stripsyms" from the "build_binary" line.
• Start the debugger: "gdb ./retawq".
• Start retawq: at the debugger prompt, enter "run".
• Now try to reproduce the crash. The debugger will catch it.
• At the debugger prompt, enter "bt" to get a stack backtrace. That's the interesting information. The easiest way is to get it verbatim with some mouse copy-pasting; you might have to toggle retawq's mouse handling mode with the keyboard command "Y" before crashing the program.

Independently, the output of a "strace" command can also be useful and might be easier to get.