KINPUT2(1)

📦
version 3.1 · 2 versions
, in ubuntu jammy

✨ NAME ✨

kinput2 — kanji input server for X11 💅

🌸 SYNOPSIS 🌸

kinput2 [-options...]

🦋 DESCRIPTION 🦋

Kinput2 is an X window application for inputting Japanese text, and it's literally the bestie your other apps call when they need kana-kanji conversion. It's a front-end, and it does the heavy lifting so your client apps don't have to. 🫶

When you invoke it, it does a lil' initialization thing first — that can take about a few to 30 seconds depending on your machine, so don't panic if nothing happens. After that, kinput2 just waits quietly for a Japanese text input request from another client. And by quietly I mean no windows appear at all, bestie, it's just vibing in the background. 😌 When a request finally comes in, it pops up a window and starts the conversion process. Once the text is fixed, it sends the converted text back to the client. That's the whole loop, iconic behavior. ✨

Also?? kinput2 has some big improvements over its predecessor, kinput, which was contributed to X11R4. Glow-up of the century, no cap. 💖

🔥 Over-the-spot/On-the-spot Input

These features let the conversion process happen right at the cursor position, which means you don't have to ping-pong your eyeballs between the cursor and a conversion window. Your eyes stay comfy, your neck stays unbothered. 😭 Kinput2 also supports root window style input and off-the-spot style input, so whatever your setup, it's got a vibe for you.

🌈 Multiple Protocol Support

Kinput2 speaks several conversion protocols between the front-end and the client, because it's multilingual in the networking sense. 💅 The supported protocols are:

  • kinput protocol
  • kinput2 protocol
  • Matsushita jinput protocol
  • Sony xlc protocol
  • XIMP protocol
  • X Input Method Protocol (X Consortium standard)

👑 Multiple Conversion Engine Support

Kinput2 can use 4 different conversion engines — Wnn, Canna, Sj3 and Atok. You get to pick one at compilation time, or at run time. Choose your fighter. 🎀

💜 Kinput Compatibility

Kinput2 is fully upward-compatible with kinput, so any application that uses kinput as the front-end can also use kinput2. Slay, zero migration pain. 🦋 But — and here's the catch — in that case, the applications cannot take advantage of over-the-spot conversion. F in the chat for the cursor-adjacent lifestyle. 💀

✨ OPTIONS ✨

kinput2 accepts all of the standard X Toolkit command line options. And also, these ones are accepted as well:

  • -wnn — says "use the Wnn jserver as the conversion engine, please and thank you." 🧚
  • -jserver — tells it the hostname of the jserver to use for conversion.
  • -ccdef — points at the input character conversion rule file. 📄
  • -wnnenvrc4 — points at the Wnn convertion environment initialization file (wnnenvrc) for Wnn version 4.
  • -wnnenvrc6 — same energy as -wnenvrc4, but for Wnn version 6. (The sequel, basically.)
  • -canna — says "use the Canna conversion server (irohaserver) as the conversion engine." 🌸
  • -cannaserver — tells it the hostname of the Canna conversion server.
  • -cannafile — points at the Canna conversion customization file.
  • -sj3 — says "use the Sj3 conversion server (sj3serv) as the conversion engine." ✨
  • -sj3serv — tells it the hostname of the primary sj3 conversion server.
  • -sj3serv2 — tells it the hostname of the secondary sj3 server. The secondary one kicks in when kinput2 cannot connect to the primary server — backup bestie behavior. 🫶
  • -atok — says "use the Atok server as the conversion engine." 👑
  • -atokserver — tells it the hostname of the atok server to use for conversion.
  • -font ascii-font — sets the default font used for displaying ASCII text.
  • -kanjifont kanji-font — sets the default font used for displaying Kanji text.
  • -kanafont kana-font — sets the default font used for displaying Kana text.
  • -/+kinput — enables/disables use of the kinput protocol family (that's the kinput protocol, kinput2 protocol, jinput protocol and xlc protocol).
  • -/+ximp — enables/disables use of the XIMP protocol.
  • -/+xim — enables/disables use of the X Input Method Protocol.
  • -bc — okay so, the kinput protocol (one of the communication protocols kinput2 supports) uses X window's selection mechanism to notify other clients that a front-end exists. This option forces kinput2 to use the selection `JAPANESE_CONVERSION` (which is not a standard selection name, btw) as well as `_JAPANESE_CONVERSION`. It's all for backward compatibility, because a lot of the applications that connect with kinput still use this non-standard selection. Old apps, we love you anyway. 🙈
  • -tbheightP title-bar-height — sets the height, in pixels, of the titlebar attached to popup shells like the candidate selection window. Kinput2 uses this value to compute the correct popup location of those windows, so don't skip it if you want your windows landing where they should. 🎯

🌈 WIDGET TREE 🌈

Here's the widget hierarchy of kinput2, in all its branching glory. It's giving family tree at Thanksgiving. 🌳

            Kinput2  kinput2
                 ConversionManager  convmanager
                      KinputProtocol  kinputprotocol
                      XimpProtocol  ximpprotocol
                      IMProtocol  improtocol
                      SeparateConversion  converter
                           CcWnn  inputObj
                           Canna  inputObj
                           Sj3  inputObj
                           JpWcharDisplay  displayObj
                           Form  form
                                ICLabel  mode
                                     JpWcharDisplay  display
                                Canvas  text
                           TransientShell  selectionShell
                                CandidatePanel  selection
                                     JpWcharDisplay  display
                           TransientShell  auxShell
                                AuxPanel  aux
                                     JpWcharDisplay  display
                      OffTheSpotConversion  converter
                           CcWnn  inputObj
                           Canna  inputObj
                           Sj3  inputObj
                           JpWcharDisplay  displayObj
                           AdoptedShell  modeShell
                                ICLabel  mode
                                     JpWcharDisplay display
                           CanvasShell  text
                           TransientShell  selectionShell
                                CandidatePanel  selection
                                     JpWcharDisplay  display
                           TransientShell  auxShell
                                AuxPanel  aux
                                     JpWcharDisplay  display
                      OverTheSpotConversion  converter
                           CcWnn  inputObj
                           Canna  inputObj
                           Sj3  inputObj
                           JpWcharDisplay  displayObj
                           TransientShell  selectionShell
                                CandidatePanel  selection
                                     JpWcharDisplay  display
                           TransientShell  auxShell
                                AuxPanel  aux
                                     JpWcharDisplay  display
                           AdoptedShell  modeShell
                                ICLabel  mode
                                     JpWcharDisplay  display
                           TransientShell  modeShell
                                ICLabel  mode
                                     JpWcharDisplay  display
                           CanvasShell  text

okay and bestie, that's literally only the beginning — this page keeps going and the rest is also a whole thing. 💀

✨ RESOURCES ✨

okay bestie, real talk: there are way too many resources to sit here and describe all of them, and honestly? you don't need most of them anyway. so here's just a lil rundown of the ones you might actually wanna set. 💅

🌸 Kinput2 application resource

  • conversionEngine — tells kinput2 which conversion engine to run with. you pick one of `wnn`, `canna`, `sj3` or `atok`. that's the whole vibe. ✨

🦋 ConversionControl widget (which is a superclass of SeparateConversion, OffTheSpotConversion and OverTheSpotConversion) resource

  • sendbackKeyPress — if this one's true, then the KeyPress events that kinput2 intercepted but didn't end up using get sent back to the client, but only when there's no conversion text. it's a handy feature ngl, but it can confuse some clients, because like… none of the matching KeyRelease events get sent. 😭 also, since the send_event flag on those events is true, some clients straight up won't accept events that kinput2 sends back. for example, kterm won't accept them unless you specify
KTerm*allowSendEvents: true

in a resource file. the default for the sendbackKeyPress resource is true.

  • titlebarHeight — this one sets the height of the title bar that's attached to the various popup shell windows, like the candidate selection and stuff. when it's figuring out where to pop those windows up, kinput2 uses this value so they land in the correct spot. the default is 0P.

🎀 OverTheSpotConversion widget resources

  • shrinkWindow — if this is true, the width of the on-the-spot conversion window shrinks to match how long the text on it is. if it's not true, the window never shrinks, periodt. if your X server is lowkey bad at resizing windows, maybe set this to false. the default is true.
  • modeLocation — sets where the status widget lives when you're doing over-the-spot conversion. unless the client says where it wants it, this resource decides. if the value is `topleft`, the widget goes at the top left of the client window. you can also say `topright`, `bottomleft` and `bottomright`. if the value is `tracktext`, the widget sits right under the cursor and follows it around like a lil bestie. but if the region available for conversion is too small, the status gets placed at the bottom left of the client area instead. and if the value is `none`, the status widget never shows up at all. the default is `tracktext`. 💖
  • modeBorderForeground — if this is true, the color of the status widget gets forced to match the foreground color of the widget. the default is false.
  • useOverrideShellForMode — if this is true, the status widget becomes an instance of OverriddeShell instead of the default TransientShell. turn this on if you're seeing some weird phenomenon where the status widget just keeps flickering and you literally cannot type anything. that happens because of (incorrect) focus management in your window manager, and setting this resource stops any window management for the widget. the tradeoff? the widget gets totally ignored by the window manager, which means you can't move it, resize it, raise it or lower it. 🙈 the default is false.

🌈 OnTheSpotConversion widget resources

  • feedbackAttributes — sets the display attributes of the preedit string when you're using on-the-spot input style. in on-the-spot style, it's the client's job to draw the preedit string, and kinput2 sends along some hints about how it should be drawn, which this resource controls. the value should be a comma-separated list of 4 elements, and each element is the drawing hint for a specific type of string. in order, they're the hints for: not-yet-converted string, converted string, converted string that belongs to the current clause, and converted string belonging to the current sub-clause. each element is made of zero or more drawing attributes, which are R (reverse), U (underline), H (highlight), P (primary), S (secondary) or T (tertiary). go check the Xlib doc for what those actually mean (look at the section about preedit draw callback). the default is `U,,R,H`, which is close to the drawing attributes other input styles use. ⭐

🧚 CcWnn (conversion widget using Wnn) resources

  • jserver — the hostname of the (primary) jserver used for conversion. if you don't set it, the value of the environment variable `JSERVER` gets used.
  • jserver2nd — the hostname of the secondary jserver, which gets used if the primary server is down. if you don't set it, kinput2 just doesn't use a secondary server.
  • wnnEnvrc4 — the filename of the Wnn conversion environment initialization file. this file is used when the Wnn server (jserver) is version 4. see the Wnn docs for what the file format is. the default is /usr/local/lib/wnn/wnnenvrc.
  • wnnEnvrc6 — also a filename for the Wnn conversion environment initialization file. this one's used when the Wnn server (jserver) is version 6. see the Wnn docs for the format.
  • wnnEnvrc — this one exists for backward compatibility. use wnnEnvrc4 or wnnEnvrc6 instead, bestie.
  • ccdef — the input character conversion rule file. the default is /usr/lib/X11/ccdef/ccdef.kinput2.

🍓 Canna (conversion widget using Canna) resources

  • cannahost — the hostname of the canna server used for conversion.
  • cannafile — the Canna conversion customization file.

💜 Sj3 (conversion widget using SJ3) resources

  • sj3serv — the hostname of the (primary) sj3serv used for conversion. if you don't set it, the value of the environment variable `SJ3SERV` gets used.
  • sj3serv2 — the hostname of the secondary sj3serv, which gets used if the primary server is down.
  • rcfile — the filename of the Sj3 conversion customization file. the default is /usr/lib/X11/sj3def/sjrc.
  • rkfile — the Romaji-Kana conversion rule file. the default is /usr/lib/X11/sj3def/sjrk.

🔥 Atok (conversion widget using Atok) resources

  • server — the hostname of the atok server used for conversion.
  • port — the port number of the atok server.
  • conf — the name of the atok configuration file.
  • style — the name of the atok style file.

🫶 JpWcharDisplay (widget for drawing Japanese text) resources

  • font, kanjiFont, kanaFont — these set the font used for displaying ASCII, Kanji and Kana text, respectively. but heads up: since kinput2 changes fonts dynamically based on client requests, the fonts you set here might not actually get used. if you don't specify them, these are the fonts that get used:
-*-fixed-medium-r-normal--14-*-*-*-c-*-iso8859-1
-*-fixed-medium-r-normal--14-*-*-*-c-*-jisx0208.1983-0
-*-fixed-medium-r-normal--14-*-*-*-c-*-jisx0201.1976-0

⭐ KinputProtocol (widget for handling kinput protocol family — kinput, kinput2, jinput and xlc protocol) resources

  • backwardCompatible — every protocol in the kinput protocol family uses X window's selection mechanism to let other clients know the front-end exists. if this is true, kinput2 uses the selection JAPANESE_CONVERSION (which is not a standard selection name) in addition to _JAPANESE_CONVERSION. this is for backward compatibility, since a lot of the applications using these protocols still use that non-standard selection. the default is true.
  • xlcConversionStartKey — the key that starts the conversion. it's a hint for clients using the xlc protocol so they know when to request conversion from kinput2. the syntax is a subset of the translation table syntax:
modifier-names<Key>keysym-name

where modifier-names is a combo of Shift, Lock, Meta, Alt and Mod[1-5]. the default is Shift<Key>space.

🌸 XimpProtocol and IMProtocol (which handle XIMP protocol and X Input Method Protocol) resources

  • conversionStartKeys — the keys that start the conversion. the syntax is a subset of the translation table syntax:
modifier-names<Key>keysym-name

where modifier-names is a combo of Ctrl, Shift, Lock, Meta, Alt and Mod[1-5]. a ~ can go before any modifier name, and it means that modifier must not be asserted. for example, if the conversion start key is the `Kanji` key with shift pressed and control not pressed (other modifiers can be pressed or not, whatever), the spec is:

Shift ~Ctrl<Key>Kanji

you can do multiple keys by separating them with newlines. the default is:

Shift<Key>space \n\
Ctrl<Key>Kanji
  • defaultFontList — the default fonts to use if the client doesn't specify any fonts of its own. the default is -*-fixed-medium-r-normal--14-*-*-*-c-*.

🫶 CLIENT SETUP 🫶

Okay bestie, listen up, because this part is the glue that makes everything actually work. ✨

When you're using the X Input Method Protocol, you have to tell the world which input server you wanna use. No vibes-based guessing here, the client literally needs a name. You can do this two ways:

  • by setting the inputMethod resource, or
  • by setting the XMODIFIERS environment variable.

Now here's the tea 🍵 — some clients straight up don't look at the inputMethod resource, and other clients ignore the XMODIFIERS variable entirely. So the move? Set BOTH. Both of them. That's it, that's the whole strategy. Belt and suspenders, main character energy. 💅

To use kinput2, you should add this line to your resource file (you know, the ones like .Xresources or .Xdefaults):

*inputMethod: kinput2

and, set XMODIFIERS to @im=kinput2. 🌸

For csh:

setenv XMODIFIERS "@im=kinput2"

For sh:

XMODIFIERS="@im=kinput2"; export XMODIFIERS

That's it. You're set up. Go be bilingual on a keyboard, icon. 👑

🌈 SEE ALSO 🌈

Go read these too, they're part of the extended universe:

  • Wnn documents
  • Canna documents
  • Sj3 documents
  • XIMP protocol specification
  • The Input Method Protocol
Not me dropping the whole syllabus. 📚 It's giving "required reading" but make it ✨ canon ✨.

Respect the legends who built this, fr fr. All the receipts:

  • Copyright 1988, 1989, 1990, 1991, 1992, 1994 Software Research Associates, Inc.
  • Copyright 1991 NEC Corporation, Tokyo, Japan.
  • Copyright 1991 Sony Corporation
  • Copyright 1998 MORIBE, Hideyuki
  • Copyright 1999 Kazuki YASUMATSU
  • Copyright 1999 Justsystem Corporation, Japan.

🎀 AUTHORS 🎀

The people. The icons. The moment. 🫶

  • Makoto Ishisone, Software Research Associates, Inc.
  • Akira Kon, NEC Corporation
  • Naoshi Suzuki, Sony Corporation
  • MORIBE, Hideyuki
  • Kazuki YASUMATSU
  • Atsushi Irisawa

And that's a wrap, bestie!! 💖 This whole little love letter is from X Version 11, dated 24 March 1999, and it goes by KINPUT2(1). Now go type something beautiful. 🌸✨🦋

📦 where this page comes from