HaXml-1.24: Utilities for manipulating XML documents

Portability | portable
Stability | experimental
Maintainer | simons@cryp.to
Safe Haskell | Safe-Inferred

Text.XML.HaXml.Verbatim

Description

The preferred method for rendering a `Document` or single `Content` is by using the pretty printing facility defined in Pretty. Pretty-printing does not work well for cases, however, where the formatting in the XML document is significant. Examples of this case are XHTML's `<pre>` tag, Docbook's `<literallayout>` tag, and many more.

Theoretically, the document author could avoid this problem by wrapping the contents of these tags in a <![CDATA[...]]> section, but often this is not practical, for instance when the literal-layout section contains other elements. Finally, program writers could manually format these elements by transforming them into a `literal` string in their `CFliter`, etc., but this is annoying to do and prone to omissions and formatting errors.

As an alternative, this module provides the function `verbatim`, which will format XML `Content` as a `String` while retaining the formatting of the input document unchanged.

Known problems:

- HaXml's parser eats line feeds between two tags.
- `Attribute`s should be formatted by making them an instance of `Verbatim` as well, but since an `Attribute` is just a tuple, not a full data type, the helper function `verbAttr` must be used instead.
- `CMisc` is not yet supported.
- `Element`s, which contain no content, are formatted as `<element-name/>`, even if they were not defined as being of type `EMPTY`. In XML this perfectly alright, but in SGML it is not. Those, who wish to use `verbatim` to format parts of say an HTML page will have to (a) replace problematic elements by `literal`s before running `verbatim` or (b) use a second search-and-replace stage to fix this.

Synopsis

- qname :: QName -> String
- class Verbatim a where
  - verbatim :: a -> String
- verbAttr :: Attribute -> String

# Documentation

qname :: QName -> String

class Verbatim a where

This class promises that the function `verbatim` knows how to format this data type into a string without changing the formatting.

Methods

verbatim :: a -> String

Instances

Verbatim Char |
Verbatim AttValue |
Verbatim Reference |
Verbatim a => Verbatim [a] |
Verbatim (Content i) |
Verbatim (Element i) |
(Verbatim a, Verbatim b) => Verbatim (Either a b) |

verbAttr :: Attribute -> String

This is a helper function is required because Haskell does not allow to make an ordinary tuple (like `Attribute`) an instance of a class. The resulting output will preface the actual attribute with a single blank so that lists of `Attribute`s can be handled implicitly by the definition for lists of `Verbatim` data types.