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
  omitXMLDeclaration = false | true | auto : false
/>

Force XXE to use the specified save options for this type of document, unless Options → Preferences, Save tab, Override settings specified in config. files checkbox has been checked by the user, in which case, it is the save options specified in the dialog box which are used.

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>
```

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" />

<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