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.