Menu
▾
▴
Tree [847668] master / History
Christian Linhart
Read Me
This file: README for XmHTML.
==========================================================================
Please read this file, it can save you a lot of problems and me a lot of
time.
==========================================================================
==========================================================================
Please read the file LICENSE.
==========================================================================
The file DEBUGGING describes how to use and add debugging output to XmHTML.
The file BUGS describes a few of the bugs that we know of.
The file FIXES contains a list of fixes made so far.
The file Changelog.txt describes the changes which are not fixes.
The file CHANGES describes the historic day-to-day development of the widget at the beginning of this project.
The file examples/test-pages/README contains a description of the test
documents.
===============================
How to use it:
===============================
You need a current version of Motif to use it. ( Version 2.3.4 may work, or the current repo-snapshot )
Please look at the examples in the "examples" directory of the source.
Here is a short outline of the code ( inspired by example_1.c ):
--------------------------------------------------------------
#include <Xm/Xm.h>
#include <XmHTML/XmHTML.h>
[...]
String content;
Widget htmlParentWidget;
[... init Motif, init the parent widget for XmHtml,
in this example: variable "htmlParentWidget" ]
/* put some html-text into the variable content */
content = "<html><body><h1>Hello World</h1><p>Example Text</p></body></html>";
html = XtVaCreateManagedWidget("html",
xmHTMLWidgetClass, htmlParentWidget,
XmNmarginWidth, 20,
XmNmarginHeight, 20,
XmNwidth, 600,
XmNheight, 500,
NULL);
XmHTMLTextSetString(html, content);
[... manage widgets, main loop, etc ... ]
--------------------------------------------------------------
===============================
How to build from source:
===============================
XmHTML build works with plain Makefiles on Linux.
You can pass the following build-variables to make:
EXTRA_INCLUDES : additional include directories ( in the form -Idir, where "dir" is the directory )
LD_FLAGS : additional linker flags
HAVE_XFT : 1 means: enable XFT support, 0 means: disable XFT support
EXTRA_CPPFLAGS : additional flags for the C-Preprocessor, such macros in the form -Dmacro=value
PLATFORM : which widget library to build it for. The following values are possible:
motif : vuild it for motif ( default )
gtk : build it for gtk ( untested. I recommend to disable XFT support when building for gtk )
These build variables are especially useful when you integrate XmHTML in the build system of a larger project.
Examples:
cd $(XMHTMLDIR); make EXTRA_INCLUDES=-I$(INSTALLBASE)/include LDFLAGS=-L$(INSTALLBASE)/lib HAVE_XFT=1
cd XmHTML-1.1.8 ; make EXTRA_INCLUDES=../install/include LDFLAGS=-L../install/lib HAVE_XFT=1
cd XmHTML-1.1.8 ; make EXTRA_INCLUDES=../install/include LDFLAGS=-L../install/lib HAVE_XFT=1 HAVE_XFT=0 PLATFORM=gtk
cd XmHTML-1.1.8 ; make EXTRA_INCLUDES=../install/include LDFLAGS=-L../install/lib HAVE_XFT=1 EXTRA_CPPFLAGS=-DDEBUG
For building on the Mac, the following flags will have to be defined:
HAVE_XFT=1 "EXTRA_CPPFLAGS=-DNEED_STRCASECMP -DNDEBUG -Dproduction"
and possibly you'll have to set EXTRA_INCLUDES and LDFLAGS appropriately so that all includes and libraries are found.
================================================================
Below is the content of the old README. Many things are probably outdated.
For example,
* imake is not supported anymore.
* LessTif is probably not supported anymore, now that Motif is Open Source.
================================================================
Table Of Contents
-----------------
1. Compiling XmHTML using Imake
1.1 mmkmf
2. Compiling XmHTML using the provided Makefiles
3. Selecting supported image types
4. Compiling a stand-alone version of the raw HTML parser
5. GIF images and the Unisys LZW patent
5.1 GIF and GZF and XmHTML
6. Personalizing XmHTML
7. Things missing in this version
8. LessTif compatibility
9. Adding Warning and Error messages
10. mkStrings
10.1 About the generated files
10.2 About the generated #defines
10.3 Examples
11. Generating Source Documentation
12. Internationalization Support
13. Troubleshooting and Other Points To Ponder
14. XmHTML Mailing List
15. Where to get it
16. How to contact us
1. Compiling XmHTML using Imake
-------------------------------
Before typing xmkmf (or imake or mxmkmf), you might wish to adjust the imake
configuration file XmHTML.cf
Things that require your attention are:
- BUILDINCTOP
BUILDINCTOP is an Imake variable that, on a properly configured imake
system, should be propagated properly throughout the entire source tree.
However, several people have reported that Imake incorrectly sets this
variable. If this is the case on your system, you can override the
default BUILDINCTOP variable in XmHTML.cf instead of modifying each
Imakefile seperatly.
- Image support
XPM support:
For getting full functionality, XmHTML *requires* that you
have libXpm and the xpm.h header file installed. If you are
using anything below Motif 2.X (which also includes
LessTif), you *must* set XPMINC to the path to the xpm.h
include file, and XPMLIB to the path & library for libXpm
(pre-Motif 2.0 imake does not include -lXpm automatically).
Please note that XmHTML includes xpm.h as <X11/xpm.h>.
You can disable usage of Xpm by setting the
makefile-variable HAVE_XPM to 0.
This only works when you use the toplevel "Makefile" as-is,
i.e., when you do not use imake or xmkmf.
XPM support is enabled by default if you use the
toplevel "Makefile" as-is.
If you use a Makefile-generator like imake, xmkmf or
configure, you will have to update the inputfiles of
these makefile generators in order to define the C-macro
HAVE_XPM, if you want XPM-support.
Otherwise, XmHtml will be built without Xpm support.
If Xpm is disabled, then some functionality will not be
available, such as default icons, or conversion to
Postscript.
JPEG support
If you want it, set JPEGINC to the location of the jpeg include files,
and set JPEGLIB to the location of libjpeg. If you don't want it,
set IHaveJPEG to NO.
PNG support
If you want it, set PNGINC to the location of the png include files,
and set PNGLIB to the location of libpng. If you don't want it,
set IHavePNG to NO.
ZLIB support
If you want it, set ZLIBINC to the location of the libz include files,
and set ZLIBLIB to the location of libz. If you don't want it,
set IHaveZLIB to NO.
Note: PNG support *requires* zlib support. If you have choosen support
for PNG but disabled zlib support, PNG *will* be disabled.
You can however disable PNG but enable ZLIB to support the GZF image
type (this is an alternate gif format. It's compacter and faster and
doesn't require a costly license from Unisys).
See also XmHTML.cf
- Common Desktop Environment and related minor incompatibilities
If you have CDE (with development system) installed on your system,
there's a big chance it didn't install a Motif.tmpl file *and* that the
directory for the Motif header files is quite different from the standard
ones (/usr/dt/include instead of /usr/X11/include). To get around this
(so you're able to build at least the library), you should uncomment the
CDE marked lines in XmHTML.cf
(Provided by Susan Liebeskind <shl@cc.gatech.edu>)
- Library targets
By default, a normal (static) library is build using the default compiler
flags and defines as configured for your system.
A shared library is build by default for all systems that support shared
libraries. Please notice that building shared libraries is currently *not*
supported for SGI Irix (pre 6.2) and Linux a.out, as these require
specification files.
For X11R6, the generated rules add code to the shared library to
automatically include the required image libraries whenever -lXmHTML is
seen. For SGI IRIX above 6.4, code is added to automatically load the
full set of X libraries as well. This feature is supported at least on
SGI IRIX, Linux and a bunch of BSD variants (including NetBSD and FreeBSD).
The only way to know for sure if your system supports this (quite
usefull) feature, is to build a simple program (any of the book/ examples
will do nicely) and *exclude* the image libraries on the link line. If
you get a bunch of unresolved errors, you're out of luck.
If you want to build a debug version of the library, you need to set
DebugLibXmHTML to YES. If you do this, the examples will be build using
this library.
- build targets
By default, the examples and tools are build when you type make (or
make all). You can change this by changing the line that reads SUBDIRS
in the toplevel Imakefile.
Each target can also be made seperatly:
make lib
builds libXmHTML;
make http
builds libhttp;
make examples
builds everything in the examples directory. Will build libXmHTML
and libhttp first if not already done;
make book
builds everything in the book directory. Will build libXmHTML
first if not already done;
make tools
builds everything in the tools directory. Doesn't require
libXmHTML but at least one tool requires libhttp.
make World
builds everything
- dmalloc
If you want to use dmalloc (see the following section), you can
uncomment the line with IHaveDmalloc. If dmalloc is not installed in
the default compiler/linker search paths, specify the path for dmalloc.h
in DMALLOCINC and add the path for libdmalloc.a to DMALLOCLIB
- debug support
If you want to enable the built-in debug support, set IWantDebug to
YES.
- Install directories
The imakefiles also allow installation of the library. By default,
typing make install will install any libraries in USRLIBDIR (most likely
to be something like /usr/X11R6/lib). The XmHTML and http header files get
installed in INCROOT/XmHTML (which most likely will be something like
/usr/X11R6/include/XmHTML).
You can specify other locations by changing the XmHTMLLibDir and
XmHTMLIncDir defines.
Please note that you need to have root privileges if you use the default
locations.
Also note that if you are installing the shared library, you will have
to reconfigure your dynamic linker. On linux you do that using ldconfig.
After you have adjusted XmHTML.cf to your likings, typing mmkmf (see
section 1.1) will produce the toplevel Makefile. If you have don't have mmkmf
available on your system you can use xmkmf instead, and if that is not
available you can use imake -DUseInstalled -I/usr/X11R6/lib/X11/config (or
wherever your Imake configuration files live). Then type make Makefiles
followed by make includes and make depend. Alternatively, you can also type
mmkmf -a or xmkmf -a which will do the same.
Once the above step is completed, typing make will build the library (or
libraries) and everything in the selected subdirectories.
If you want to install the library and header files, type make install.
If you have not modified the default install directories, you will
have to have root privileges.
If you have build the shared library and installed it, please remember that
you need to re-configure your dynamic loader, even if you use the default
install directories. The command for this under Linux is ldconfig (and possibly
editing of /etc/ld.so.conf). (Anyone knows what the requirements are on other
systems supporting shared libs?)
If you do not have root priviliges and you want to use the shared XmHTML
library, you need to adjust the path your dynamic linker searches. On Linux
you can do this by setting an appropriate value for the LD_LIBRARY_PATH
environment variable:
csh, tcsh: setenv LD_LIBRARY_PATH <shared lib installation path>
sh, bash: export LD_LIBRARY_PATH="<shared lib installation path>"
The name of this environment variable may differ on other systems (see the
manual pages for ld and/or ld.so or something like that).
Note: you need to do this when the examples have been linked against a newly
build XmHTML shared library or they won't run.
1.1 mmkmf
---------
This is what Richard Offer <offer@sgi.com> has to say about mmkmf. Read it
and use it.
mmkmf (for Motif Makefile), adds some extra options to the imake line
which pulls in some different Imake config files. While xmkmf still works,
using mmkmf allows you to set LDREQLIBS so the number of unresolved symbols
at link time is reduced (and those that are unresolved are generally things
you should be worrying about as it means that the symbols really can't
be found in any library that you've specified). Also in the future using
mmkmf will allow the compilation to work out which version of Motif you are
using, so that (for example) /usr/Motif-1.2/bin/mmkmf will generate
Makefiles that need no further intervention to always pick up the Motif 1.2
header files and libraries, where as xmkmf will simply use the default
Motif version. [Okay this isn't applicable right now (only one version
of Motif), but still documenting mmkmf gets people into the habit of
using it.]
2. Compiling XmHTML using the provided Makefiles
------------------------------------------------
If you do not have imake, or imake is configured poorly on your system,
you can compile everything by using the provided makefiles.
The provided makefiles do *not* support building shared libraries.
Unless you are using Linux, you probably have to adjust the toplevel makefile.
Things that require your attention are:
- CFLAGS
Flags required for you compiler. An ansi C compiler is required.
The list below gives the flags required to put some compilers into ansi
mode (not sure of these except for gcc, AIX and HPUX):
gcc: -ansi
DEC OSF1/AXP/Ultrix: -std1
USL SV4: -Xa
HPUX: -Ae [Note: this is the same as -Aa -D_POSIX_SOURCE]
AIX: -qlanglvl=ansi
SGI: -xansi
- IMAGEDEFINES
These control what type of image XmHTML will support. See section 3 for
more info.
- LIBDIR
This must point to the directories where your X11 and Xm libraries
can be found.
- INCLUDES
This must point to the directories where your X11 and Xm include
files can be found;
- CPPFLAGS
This is probably the most cumbersome. A number of things can
be undefined if you do not add the proper defines. If you are using
the GNU libc, you will have to add -D_BSD_SOURCE or strcasecmp and
strdup (and a few others as well) will not be prototyped.
HPUX might need -D_HPUX_SOURCE while SunOs also probably needs
-D_POSIX_SOURCE
If your system does not have the str[n]casecmp routines, you will
want to add -DNEED_STRCASECMP (Unixware).
If your system does have the str[n]casecmp routines but they are
defined in <strings.h> instead of <string.h>, add -DHAVE_STRINGS_H
If your system supports POSIX regular expressions, add -DHAVE_REGEX_H
Debugging output is only enabled if -DDEBUG is defined. A number of
routines (especially the event handlers) have debug output enabled
only if either the -dfull command line option is used or when the
XmNdebugEnableFullOutput is set to True (this will cause a *huge*
amount of output). See the file DEBUGGING for more info.
- LIBS
This also can be annoying. On linux with X11R6.1, the complete X
library package is required:
-lXm -lXpm -lXmu -lXt -lXext -lX11 -lSM -lICE
Just use the libs you normally use when linking Motif/X11 apps.
Note: Motif 2.X *requires* libXpm.
Note: LIBDIR and LIBS are only used when building the examples
- Image support
XmHTML *requires* that you have libXpm and the xpm.h header file
installed, which XmHTML includes as <X11/xpm.h>.
JPEG and PNG are compilation options.
- dmalloc
I am using the dmalloc package (by Gray Watson) to trace memory
leaks and thelike. It is disabled by default. If you want to use
dmalloc, you need to add -DDMALLOC to CPPFLAGS and -ldmalloc to
LIBS and update INCLUDES and LIBDIR.
The homepage of dmalloc can be found at http://www.letters.com/dmalloc
You can ftp it from there or directly from ftp.letters.com, directory
/src/dmalloc.
One known problem here: when using dmalloc, the SetValues method seems
to behave erratic. In some cases, dmalloc keeps hanging in it's own heap
checking. Don't know if it's due to a bug in XmHTML or a conflict between
dmalloc and X. You can get around this by using a large enough heap
check interval, 100 or larger will do nicely.
- removing debug support
If you want to exclude debug support completely, add -DNDEBUG to
CPPFLAGS. Simply removing -DDEBUG will only disable debug output but
leave the actual debug functions present.
- build targets
See ``Compiling XmHTML using Imake''
Once you have made your adjustments, typing make should give you a library
called libXmHTML.a
BTW: there is a backup copy of each Makefile called Makefile.org
There is no test suite (try modifying Mosaic to use XmHTML ;-), but there are
a few examples in the examples directory. These are built by default, so if
you do not want to build the examples, remove the examples directory from the
SUBDIRS line in the toplevel makefile. Likewise for the tools directory.
You can find the full widget documentation in the html directory.
3. Selecting supported image types
----------------------------------
XmHTML *requires* libXpm, version 3.4g or above
Support for JPEG, PNG and GZF images are selectable compilation options.
-DHAVE_LIBJPEG
enables JPEG support. This requires libjpeg by the Independent JPEG Group.
Version 6 or above;
-DHAVE_LIBPNG
enables PNG support. This requires libpng, version 0.96 or above and
zlib, version 1.0.4 or above. libpng version 0.89 (also seen as
libpng.so.1.0.89) will *not* work.
-DHAVE_LIBZ
enables GZF support. When you have already selected PNG support you do
not have to set this. Set ZLIBINC to the path of the zlib include files
and ZLIBLIB to the path of the zlib library.
Requires zlib, version 1.0.4 or above.
Note: this only applies when you build XmHTML with the default Makefile.
4. Compiling a stand-alone version of the raw HTML parser
---------------------------------------------------------
The raw HTML parser can also be compiled as a stand-alone program, which
can be used to verify HTML documents and look at the repair capabilities
of the parser.
If you have selected the tools directory, this parser will be build for you.
To build this stand-alone parser manually you do the following:
enter the tools directory and type:
make -f Makefile.org HTMLparse
This will generate the standalone HTML parser. When run on a HTML input file,
it can generate two output files. One with parser details (all elements with
line numbers) and one HTML document suitable for loading into a browser.
The latter file is the output from the parser itself, and is not a copy from
the document fed to the parser.
The standalone parser has the following command line options:
-debug
Displays the states the parser is switching through when parsing
a document.
-notext
only output the HTML tags and ignore the text between them;
-nowarn
Don't display warnings when parsing a file;
-nowrite
Don't generate output files.
-nostrict
tell's the parser to be less strict. HTML 3.2 violation warnings will
still be issued but unterminated elements are kept in place.
5. GIF images and the Unisys LZW patent
---------------------------------------
A lot of HTML documents contain GIF images in which the raster data has
been compressed with the LZW compression algorithm. Unfortunately, LZW is
covered by a software patent which is owned by Unisys Corporation. In the past,
Unisys has allowed the use of this patent for decoding GIF images without the
need of a license, but this attitude has changed considerably. Unisys now
requires one to obtain a license for this patent for GIF-decoding in software
such as XmHTML which is released for free and which may be freely
redistributed.
As a workaround, XmHTML converts the GIF-format LZW data to compress-format
LZW data. (The standard UNIX compress utility also uses LZW, but with a
slightly different file format.) This conversion does *not* decompress the
data; it simply converts it to a different file format. XmHTML then calls
uncompress to actually decompress the data.
I have been told by several notable people that the LZW patent covers
compression only, and does not cover decompression. The original patent however
covers both compression *and* decompression in 186 claims, and since all 186
claims have been granted by the US patent office back in 1986, I'm going to
stick with my workaround. At least for now.
Software patents in general are a bad idea. Consider supporting the
League for Programming Freedom <http://www.lpf.org/>.
For Unisys's slant on things (mostly regarding GIF), see
<http://www.unisys.com/LeadStory/lzwterms.html> and
<http://www.unisys.com/LeadStory/lzwfaq.html>. These pages mention
an email address for feedback (these links may be out of data).
<http://www.xmission.com:80/~mgm/gif/> has pointers to other interesting
information.
A very interesting article about this Gif controversy can be found at:
<http://www.omnipresence.com/Amiga/News/AR/ar311_Sections/feature5.HTML>
If you have or want to obtain a license which allows you to use the LZW
algorithm, the file docs/README.gifs describes how you can add your own LZW
decoder to XmHTML.
5.1 GIF and GZF and XmHTML
--------------------------
XmHTML offers some sort of alternative to the GIF format: GZF.
This is a rather compatible with GIF. It only differs in the way the
compressed raster data is stored: instead of using LZW, it uses the deflate
format. The deflate format is in the public domain (see RFC 1950 and
1951) and as such is not and can't be challenged by coorporate patent hunters.
There are multiple advantages to the deflate format: it's smaller than LZW
(an average of 20% with extremes to more than 50%) and the compress/decompress
routines are freely available in the form of zlib.
XmHTML comes with a gif to gzf translator (to be found in the tools directory)
which translates *all* types of GIF images to GZF images using the workaround
mentioned above. libXmHTML contains a convenience function which does the same.
The purpose of the GZF format in combination with XmHTML is to offer some
sort of speedup: when you need to display a GIF image, it can be costly to
use the workaround every time the document is displayed. What you can do
instead is to translate the GIF image to a GZF image and use that image
whenever the GIF image is requested. This way you can still support GIF images
without a costly LZW license and without a delay by using the workaround.
The file docs/README.gzf describes how to use LZWStream for your own purposes.
6. Personalizing XmHTML
-----------------------
The include file src/XmHTMLfuncs.h contains a number of configuration options
that influence XmHTML's default behaviour.
Options include:
- time window in which a button press & release trigger the
XmNactivateCallback;
- default horizontal & vertical margins;
- default horizontal & vertical scroll increment;
- default character set and fonts for proportional and fixed text;
- default font sizes;
- default column and row spacing in tables;
- default screen gamma value;
- progressive loader default buffer size & timings;
- maximum number of iterations several layout routines may reach;
- absolute maximum number of colors XmHTML may use;
- initial colorhashtable size.
All configuration options (and the effect they have on XmHTML's default
behavior) are described in depth in src/XmHTMLfuncs.h
You can also modify the warnings messages XmHTML can issue. The file
src/warnings.lst contains the text for each and every warning message
XmHTML can issue. This file is used to generate a table of all warning
messages using the mkStrings program (see below).
You can change them as you like provided three conditions are met:
a) the order of the lines is not changed;
b) each modification must preserve the order and number of the
printf format specifiers.
c) the entire library must be recompiled.
Failing to comply with these conditions can lead to erratic behavior.
7. Things missing in this version
---------------------------------
- server-side imagemaps
- no applets
- getting formatted text from the widget in plain or PostScript format.
Work is being done on that.
8. LessTif compatibility
------------------------
XmHTML has received limited testing under LessTif 0.80. It runs fine,
scrolling is actually smoothier than under Motif 2.0.1.
There is a small screen-update problem: the first time XmHTML is up and
text is scrolled up, XmHTML does not clear the bottom part of the display
area properly. This goes away by resizing the widget a bit.
9. Adding Warning and Error messages
------------------------------------
If you are modifying the XmHTML source and want to add a warning or error
message, you can use the following functions:
- _XmHTMLWarning(__WFUNC__(Widget w, String routine), String fmt, ...)
Displays a warning message on stderr.
- _XmHTMLError(__WFUNC__(Widget w, String routine), String fmt, ...)
Displays an error message on stderr and exits.
- _XmHTMLAllocError(Widget w, char *module, char *routine, char *func, int size)
Displays an error message on stderr and exits.
In these functions, routine is the name of the routine that is calling the
function. In the first two, these are only displayed when DEBUG was defined
during compilation. The latter function always displays them. They may
_never_ be NULL since they aren't checked.
__WFUNC__ is a define that includes file & line number information when DEBUG
was defined during compilation, and when DEBUG is not defined it only uses
the Widget arg (the reason behind this is that the actual warning & error
routines have different args for production and distribution builds).
When the _XmHTMLError function is called, XmHTML will append a message
saying to contact the XmHTML author. You can change this message by
altering the string ``authors'' in src/error.c
The first two functions allow you to print out any message you want: fmt is a
printf format string and ... are arguments to fmt. One big WARNING: the
total size of fmt and arguments may not exceed 512 bytes. If you want to
use warning message that large, think of a smaller one or use multiple warning
messages.
The last function is only used when a check on an allocation fails: func is
the name of the memory allocation function that failed (malloc, calloc, ...)
and size is the size of the memory that was requested. It is hardly used by
XmHTML itself; production builds use either asserted versions of the memory
allocation routines or dmalloc, while distribution builds use the Xt versions.
All of them will exit XmHTML when allocation fails (the first two will dump
core).
10. mkStrings
-------------
The src/ directory contains a small program, mkStrings, that is used to
generate a Motif-specific string table. A string table is a table containing
all (or a number of) resource names defined and used by a Widget (or
application).
mkStrings is a pretty generic tool: it reads any list of strings from
standard input and sends the generated C file to standard output.
Usage:
mkString [name] [ch]
Where:
name: name of the application or library for which a stringtable must
be generated. This name is used to generate the name of stringtable;
c : generate a C source file;
h : generate a C include file;
The c and h options are mutually exclusive.
I personally find mkStrings a very usefull tool (and absolutely necessary
if one wants to work with stringtables). If you are a Widget writer yourself
or designing an application that uses it's own resources, you will find
mkStrings an absolute valuable tool. It's easy. Use it. Spread it.
10.1 About the generated files
-------------------------------
When a C source file is generated, the contents of the input is stored
in a character array where each line is terminated by a \0.
This character array is named _<name>Strings.
When a C include file is generated, two sets of #defines are created (String
is a single line read from the input and index is the index in the actual
stringtable):
- one set consisting of #define <prefix><String> <String>
- one set consisting of #define <prefix><String> _<name>Strings[index]
The first set is surrounded by a #ifndef <name>_STRINGDEFINES/#endif.
10.2 About the generated #defines
---------------------------------
When a line starts with a lowercase character, a XmN #define is created,
and when a line starts with a uppercase character, both a XmC and a XmR
#define are created. To prevent name clashes with existing (or future)
defines, each #define is surrounded with a #ifndef/#endif.
10.3 Examples
-------------
Using the following input file (the --- .... of in/output --- is *not*
generated by mkStrings):
---- Start of input ---
BalloonStyle
balloonStyle
---- End of input ---
The generated C source file is:
---- Start of output ---
#include <Xm/XmP.h>
#if XtSpecificationRelease < 6
#include <X11/IntrinsicP.h>
#endif
/*****
* The missing commas are intentional. Let the compiler
* concatenate the strings
*****/
_XmConst char _BalloonStrings[] =
/* 0 */ "BalloonStyle\0"
/* 13 */ "balloonStyle\0"
/* ????? */
"\0";
---- End of output ---
(Generated by using: ./mkString Balloon c < input > output)
and the generated C include file is:
---- Start of output ---
#ifndef __Balloon_Strings_h__
#define __Balloon_Strings_h__
_XFUNCPROTOBEGIN
/*****
* Don't define Balloon_STRINGDEFINES if you want to save space
*****/
#ifndef Balloon_STRINGDEFINES
# ifndef _XmConst
# define _XmConst
# endif
extern _XmConst char _BalloonStrings[];
#endif
#ifdef Balloon_STRINGDEFINES
# ifndef XmCBalloonStyle
# define XmCBalloonStyle "BalloonStyle"
# endif
# ifndef XmRBalloonStyle
# define XmRBalloonStyle "BalloonStyle"
# endif
#else
# ifndef XmCBalloonStyle
# define XmCBalloonStyle ((char *)&_BalloonStrings[0])
# endif
# ifndef XmRBalloonStyle
# define XmRBalloonStyle ((char *)&_BalloonStrings[0])
# endif
#endif
#ifdef Balloon_STRINGDEFINES
# ifndef XmNballoonStyle
# define XmNballoonStyle "balloonStyle"
# endif
#else
# ifndef XmNballoonStyle
# define XmNballoonStyle ((char *)&_BalloonStrings[13])
# endif
#endif
_XFUNCPROTOEND
/* Don't add anything after this endif! */
#endif /* __Balloon_Strings_h__ */
---- End of output ---
(Generated by using: ./mkString Balloon h < input > output)
11. Generating Source Documentation
-----------------------------------
XmHTML's source tree is becoming increasingly complex and huge, and therefore
not easy to comprehend. For those that want to dig into the source, there
is a small tool that extracts all function definitions and a description of
these functions.
Typing
make -f Makefile.org docs
from the root of the XmHTML root directory will generate a file called
docs/sources.desc. Please not that generating this file can take a while
and that it is pretty large: it will contain a description of almost all
functions in the ./src directory (in excess of 200kb, and that's the reason
it is not included by default).
12. Internationalization
------------------------
XmHTML contains prelimenary i18n support. To enable this, define I18N when
compiling the library. The default is to build without i18n support since
full i18n support can lead to a slight performance decrease.
13. Troubleshooting and Other Points To Ponder
----------------------------------------------
- All files have a tabstop of 4, so if your editor has a different one,
it will look ugly.
- dithering: there are two algorithms available that allow XmHTML to construct
a default palette if none has been specified (the XmNimageMapToPalette
resource is set but no palette has been given with the XmNimagePalette
resource). The default algorithm constructs an evenly distributed palette in
RGB space but is not always able to match the requested number of colors and
requires a minumum of 8 colors. The alternative always creates a palette
with the requested number of colors but does not always succeed in creating
an evenly distributed palette. You can choose the latter by defining
DITHER_SIMPLE_COLORMAP.
- If you are getting wierd results when scrolling, try recompiling with
NO_XLIB_ILLEGAL_ACCESS defined. This will make XmHTML use the official
intrinsics XtGetValues method instead of accessing the instance structures
of the scrollbars directly.
- If you keep getting undefined references to _XmDrawShadows
(or XmeDrawShadows), try recompiling with NO_XM_ILLEGAL_ACCESS defined.
Horizontal rules, buttoned anchors and table borders will look a bit
different then but you will still get good results.
- XmHTML is a subclass of Manager, but utilizes a number of resources from
other widgets, noticably DrawingArea and ScrollBar. Some of XmHTML's
resources are enumeration types, which are converted to an internal
representation type by the XmRepType functions.
Because XmHTML uses resources from the named widgets (and others), it needs
to get access to the internal resource translation tables (resource file
string -> enum). It does does by calling the XmRepTypeGetId function with
the name of the resource converters it has to use. When a converter is not
found, XmHTML will issue a warning message:
"Warning: Representation type resource convertor <some name> not found
Please contact ripley@xs4all.nl"
The <some name> is the name of the offending convertor. Chances are that this
*can* happen on some early versions of Motif 1.2 and/or 1.1
If you whish to solve this by yourself, a little program is distributed along
with XmHTML: tools/GetRepTypes.c If you compile and run this program you will
get a list of all resource converters that are installed by Motif on
*your* system.
- you can get rid of the rcsId's that are contained in each .c file by
adding -Dproduction when compiling the library. Note however that this
is only allowed when building a real production build, e.g., with -DNDEBUG
also defined.
- you can safely strip the library (at least I can). On my system (Linux),
this reduces the size of the production-build static library to a mere
270kb, while the dynamic version comes at 320kb.
- if you really hate stringtables, define -DXmHTML_STRINGDEFINES when
compiling the library. This will cause XmHTML to #define each and every
resource name, class, representation type as well as the warning
messages instead of referring to the string tables. Doing this will have
a severe impact on the size of the library and *will* affect performance.
Also note that in this case you will have to add -DXmHTML_STRINGDEFINES
when compiling an application that uses this impaired library (you'll get
undefined references to _XmHTMLStrings and _XmHTMLMessages otherwise).
14. XmHTML Mailing List
-----------------------
XmHTML has it's own mailing list, situated at simplicity.net. This list
is a general XmHTML discussion list and is also used to announce new
releases and patches.
You can subscribe to the XmHTML mailing list by sending an email to
Majordomo@simplicity.net and placing the following in the BODY of your mail:
subscribe xmhtml-dev your email address
You will receive a message confirming your subscribtion.
This service has been kindly provided by Brian Dowling (brian@simplicity.net)
from Simplicity Communications, www.simplicity.net.
15. Where to get it
-------------------
The main XmHTML homepage is located at http://www.xs4all.nl/~ripley/XmHTML/
New releases will be announced at the above location.
16. How to contact us
---------------------
You can reach us by email at ripley@xs4all.nl
Our address is:
Lau Mazirellaan 77
2525 ZK The Hague
The Netherlands
tel: (00-31) - (0)70 - 3885918
If you have any comments, encounter problems, suggestions or just want to tell
us how great XmHTML is ;-) feel free to contact us.
Koen D'Hondt & Niels Hilbrink
Ripley Software Development.