@@ -79,6 +79,72 @@ with some special rules to handle some omissions from `terminfo`.
7979
8080Windows is not supported.
8181
82+# Multi-Column Character Support
83+
84+Vty supports rendering of multi-column characters such as two-column
85+Asian characters and Emoji characters. This section details how to
86+take advantage of this feature, since its behavior will depend on the
87+terminal emulator in use.
88+
89+Terminal emulators support Unicode to varying degrees, and each terminal
90+emulator relies on a table of column widths for each supported Unicode
91+character. Vty also needs to rely on such a table to compute the width
92+of Vty images to do image layout. Since those tables can disagree if
93+Vty and the terminal emulator support different versions of Unicode,
94+and since different terminal emulators will support different versions
95+of Unicode, it's likely that for some wide characters, Vty applications
96+will exhibit rendering problems. Those rendering problems arise from Vty
97+and the terminal emulator coming to different conclusions about how wide
98+some characters are.
99+
100+Vty has a built-in Unicode character width table. Unless configured to
101+do otherwise, by default, Vty will use this built-in table. But since
102+the built-in table is likely to eventually disagree with your terminal,
103+Vty provides a feature called custom Unicode character width table
104+support. This feature allows Vty to query your terminal to build a width
105+table based solely on your terminal emulator's logic. That table is then
106+saved to disk and loaded by Vty-based applications to ensure that Vty's
107+width calculations are correct for that particular terminal.
108+
109+Custom Unicode width tables based on your terminal emulator can be
110+built by running Vty's built-in tool, `vty-build-width-table`. The tool
111+works by querying the current terminal emulator to obtain its width
112+measurements for the entire supported Unicode range. The
113+results are then saved to a disk file. These custom tables
114+can also be generated programmatically by using the API in
115+`Graphics.Vty.UnicodeWidthTable.Query`.
116+
117+Saved width tables can then be loaded in one of two ways:
118+
119+* Via the library API in `Graphics.Vty.UnicodeWidthTable.IO`
120+* By adding a `widthMap` directive to your Vty configuration file
121+
122+The Vty configuration file supports the `widthMap` directive to allow
123+users to specify which custom width table should be loaded for a given
124+terminal type. This is done by specifying, e.g.,
125+
126+```
127+widthMap "xterm" "/path/to/map.dat"
128+```
129+
130+where the first argument is the value that `TERM` must have in order for
131+the table to be loaded, and the second argument is the path to the table
132+file itself as generated by the two alternatives listed above. If the
133+Vty configuration file contains multiple matching `widthMap` directives
134+for the current value of `TERM`, the last one listed in the file is
135+used.
136+
137+The tables declared in the configuration file are only ever
138+automatically loaded when applications set up Vty by calling
139+`Graphics.Vty.mkVty`.
140+
141+Before a custom table has been loaded, calls to the library's character
142+width functions (e.g. `wcwidth`) will use the default built-in table.
143+Once a custom table has been loaded, the functions will use the new
144+custom table. Only one custom table load can be performed in a Vty
145+program. Once a custom table has been loaded, it cannot be replaced or
146+removed.
147+
82148# Contributing
83149
84150If you decide to contribute, that's great! Here are some guidelines you