@@ -315,16 +315,47 @@ elements, converting characters such as `>` to HTML entities. For example:
315315
316316### Marks
317317
318−The mark for a raw `$manx` is a `%hymn`. This mark is included in the `%base`
319−desk. The mark for a rendered HTML cord is `%html`. The `%hymn` mark includes
320−conversion methods to both `%html` and `%mime`. The `%html` mark includes
321−conversion methods to `%mime` and `%hymn`.
322−
323−If you want to produce an HTML document through Eyre's scry interface, for
324−example, you can either produce a `$manx` with a `%hymn` mark and let Eyre
325−convert it to `%html`, or else you can call `++en-xml:html` and then `++crip` on
326−the product of your Sail expressions and produce a cord with an `%html` mark
327−directly.
318+There are a few different HTML and XML related marks, so it can be a bit
319+confusing. We'll look at the ones you're most likely to use.
320+
321+#### `%html`
322+
323+- Type: `@t`
324+
325+This mark is used for HTML that has been printed as text in a cord. You may wish
326+to return this mark when serving pages to the web. To do so, you must run the
327+`$manx` produced by your Sail expressions through `++en-xml:html`, and then run
328+the resulting `tape` through `++crip`.
329+
330+#### `%hymn`
331+
332+- Type: `$manx`
333+
334+The `%hymn` mark is intended to be used for complete HTML documents - having an
335+`<html>` root element, `<head>`, `<body>`, etc. This isn't enforced on
336+the type level but it is assumed in certain mark conversion pathways. Rather
337+than calling `++en-xml:html` on the `$manx` produced by your Sail expressions
338+and returning an `%html` mark, you may wish to return the `$manx` directly as a
339+`%hymn` and let Eyre handle converting it to `%html` before giving it to web
340+clients.
341+
342+#### `%elem`
343+
344+- Type: `$manx`
345+
346+The type of the `%elem` mark is a `$manx`, just like a `%hymn`. While `%hymn`s
347+are intended for complete HTML documents, `%elem`s are intended for more general
348+XML structures. You may wish to use an `%elem` mark if you're producing smaller
349+fragments of XML or HTML rather than whole documents. Like a `%hymn`, Eyre can
350+automatically convert it to `%html` and provide it to web clients.
351+
352+#### Summary
353+
354+In general, if you're going to be composing web pages and serving them to web
355+clients, running the result of your Sail through `++en-xml:html`, `++crip`ping
356+it and producing `%html` is the most straight-forward approach. If you might
357+want to pass around a `$manx` to other agents or ships which may wish to
358+manipulate it futher, a `%hymn` or `%elem` is better.
328359
329360## Sail Runes
330361