23. saveOptions
Prev | Chapter 7. Configuration elements | Next

## 23. saveOptions

    <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: "`&euro;`") or as numeric character references (example: "`&#8364;`").

  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 "`&copy;`". 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.

  ### Note

  There is no need to specify the non-breaking space character (`nbsp` = `160` = `0xa0` = `0240`) as it is always implicitly added to this list.

`favorInteroperability`

  If value is `true`, favor interoperability with HTML and SGML.

  - 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).

`omitXMLDeclaration`

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

  ### Note

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

Prev | Up | Next
22. relaxng | Home | 24. schema