KVXMLOptions

This structure defines the options that control the XML markup written in response to the general style and attributes (font, color, and so on) of the document. The structure is initialized by calling the fpConvertStream() or KVXMLConvertFile() function. See fpConvertStream() or KVXMLConvertFile().

typedef struct tag_KVXMLOptions
{
    BOOL                    bUseVerityDTD;
    char                    *pszVerityDTDPath;
    KVXMLStyleSheetType     eStyleSheetType
    BOOL                    bUseExistingStyleSheet;
    char                    *pszStyleSheet;
    BOOL                    bIndexOnly;
    KVCharSet               eOutputCharSet;
    BOOL                    bForceOutputCharSet;
    KVCharSet               eSrcCharSet;
    BOOL                    bForceSrcCharSet;
    KVLanguageID            eOutputLanguageID;
    BOOL                    bUseDocumentColors;
    BOOL                    bUseDocumentFontInfo;
    BOOL                    bNbspEmptyCells;
    ENSATableBorder         eSATableBorder;
    int                     nTableBorderWidth;
    char                    *pszBaseURL;
    char                    *pszMainURL;
    char                    *pszDefaultOutputDirectory;
    char                    *pszPicPath;
    char                    *pszPicURL;
    char                    *pszJavaURL;
    BOOL                    bRemoveFileNameSpaces;
    BOOL                    bRasterizeFiles
    KVXMLGraphicType        eOutputRasterGraphicType;
    KVXMLGraphicType        eOutputVectorGraphicType;
    int                     cxVectorToRasterXRes;
    int                     cyVectorToRasterYRes;
    int                     nCompressionQuality;
    BOOL                    bGenerateURLs;
    long                    lcbMaxMemUsage;
    BYTE                    cReplaceChar;
    BYTE                    cRedact;
    KVXMLEmptyParaType      eEmptyParaType;
    KVXMLHardPageBreakType  eHardPageBreakType;
    BOOL                    bSupportColumnHeadings;
    BOOL                    bSupportRowHeadings;
    BOOL                    bSupportCellSpan;
    BOOL                    bSupportRowSpan;
    BOOL                    bSupportColumnWidth;
    BOOL                    bRemoveEmptyColumns;
    BOOL                    bRemoveEmptyRows;
    BOOL                    bEnableEmptyRows;
    int                     nRowsBeforeSplit;
}
KVXMLOptions;

Member Descriptions

bUseVerityDTD

Set bUseVerityDTD to TRUE to generate XML based on the Verity DTD. For more information, see Use the KeyView Document Type Definition (DTD). This generates a valid XML document suitable as a general interchange format. If you set bUseVerityDTD to FALSE, the XML is based on the source document's paragraph structure.

The default is TRUE.

pszVerityDTDPath

If you move the Verity DTD from the default tempout directory to another output directory, set the string value of pszVerityDTDPath to the new location. This path is added to the document type declaration in the XML file.

The default is no path, that is, the DTD is assumed to be in the same directory as the generated XML files.

eStyleSheetType

One of the enumerated options for processing style sheet information. The options are defined in KVXMLStyleSheetType in kvxml.h. See KVXMLStyleSheetType.

  • STYLESHEET_DISABLED—Disables style sheet formatting. This is the default option.
  • XML_CSS—Enables Cascading Style Sheet (CSS) formatting, and outputs the generated formatting data in an external CSS file referenced in the XML output as a tag.
  • XML_XSL—Enables Extensible Style Sheet Language (XSL) formatting, and uses an external XSL file referenced in a <?xml-stylesheet...?> processing instruction.

bUseExistingStyleSheet

Set bUseExistingStyleSheet to TRUE to apply an existing XSL style sheet or a CSS file to an XML document. The style sheet file name is inserted into the type declaration at the beginning of the XML file. The location of the external style sheet file is set by pszStyleSheet. If pszStyleSheet is not specified and the style sheet type is XSL, a default XSL style sheet appropriate for the source document type is used. The default XSL style sheets are:

  • wp.xsl (for word processing documents)

  • ss.xsl (for spreadsheets)

  • pg.xsl (for presentations)

If pszStyleSheet is not specified and the style sheet type is CSS, a CSS file is created.

Existing style sheets are not validated.

The default is FALSE.

pszStyleSheet

The path and file name of an external style sheet.

The default is no path.

bIndexOnly

Set bIndexOnly to TRUE to generate output with minimal markup (ID and style paragraph attributes) and without images. Because the generated output is minimized to textual content, it is suitable for an indexing engine. If you set bIndexOnly to FALSE, embedded images in a document are regenerated as separate files and stored in the output directory.

The template file named xml_index.ini demonstrates the effect of setting bIndexOnly.

To generate output with verbose markup and without images, set the nType argument of the KVXMLConfig() function to KVCFG_SUPPRESSIMAGES. See KVXMLConfig().

The default is FALSE.

eOutputCharSet

The character set to use for textual output. To ensure that the character set defined here is used, you must set bForceOutputCharSet to TRUE. The available character sets are enumerated in KVCharSet in kvcharset.h. See Convert Character Sets.

Document Readers lists the file formats for which character set information can be determined.

The default is KVCS_UNKNOWN.

bForceOutputCharSet

Set bForceOutputCharSet to TRUE to use the output character set specified in eOutputCharSet. See Convert Character Sets.

Forcing a character set to KVCS_UNKNOWN is always ignored.

The default is FALSE.

eSrcCharSet

This option specifies the character set of the document. To ensure that the character set defined here is used, you must set bForceSrcCharSet to TRUE. The available character sets are enumerated in KVCharSet in kvcharset.h. See Convert Character Sets. Document Readers lists the file formats for which character set information can be determined.

The default is KVCS_UNKNOWN.

bForceSrcCharSet

Set bForceSrcCharSet to TRUE to use the source character set specified in eSrcCharSet, regardless of the internal document information. See Convert Character Sets.

Forcing a character set to KVCS_UNKNOWN is always ignored.

The default is FALSE.

eOutputLanguageID

The language for the textual output of language-specific data such as time and date. eOutputLanguageID must be in the system locale. If eOutputLanguageID is invalid or not supplied, the system default is used. Language IDs are defined in KVLanguageID in kvtypes.h.

The default is Language_UNKNOWN.

bUseDocumentColors

Set bUseDocumentColors to TRUE to retain the color attributes information contained in the source document. If you set bUseDocumentColors to FALSE, no color attributes appear in the <font> tags of the output.

The default is FALSE.

bUseDocumentFontInfo

Set bUseDocumentFontInfo to TRUE to retain the font information contained in the source document. If you set bUseDocumentFontInfo to FALSE, no font information appears in the <font> tags in the output.

The default is FALSE.

bNbspEmptyCells

Set bNbspEmptyCells to TRUE to include a non-breaking space (<td>&nbsp;</td>) in the markup for empty table cells in the source document. If you set bNbspEmptyCells to FALSE, <td></td> is generated for empty table cells.

This option applies to word processing documents and spreadsheets only.

The default is TRUE.

eSATableBorder

This option specifies whether table borders are based on the setting in the source document, are always on, or are always off. The options are enumerated in ENSATableBorder in kvtypes.h. See ENSATableBorder.

This option applies to word processing documents only.

The default is SA_BaseOnDocument.

nTableBorderWidth

This option sets the width of the table border in pixels.

This option applies to word processing documents only.

The default is 1.

pszBaseURL

The base URL that replaces the $BASE token in the XML output.

The default is NULL.

pszMainURL

The main URL that replaces the $MAIN token in the XML output.

The default is NULL.

pszDefaultOutputDirectory

The default output directory for auxiliary files created during the conversion.

The default is NULL, and the files are placed in the directory in which your application is running.

pszPicPath

The output directory for graphic files created during the conversion. If specified, this member can also be used by the callback functions KVXMLGetAnchor and KVXMLGetAuxOutput.

This option applies to word processing documents only.

The default is NULL, and the files are placed in the directory in which your application is running.

pszPicURL

The URL of the graphic files created from embedded graphics in the source document. To specify a complete image source, this element must be combined with pszAnchor of the fpGetAnchor callback function. See GetAnchor().

For example, setting pszPicURL to ../cgi-bin/ and setting pszAnchor to pic.jpg results in the following markup:

<a xmlns:xlink= xlink href="../cgi-bin/pic.jpg">

This option applies to word processing documents only.

The default is NULL.

pszJavaURL

The URL where the Java rasterizer (kvvector.jar) is located.

The Java rasterizer is not currently enabled.

The default is NULL.

bRemoveFileNameSpaces

Set bRemoveFileNameSpaces to TRUE to remove spaces from generated output file names.

The default is FALSE.

bRasterizeFiles

Set bRasterizeFiles to TRUE to rasterize slides from presentations into single images. Set bRasterizeFiles to FALSE to only extract text from presentation files. When you set this member to FALSE, graphics do not appear in the output.

The default is FALSE.

NOTE: When bRasterizeFiles is FALSE, the export process uses the ordering in the file to produce the output, which does not necessarily match the logical reading order for the presentation. To use a logical reading order instead, you can set the LogicalOrder parameter in the [Options] section of formats_e.ini. See Convert Presentation Files.

eOutputRasterGraphicType

The output format of rasterized embedded graphics. The options are enumerated in KVXMLGraphicType in kvxml.h.

eOutputVectorGraphicType

The output format of vector graphics. The options are enumerated in KVXMLGraphicType in kvxml.h. For more information, see Vector Graphics Output.

cxVectorToRasterXRes

Specifies the horizontal resolution when converting presentation files and vector graphics. This is set in conjunction with cyVectorToRasterYRes. For more information, see Set the Resolution of Presentations and Vector Graphics.

The default value is 0, which means the original resolution is retained.

cyVectorToRasterYRes

Specifies the vertical resolution when converting presentation files and vector graphics. This is set in conjunction with cxVectorToRasterXRes. For more information, see Set the Resolution of Presentations and Vector Graphics.

The default value is 0, which means the original resolution is retained.

nCompressionQuality

This option controls the output quality of graphics that support compression quality (for example, JPEG). A value of 0 means default quality (85 compression); 1 is the lowest quality (highest compression and therefore the smallest file size); 100 is the highest quality (no compression and therefore the largest file size).

This option applies to word processing documents only.

The default is 0.

bGenerateURLs

Set bGenerateURLs to TRUE to add anchor tags (<a xmlns:xlink= xlink href=> </a>) to text starting with "www", "http:" or "file:".

This option applies to word processing documents only.

The default is FALSE.

lcbMaxMemUsage

The maximum memory allocated dynamically for token buffers during file processing. If this maximum is reached, Export performs a swap-to-disk operation internally, and then reuses the memory blocks. Export maintains an internal minimum memory size.

This option applies to word processing or text documents only.

The default is LONG_MAX. The unit is in bytes.

cReplaceChar

The character used when a character in the source document's character set cannot be mapped to the output character set.

The default replacement character is a question mark (?).

cRedact

The character that replaces tagged text that has been designated, through style mapping, to be omitted from the output. This functionality is useful when you need to hide confidential or sensitive information.

The specified character is used for all text that has been mapped to a style processed with the KVSTYLE_REDACT flag (defined in kvtypes.h). See Map Styles.

This option applies to word processing documents only.

The default replacement character is "X".

eEmptyParaType

This option determines if paragraphs without content generate markup or ID attributes in the output file. There are three options enumerated in KVXMLEmptyParaType in kvxml.h. See KVXMLEmptyParaType.

This option applies to word processing documents only.

The default is KVEPT_SUPPRESS.

eHardPageBreakType

This option determines if hard page breaks generate markup or ID attributes in the output file. There are four options enumerated in KVXMLEmptyParaType in kvxml.h. See KVXMLHardPageBreakType.

This option applies to word processing documents only.

The default is KVHPBT_SUPPRESS.

bSupportColumnHeadings

Set bSupportColumnHeadings to TRUE to include column headings from the source spreadsheet in the output.

This option applies to spreadsheets only.

The default is FALSE.

bSupportRowHeadings

Set bSupportRowHeadings to TRUE to include row headings from the source spreadsheet in the output.

This option applies to spreadsheets only.

The default is FALSE.

bSupportCellSpan

Set bSupportCellSpan to TRUE to include colspan="n" markup in the output.

This option applies to spreadsheets only.

The default value is FALSE.

bSupportRowSpan

Set bSupportRowSpan to TRUE to include row span data from the source spreadsheet in the output.

This option applies to spreadsheets only.

The default value is FALSE. Currently not supported.

bSupportColumnWidth

Set bSupportColumnWidth to TRUE to include column width data from the source spreadsheet in the output.

This option applies to spreadsheets only.

The default value is FALSE.

bRemoveEmptyColumns

Set bRemoveEmptyColumns to TRUE to remove spreadsheet columns that do not contain data and to disable cell merging.

This option applies to spreadsheets only.

The default is FALSE.

bRemoveEmptyRows

Set bRemoveEmptyRows to TRUE to remove spreadsheet rows that do not contain data or color, and to disable cell merging.

This option applies to spreadsheets only.

The default is FALSE.

bEnableEmptyRows

Set bEnableEmptyRows to TRUE to display empty rows in a spreadsheet format. If you set bEnableEmptyRows to FALSE, empty rows are not displayed. This applies only to 20 or more consecutive empty rows.

This option applies to spreadsheets only.

The default is FALSE.

nRowsBeforeSplit

The approximate number of spreadsheet rows to be processed before splitting a table. This helps to prevent large spreadsheet tables from occurring in a single document, which can cause speed and processing problems for the browser.

This option applies to spreadsheets only.

The default is 0.

Discussion

A pointer to this structure is passed as an argument to fpConvertStream() and KVXMLConvertFile(). If the pointer to the structure is not NULL, the values of the members specified in the structure are used. If the pointer to the structure is NULL, the default values are used.

Set the Resolution of Presentations and Vector Graphics

The members cxVectorToRasterXRes and cyVectorToRasterYRes are set in conjunction to specify the resolution (width and height) at which presentation files and vector graphics are converted.

You can specify the resolution as an absolute size in pixels, or as a proportion of the original size.

KeyView always maintains the aspect ratio of the original graphic and does not increase the resolution. If you set values that would enlarge a graphic, KeyView only changes the size of the XML element.

To set the resolution in pixels

To specify the resolution in pixels, specify the width (cxVectorToRasterXRes) and/or height (cyVectorToRasterYRes).

To export the largest image that fits within a bounding box, without changing the original aspect ratio, set both the width and height. For example, to export the largest image that fits in an 800x500 bounding box:

cxVectorToRasterXRes=800
cyVextorToRasterYRes=500

Alternatively you can fix one of the dimensions. Set one value and set the other to zero. For example, to export images with a height of 1500 pixels and whatever width is necessary to maintain the original aspect ratio:

cxVectorToRasterXRes=0
cyVextorToRasterYRes=1500

The maximum size permitted for either dimension is 4000 pixels.

To set the resolution proportionally

To set the resolution proportionally, set cxVectorToRasterXRes to a negative value. A negative value represents a percentage of the original resolution. Set cyVectorToRasterYRes to 0 (zero). Negative (percentage) values for cyVectorToRasterYRes are ignored.

The following example exports a graphic at 50 percent of its original resolution:

cxVectorToRasterXRes=-50
cyVectorToRasterYRes=0