#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\nMy 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.}}