This file: README for XmHTML.
-------------------------------------------------------------------------------
| 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 CHANGES describes the day-to-day development of the widget.
The file examples/test-pages/README contains a description of the test
documents.
Table Of Contents
-----------------
1. Compiling XmHTML using Imake
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. Things missing in this version
7. LessTif compatibility
8. Adding Warning and Error messages
9. Points To Ponder
10. 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:
- Image stuff
XmHTML *requires* that you have libXpm and the xpm.h header file
installed. If you are using anything below Motif 2.0 (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).
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
- 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.
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 examples
builds everything in the examples directory. Will build libXmHTML
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.
- 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
- 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 header files get
installed in INCROOT/Xm (which most likely will be something like
/usr/X11R6/include/Xm).
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 xmkmf will produce
the toplevel Makefile. Then type make Makefiles followed by make depend. Once
this 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 probably 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.
2. Compiling XmHTML using the provided Makefiles
------------------------------------------------
If you do not have imake, or imake is configured poorly on your system,
you can compile the library and examples by using the provided makefiles.
You might want to check the make directory, it contains some toplevel
makefiles for different systems.
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 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 will not be prototyped.
HPUX might need -D_HPUX_SOURCE
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).
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.0.X *requires* libXpm.
Note: LIBDIR and LIBS are only used when building the examples
- Image stuff
XmHTML *requires* that you have libXpm and the xpm.h header file
installed. 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. dmalloc sometimes 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 so will do nicely.
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 description in the html directory.
3. Selecting supported image types
----------------------------------
Support for JPEG, PNG and GZF images are selectable compilation options.
-DHAVE_JPEG
enables JPEG support. This requires libjpeg by the Independent JPEG Group.
Version 6 or above;
-DHAVE_PNG
enables PNG support. This requires libpng, version 0.96 or above and
zlib, version 1.0.4 or above.
-DHAVE_ZLIB
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.
4. Compiling a stand-alone version of the raw HTML parser
---------------------------------------------------------
From XmHTML version 1.0.20 this is automatically done if you have selected
the tools directory.
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.
To compile this standalone version, enter the src directory and type:
make -f Makefile.org HTMLparse
-or-
cc -o HTMLparse -DPEDANTIC -DVERIFY parse.c
Both commands will produce an executable called HTMLparse.
The -DPEDANTIC flag will enable warning messages. If you don't want them,
remove it from the compiler command line.
As output, two files are produced. 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.
5. GIF images and the Unisys LZW patent
---------------------------------------
Nearly all 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. Things missing in this version
---------------------------------
- server-side imagemaps
- no tables or applets
- getting formatted text from the widget in plain or PostScript format
Form support is limited at this time. The Submit button doesn't trigger
the XmNformCallback resource yet. Scrolling large forms can go haywire.
7. 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 clean the bottom part of the display
area properly. This goes away by resizing the widget a bit.
8. 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 1024 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).
9. Points To Ponder
-------------------
- 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.
- 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.
- All files have a tabstop of 4, so if your editor has a different one,
it will look ugly.
10. How to contact us
--------------------
You can reach us by email at ripley@xs4all.nl
The XmHTML homepage is located at http://www.xs4all.nl/~ripley/eXode/XmHTML.html
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.
