# Convert XML Files

Export enables you to extract all or selected content from source XML files (see Configure Element Extraction for XML Documents). It detects the following XML formats:

- generic XML

- Microsoft Office 2003 XML (Word, Excel, and Visio)

- StarOffice/OpenOffice XML (text document, presentation, and spreadsheet)

See File Format Detection for more information on format detection.

## Configure Element Extraction for XML Documents

When you convert XML files, you can specify which elements and attributes are extracted according to the file's format ID or root element. This is useful when you want to extract only relevant text elements, such as abstracts from reports, or a list of authors from an anthology.

A root element is an element in which all other elements are contained. In the XML sample below, `book` is the root element:

    <book>
      <title>XML Introduction</title>
      <product id="33-657" status="draft">XML Tutorial</product>
      <chapter>Introduction to XML
         <para>What is HTML</para>
         <para>What is XML</para>
      </chapter>
      <chapter>XML Syntax
         <para>Elements must have a closing tag</para>
         <para>Elements must be properly nested</para>
      </chapter>
    </book>

For example, you could specify that when converting files with the root element `book`, the element `title` is extracted as metadata, and only `product` elements with a `status` attribute value of `draft` are extracted.

When you extract an element, the child elements within the element are also extracted. For example, if you extract the element `chapter` from the sample above, the child element `para` is also extracted.

Export defines default element extraction settings for the following XML formats:

- generic XML

- Microsoft Office 2003 XML (Word, Excel, and Visio)

- StarOffice/OpenOffice XML (text document, presentation, and spreadsheet)

These settings are defined internally and are used when converting these file formats; however, you can modify their values.

In addition to the default extraction settings, you can also add custom settings for your own XML document types. If you do not define custom settings for your own XML document types, the settings for the generic XML are used.

### Modify Element Extraction Settings

You can modify configuration settings for XML documents by using the API.

You can also test this feature by modifying the `kvxconfig.ini` file, and passing it to the sample program `htmlini`.

NOTE: You can use customized element extraction settings only when converting files in process. When converting out of process, the default extraction settings are used.

#### Use the C API

You can use the C API to modify the settings for the standard XML document types or add configuration settings for your own XML document types.

To modify settings

1. Call the fpInit() or fpInitWithLicenseData() function.

2. Define the `KVXConfigInfo` structure. See KVXConfigInfo.

3. Call the `KVHTMLConfig()` function with the following arguments (see KVHTMLConfig():

   Argument | Parameter
   `nType` | `KVCFG_SETXMLCONFIGINFO`
   `nValue` | `0`
   `pData` | address of the `KVXConfigInfo` structure

   For example:

       KVXConfigInfo  xinfo;  /* populate xinfo */
       (*fpHTMLConfig)(pKVHTML, KVCFG_SETXMLCONFIGINFO, 0, &xinfo);

4. Repeat steps 2 and 3 until the settings for all the XML document types you want to customize are defined.

5. Call the `fpConvertStream()` or `KVHTMLConvertFile()` function. See fpConvertStream() or KVHTMLConvertFile().

### Modify Element Extraction Settings in the kvxconfig.ini File

The `kvxconfig.ini` file contains default element extraction settings for supported XML formats. The file is in the directory `install\OS\bin`, where `install` is the path name of the Export installation directory and `OS` is the name of the operating system.

For example, the following entry defines extraction settings for the Microsoft Visio 2003 XML format:

    [config3]
    eKVFormat=MS_Visio_XML_Fmt
    szRoot=
    szInMetaElement=DocumentProperties
    szExMetaElement=PreviewPicture
    szInContentElement=Text
    szExContentElement=
    szInAttribute=

The following options are available.

Configuration Option | Description
--- | ---
`eKVFormat` | The format ID as detected by the KeyView detection module. This determines the file type to which these extraction settings apply. See File Format Detection for more information on format ID values. If you are adding configuration settings for a custom XML document type, this is not defined.
`szRoot` | The file's root element. When the format ID is not defined, the root element is used to determine the file type to which these settings apply. To further qualify the element, specify its namespace. See Specify an Element's Namespace and Attribute.
`szInMetaElement` | The elements extracted from the file as metadata. All other elements are extracted as text. Multiple entries must be separated by commas. To further qualify the element, specify its namespace, its attributes, or both. See Specify an Element's Namespace and Attribute.
`szExMetaElement` | The child elements in the included metadata elements that are not extracted from the file as metadata. For example, the default extraction settings for the Visio XML format extract the `DocumentProperties` element as metadata. This element includes child elements such as `Title`, `Subject`, `Author`, `Description`, and so on. However, the child element `PreviewPicture` is defined in `szExMetaElement` because it is binary data and should not be extracted. You cannot exclude any metadata elements from the output for StarOffice files. All metadata is extracted regardless of this setting. Multiple entries must be separated by commas. To further qualify the element, specify its namespace, its attributes, or both. See Specify an Element's Namespace and Attribute.
`szInContentElement` | The elements extracted from the file as content text. Enter an asterisk (*) to extract all elements including child elements. Multiple entries must be separated by commas. To further qualify the element, specify its namespace, its attributes, or both. See Specify an Element's Namespace and Attribute.
`szExContentElement` | The child elements in the included content elements that are not extracted from the file as content text. Multiple entries must be separated by commas. To further qualify the element, specify its namespace, its attributes, or both. See Specify an Element's Namespace and Attribute.
`szInAttribute` | The attribute values extracted from the file. If attributes are not defined here, attribute values are not extracted. Enter the namespace (if used), element name, and attribute name in the following format: `namespace:elementname@attributename` For example: `keyview:division@name` Separate multiple entries with commas.

### Specify an Element's Namespace and Attribute

To further qualify an element, you can specify that the element must exist in a certain namespace, must contain a specific attribute, or both. To define the namespace and attribute of an element, enter the following:

    ns_prefix:elemname@attribname=attribvalue

You must enclose attribute values that contain space in quotation marks.

For example, the following entry:

    bg:language@id=xml

extracts a `language` element in the namespace `bg` that contains the attribute name `id` with the value of `"xml"`. This entry extracts the following element from an XML file:

    <bg:language id="xml">XML is a simple, flexible text format derived from SGML</bg:language>

but does not extract:

    <bg:language id="sgml">SGML is a system for defining markup languages.</bg:language>

or

    <adv:language id="xml">The namespace should be a Uniform Resource Identifier (URI).</adv:language>

### Add Configuration Settings for Custom XML Document Types

You can define element extraction settings for custom XML document types by adding the settings to the `kvxconfig.ini` file. For example, for files containing the root element `keyviewxml`, you could add the following section to the end of the initialization file:

    [config101]
    eKVFormat=
    szRoot=keyviewxml
    szInMetaElement=dc:title,dc:meta@title,dc:meta@name=title
    szExMetaElement=
    szInContentElement=keyview:division@name=dev,keyview:division@name=export,p@style="Heading 1"
    szExContentElement=
    szInAttribute=keyview:division@name

The custom extraction settings must be preceded by a section heading named `[configN]`, where `N` is an integer that starts at 100 and increases by 1 for each additional file type (for example, `[config100]`, `[config101]`, `[config102]`, and so on). The default extraction settings for the supported XML formats are numbered `config0` to `config99`. Currently only `0` to `6` are used.

Because a custom XML document type is not recognized by the KeyView detection module, the format ID is not defined. The file type is identified by the file's root element only.

If a custom XML document type is not defined in the `kvxconfig.ini` file or by the `KVHTMLConfig()` function, the default extraction settings for a generic XML document are used.

_FT_HTML5_bannerTitle.htm