This file: DEBUGGING
Table Of Contents
-----------------
1. Debug Resources
2. Adding Debug comments to XmHTML
3. _XmHTMLFullDebug
4. debug_menu.c
1. Debug Resources
------------------
XmHTML provides the following (undocumented) resources to aid in debugging.
These resources will always be available, but will only take effect when the
symbol DEBUG was defined during compilation.
Name Type Default Access
XmNdebugDisableWarnings Boolean False CSG
XmNdebugFilePrefix String NULL CSG
XmNdebugLevels String NULL CSG
XmNdebugEnableFullOutput Boolean False CSG
XmNdebugSaveClipmasks Boolean False CSG
XmNdebugNoAnimationLoopCount Boolean False CSG
XmNdebugDisableWarnings
When set to True, XmHTML will show every warning that occurs. If enabled,
a lot of warnings will be generated mainly be the parser and formatting
routines.
This resource has no effect when _XmHTMLWarning has been called with a
NULL argument for the widget.
XmNdebugFilePrefix
This resource enables you to take a look at the internal representation
of the parsed HTML file, it need not be the same as the input file.
This is mainly intended for checking the parser's ability to add closing
elements on
,
, and .
An output file is generated for every file/text parsed.
The name of the output file is the prefix appended with the number of
files parsed so far, e.i., the first file will have the extension 0,
the next will have 1 and so on.
XmNdebugLevels
This resource indicates the number of the source file of which you
want to see debugging output. See below.
XmNdebugEnableFullOutput
enable output from the _XmHTMLFullDebug routines.
XmNdebugSaveClipmasks
will save all clipmasks XmHTML creates when encountering a transparent
image. The clipmasks will be saved in a file called .xbm
This option is not effective for progressive image loading.
XmNdebugNoAnimationLoopCount
When set, all animations will loop forever; any loopcount specification in
the NETSCAPE2.0 extension is ignored then.
2. Adding Debug comments to XmHTML
----------------------------------
The include file src/debug.h offers a way to add some sort of ``controlled''
debug statements in XmHTML. Each source file is assigned a number. A
command line option (-d) or the XmNdebugLevels resource controls from which
source files debug output should be allowed. Debug output is only possible
when DEBUG has been defined during compilation.
To add a debug statement, you use the following:
_XmHTMLDebug(, ());
The number is the source file number, and text is the text to output (printf
style). _XmHTMLDebug is the following macro:
#define _XmHTMLDebug(LEVEL,MSG) {\
if(xmhtml_debug_levels_defined[LEVEL] || xmhtml_debug_all == True) \
{ __rsd_fprintf MSG; } \
}
xmhtml_debug_levels_defined is a static array with length MAX_DEBUG_LEVELS,
defined at 32 in debug.h.
__rsd_fprintf is an fprintf wrapper that writes the output either to stdout
or some other output file.
If you want to use it in an application, debug.h includes a routine which
checks the command line options to your program in search of -d options:
extern void _XmHTMLtSetDebugLevels(int *argc, char **argv);
This call will enable all given debug levels and remove any -d option from
the command line. The options recognized are:
-d[sequence of comma separated numbers]: enables debug output for the
requested files;
-dall: enables debug output from *all* files;
-dfile:[filename]: causes all debug messages to be sent to file. Note
that there may be *no* spacing between the color and the filename to use.
The debug routines recognize a special filename: pid. If this is used,
output will be send to a file called .out
-dfull: allow output from all _XmHTMLFullDebug() calls (see below).
To select a debug level, start an application with the -d command line option:
-d1,4,5 selects debug output from source files 1, 4 and 5.
You can also set the XmNdebugLevels resource, either in an app-defaults file
or by means of the -xrm X11 command line option.
Combinations of numbers and words, or multiple words is not supported, although
multiple -d are allowed.
The levels 1 thru 16 are used by XmHTML
XmHTML uses the following source file mapping:
Source file Debug Id Note
-------------------------------------
XmHTML.c 1
format.c 2
callbacks.c 3
parse.c 4
paint.c 5
images.c/XmImage.c 6
colors.c 7
fonts.c 8
XCC.c 9 also the HashTable stuff in StringUtil.c
map.c 10
frames.c 11
forms.c 12
quantize.c 13
plc.c 14
Image readers 15 All readXXX.c files
reserved 16
When you are running XmHTML with some or all debug levels defined, screen
updates will be slow or even incomplete. This goes away when running it
cleanly.
3. _XmHTMLFullDebug
-------------------
The debug routines also provide the macro _XmHTMLFullDebug(LEVEL,MSG).
Use of this macro is for heavily used functions (such as nearly every
event handler in XmHTML).
Use of this macro is the same as _XmHTMLDebug(), except that output is only
shown if -dfull was used (via command line or the XmNdebugEnableFullOuput
resource).
I added this macro to see what the library is doing in a certain
part of the program and a debugger was not handy to use. It's best to only
enable this resource for tests with small documents, and only enable debug
output from a single file, as it generates *HUGE* amounts of output.
4. debug_menu.c
---------------
The file examples/debug_menu.c contains a routine that adds a XmHTML debug
menu to the menubar of your own application.
This menu allows you to select XmHTML debug output while an application is
running. The menu itself consists of togglebuttons, one for each source file
(or group of source files) that allow selectable debug output. It also
contains four buttons that toggle the following XmHTML debug resources:
XmNdebugDisableWarnings, XmNdebugEnableFullOutput, XmNdebugSaveClipmasks and
XmNdebugNoAnimationLoopCount.
Usage is as follows:
#include "debug_menu.h"
DebugAddMenu(html, menubar, label);
where:
html
XmHTMLWidget id. Used to get & set the XmNdebug resources.
It is a required value.
menubar
the Widget id of the menubar to which a debug menu should be
added. It is a required value.
label
the menu label to use. When NULL, the string "Debug" is used.
DebugAddMenu uses the first character of this label as the
menu accelerator.
This function will set the values of each toggle button according to the
initially selected debug levels (the -d command line option) and the
initial value of any of the XmNdebug resources (hardcoded or through
specification in a resource file).
This function is always available, but *only* active when compiled with
-DDEBUG.