* KayHTML - advanced HTML handling for Kaya The aim of the KayHTML modules is to provide a set of (X)HTML handling libraries for Kaya, that encourage (and enforce where possible) good quality code, allow straightforward construction and templating of web pages, and interface well with Kaya's built-in session handling to allow as much separation of logic from template as is possible. Additionally, to provide an alternative Webprog library suitable for larger web applications. This document is intended as a developer's reference - also see comments in the source code and the generated documentation. * Files ** HTMLDocument.k This file sets out the basic structure of a HTML document and provides general editing capability. High-level operations such as templating should probably be provided by another module. It is divided into several parts: 1) Data type definitions 2) Document constructor and toString convertor 3) <head> data editing (including HTTP headers) 4) Setting generic attributes on elements 5) Handling block-level elements 6) Handling inline elements 7) Handling tables 8) Handling forms (webapp/webprog-enabled or otherwise) TODO: Need a fromString function that will appropriately fill an ElementTree. Writing one that will deal with HTML as well as XHTML may be tricky, due to optional end tags such as </p>, and even optional start tags such as <head>. ** ElementTree.k This file provides low-level operations on a document tree structure. Note that its print-out operation will always escape < to < and so on, so it's only possible to add HTML tags as part of an element. This guarantees well-formedness of code. TODO: This needs a generic fromString function that will construct an ElementTree from a String of XML data. ** ElementTreeData.k This file defines the document tree structure. Nothing other than data definitions should live here. ** HTMLnesting.k This file partially defines the nesting behaviour allowed in the HTML DTD. Any divergence from the HTML 4.01 DTD's allowed nesting is a bug and should be fixed. ** HTMLentities.k and XMLentities.k Processing functions to convert between literal UTF-8 characters (which are stored in Kaya as a UCS Char()), numeric references, and named references (where they exist in the standard). Output from KayHTML should always use either literal UTF-8 characters or numeric references, but users may find it convenient to enter named entities. Internal storage should always be as literal UCS Char's, to make length-dependent functions work properly. Use of XMLentities.k for non-(X)HTML documents will require adding an option to disable the processing of the HTMLentities.k data except for the five standard named entities. ** Webprog.k Base functions for the 'webprog' program type. Similar to 'Webapp.k' ** URL.k [TODO] URL manipulation functions to make constructing and properly URLencoding URLs a bit easier. * User documentation When it gets stable enough it will need some. At the moment the HTMLtest.k program gives a quick example of how the HTMLDocument API works, and the webprog.k -> simple.cgi very simply demonstrates webprog-style programs. * Authors and copyright KayHTML is copyright Chris Morris 2005 except where otherwise stated. It is released under the GNU Lesser General Public License 2.1