KeyView 24.4
KeyView HTML Export SDK C Programming Guide

# Include Revision Information

Applications sometimes have revision tracking features — such as Track Changes in Microsoft Word — and save information about the changes that are made to a document. This information might include the reviewer's name and the date and time of each change.

When a supported file contains revision information, KeyView can convert any deleted text and graphics and include the revision information in the HTML output. Deleted content and revision information are not included in the HTML output by default.

If you include revision information in the output, content that was added to a document is identified by `<ins>` tags and is usually underlined when displayed in a browser. Content that was deleted from a document is identified by `<del>` tags and is usually displayed with strikethrough formatting. The precise appearance depends on the browser and can be modified with CSS.

KeyView generates `<ins>` and `<del>` tags that can include the following attributes:

`style` | The standard `style` attribute, which you can use to alter the presentation of the text. You can define a collection of styles to apply to changes. If you define sufficient styles, each reviewer's changes are displayed in a different style. This attribute is not included by default. See Configure the Revision Style.
`title` | By default, the value of this attribute is "inserted:" or "deleted:", followed by the reviewer's name and the date and time of the change. You can customize the prefix and include or exclude the reviewer's name and the date and time. For information about customizing this attribute, see Configure the Revision Title.
`cite` | The name of the reviewer who made the revision.
`datetime` | The date and time the revision was made, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss`).

For example, the following markup could be generated for some inserted text:

`<ins style="color: red;" title="inserted: John D, 2022-06-13T11:17:00Z" cite="mailto:John D" datetime="2022-06-13T11:17:00Z">This text was added</ins>`

This text is displayed in the browser as follows:

This text was added ...while this existed before the change.

When you hover the cursor over the underlined text in the browser, the value of the `title` attribute, for example "inserted: John D, 2022-06-13T11:17:00Z", is displayed as a tooltip.

To convert deleted text and graphics and include revision information

1. Call the fpInit() function.

2. Define the `KVRevisionMark` structure. See KVRevisionMark.

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

   Argument | Parameter
   `nType` | `KVCFG_INCLREVISIONMARK`
   `nValue` | `TRUE`
   `pData` | A pointer to the `KVRevisionMark` structure which defines the information that appears in the `title` attribute and the HTML styles applied to revised content. If you pass `NULL` to this function, defaults are used.

   For example:

       KVRevisionMark    RMark;
       memset(&RMark, 0, sizeof(KVRevisionMark));
       KVStructInit(&RMark);
       RMark...
       (*fpHTMLConfig)(pKVHTML, KVCFG_INCLREVISIONMARK, TRUE, &RMark))

   The `htmlini` sample program demonstrates this function. See htmlini.

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

## Configure the Revision Title

You can customize the value of the `title` attribute.

- To exclude the `title` attribute from the `<ins>` and `<del>` tags, set the `RM_TITLE_FLAG` in the `KV_RM_Title` structure to `RMT_Off`. See KV_RM_Title.

- To define a different text string for the prefix, specify a new text string in the `pPrefix` member and set the `nSize` and `eCharSet` members of the `KV_RM_Title` structure. See KV_RM_Title.

- To change the revision information included in the `title` attribute, set the `RM_TITLE_FLAG` in the `KV_RM_Title` structure. See RM_Title_Flag.

The following example sets the prefix to "Added:" or "Removed:", for inserted and deleted text respectively, and includes the contributor's name but not the date/time:

    KVRevisionMark    RMark;
    char              RMInsPre[16] = "Added:";
    char              RMDelPre[16] = "Removed:";
        memset(&RMark, 0, sizeof(KVRevisionMark));
        KVStructInit(&RMark);
        RMark.InsTitle.eFlag = RMT_Author;
        RMark.InsTitle.pPrefix = (BYTE *)(&RMInsPre);
        RMark.InsTitle.nSize = strlen(RMInsPre);
        RMark.InsTitle.eCharSet = KVCS_UTF8;
        RMark.DelTitle.eFlag = RMT_Author;
        RMark.DelTitle.pPrefix = (BYTE *)(&RMDelPre);
        RMark.DelTitle.nSize = strlen(RMDelPre);
        RMark.DelTitle.eCharSet = KVCS_UTF8;
    (*fpHTMLConfig)(pKVHTML, KVCFG_INCLREVISIONMARK, TRUE, &RMark))

## Configure the Revision Style

You can define a style (such as `color: red; background: yellow;`) to apply to a reviewer's modifications, so that your users can identify new or deleted text, and even differentiate between contributors to the document. For example, changes made by one contributor could be displayed in red, changes by another in green, and so on.

To define revision styles, set the number of revision styles in the `nAuthorStyles` member of the `KVRevisionMark` structure, and use the `ppAuthorStyles` member for each style to define the contents of the `style` attribute. See KVRevisionMark.

The following example defines two revision styles:

    KVRevisionMark    RMark;
    char    RMAuthorStyle0[60] = "color: red; background: yellow";
    char    RMAuthorStyle1[60] = "color: green; background: silver";
        memset(&RMark, 0, sizeof(KVRevisionMark));
        KVStructInit(&RMark);
        RMark.nAuthorStyles = 2;
        RMark.ppAuthorStyles = (char **)malloc(sizeof(char *)*2);
        if(!RMark.ppAuthorStyles) return(1);
        RMark.ppAuthorStyles[0] = RMAuthorStyle0;
        RMark.ppAuthorStyles[1] = RMAuthorStyle1;
    (*fpHTMLConfig)(pKVHTML, KVCFG_INCLREVISIONMARK, TRUE, &RMark))

If there are more reviewers than defined styles, KeyView applies styles to the reviewers in the order in which they are encountered in the document, and then applies styles starting from the beginning of the list to the remaining reviewers. This process is repeated until all reviewers' edits are highlighted.

NOTE: KeyView does not validate styles. They are written directly to the HTML output.

## Generate a Revision Summary

You can configure KeyView to summarize the changes made to a document in a revision summary file that is generated during the HTML conversion. The summary file is created in the directory where the HTML output is generated. The default file name is `output_filename.revsum.htm`. You can customize this file name by using the `fpGetAnchor` callback function. See GetAnchor().

To create a revision summary file, set the `bCreateSummary` flag to `TRUE` in the `KVRevisionMark` structure, and use the `pszRevSumStartBlock` and `pszRevSumEndBlock` members to define the markup and tokens inserted at the beginning and end of the revision summary file.

For example:

    KVRevisionMark    RMark;
    char              RMStartBlock[500] = "<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <body>";
    char              RMEndBlock[30] = "</body> </html>";
        memset(&RMark, 0, sizeof(KVRevisionMark));
        KVStructInit(&RMark);
        RMark.pszRevSumStartBlock = RMStartBlock;
        RMark.pszRevSumEndBlock = RMEndBlock;
        RMark.bCreateSummary = TRUE;
    (*fpHTMLConfig)(pKVHTML, KVCFG_INCLREVISIONMARK, TRUE, &RMark))

Copyright 1997-2024 Open Text
Version 24.4 | Last updated September 2024

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: IDOL KeyView 24.4

Topic Title: Include Revision Information