26. saveOptions

26. saveOptions
	Chapter 6. Configuration elements

<saveOptions
  encoding = NMTOKEN
  indent = none | (int >= 0)
  maxLineLength = unbounded | (int > 0)
  addOpenLines = boolean
  cdataSectionElements = list of XPath (subset)
  saveCharsAsEntityRefs = boolean
  charsSavedAsEntityRefs = list of character ranges
  favorInteroperability = boolean
  predeclarePrefixPreferences = false | true | auto : auto
  omitXMLDeclaration = false | true | auto : false
/>

Force XXE to use the specified save options for this type of document, and this, even if different options are specified in the Save section in XMLmind XML Editor - Online Help of the Options → Preferences dialog box.

encoding

Specifies the encoding used for XML files saved by XXE.

indent

If this value is different from none, XML files saved by XXE are indented .

Note that XXE cannot indent XML files not constrained by a grammar.

indentation

Specifies the number of space characters used to indent a child element relatively to its parent element.

maxLineLength

Specifies the maximum line length for elements containing text interspersed with child elements.

This value is only used as a hint: XML files created by XXE may contain lines much longer than the specified length.

addOpenLines

If value is true, an open line is added between the child elements of a parent element (if the content model of the parent only allows child elements).

cdataSectionElements

List of XPaths specifying elements. These elements are expected to only contain text and to have an xml:space="preserve" attribute.

Text contained in elements matching any of the XPaths specified by this attribute is saved as a CDATA section. Text inside a CDATA section is not escaped which makes it more readable using a text editor. Example:

<script type="text/javascript"><![CDATA[function min(x, y) {
    return (x < y)? x : y;
}]]></script>

If an element matching any of the XPaths specified by this attribute contains anything other than text (even a comment), it is saved normally.

Note that, in most configuration elements, XXE only supports the XPath subset needed to implement XML-Schemas (but not only relative paths, also absolute paths). Moreover, for efficiency reasons, an XPath whose last step does not test an element name is ignored. For example, "foo//*" is ignored.

saveCharsAsEntityRefs

Specifies whether characters not supported by the encoding are saved as entity references (example: "€") or as numeric character references (example: "€").

Of course, for a character to be saved as an entity reference, the corresponding entity must have been defined in the DTD.

charsSavedAsEntityRefs

Specifies which characters, even if they are supported by the encoding, are always saved as entity references.

For example, the Copyright sign is supported by the ISO-8859-1 encoding but you may prefer to see it saved as "©". In such case, specify charsSavedAsEntityRefs="169".

Ignored if saveCharsAsEntityRefs is false.

This attribute contains a list of character ranges. A character range is either a single character or an actual range char1:char2.

A character may be specified using its Unicode character number, in decimal (example: 233 for e acute), in hexadecimal (example: 0xE9) or in octal (example: 0351).

Because names are easier to remember than numbers, a character may also be specified using its entity name as defined in the DocBook 4.2 DTD (example: eacute). Note that is possible whatever is the DTD or Schema targeted by the configuration file.

favorInteroperability

If value is true, favor interoperability with HTML.

Empty elements having a non empty content are saved as "<tag></tag>".
Empty elements having an empty content are saved as "<tag />" (with a space after the tag).
The CDATA sections optionally inserted (see above) in html:script and html:style elements are commented out like in the following example:
```
<script>/*<![CDATA[*/function sayHello() {
    alert("Hello <world>!");
}/*]]>*/</script>
```

predeclarePrefixPreferences

Specifies which namespace prefix declarations are to be added to the root element when saving a document.

false

Add the namespace prefix declarations which are actually needed to save the document.

Example: add just xmlns="http://www.w3.org/1999/xhtml" to the saved XHTML file.

true

Add the namespace prefix declarations which are actually needed to save the document and when possible, also add extra namespace prefix declarations (generally found in the template used to create the document and/or in the schemas to which the document is conforming) which may be useful later when you'll modify the document.

Example: add xmlns="http://www.w3.org/1999/xhtml" and also xmlns:svg="http://www.w3.org/2000/svg", xmlns:mml="http://www.w3.org/1998/Math/MathML" to the saved XHTML file because these prefixes may prove useful in the future when embedding SVG and MathML.

Note that value true is the most conservative choice because it avoids errors when, for example, some attribute values reference qualified XML names (or just namespace prefixes) as it is often the case with schemas, stylesheets, configuration files, etc. XSLT stylesheet example: the only namespace prefix actually needed to save the stylesheet below is "xsl".

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                exclude-result-prefixes="rx xslthl" 
                xmlns:rx="http://www.renderx.com/XSL/Extensions"
                xmlns:xslthl="http://xslthl.sf.net">

auto

Default value. Equivalent to false if the document is conforming to a DTD or if favorInteroperability="true" and to true otherwise.

omitXMLDeclaration

Specifies whether the XML declaration (that is, <?xml version="1.x"...?>) is to be omitted from the save file.


Omitting the XML declaration is useful when an XHTML document is delivered by the Web server to the Web browser as if it were an HTML document. That is, for the Web browser, the media type of the document is `text/html` and not `application/xhtml+xml`. This is useful because both the XML declaration and the `<!DOCTYPE>` declaration have an effect on the behavior of Web browsers. See Activating Browser Modes with Doctype.

Omitting the XML declaration is useful when an XHTML document is delivered by the Web server to the Web browser as if it were an HTML document. That is, for the Web browser, the media type of the document is text/html and not application/xhtml+xml.

This is useful because both the XML declaration and the <!DOCTYPE> declaration have an effect on the behavior of Web browsers. See Activating Browser Modes with Doctype.

false

Default value. Do not omit the XML declaration from the save file.

true

Omit the XML declaration and force the encoding of the save file to be UTF-8.

auto

Determine whether the XML declaration is to be omitted by examining the content of the document to be saved.

If the document is an XHTML document and contains <meta http-equiv="Content-Type" content="MEDIA;charset=CHARSET"/>, then:

If the media type is "text/html" and the charset is "UTF-8", then the XML declaration is omitted and the encoding of the save file is forced to be UTF-8.
Otherwise the XML declaration is not omitted but, if a valid charset has been successfully parsed, the encoding of the save file is forced to be this charset.

If the document is not an XHTML document or does not contain <meta http-equiv="Content-Type".../>, then the XML declaration is not omitted.

Element <meta charset="CHARSET"/> is considered to be equivalent to <meta http-equiv="Content-Type" content="text/html;charset=CHARSET"/>.

The values of all the aforementioned attributes are parsed in a case-insensitive manner.

Examples:

<saveOptions addOpenLines="false" predeclarePrefixPreferences="false" />

<saveOptions xmlns:htm="http://www.w3.org/1999/xhtml" 
  cdataSectionElements="htm:head/htm:script"
  omitXMLDeclaration="auto" />

<saveOptions saveCharsAsEntityRefs="true"
             charsSavedAsEntityRefs="copy reg 023400:024000"/>

Note that a saveOptions element does not replace the saveOptions element previously found in a configuration file. When a configuration file contains several saveOptions elements, these saveOptions elements are merged.

Example:

<cfg:saveOptions xmlns="" cdataSectionElements="script pre" 
                 addOpenLines="false"/>
...
<cfg:saveOptions addOpenLines="true" encoding="ISO-8859-1"/>

is equivalent to:

<cfg:saveOptions xmlns="" cdataSectionElements="script pre"
                 addOpenLines="true" encoding="ISO-8859-1" />


25. relaxng		27. schema