9.1 Writing documents

The library library(sgml_write) provides the inverse of the parser, converting the parser's output back into a file. This process is fairly simple for XML, but due to the power of the SGML DTD it is much harder to achieve a reasonable generic result for SGML.

These predicates can write the output in two encoding schemas depending on the encoding of the Stream. In UTF-8 mode, all characters are encoded using UTF-8 sequences. In ISO Latin-1 mode, characters outside the ISO Latin-1 range are represented using a named character entity if provided by the DTD or a numeric character entity.

xml_write(+Stream, +Term, +Options)

Write the XML header with encoding information and the content of the document as represented by Term to Stream. This predicate deals with XML with or without namespaces. If namespace identifiers are not provided they are generated. This predicate defines the following Options

dtd(DTD)

Specify the DTD. In SGML documents the DTD is required to distinguish between elements that are declared empty in the DTD and elements that just happen to have no content. Further optimisation (shortref, omitted tags, etc.) could be considered in the future. The DTD is also used to find the declared named character entities.

doctype(Doctype)

Document type to include in the header. When omitted it is taken from the outer element.

header(Bool)

If Bool is false, the XML header is suppressed. Useful for embedding in other XML streams.

layout(Bool)

Do/do not emit layout characters to make the output readable, Default is to emit layout. With layout enabled, elements only containing other elements are written using increasing indentation. This introduces (depending on the mode and defined whitespace handling) CDATA sequences with only layout between elements when read back in. If false, no layout characters are added. As this mode does not need to analyse the document it is faster and guarantees correct output when read back. Unfortunately the output is hardly human readable and causes problems with many editors.

indent(Integer)

Set the initial element indentation. It more than zero, the indent is written before the document.

nsmap(Map)

Set the initial namespace map. Map is a list of Name = URI. This option, together with header and ident is added to use xml_write/3 to generate XML that is embedded in a larger XML document.

net(Bool)

Use/do not use Null End Tags. For XML, this applies only to empty elements, so you get <foo/> (default, net(true)) or <foo></foo> (net(false)). For SGML, this applies to empty elements, so you get <foo> (if foo is declared to be EMPTY in the DTD), <foo></foo> (default, net(false)) or <foo// (net(true)). In SGML code, short character content not containing / can be emitted as <b>xxx</b> (default, net(false) or <b/xxx/ (net(true))

sgml_write(+Stream, +Term, +Options)

Write the SGML DOCTYPE header and the content of the document as represented by Term to Stream. The Options are described with xml_write/3.

html_write(+Stream, +Term, +Options)

Same as sgml_write/3, but passes the HTML DTD as obtained from dtd/2. The Options are described with xml_write/3.