pith/IO.ReadMe

   1 Here's an attempt at a high-level description of the I/O flow and the
   2 character set conversions for Alpine from the UNIX point of view. Pico and
   3 Pine were developed separately so there is a big difference in the way
   4 that Alpine handles stuff and the way the pico composer handles stuff.
   5
   6 INPUT
   7
   8 There's a low-level function called input_ready() that does a select
   9 or a poll to see if an octet is ready to be read.  Alpine's read_char
  10 and pico's GetKey call this:
  11
  12    read_char                     Alpine
  13      check_for_timeout
  14        input_ready
  15 or
  16    GetKey                        Pico
  17      ReadyForKey
  18        input_ready
  19
  20 Once they've decided an octet is ready to be read they use various versions
  21 of ttgetc (ttgetc, simple_ttgetc, pine_simple_ttgetc) which all boil down
  22 to a read of one octet from the keyboard. That incoming stream of
  23 characters is a stream of multi-byte characters. For example, it might
  24 be ASCII, UTF-8, ISO-8859-1, or EUC-JP. This would usually be configured
  25 using the LANG or LC_CTYPE environment variables, or possibly using
  26 the Alpine Keyboard-Character-Set or Display-Character-Set options.
  27 The pith routine mbtow is used to convert this stream of bytes into
  28 UCS-4 characters in the routine kbseq.
  29
  30    read_char
  31      kbseq          (uses ttgetc to accumulate bytes)
  32        mbtow
  33 or
  34    GetKey
  35      kbseq          ( " )
  36        mbtow
  37
  38 So read_char and GetKey both return UCS-4 characters from the keyboard.
  39 They actually return a superset of a UCS-4 character (typedef UCS) that
  40 is 32 bits wide. The superset comes about from the handling of
  41 escape sequences and error conditions. Besides the 21 bits of UCS-4
  42 characters other values that might be returned are values like KEY_UP,
  43 KEY_RESIZE, F1-F12, PF1-PF12, NO_OP_COMMAND, NO_OP_IDLE, BADESC, KEY_JUNK,
  44 and NODATA. The way that read_char and GetKey work are slightly differnt
  45 from each other. GetKey has some special bits (CTRL, FUNC, MENU) that
  46 it might OR together with a character and some of the return values
  47 are possible in only one or the other function.
  48
  49 Pico is internally UCS-4. A CELL contains one character.
  50 Alpine, on the other hand, uses UTF-8 internally. The input from read_char
  51 is read by read_command, radio_buttons, and optionally_enter and is
  52 then converted to UTF-8 before it is used internally in Alpine.
  53
  54 OUTPUT
  55
  56 All Alpine output to the display funnels through Writechar. The input to
  57 Writechar is a stream of UTF-8 characters which are then converted to
  58 the display's multi-byte character stream using c-client's utf8_get
  59 to convert it to UCS-4 and then wtomb to convert to the multi-byte
  60 representation.
  61 The similar function in pico is ttputc (also known as t_putchar) which
  62 takes an incoming stream of UCS-4 characters and converts it to multi-byte
  63 characters for the display.
  64
  65
  66
  67
  68 CHARACTER SET CONVERSIONS
  69
  70 Here is a simplified version of the complicated character set conversions
  71 going on.
  72
  73     ----------                          |--read_char
  74    | Keyboard |-ttgetc->-mbtow->-kbseq->|              (UCS-4)
  75     ----------         (to UCS-4)       |--GetKey
  76
  77
  78               |--optionally_enter               ----------------
  79    read_char->|--read_command    ------------> | Alpine internal|
  80               |--radio_buttons    (to UTF-8)   |     UTF-8      |
  81                                                 ----------------
  82 or
  83               |--pico
  84               |--LineEdit                       ----------
  85       GetKey->|--mlyesno         ------------> | Composer |
  86               |--mlreplyd                      |  UCS-4   |
  87               |--FileBrowse                     ----------
  88
  89
  90     ----------------                               ----------
  91    | Alpine internal| <-------pico_readc--------- | Composer |
  92    |    UTF-8       | --------pico_writec-------> |  UCS-4   |
  93     ----------------                               ----------
  94
  95
  96     ----------------                                   ---------
  97    | Alpine internal| -Writechar->-utf8_get->-wtomb-> | Display |
  98    |    UTF-8       |                                 |  (LANG) |
  99     ----------------                                   ---------
 100
 101     ----------                                   ---------
 102    | Composer | ---pputc-->ttputc->-----wtomb-> | Display |
 103    |  UCS-4   |                                 |  (LANG) |
 104     ----------                                   ---------
 105
 106
 107     ----------------                                    -----------
 108    | Alpine internal| <-decode_text--------<-c-client- | MailStore |
 109    |    UTF-8       |   get_body_part_text             |           |
 110     ----------------                                    -----------
 111
 112
 113     ----------------                               ------------
 114    | Alpine internal| <-------------------------- | FileSystem |
 115    |    UTF-8       | --------------------------> |            |
 116     ----------------  see flags READ_FROM_LOCALE   ------------
 117                         and WRITE_TO_LOCALE
 118
 119     ----------                                   ------------
 120    | Composer | <--------ffgetline------------- | FileSystem |
 121    |  UCS-4   | ---------ffputline------------> |            |
 122     ----------                                   ------------