patch for fcitx developer handbook

diff -c fcitx.developer-handbook//addon.docbook modi-fcitx-developer-handbook//addon.docbook
*** fcitx.developer-handbook//addon.docbook 2011-08-27 22:50:53.215077899 -0700
--- modi-fcitx-developer-handbook//addon.docbook    2011-08-27 23:32:12.434980146 -0700
***************
*** 6,13 ****
      <article>
          <title>Register a addon in Fcitx</title>
          <para>
!             You need a configure file for your own addon. A common configure
!             file is like this one, fcitx-pinyin.conf.in.
          </para>
          <programlisting>
  [Addon]
--- 6,13 ----
      <article>
          <title>Register a addon in Fcitx</title>
          <para>
!             You need a configuration file for your own addon. A common configuration
!             file is like this one, fcitx-pinyin.conf.ini.
          </para>
          <programlisting>
  [Addon]
***************
*** 23,29 ****
          <para>
              All Fcitx config file are using ini style format, GeneralName and
              Comment are I18NString that can be translated into other languages.
!             Here is fcitx-pinyin.conf that is merged with translation.
          </para>
          <programlisting>
  [Addon]
--- 23,29 ----
          <para>
              All Fcitx config file are using ini style format, GeneralName and
              Comment are I18NString that can be translated into other languages.
!             Here is a fcitx-pinyin.conf that is merged with translation.
          </para>
          <programlisting>
  [Addon]
diff -c fcitx.developer-handbook//architecture.docbook modi-fcitx-developer-handbook//architecture.docbook
*** fcitx.developer-handbook//architecture.docbook  2011-08-27 22:50:53.215077899 -0700
--- modi-fcitx-developer-handbook//architecture.docbook 2011-08-27 22:58:16.402676946 -0700
***************
*** 6,34 ****
      <article>
          <title>Input Method Architecture</title>
          <para>
!             All Input Method has a very simple architecture, basically it receives
              Keyboard Event from Application, then try to do some work with this
!             Keyboard Event, like simply let it pass, or block it and commit a
              string to the application.
          </para>
          <para>
!             The way that Fcitx handle the keyboard event can be separated into 4
!             stage, Pre-Input, Input Method, Post-Input, and Hotkey. All the input
!             method engine, such as "Chinese Pinyin", will be called at the second
              stage.
          </para>
          <para>
!             Fcitx has a temporarily disabled mode, which can switched with Left Ctrl
              by default, when this mode is on, Pre-Input, Input-Method, Post-Input
              will be skipped and only Hotkey takes effect.
          </para>
          <para>
!             Fcitx Addon (which you can also think as a module) can be separated into
              3 categories. First is Backend, which receives key event and pass it to
              Fcitx; Second is Input Method Engine, which help you input your Language
!             with keyboard; Third is Misc Module, it simply can do anything you want,
              like registering hook for pre-input or post-input, receiving event from other
!             process, or so on.
          </para>
      </article>
  </part>
--- 6,34 ----
      <article>
          <title>Input Method Architecture</title>
          <para>
!             All Input Methods have a very simple architecture, basically they receive
              Keyboard Event from Application, then try to do some work with this
!             Keyboard Event, like simply letting it pass, or to block it and commit a
              string to the application.
          </para>
          <para>
!             The way that Fcitx handles the keyboard events can be separated into 4
!             stages, Pre-Input, Input Method, Post-Input, and Hotkey. All the input
!             method engines, such as "Chinese Pinyin", will be called at the second
              stage.
          </para>
          <para>
!             Fcitx has a temporarily disabled mode, which can be switched on with Left Ctrl
              by default, when this mode is on, Pre-Input, Input-Method, Post-Input
              will be skipped and only Hotkey takes effect.
          </para>
          <para>
!             Fcitx Addons (which you can also think of as modules) can be separated into
              3 categories. First is Backend, which receives key event and pass it to
              Fcitx; Second is Input Method Engine, which help you input your Language
!             with keyboard; Third is Misc Module, which simply can do anything you want,
              like registering hook for pre-input or post-input, receiving event from other
!             process, and so on.
          </para>
      </article>
  </part>
diff -c fcitx.developer-handbook//convention.docbook modi-fcitx-developer-handbook//convention.docbook
*** fcitx.developer-handbook//convention.docbook    2011-08-27 22:50:53.218411214 -0700
--- modi-fcitx-developer-handbook//convention.docbook   2011-08-27 23:34:31.610892831 -0700
***************
*** 6,35 ****
      <article>
          <title>File and Directory Convention</title>
          <para>
!             Fcitx have two prefix for directory, one is named "PREFIX", which is configured
!             while being built, the other is "USERPREFIX", which is based on XDG environment
              variable. Normally, PREFIX is /usr/share/fcitx, and USERPREFIX is ~/.config/fcitx
          </para>
          <para>
!             In order to make Fcitx Configuration Tool find your config file automatically,
!             and let Fcitx load your addon correctly, you need to put your config file under
              correct path with correct name.
          </para>
          <para>
              Each addon has a config file, and it should be installed under PREFIX/addon/.
!             This config file defines the name, category, library name, type, and priority.
              Filename need to be addon-name.conf.
          </para>
          <para>
              If your addon can be configured, you need a confguration description file,
              which should be installed under PREFIX/configdesc/, with name addon-name.desc.
!             The corresponding config file should be placed under USERPREFIX/conf/, with name
              addon-name.config.
          </para>
          <para>
!             If your addon has some data file to load/save, there is two case. If you only has
!             one file to be processed, you can place it under PREFIX/data. If you have more than
!             one file, you'd better create a directory (with the name you like) to place them.
          </para>
      </article>
      <article>
--- 6,35 ----
      <article>
          <title>File and Directory Convention</title>
          <para>
!             Fcitx has two prefixes for directory, one is named "PREFIX", which is configured
!             during building, the other is "USERPREFIX", which is based on XDG environment
              variable. Normally, PREFIX is /usr/share/fcitx, and USERPREFIX is ~/.config/fcitx
          </para>
          <para>
!             In order to let Fcitx Configuration Tool find your config files automatically,
!             and to let Fcitx load your addon correctly, you need to put your config files under
              correct path with correct name.
          </para>
          <para>
              Each addon has a config file, and it should be installed under PREFIX/addon/.
!             This config file defines its name, category, library name, type, and priority.
              Filename need to be addon-name.conf.
          </para>
          <para>
              If your addon can be configured, you need a confguration description file,
              which should be installed under PREFIX/configdesc/, with name addon-name.desc.
!             The corresponding config file should be placed under USERPREFIX/conf/, with the name
              addon-name.config.
          </para>
          <para>
!             If your addon has some data file to load/save, there are two cases. If you only have
!             one file to process, you can place it under PREFIX/data. If you have more than
!             one file, you'd better create a directory (with a name you like) to place them.
          </para>
      </article>
      <article>
diff -c fcitx.developer-handbook//frontend.docbook modi-fcitx-developer-handbook//frontend.docbook
*** fcitx.developer-handbook//frontend.docbook  2011-08-27 22:50:53.218411214 -0700
--- modi-fcitx-developer-handbook//frontend.docbook 2011-08-27 23:11:47.664948627 -0700
***************
*** 6,16 ****
      <article>
          <title>Frontend</title>
          <para>
!             Frontend is a library that communicate with the client, and process
!             the key input from client, send string to client for input.
          </para>
          <para>
!             Currently, there are 13 functions need to be implement for a frontend.
              (Defined in fcitx/frontend.h)
          </para>
          <programlisting>
--- 6,16 ----
      <article>
          <title>Frontend</title>
          <para>
!             Frontend is a library that communicates with the client, processes
!             the key input from client, and send string to client for input.
          </para>
          <para>
!             Currently, there are 13 functions need to be implemented for a frontend.
              (Defined in fcitx/frontend.h)
          </para>
          <programlisting>
***************
*** 30,63 ****
          </programlisting>
          <para>
              Basically, frontend is to manage input contexts. A client at least
!             have one input context, which hold some private data, which
              can identify the specific input context. The CreateIC and
              DestroyIC are functions that create and destroy private
!             input context data. A input context usually have a private id,
              which will be used in CheckIC to find the specific ic.
          </para>
          <para>
!             Some input context hold a state at the client side, which indicates
              whether this input context is active or not. EnableIM and
!             CloseIM are callbacks if fcitx want to enable or disable
              input context from fcitx side.
          </para>
          <para>
              CommitString, ForwardKey, are callbacks that will be called  when
!             fcitx want to commit string to client window, or forward a key event
              to client window.
          </para>
          <para>
              SetWindowOffset, and GetWindowOffset, are callbacks when fcitx
!             want to know the current window position to the screen.
          </para>
          <para>
              UpdatePreedit, and UpdateClientSideUI, are callbacks that will be called
              when UI elements, like preedit string, or any ui element get updated.
!             These two function are especially for input context, which capacities
!             has CAPACITY_PREEDIT and CAPACITY_CLIENT_SIDE_UI. Only if input context
!             claims to support opposite capacity, these two function will be
              called.
          </para>
      </article>
! </part>
\ 文件尾没有 newline 字符
--- 30,63 ----
          </programlisting>
          <para>
              Basically, frontend is to manage input contexts. A client at least
!             have one input context, which hold some private data that
              can identify the specific input context. The CreateIC and
              DestroyIC are functions that create and destroy private
!             input context data. A input context usually has a private id,
              which will be used in CheckIC to find the specific ic.
          </para>
          <para>
!             Some input context holds a state at the client side, which indicates
              whether this input context is active or not. EnableIM and
!             CloseIM are callbacks when fcitx wants to enable or disable
              input context from fcitx side.
          </para>
          <para>
              CommitString, ForwardKey, are callbacks that will be called  when
!             fcitx wants to commit string to client window, or to forward a key event
              to client window.
          </para>
          <para>
              SetWindowOffset, and GetWindowOffset, are callbacks when fcitx
!             wants to know the current window position to the screen.
          </para>
          <para>
              UpdatePreedit, and UpdateClientSideUI, are callbacks that will be called
              when UI elements, like preedit string, or any ui element get updated.
!             These two function are specially for input context, whose capacities
!             have CAPACITY_PREEDIT and CAPACITY_CLIENT_SIDE_UI. Only when input context
!             claims to support opposite capacity, will these two function be
              called.
          </para>
      </article>
! </part>
只在 fcitx.developer-handbook/ 存在：.hg
diff -c fcitx.developer-handbook//inputmethod.docbook modi-fcitx-developer-handbook//inputmethod.docbook
*** fcitx.developer-handbook//inputmethod.docbook   2011-08-27 22:50:53.221744529 -0700
--- modi-fcitx-developer-handbook//inputmethod.docbook  2011-08-27 23:18:05.646234261 -0700
***************
*** 6,48 ****
      <article>
          <title>Input Method Engine</title>
          <para>
!             Input Method Engine are main component of Fcitx. It will process
!             key event, and decide whether the preedit should be updated, or
              add candidate words.
          </para>
          <para>
              Every single input method addon can add more than one input method
!             to Fcitx. Like fcitx-table, it will load table configure file first,
              then add opposite table input method.
          </para>
          <para>
              Input methods are registered via FcitxRegisterIM. It will provide
!             two strings, one is name which will be displayed directly to user,
!             so if you want it to be translated, you should do it before pass to
              FcitxRegisterIM. Icon Name is a property that will be used in UI
              display, the actual usage for Icon Name depends on the UI Module
              implementation. For fcitx-classic-ui, it will be used as the original
              png file name; for fcitx-kimpanel-ui, it will be used with a "fcitx-"
!             prefix and find icon in system icon themes.
          </para>
          <para>
!             Init is function will be called when a input method being switched to. ResetIM is
!             usually being called in ResetInput. DoInput is the key function, which
              process the key event. And if the return state is IRV_DISPLAY_CANDWORDS,
!             the GetCandWords will be called. Save will be called when fcitx want to
!             save the data, usually when logout.
          </para>
          <para>
              Priority control the order of input methods, each IM should take care of
!             it's own priority value. If a priority value less equal than zero, this
              input method will not be registered to fcitx.
          </para>
      </article>
      <article>
!         <title>The things that a input method should do and should not do.</title>
          <para>
!             Fcitx changes the behavior of Candidate Word handling in 4.1.0. Input method
!             should provides all candidate word, instead of a single page.
          </para>
          <para>
              Fcitx will provide the paging function, if you correctly use the candidate
--- 6,48 ----
      <article>
          <title>Input Method Engine</title>
          <para>
!             Input Method Engine is a main component of Fcitx. It will process
!             key event, and decide whether the preedit should be updated, or to
              add candidate words.
          </para>
          <para>
              Every single input method addon can add more than one input method
!             to Fcitx. Like fcitx-table, it will load table configuration file first,
              then add opposite table input method.
          </para>
          <para>
              Input methods are registered via FcitxRegisterIM. It will provide
!             two strings, one is name, which will be displayed directly to user.
!             So if you want it to be translated, you should do it before pass to
              FcitxRegisterIM. Icon Name is a property that will be used in UI
              display, the actual usage for Icon Name depends on the UI Module
              implementation. For fcitx-classic-ui, it will be used as the original
              png file name; for fcitx-kimpanel-ui, it will be used with a "fcitx-"
!             prefix and look for icon in system icon themes.
          </para>
          <para>
!             Init is the function called when an input method is being switched to. ResetIM is
!             usually called in ResetInput. DoInput is the key function, which
              process the key event. And if the return state is IRV_DISPLAY_CANDWORDS,
!             the GetCandWords will be called. Save will be called when fcitx wants to
!             save the data, usually at logout.
          </para>
          <para>
              Priority control the order of input methods, each IM should take care of
!             it's own priority value. If a priority value is less than or equal to zero, this
              input method will not be registered to fcitx.
          </para>
      </article>
      <article>
!         <title>The things that a input method should and should not do.</title>
          <para>
!             Fcitx changes the behavior of Candidate Words handling in 4.1.0. Input method
!             should provides all candidate words, instead of a single page.
          </para>
          <para>
              Fcitx will provide the paging function, if you correctly use the candidate
***************
*** 55,61 ****
              input method, but in a separate module.
          </para>
          <para>
!             Currently fcitx only supports shared library input method, which you might think it's
              better to implement input method in a separate process, you might want to
              use DBus as a protocol. There is no easy way to do this currently, but still you
              should check the inter-module function call in order to use the shared DBus connection.
--- 55,61 ----
              input method, but in a separate module.
          </para>
          <para>
!             Currently fcitx only supports shared library input method. In case you think it's
              better to implement input method in a separate process, you might want to
              use DBus as a protocol. There is no easy way to do this currently, but still you
              should check the inter-module function call in order to use the shared DBus connection.
diff -c fcitx.developer-handbook//module.docbook modi-fcitx-developer-handbook//module.docbook
*** fcitx.developer-handbook//module.docbook    2011-08-27 22:50:53.225077844 -0700
--- modi-fcitx-developer-handbook//module.docbook   2011-08-27 23:26:49.483396391 -0700
***************
*** 6,12 ****
      <article>
          <title>Event Module</title>
          <para>
!             Event based Module in Fcitx are using fd to notify the mainloop whether
              there is new event or not. Following definition is defined in fcitx/module.h.
          </para>
          <programlisting>
--- 6,12 ----
      <article>
          <title>Event Module</title>
          <para>
!             Event based Modules in Fcitx are using fd to notify the mainloop whether
              there is new event or not. Following definition is defined in fcitx/module.h.
          </para>
          <programlisting>
***************
*** 35,45 ****
  } FcitxModule;
          </programlisting>
          <para>
!             After select, the ProcessEvent will be called and module have time to process there
!             own event.
          </para>
          <para>
!             Module neet to update rfds, wfds, efds in FcitxInstance and set the maxfd property,
              Everytime all the event get processed, all three fd_set will be set by FD_ZERO
              and SetFD will be called to reset them.
          </para>
--- 35,45 ----
  } FcitxModule;
          </programlisting>
          <para>
!             After selection, the ProcessEvent will be called and modules will have time to process their
!             own events.
          </para>
          <para>
!             Modules need to update rfds, wfds, efds in FcitxInstance and set the maxfd properly,
              Everytime all the event get processed, all three fd_set will be set by FD_ZERO
              and SetFD will be called to reset them.
          </para>
***************
*** 47,57 ****
      <article>
          <title>Other Module</title>
          <para>
!             In spite of Event based module, all other misc module will use built-in
!             hook to interference the key event processing.
          </para>
          <para>
!             Currently, there are following usable hook to interference with key event
              processing.
          </para>
          <programlisting>
--- 47,57 ----
      <article>
          <title>Other Module</title>
          <para>
!             Except Event based modules, all other misc module will use built-in
!             hook to interfere with the key event processing.
          </para>
          <para>
!             Currently, there are following usable hook to interfere with key event
              processing.
          </para>
          <programlisting>
***************
*** 68,79 ****
          </programlisting>
          <para>
              As mentioned in Architecture before, the key event processing is separated into
!             4 phases. PreInput are called before Input Method's DoInput function, usually there is
!             something that similar to input method get processed. PostInput will be called after
              Input Method's DoInput function, if the key event doesn't get processed.
          </para>
          <para>
!             Hotkey will be processed at last, but it will not be blocked even if input context
              state is ENG. That's the main difference to Pre and Post filter. If you only have
              a state need to be toggled, you'd better use hotkey instead of Input Filter.
          </para>
--- 68,79 ----
          </programlisting>
          <para>
              As mentioned in Architecture before, the key event processing is separated into
!             4 phases. PreInput is called before Input Method's DoInput function, usually there is
!             something similar to input method get processed. PostInput will be called after
              Input Method's DoInput function, if the key event doesn't get processed.
          </para>
          <para>
!             Hotkey will be processed last, but it will not be blocked even if input context
              state is ENG. That's the main difference to Pre and Post filter. If you only have
              a state need to be toggled, you'd better use hotkey instead of Input Filter.
          </para>
***************
*** 85,96 ****
      <article>
          <title>Inter Module function call</title>
          <para>
!             In order to reusing some common code, there is mechanism to do inter module function
!             call. Although it's call inter module, but all kinds of addon can provides such functions.
          </para>
          <para>
!             If a module want to provide some function, first it need a header defines correct
!             macro. Here is something that defined in fcitx/module/x11stuff.h
          </para>
          <programlisting>
  #define FCITX_X11_NAME "fcitx-x11"
--- 85,96 ----
      <article>
          <title>Inter Module function call</title>
          <para>
!             In order to reuse some common code, there is a mechanism to do inter module function
!             call. Although it's called inter module, but all kinds of addon can provide such functions.
          </para>
          <para>
!             If a module wants to provide some functions, first it need a header defineing the correct
!             macro. Here is something defined in fcitx/module/x11stuff.h
          </para>
          <programlisting>
  #define FCITX_X11_NAME "fcitx-x11"
***************
*** 115,135 ****
          </programlisting>
          <para>
              fcitx_add_addon_header is provided by FcitxMacro.cmake to get this header installed to
!             correct place.
          </para>
          <para>
!             All function has the same interface, like this:
          </para>
          <programlisting>
  void* X11GetDisplay(void* arg, FcitxModuleFunctionArg args);
          </programlisting>
          <para>
!             For any other addon need to call a function, if this is a must for your addon,
!             you should add that module as dependency in your addon configure file.
!             You can also check the module is loaded or not at runtime via GetAddonByName.
          </para>
          <para>
!             If you want to call a function in other module, you should use InvokeFunction macro
              defined in fcitx/module.h.
          </para>
          <programlisting>
--- 115,135 ----
          </programlisting>
          <para>
              fcitx_add_addon_header is provided by FcitxMacro.cmake to get this header installed to
!             the correct place.
          </para>
          <para>
!             All functions have the same interface, like this:
          </para>
          <programlisting>
  void* X11GetDisplay(void* arg, FcitxModuleFunctionArg args);
          </programlisting>
          <para>
!             For any other addon that need to call a function, if this is a must for your addon,
!             you should add that module as a dependency in your addon configure file.
!             You can also check whether the module is loaded or not at runtime via GetAddonByName.
          </para>
          <para>
!             If you want to call a function in other module, you should use the InvokeFunction macro
              defined in fcitx/module.h.
          </para>
          <programlisting>
***************
*** 137,143 ****
          </programlisting>
          <para>
              FcitxModuleFunctionArg provides ten void* slot for passing argument, which is
!             enough to passing arguments.
          </para>
      </article>
      <article>
--- 137,143 ----
          </programlisting>
          <para>
              FcitxModuleFunctionArg provides ten void* slot for passing argument, which is
!             enough for passing arguments.
          </para>
      </article>
      <article>
diff -c fcitx.developer-handbook//userinterface.docbook modi-fcitx-developer-handbook//userinterface.docbook
*** fcitx.developer-handbook//userinterface.docbook 2011-08-27 22:50:53.225077844 -0700
--- modi-fcitx-developer-handbook//userinterface.docbook    2011-08-27 23:27:12.193273362 -0700
***************
*** 9,15 ****
          </para>
      </article>
      <article>
!         <title>Using user interface element in module</title>
          <para>
          </para>
      </article>
--- 9,15 ----
          </para>
      </article>
      <article>
!         <title>Using user interface elements in module</title>
          <para>
          </para>
      </article>