Menu
▾
▴
[linuxdc-cvs] CVS: docs/tools/ht2html README,NONE,1.1
|
From: Karl T. K. <ka...@us...> - 2001-03-05 01:59:03
|
Update of /cvsroot/linuxdc/docs/tools/ht2html In directory usw-pr-cvs1:/tmp/cvs-serv5049 Added Files: README Log Message: Oops --- NEW FILE --- ht2html.py -- The www.python.org Web site generator Contact: Barry Warsaw Email: bw...@py... Download: http://www.python.org/~bwarsaw/software/pyware.html Version: 1.0 INTRODUCTION HTML frames are cool in theory, but horrible in practice. The biggest problem with them is that it totally breaks navigation, especially when you end up at a frame page not through the frameset HTML. Bookmarks are also more difficult when using frames. So the brothers Van Rossum designed the current python.org Web site to use HTML tables, providing much of the benefit of a frames oriented table of contents, without the hassles. Naturally, Guido had to write a Python script to generate the python.org style, which was really cool, except he probably didn't figure that other people would want to generate Web pages using slightly modified versions of that style. Guido's script isn't easily extensible or modifiable, so Andrew Kuchling did another implementation based on Digicool's DocumentTemplate. I couldn't grok Andrew's script -- which says much more about me than his code or DocumentTemplate -- so I did what any self-respecting hacker would do. I reinvented the wheel for the third time. Hey, at least this time I mostly understand how it works. This script is called `ht2html.py' because it generates .html files from .ht template files. The format of these .ht files is essentially normal HTML, with a set of optional RFC822-like headers at the top of the file. These headers specify certain options that ht2html's various classes support. You must include at least one blank line between the last header and the start of the body HTML. More details below. LAYOUTS 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 (see below for how this works). 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. BANNER 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 (described below) 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. CORNER 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. SIDEBAR 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. BODY 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 PECULIARITIES AND BUGS below). CONTINUATION 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 tag in your .ht file: <!--table-stop--> The tag 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 tag because ht2html substitutes row and table end tags for this special marker. PECULIARITIES AND BUGS If you have really wide <pre> stuff in the body, the banner can get drawn to wide, at least with Netscape 4.x. The mixin class structure doesn't work as well as I'd like. Writing the style class is more awkward than it should be, but at least there are enough examples for you to go by. USAGE See the docstring for ht2html.py for usage information and more documentation. EXAMPLES This is what you really want -- examples of how to create your own Web site styles. These are done by creating a `generator' class, which customizes not only style elements such as the sidebar colors and the corner icon, but also such elements as the copyright notice and what RFC822-style headers are recognized. Sorry, but there's no really good documentation for how to do this yet, so UTSL. Here are a list of generator classes I've included: PDOGenerator.py -- this is the generator class for the www.python.org site. If you can find a .ht file for a .html file on the site, you can see how this generator works. Not all .ht files are uploaded to the public web site, so hunt around. If you're interested, let me know and I'll try to twiddle some makefiles to get the corresponding .ht files uploaded. BAWGenerator.py -- this is the generator for my personal Web pages at http://www.python.org/~bwarsaw JPyGenerator.py -- this is the generator for the www.jpython.org site. JPyLocalGenerator.py -- this is the generator for the documentation that comes with JPython. The neat thing about this is that I can maintain one set of source .ht files for both the on-line version of the docs <http://www.jpython.org/docs/> and the off-line version that you can access via file: URLs once you've installed JPython. This handles the situation where some links for the off-line version will have to send you out onto the Web. Makes my life much easier! StandardGenerator.py -- not really used anywhere but provides a fallback when no other generator is specified. Also, it shows you how simple a generator can be. |
