# terminal resources

The virtual terminal subsystem requires various resources.

## keyboard maps

On systems with `/usr/share/vt/keymaps/` (such as FreeBSD), the external formats conversion subsystem takes the old-style SCO/FreeBSD kernel virtual terminal keyboard maps from there and generates a range of keyboard map files suitable for `console-ugen-hid-realizer` (and the other keyboard realizers) by passing them through `console-convert-kbdmap`. The original maps are converted with some modifications supplied by overlay map files:

`soft_backspace.kbd`

  The DEC VT backspace ⌫ key is actually programmable with the DECBKM control sequence. The FreeBSD keyboard maps hardwire the mapping from the backspace ⌫ keycode to the `DEL` and `BS` control characters, and if used as they stand would prevent the key from being soft-switchable. This overlay replaces that with a mapping to the `bspace` action, letting `console-terminal-emulator` handle the mapping to control characters in concert with the DECBKM setting.

`soft_delete.kbd`

  The XTerm delete ⌦ key is actually programmable with the DECSM/DECRM 1037 control sequences. The FreeBSD keyboard maps hardwire the mapping from the delete ⌦ keycode to the `DEL` control character, and if used as they stand would prevent the key from being soft-switchable. This overlay replaces that with a mapping to the `delete` action, letting `console-terminal-emulator` handle the mapping to control characters in concert with the DECSM/DECRM 1037 setting.

`soft_enter.kbd` and `soft_return.kbd`

  Likewise, these replace hardwired FreeBSD mappings, from the return ⮠ and enter keys to the `CR` and `LF` control characters, with the `return` and `enter` actions. The DEC VT enter key is actually programmable with the DECNKM control sequence. The `enter` action lets `console-terminal-emulator` handle the mapping to control characters in concert with the DECNKM setting. The `return` action ensures that the return key can be distinguished from a `CR` or `LF` control character in input messages.

`soft_escape.kbd`

  The escape ⌫ key is actually programmable with a control sequence. The FreeBSD keyboard maps hardwire the mapping from the escape ⌫ keycode to the `ESC` control character, and if used as they stand would prevent the key from being soft-switchable. This overlay replaces that with a mapping to the `escape` action, letting `console-terminal-emulator` handle the mapping to control characters in concert with the terminal emulator setting.

`soft_tab.kbd`

  The FreeBSD keyboard maps hardwire the mapping from the tab ⇥ keycode to the `TAB` control character, and if used as they stand would prevent the key from being soft-switchable. This overlay replaces that with a mapping to the `tab` action, letting `console-terminal-emulator` handle the mapping to control characters. The `tab` action ensures that the tab key can be distinguished from a `TAB` control character in input messages.

`jp_to_jp.104.kbd` `jp_to_jp.109.kbd`

  The FreeBSD keyboard maps usually apply to all of the Model M/Windows keyboards invariantly. Overlays such as this are per-country per-keycount fixes for various things.

  The FreeBSD `jp.kbd` keyboard map maps the "Grave" key (engraved with Zenkaku/Henkaku/Kanji on the JIS 109-key keyboard) to the `ESC` control character.

  - `jp_to_jp.109.kbd` fixes it for 109-key keyboards to instead map the "Grave" key to the "IM Switch" input event that activates and deactivates the input method front-end processor, mapping the extra "International3" key on the 109-key keyboard to (most of) what the "Grave" key does on 104-key keyboards.

  - `jp_to_jp.104.kbd` fixes it for other keycount keyboards to instead map the "Grave" key to what the "International3" key does on 109-key keyboards.

`swap_capsctrl.kbd` `modelm_capsctrl.kbd`

  Normally keyboard maps are built with the `modelm_capsctrl.kbd` overlay that uses the normal Model M/Windows keyboard placement of the "Caps Lock" and "Ctrl" keys, but adds a "Shift Lock" capability to the "Caps Lock" key. When the `.capsctrl` option is used they are instead built with the `swap_capsctrl.kbd` overlay that still adds "Shift Lock" but swaps the positions of the two keys.

On systems where there is no `/usr/share/vt/keymaps/`, the external formats conversion subsystem generates a (narrower) range of keyboard map files by overlaying the default null map, U.S. International, built into `console-convert-kbdmap` with map files that provide just the differences between U.S. International and other layouts rather than entire maps as come with FreeBSD. For example:

- `default_to_de.kbd` is the difference between U.S. International and DIN standard.

- `default_to_uk.kbd` is the difference between U.S. International and U.K. International.

The generated keyboard maps are placed in `/etc/system-control/convert/kbdmaps/` and can be linked to the service directories of, or simply used directly by, any keyboard device user-space virtual terminal realizer services. Their names follow a regular pattern comprising the ISO country code, the PC Windows keyboard variant (i.e. 104, 105, 106, 107, or 109), and any options such as `.capsctrl`.

N.B.: Each country has multiple keycount variants as there are different conventional mappings for the different keycounts in several countries. One could have either a 105-key ABNT keyboard or a 107-key ABNT2 keyboard in Brazil, for example, which differ for starters in how the key at B10 is mapped. (Technically, the old ABNT NBR 10346:1988 standard was replaced by the newer NBR 10346:1991 standard.)

## fonts

Fonts suitable for `console-fb-realizer` and `console-kvt-realizer` have to be in the "vt" format of FreeBSD. Unifont-style HEX fonts and BDF fonts can be converted to this format with FreeBSD's `vtfontcvt` tool.

### `vtfontcvt` caveats

In order to work with FreeBSD's `vtfontcvt` tool:

- HEX fonts must either be height 16 or begin with an explicit `# Height :` directive. Otherwise, `vtfontcvt` will by default do things such as erroneously treat an 8×8 font as a 4×16 font, processing it nybble by nybble instead of byte by byte.

- BDF fonts must be (arbitrarily) limited to 8 or 16 pixel-wide bounding rectangles. This unfortunately prevented FreeBSD's `vtfontcvt` until 2019 from being able to convert Ubuntu Monospace, which has varying-sized bounding rectangles for individual characters.

One can convert other formats to BDF format first, using tools like Jan Engelhardt's fnt2bdf.

The "vt" font format uses 16-bit integers for some fields, such as the internal glyph index. It cannot cope with fonts that cover more than about half of a Unicode plane. Fortunately, `console-fb-realizer` and `console-kvt-realizer` allow one to build up full Unicode coverage using multiple font files as a sequence of overlays.

### Broad range monospace fonts

These cover large parts or even all of the defined Unicode code pointsm, ranging from a few thousand to over a hundred thousand glyphs.

- GNU Unifont has extensive glyph coverage of Unicode, and comes in HEX form.

  The "_all" files exceed the 16-bit limits of "vt" font files; and they also fill in unused glyphs with placeholders. The latter would make falling back from Unifont to another font that has the placeholders impossible, even without the 16-bit limits. Fortunately, Unifont also (now) comes in the form of one-file-per-plane, and those are what must be used.

- vgarom-8x16 is a "vt" font that comes in the box with FreeBSD (in `/usr/share/vt/fonts/`), purportedly taken from VGA ROM firmware of a PC compatible. It only has a very small glyph repertoire of some 600 glyphs, covering mainly the common 8-bit code pages of MS/PC/DR-DOS systems.

- Ed Maste also produced a small repository of "vt" fonts for FreeBSD's "vt" subsystem. Amongst others, this includes HEX versions of fonts which are also available standalone:

  - k16-1990.bdf — a square 16×16 pixels JISX0208.1990 font with many CJK glyphs.

- Ville-Matias Heikkilä's unscii-16 font takes inspiration from personal and home computer 8×8 and 8×16 fonts, and comes in HEX form. Home computer 8×8, 8×16, and 16×16 fonts are particularly useful for `console-fb-realizer` and `console-kvt-realizer` as they were designed for a square aspect ratio rather than for an oblong one. They also provide useful glyph close to or the same as the originals for microcomputer text-glyph art often used in TUIs, such as indeed the MouseText that is used by the `login-envuidgid` command.

  The "-full" variant fills in the code points not supplied by unscii itself with glyphs from a years out-of-date version of GNU Unifont, and also mixes in a few thousand glyphs from Darien Valentine's FixedSys Excelsior (a clone of Microsoft Windows' FixedSys, whose old WWW site is long since defunct but which is nowadays available from Kirill Pertsev). The source includes glyphs from 8×8 fonts from old home computers, such as the BBC Micro, CPC64, and Sinclair ZX Spectrum; but they are not incorporated into the built HEX fonts supplied by the author.

  This fork builds more fine-grained HEX files, suitable for use as overlay fonts with `console-fb-realizer`. including all of the home computer fonts as individual overlays, and the just over 3 thousand glyphs that are actually Unscii's own in its own individual overlay too. It also contains enlarged 16×16 versions of the 8×8 Commodore PET, Dragon 32/64, and BBC Micro fonts; which have better curves and diagonals for the strokes.

- Ben Harris's bedstead fonts cover the character sets in every national variant of the Mullard SAA5050 teletext chip, which is roughly 2 thousand glyphs. It comes in BDF form.

- Markus Kuhn's -misc-fixed- fonts, especially 9x15 and 9x15B, have a fairly wide coverage of the BMP. They come in BDF form.

- Dmitry Yu. Bolkhovityanov's Unicode VGA is based upon the vga.bdf in XDosEmu. It covers several thousand glyphs in the BMP, but not all of it, nor any of the supplementary Unicode planes.

- Uwe Waldmann's UW ttyp0 covers only some of the BMP. It comes in BDF form.

- Dmitry Bolkhovityanov's VGA font covers only some of the BMP. It comes in BDF form.

- M+ fonts come in BDF form and cover roughly 7 thousand Kanji (JISX0208) glyphs.

- Hisham Muhammad's lode fonts come in BDF form (in the X11 subdirectory — not the consolefont subdirectory) and cover roughly 4 thousand glyphs.

- Micah Elliott's Orp font (git) is based upon Markus Kuhn's, with some alterations and som imports from other fonts, and comes in BDF form.

- tewi font comes in BDF form and covers roughly 3400 glyphs.

- Dylan Simon's font comes in BDF form and covers roughly 3300 glyphs, with explicit bold and oblique variants.

- lemon font comes in BDF form and covers roughly 2700 glyphs. The source code repository includes copies of several other people's fonts in BDF form, including antidote, uushi, limey, and berry.

- Wiktor Kerr's leggie font (git) comes in BDF form and covers roughly 1700 glyphs.

- Frederic Cambus's spleen font (git) comes in BDF form and covers roughly 900 glyphs. The FreeBSD port builds and installs "vt" format font files, but does not place them in `/usr/share/vt/fonts/`.

- IBM PlexMono in "vt" font form.

### Limited range monospace fonts

These cover only small parts of Unicode, usually little more than a few hundred glyphs that form a subset defined by an 8-bit character set such as an ISO 8859 one or an IBM/Microsoft code page. Generally these are not useful for the more modern, more free, uses of Unicode in terminals, which will often extend to many things not in the old 8-bit character sets, from non-VGA drawing and box characters through extra punctuation and symbols to MouseText and emoji.

- Rob Hagemans' "hoard of bitfonts does not have very extensive glyph coverage, but like Unscii provides useful 8×8 glyphs of many home computer flavours covering ASCII and some of the ISO/IEC 8859-1 code points, as well as quite a few non-Latin dingbat glyphs such as arrows and box/line drawing characters.

  The fonts come in an idiosyncratic YAFF format, for which the collector has not coincidentally developed a font editor program, and there is no direct conversion from that to BDF. However, it is a matter of a short Perl script to convert YAFF to Unscii's more versatile text form, and from that use Unscii tooling to generate Unifont HEX format files and thence a "vt" format font.

- Cyril Hrubis's Haxor fonts come in BDF form, and cover only ISO 8859-2.

- Carpentier Pierre-Francois's kakwa font comes in BDF form, and covers only ISO 8859-1.

- Kim A. Ødegaard's lokaltag fonts come in BDF form, and cover only ISO 8859-1 plus a few symbols in the PUA.

- Hugo Chargois's GoHuFont (git) is partly based upon Markus Kuhn's, and comes in BDF form. (Note: The FreeBSD port does not build or install any "vt" fonts, even though it could; it only builds fonts for X11.) It only includes a few hundred glyphs, mostly ISO 8859-1, and not the entire range of the base Kuhn fonts.

- bijn's ctrl-d font comes in BDF form, and covers only ISO 8859-1 plus a few arrows and blocks and some symbols in the PUA, coming to just over 3 hundred glyphs.

- Aaron Chrisianson's biatocra and bitubuntu fonts come in BDF form, and cover only ISO 8859-1 plus Latin Extended-A, coming to just over 4 hundred glyphs.

- Ruby Juricf's augmented version of ypnose's envypn font comes in BDF form, and covers only ISO 8859-1, a few triangles, and some PUA characters, coming to just over 2 hundred glyphs.

- Leah Neukirchen's sq font comes in BDF form, and covers only ISO 8859-1, coming to just under 2 hundred glyphs.

- cherry font comes in BDF form, and covers only ISO 8859-1, coming to just under 2 hundred glyphs.

- Gilles Boccon-Gibod's MonteCarlo has derivative Scott Fial's Tamsyn which in turn has derivative Suraj N. Kurapati's Tamzen. They all come in BDF form, but only cover ISO 8859-1, coming to just under 2 hundred glyphs.

- Joseph Gil's fntcol16.zip package is a collection of VGA firmware and MS/PC-DOS fonts. The fonts are in an idiosyncratic format that first must be converted to BDF and mapped to the relevant Unicode code points.

## input methods

`console-input-method` is table-driven. The tables that it uses are the same CIN data files as are used by xcin, gcin (GitHub), jscin (GitHub), hime (GitHub), PIME (GitHub), OpenVanilla (GitHub), Chinese Open Desktop (GitHub), OkidoKey.app (GitHub), and MacOS.

Some operating systems supply snapshots of some of these collections as packages, such as Debian's openvanilla-imgeneric-data-all package for example.

The CIN file collections supplied with each software do not exactly overlap, and some are more up-to-date than others, but taken as a whole they range from Esperanto input helpers through Pinyin and Katakana to Hanja. The nosh toolset does not provide yet another collection to augment the mess. Rather, one should pull the CIN files from these collections. There are three exceptions:

`hiragana`

  This data table provides an input method for Hiragana, encoding everything explicitly in the data table itself, including gemination of consonants for sokuon. It incorporates only Nihon-shiki and Kunrei-shiki, and is case-insensitive.

`katakana`

  This data table provides an input method for Katakana and symbols, encoding everything explicitly in the data table itself, including gemination of consonants for sokuon and gemination of vowels for chōonpu. It is a grab-bag mixture of Nihon-shiki, Kunrei-shiki, Hebon-shiki, Hyoojun-shiki, old ANSI/BS standards, and unofficial but common stuff (such as an "l" prefix for little kana). It also incorporates ASCII spellings for punctuation and symbols, such as "hakko" for various sorts of brackets, and is case-insensitive.

`romaji-x11`

  This data table incorporates a subset of the Xlib compose key sequences, not duplicating Xlib sequences that are available in other ways on user-space virtual terminals. (For examples: Many of the combining diacritics are already a standard part of the keyboard map, in the common secondary group, because of ISO 9995-3. Hangeul and Kana are already directly available via other input methods dedicated to them.) It is suitable for use as a "romaji" input method alongside CJKV input methods.