#lang scribble/doc @; THIS FILE IS GENERATED @(require scribble/manual) @(require (for-label (planet neil/html-writing:1:=0))) @(require (for-label racket)) @title[#:version "0.1"]{@bold{html-writing}: Writing HTML from SXML/xexp in Racket} @author{Neil Van Dyke} License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/racket-html-writing/" #:underline? #f]{http://www.neilvandyke.org/racket-html-writing/} @defmodule[(planet neil/html-writing:1:=0)] @section{Introduction} @emph{Note: This package is in a state of active development, and some interface changes, perhaps not backward-compatible, are expected. Documentation is gravely lacking.} The @bold{html-writing} package provides support for writing HTML encoded as @link["http://www.neilvandyke.org/racket-xexp/"]{SXML/@emph{xexp}} as HTML. This can be used for hand-constructed HTML, HTML constructed by program, or emitting HTML that has been read via @link["http://www.neilvandyke.org/racket-html-parsing/"]{html-parsing}. For a different way of writing HTML from chunks of hand-constructed @emph{xexp}, see the @link["http://www.neilvandyke.org/html-template-scheme/"]{html-template} package. @section{Foreign Filters} @defproc[ (error-html-writing-foreign-filter (object any/c) (context any/c)) any/c]{ !!! } @defparam[current-html-writing-foreign-filter x any/c]{ !!! } @section{Writing} !!! The two most common procedures in @bold{html-writing} for writing HTML from an @emph{xexp} representation are @tt{write-html} and @tt{xexp->html}. These are perhaps most useful for emitting the result of parsed and transformed input HTML. They can also be used for emitting HTML from generated or handwritten @emph{xexp}. @subsection{Writing Attributes} @defproc[ (write-html-attribute-value-char (chr any/c) (out any/c)) any/c]{ !!! } @defproc[ (write-html-attribute-value-string (str any/c) (out any/c)) any/c]{ !!! } @defproc[ (write-html-attribute-value-part/fixed (val any/c) (out any/c) (foreign-filter any/c)) any/c]{ !!! } @defproc[ (write-html-attribute-value (attr any/c) (out any/c) (foreign-filter any/c)) any/c]{ !!! } @defproc[ (write-html-attribute (attr any/c) (out any/c) (foreign-filter any/c)) any/c]{ !!! } @defproc[ (write-html-attribute-list (attr-list any/c) (out any/c) (foreign-filter any/c)) any/c]{ !!! } @defproc[ (write-html-attribute-or-list (attr-or-list any/c) (out any/c) (foreign-filter any/c)) any/c]{ !!! } @subsection{Writing Other} @defproc[ (write-html-decl/fixed (xexp any/c) (out any/c)) any/c]{ !!! } @defproc[ (write-html-pi/fixed (xexp any/c) (out any/c)) any/c]{ !!! } @defproc[ (write-html-entity-ref (ref any/c) (out any/c)) any/c]{ !!! } @subsection{Writing HTML} @defproc[ (write-html (xexp any/c) (out any/c) (foreign-filter any/c)) any/c]{ Writes a conventional HTML transliteration of the @emph{xexp} @schemevarfont{xexp} to output port @schemevarfont{out}. If @schemevarfont{out} is not specified, the default is the current output port. HTML elements of types that are always empty are written using HTML4-compatible XHTML tag syntax. If @schemevarfont{foreign-filter} is specified, it is a procedure of two argument that is applied to any non-@emph{xexp} (``foreign'') object encountered in @schemevarfont{xexp}, and should yield @emph{xexp}. The first argument is the object, and the second argument is a symbol for the context. The possible symbols are: !!! No inter-tag whitespace or line breaks not explicit in @schemevarfont{xexp} is emitted. The @schemevarfont{xexp} should normally include a newline at the end of the document. For example: @SCHEMEBLOCK[ (write-html '((html (head (title "My Title")) (body (\@ (bgcolor "white")) (h1 "My Heading") (p "This is a paragraph.") (p "This is another paragraph."))))) ] produces the output: @verbatim["My Title\n

My Heading

This is a paragraph.

This is\nanother paragraph.

"] } @defproc[ (xexp->html (xexp any/c)) any/c]{ Yields an HTML encoding of @emph{xexp} @schemevarfont{xexp} as a string. For example: @SCHEMEBLOCK[ (xexp->html (html->xexp "

This isbold italic text.

")) ==> "

This is
bold italic text.

" ] Note that, since this procedure constructs a string, it is normally best used when the HTML is small. When encoding HTML documents of conventional size, @tt{write-html} is likely more efficient. } @section{History} @itemize[ @item{Version 0.1 --- 2011-08-21 -- PLaneT @tt{(1 0)} Part of forked development from HtmlPrag, with substantial changes. } ] @section[#:tag "Legal"]{Legal} Copyright (c) 2004--2011 Neil Van Dyke. This program is Free Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License (LGPL 3), or (at your option) any later version. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See http://www.gnu.org/licenses/ for details. For other licenses and consulting, please contact the author. @italic{@smaller{Standard Documentation Format Note: The API signatures in this documentation are likely incorrect in some regards, such as indicating type @tt{any/c} for things that are not, and not indicating when arguments are optional. This is due to a transitioning from the Texinfo documentation format to Scribble, which the author intends to finish someday.}}