For a complementary way of writing HTML from SXML, see the html-template package.

1.1HTML5 Emphasis

This package will emphasize HTML5 behavior, now and in the future.
Historically, this code was written for HTML 4.x and earlier, and for XHTML.
XHTML is no longer supported. Pre-HTML5 HTML will be supported for the
forseeable future, except when that conflicts with support for HTML5.

1.2script Element

The HTML script element is handled specially, for compatibility with HTML5 and
pre-HTML5, as well as an aid for Ractive.js type="text/ractive". Specifically, when the content of the script element contains element SXML and other non-strings, those
non-strings are written as what we’ll call “CDATA faux HTML“. In this CDATA
faux HTML, strings are written without character entity escaping. This permits, say, the script to be
some kind of template that looks like HTML and that contains bits of
JavaScript. (We don’t endorse Ractive.js, but supporting script in this way seemed sensible for other reasons, and helped a Racket
developer who happened to be using that framework.)

2Foreign Filters

A foreign filter is a procedure that is called by the writing procedures
of this package when encountering an unrecognized object in the SXML. For
one hypothetical use of this, consider the embedding of absolute URL objects in
some SXML, which are converted to relative URLs at time HTML is written.

The foreign filter procedure is called with two arguments:

context, which is one the symbols 'content, 'attribute, or 'attribute-value.

3Low-Level Writing

This section lists some low-level writing procedures that are
currently provided for historical reasons, and should be considered deprecated
for now.

The two most common procedures for writing HTML from an SXML
representation are the high-level write-html and xexp->html, described in the next section.

procedure

(write-html-attribute-value-part-string

str

out)

→

void?

str:string?

out:output-port?

Deprecated.

procedure

(write-html-attribute-value-partthingout)→void?

thing:any/c

out:output-port?

Deprecated.

procedure

(write-html-attributesattr-or-listout)→void?

attr-or-list:any/c

out:output-port?

Deprecated.

procedure

(xexp->html-attribute-value-bytesxexp)→void?

xexp:any/c

Deprecated.

procedure

(write-html-declthingout)→void?

thing:any/c

out:output-string?

Deprecated.

procedure

(write-html-pithingout)→void?

thing:any/c

out:output-string?

Deprecated.

4High-Level Writing

procedure

(write-htmlxexpout)→void?

xexp:xexp?

out:output-port?

Writes conventional HTML of the SXML xexp to
output port out. If 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.

No inter-tag whitespace or line breaks not explicit in xexp is emitted. The xexp should normally include a newline at the end of
the document.

procedure

(xexp->htmlxexp)→string?

xexp:xexp?

Yields an HTML encoding of SXML xexp as a string. For example (using the html->xexp procedure from package html-parsing, to show going full-circle):

> (xexp->html

(html->xexp

"<P>This is<br<b<I>bold </foo>italic</ b > text.</p>"))

"<p>This is<br><b><i>bold italic</i></b> text.</p>"

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, write-html is likely more efficient.

procedure

(xexp->html-bytesxexp)→bytes?

xexp:xexp?

Like xexp->html, but returns a byte string instead of a string.

5Known Issues

Determine whether currently implemented way of handling !DOCTYPE is sufficiently SXML-compliant, before documenting it.

Move more to pure SXML: remove the support for character literals?

Move more to pure SXML: consider whether to eliminate & character entity references.

Many other TODO items from source code.

6History

Version 4:0 — 2016-03-25

Restored some undocumented provides that turned out to be used by the html-template package, and added documentation for them. Renamed html->bytes to xexp->html-bytes, and html-attribute-value->bytes to xexp->html-attribute-value-bytes for naming consistency. (Thanks to Sam Tobin-Hochstadt for
reporting.)

Documentation tweaks.

Version 3:5 — 2016-03-22

Non-CDATA SXML content of the script element is now treated as “CDATA faux HTML”, for the
benefit of Ractive.js.

Made error message for an attribute not nested in a list
say “attribute, not just an attribute name” rather than “valid foreign
object”.

Adding support for using SXML element syntax within script element content, to support Ractive.js type="text/ractive", even though we believe that content to be strictly
string CDATA, not DOM elements. Part of the rationale is that this should not
conflict with the normal HTML5 uses of script, and it is consistent with older HTML interpretations. (Suggested by Dan Prager.)

Removed some vestigal provides, for undocumented identifiers.

Organized unit tests a bit.

Documentation improvements, including to Known Issues.

Version 3:3 — 2016-03-21

For HTML5 compatibility, the contents of the script element are written without character entity
escaping. (Thanks to Daniel Prager.)

Fixed bug in which a valid null inside of a list would
invoke the foreign filter, rather than being ignored.

Added documentation about HTML5 now emphasized by this package.

Version 3:2 — 2016-03-02

Tweaked info.rkt, filenames.

Changed “SXML/xexp” references to “SXML”.

Version 3:1 — 2016-02-25

Fixed deps.

Version 3:0 — 2016-02-25

Moving from PLaneT to new package system.

Documented foreign filters.

Cleaning up documentation for now.

Version 2:0 — 2012-06-12

Heavy API and implementation changes (although the
previous version was not really documented), including
the following.

The suffix /fixed has been removed from all identifiers, since all
procedures now have fixed arguments.

write-html-attribute-or-list is renamed to write-html-attributes.

write-html-attribute-value-string is renamed to write-html-attribute-value-part-string.

Added html->bytes and html-attribute-value->bytes.

We no longer do backward-compatible XHTML empty element
terminators like the string " />"; now they’re just ">".

In attribute values, some additional characters are now
written as numeric character references: ASCII 0 through
31, and 127.

Got rid of the *splice* form that we have experimentally added, and
philosophically switched back to SXML’s arbitrarily nested lists for splicing
with generally less allocation.

Restored some of the handling of unnecessary list
nesting in SXML/xexp, which had been removed after
forking from HtmlPrag and a brief experiment with *splice* when trying to unify SXML and PLT xexprs.

Converted to McFly and Overeasy.

Version 0.1 — Version 1:0 — 2011-08-21

Part of forked development from HtmlPrag, with
substantial changes.

7Legal

Copyright 2004–2012, 2016 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,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.