Web library man pages

# Web page library manual

This is a preliminary manual for the WebTk HTML display library. The display library is in the file `dpackage.tcl`. WebTk is a client of this package, so this document should give you a tiny bit of insight to how WebTk uses the display library.

The Web library is designed to be easy to use for simple applications, yet provide a flexible framework for sophisticated solutions. The library is packaged so that all procedures and external variables are prefixed by `HM`. It is safe to run `sed` over the library to globally change `HM` to something else if needed.

For the simplest use of the library

1. Create a text widget, called `.text`
2. Initialize the text widget by calling `HMinit_win .text`
3. Put an HTML document into the tcl variable `html`
4. render the document by calling `HMparse_html $html "HMrender .text"`

Any time the user clicks on a hypertext link, the library will call the procedure (which you need to supply):

    	proc HMlink_callback {win href} { ...}
       		win      The name of the text widget (.text)
       		href     The name of the link

Presumably this procedure will figure out how to turn the link into a tcl variable containing HTML, and then call

1. `HMreset_win .text` to reset the text widget
2. render the document by calling `HMparse_html $html "HMrender .text"`

When the library encounters an inline image while rendering a page, it calls the procedure (you supply this one too):

    	proc HMset_image {handle src}
    		handle  a handle that identifies this image
    		src     The name (or url) of the image

Its up to the application to fetch the image, and make it into a TK image, by using a call something like:

    	image create photo $image_name -file $src

Once the image is loaded into TK, the application should call

    	HMgot_image $handle $image_name

where `$handle` is the token passed to `HMset_image` and `$image_name` is the name of the TK image. If, for some reason the image could not be obtained, you may set `image_name` to a text string that will be displayed instead. If you never call `HMset_image` at all, the alt entry in the image parameter list will be displayed instead.

## Advanced usage

The HTML library is programmable in several ways. This section will be expanded as time permits.

- There are procedures available to change the look of the rendering. Some of the easier ones to use are:
  `
  HMset_indent $text_widget $indent_in_cm
  `Sets the indent spacing for list constructs `
  HMset_state $text_widget -param value -param value ...
  `overrides the default settings for several of the display parameters. This will get fleshed out later on.
- Some of the built-in procedures may be replaced entirely by advanced applications. A good example is
  `
  HMlink_setup $text_widget $href
  `Which is called every time a hypertext link is first seen, to set up the link behaviors.
- New procedures may be written that are automatically recognized by the library (based on their naming convention) and called at appropriate times.
  `
  HMtag_html-tag $text_widget $parameter_list text
  `Each HTML tag can have its own procedure that gets called automatically when the tag is seen. New behaviors can be associated with tags using this technique.

I plan to expand the library interface, providing both more call-backs and infomation on existing call-backs in future releases.

home