A Web page is divided into 5 parts: banner, corner, sidebar, body, and continuation. ht2html lets you control which of these parts are included, and you control what goes in each of these parts. Here's a picture:
+-----------+-------------------------------------------------+ | | | | corner | banner | | | | +-----------+-------------------------------------------------+ | | | | sidebar | body | | | | | | | | | | | | | | | | | | | | ... | ... | +-----------+-------------------------------------------------+ | | | continuation | | | | | | | | ... | +-------------------------------------------------------------+
Normally the corner, banner, sidebar, and body are each placed into cells of a table. This table is closed just before the continuation.
You can omit any of these 5 elements; by default there is no continuation, so you have to do something explicit to include that on the page. Without the continuation, the sidebar will extend to the bottom of the page.
If you omit the banner, you do not get a corner. In that case you should put any corner HTML in the first cell of the sidebar. If you have no sidebar, the table will actually be closed after the banner and both the body and continuation will be outside the table, at the full width of the page.
The banner can contain any html you want, but the python.org site uses this area to provide links for top level topic areas that we want to be accessible from any page. We call these site links. ht2html provides a class called Banner which automatically lays out a specified set of links into rows and columns (by default 4) for the banner area.
Banner's constructor takes two arguments, a list of links and the number of columns to use for layout. Links are inserted from left to right, top to bottom, in their own nested table. As many rows as needed are used so that all the links are displayed. The last row may contain some empty cells if the number of links isn't a multiple of columns.
Each element of the list argument must be a tuple of the form (URL, LTEXT [, EXTRA]), where URL is either a string or None. If URL is a string, it is used in an anchor tag wrapped around the LTEXT. If the URL is None, then LTEXT is not hyperlinked, but inserted into the cell verbatim. EXTRA is optional and if provided, can be arbitrary html, which gets written after the hyperlinked LTEXT.
Again, the corner can contain any html, but usually this contains a logo for the site which links to the site's home page. You manage this explicitly though, so you can do anything you want with this area.
Usually the sidebar is used for a table of contents for the subdirectory the page is in. ht2html provides a class called Sidebar which manages a table of contents for this area.
Sidebar takes one argument in its constructor: a list of links similar to that used by the Banner class. Each element of this list can be either a string or a tuple. If it's a tuple, it has the same semantics as with the Banner class. If the element is a string, then it's interpreted as a table-of-contents section header and it is displayed (non-hyperlinked) in reverse video.
This contains the meat of your web page. You write all this stuff and ht2html just sticks it in the right place in the page's table. The body can contain nested tables, or any other html, and this usually ends up looking as you expect (but see the Bugs and peculiarities section).
For long pages, you may not want to have a sidebar that extends to the bottom of the web page. Maybe part of your text looks better if it extended to the full width of the page. You specify the separation between the body and the continuation text by including a special comment in your .ht file:
<!--table-stop-->
The mark must look exactly like this (don't put any spaces in the angle brackets). Put this where you'd like the continuation html to start. You can't span forms or tables across this mark because ht2html substitutes row and table end tags for this special marker.