[Uim] A document tracking API/ABI compatibility change has been added to the source distribution

[YamaKen]

Hi all,

I've committed doc/COMPATIBILITY which describes API/ABI
compatibility change for developers. Please review it.

Our uim implementation and interfaces are still altering to
become better. But the changes are patience for cooperative
developers who implements IMs or bridges.

To reduce the patience, we should describe any API/ABI change in
well-readable format. svn log is unfriendly to detect such
change.

Current revision of the document is described with one entry as
follows. Tell me any opinions.


doc/COMPATIBILITY:
----------------------------------------------------------------
This document tracks API/ABI compatibility change for convenience of
developers.

Each change consist of following fields. All fields must be required.

  - Date
    When the change committed into the repository

  - Modifier
    Who had applied the change

  - Revision
    Which revision(s) performs the change. Enumerate as comma separated
    revision numbers if performed by several commit

  - Summary
    Short description of the change

  - Affects
    Who will be suffered
    * IM developers
    * Bridge developers
    * Helper program developers

  - Related

    What issues are related to this change. Describe in free format. But if
    you refer items in the bug tracking system, describe as "bug #1450, #1451"

  - URL
    Write URL(s). Use subsequent line(s) with 2 space prefix to describe
    multiple URLs (i.e. describe one URL per line)

  - Changed
    Which functions or structs are changed. Describe one item per line with 2
    space prefix for clear view

  - Description
    Detailed description of the change

------------------------------------------------------------------------------
Date: 2004-09-27
Modifier: YamaKen
Revision: 1304
Summary: Context object integration
Affects: IM developers
Related: bug #1450
URL: http://freedesktop.org/pipermail/uim/2004-September/000641.html
Changed:
  im-commit
  im-commit-raw
  im-set-encoding
  im-clear-preedit
  im-pushback-preedit
  im-update-preedit
  im-clear-mode-list
  im-pushback-mode-list
  im-update-mode-list
  im-update-prop-label
  im-update-prop-list
  im-update-mode
  im-activate-candidate-selector
  im-select-candidate
  im-shift-page-candidate
  im-deactivate-candidate-selector
  im-request-surrounding
  im-delete-surrounding
  *-init-handler
  *-release-handler
  *-mode-handler
  *-press-key-handler
  *-release-key-handler
  *-reset-handler
  *-get-candidate-handler
  *-set-candidate-index-handler
  *-prop-handler
Description:
  This change integrates following 3 context objects into one.

  - id
  - context
  - im-specific-context

  Although some reasons to distinguish the objects exist for API implementor,
  all 3 context objects semantically mean same 'this input context' for
  IM-implementors. So we should show the context object as unified one for
  IM-implementors to eliminate complexity and confusion.

  Scheme procedures has been changed as follows.

  - To generate the integrated context object, use define-record with pseudo
    inheritance (i.e. concatenate context-rec-spec with your own context
    rec-spec). See anthy.scm for example

  - im-* procedures now accepts the integrated Scheme-side context object as
    first argument. It also accepts 'id' as backward compatibility, but not
    recommended

  - *-init-handler (such as anthy-init-handler) now accepts additional 'im'
    argument. And it must return an integrated context object. The object must
    be initialized with 'id' and 'im' arguments which passed to this
    handler. See anthy-init-handler for example

  - All other *-*-handler has been changed to accept the integrated context
    object as first argument instead of 'id'
------------------------------------------------------------------------------


-------------------------------
YamaKen  yamaken at bp.iij4u.or.jp