comment -*- mode: text -*-
comment $Id$

mlterm configuration protocol
version 20140816

* Protocol
  exec             = "\x1b]5379;" <command> "\x07"
  set              = "\x1b]5379" ( ";" ( "/dev/..." ":" ) <key> "=" <value> )* "\x07"
  get(pty)         = "\x1b]5380;" <challenge> ";" ( "/dev/..." ":" ) <key> "\x07"
  get(GUI menu)    = "\x1b]5381;" ( "/dev/..." ":" ) <key> "\x07"
  set&save         = "\x1b]5383;" <challenge> ( ";" ( "/dev/..." ":" ) <key> "=" <value> )* "\x07"

  set font         = "\x1b]5379;" <font filename> ":" <key> "=" <value> "\x07"
  get(pty)	   = "\x1b]5380;" <challenge> ";" <font filename> ":" <key> "," <fontsize> "\x07"
  get(GUI menu)	   = "\x1b]5381;" <font filename> ":" <key> "," <fontsize> "\x07"
  set&save         = "\x1b]5383;" <challenge> ";" <font filename> ":" <key> "=" <value> "\x07"

  set color        = "\x1b]5379;color:" <key> "=" <value> "\x07"
#if  0
  get(pty)	   = "\x1b]5380;" <challenge> ";color:" <key> "\x07"
  get(GUI menu)	   = "\x1b]5381;color:" <key> "\x07"
#endif
  set&save         = "\x1b]5383;" <challenge> ";color:" <key> "=" <value> "\x07"

  return value     = "#" <key> "=" <value> "\x0a" | "#error\x0a" | "#forbidden\x0a"
  exec command     = paste | select_pty <dev> | full_reset | open_pty | close_pty (<dev>) |
                     open_screen | snapshot ("<file name>") ("<encoding name>") |
                     gen_proto_challenge | mlclient "<prefix options>" "<options>" |
                     mlclientx "<prefix options>" "<options>" |
                     search_prev <pattern> | search_next <pattern> | update_all |
                     show_picture "<file name>" "(WxH)" "(WxH+X+Y)" |
                     add_frame "<file name>" "(WxH)" |
                     set_shortcut <key>=<operation>
                     scp "(local:|remote:)<src file name>" "(local:|remote:)<dst directory name>"
                     "(<encoding name>)"
  set key          = encoding | fg_color | bg_color | tabsize | logsize | fontsize |
                     fade_ratio | mod_meta_key | mod_meta_mode | bel_mode | type_engine |
                     use_anti_alias | use_variable_column_width | use_combining |
                     use_transbg | use_bidi | bidi_mode | bidi_separators | use_ind |
                     receive_string_via_ucs | input_method | locale | wall_picture |
                     brightness | gamma | contrast | line_space | letter_space |
                     screen_width_ratio | screen_height_ratio | vertical_mode | scrollbar_mode |
                     static_backscroll_mode | use_multi_column_char | col_size_of_width_a |
                     scrollbar_view_name | sb_fg_color | sb_bg_color | use_dynamic_comb |
                     cursor_fg_color | cursor_bg_color | bd_color | it_color | ul_color |
                     bl_color | co_color | use_bold_font | use_italic_font | hide_underline |
                     icon_path | logging_vt_seq | logging_msg | word_separators | use_clipboard |
                     auto_restart | use_alt_buffer | use_ansi_colors | exit_backscroll_by_pty |
                     only_use_unicode_font | not_use_unicode_font | unicode_noconv_areas |
                     unicode_full_width_areas | box_drawing_font | use_urgent_bell |
                     allow_osc52 | allow_scp | auto_detect_encodings | use_auto_detect
  get key          = encoding | is_auto_encoding | fg_color | bg_color | tabsize | logsize |
                     fontsize | fade_ratio | mod_meta_key | mod_meta_mode |
                     bel_mode | type_engine | use_anti_alias | use_variable_column_width |
                     use_combining | use_transbg | use_bidi | bidi_mode | bidi_separators |
                     use_ind | receive_string_via_ucs | input_method | locale | wall_picture |
                     pwd | brightness | gamma | contrast | line_space | letter_space |
                     screen_width_ratio | screen_height_ratio | vertical_mode |
                     scrollbar_mode | static_backscroll_mode | use_multi_column_char |
                     col_size_of_width_a | scrollbar_view_name | sb_fg_color | sb_bg_color |
                     use_dynamic_comb | rows | cols | cursor_fg_color | cursor_bg_color |
                     bd_color | it_color | ul_color | bl_color | co_color | use_bold_font |
                     use_italic_font | hide_underline | pty_list | pty_name | use_clipboard |
                     use_alt_buffer | use_ansi_colors | icon_path | logging_vt_seq | gui |
                     allow_osc52 | allow_scp | only_use_unicode_font |
                     not_use_unicode_font | box_drawing_font | auto_detect_encodings |
                     use_auto_detect
  value            = <values for each key>
  challenge        = <string in ~/.mlterm/challenge>

  font filename    = font | aafont | vfont | tfont | vaafont | taafont
  font key         = see man/mlterm.1
  font value       = see man/mlterm.1
  fontsize         = <fontsize digit>

  color key        = see man/mlterm.1
  color value      = see man/mlterm.1

* Values for each key
  allow_osc52 = true | false | switch
  allow_scp = true | false | switch
  auto_restart = true | false | switch | <restart command>
  auto_detect_encodings = (<encoding name>,)*
  bidi_separatos = <any ASCII sign>*
  bd_color = <color name> | <color rgb>
  bl_color = <color name> | <color rgb>
  bel_mode = none | sound | visual
  bg_color = <color name> | <color rgb>
  box_drawing_font = unicode | decsp | noconv
  brightness = <any ASCII decimal digit>
  cols = <any ASCII decimal digit>
  col_size_of_width_a = 1 | 2
  contrast = <any ASCII decimal digit>
  co_colors = <color name> | <color rgb>
  cursor_bg_color = <color name> | <color rgb>
  cursor_fg_color = <color name> | <color rgb>
  encoding = <encoding name> | auto
  fade_ratio = <any ASCII decimal digit>
  fg_color = <color name> | <color rgb>
  fontsize = <any ASCII decimal digit> | larger | smaller
  gamma = <any ASCII decimal digit>
  hide_underline = true | false | switch
  icon_path = <file path>
  input_method = <input method> ":" <input method specific options> ...
  it_color = <color name> | <color rgb>
  line_space = <any ASCII decimal digit>
  locale = <locale name>
  logsize = <any ASCII decimal digit>
  mod_meta_key = none | mod1 | mod2 | mod3 | mod4 | meta | alt | super | hyper
  mod_meta_mode = none | esc | 8bit
  not_use_unicode_font = true | false | switch
  only_use_unicode_font = true | false | switch
  pty_list = (<pty dev>:<active flag>;)*
  pty_name = <pty dev> | <pty title>
  pwd = <current working directory>
  receive_string_via_ucs = true | false | switch
  rows = <any ASCII decimal digit>
  sb_bg_color = <color name> | <color rgb>
  sb_fg_color = <color name> | <color rgb>
  screen_height_ratio = <any ASCII decimal digit>
  screen_width_ratio = <any ASCII decimal digit>
  scrollbar_mode = none | left | right
  scrollbar_view_name = <name>
  stataic_backscroll_mode = true | false | switch
  tabsize = <any ASCII decimal digit>
  type_engine = xcore | xft
  ul_color = <color name> | <color rgb>
  unicode_noconv_areas = (U+XXXX-XXXX,)*
  unicode_full_width_areas = (U+XXXX-XXXX,)*
  use_alt_buffer = true | false | switch
  use_ansi_colors = true | false | switch
  use_anti_alias = true | false | switch
  use_auto_deetect = true | false | switch
  use_bidi = true | false | switch
  use_bold_font = true | false | switch
  use_italic_font = true | false | switch
  use_ind = true | false | switch
  use_combining = true | false | switch
  use_dynamic_comb = true | false | switch
  use_multi_column_char = true | false | switch
  use_transbg = true | false | switch
  use_variable_column_width = true | false | switch
  vertical_mode = none | cjk | mongol
  wall_picture = <file path>
  logging_vt_seq = true | false | switch
  logging_msg = true | false | switch

* Note
  o Encoding names are regularized , that is , `-' , `_' are removed , and only
    upper case letters are used. But encoding names which are not regularized
    can be used in ESC ] 5379 ; encoding= <value> BEL sequence by secondary
    effect.
  o Adjusting and operation arguments of  ESC ] 20 ; pt BEL sequence are not
    used for now.
  o It is configuration programs themselves that search ~/.mlterm/xim and
    ${SYSCONFDIR}/mlterm/xim files for pairs of xim name and its preferable
    locale.
  o If /dev/... is specified with 'pty_name' key, <pty title> is returned.
    Otherwise, <pty dev> returned.
  o /dev/... in 5379,5382,5383 proto is ignored for now.
  o If "snapshot" command issued without <file name> or with no value,
    screen snapshot is output to ~/.mlterm/[tty].snp.
  o "mlclient" command accepts arguments like mlclient comman except '='.
    mlclient or mlclientx executables of tool/mlclient is recommended to use.
    e.g. "\x1b]5379;mlclient --km utf8\x07"
  o "mlclientx" command is similar to "mlclient" one except for not creating
    any new window.
  o "mlclient" and "mlclientx" commands doesn't accept "-e", "--initstr",
    "--osc52" and "--shortcut" options, while they are available in ~/.mlterm/key
    like Control+F1="proto:mlclient -osc52".
  o "selected_text(:encoding)" command returns selected text in which NL is
    replaced to CR.
  o "paste" command works like INSERT_SELECTION.
  o "scp" command works as follows. ("foo.bar" is a remote host.)
    If the destination directory is an absolute path, scp isn't executed unless
    "allow_scp = true".
    If the destination directory is a relative path, the target file is stored
    in $HOME/.mlterm/scp/... (mkdir $HOME/.mlterm/scp in advance.)
    e.g.)
     \x1b]5379;scp /bin/ls .\x07
       => scp localhost:/bin/ls foo.bar:$HOME/.mlterm/scp/./ls
     \x1b]5379;scp remote:/bin/ls .\x07
       => scp foo.bar:/bin/ls localhost:$HOME/.mlterm/scp/./ls
     \x1b]5379;scp \"$HOME/my text.txt\" ""\x07
       => scp "localhost:$HOME/my text.txt" "foo.bar:$HOME/.mlterm/scp/my text.txt"
     \x1b]5379;scp c:\\users\\text.txt .\x07
       => scp localhost:c:\users\text.txt foo.bar:$HOME/.mlterm/scp/./text.txt
          ("\" is available as a separator only in win32.)
     \x1b]5379;scp remote:/bin/ls /usr/bin\x07
       => scp foo.bar:/bin/ls localhost:/usr/bin/ls
     \x1b]5379;scp local:$PWD/hosts remote:/etc\x07
       => scp localhost:$PWD/hosts foo.bar:/etc/hosts
  o Source and destination file names of "scp" command are convered to system
    locale encoding and terminal encoding respectively.

* Note about font configuration
  If you specify like "12," as <value>, previous setting of 12 pixel font is cleared.
  If you specify "" as <value>, previous setting of default font is cleared.
  Values like "12," or "" aren't written to ~/.mlterm/(vt)(aa)font files.

  e.g.)
  $ printf "\x1b]5384;font:ISO8859_1=12,a12\x07"
    => Use "a12" for 12 pixel font.
  $ printf "\x1b]5384;font:ISO8859_1=-*--%d-*-iso8859-1\x07"
    => Use "-*--%d-*-iso8859-1" for default font.
  $ printf "\x1b]5384;font:ISO8859_1=12,\x07"
    => 12 pixel font setting is cleared.
  $ printf "\x1b]5384;font:ISO8859_1=\x07" or "\x1b]5384;font:ISO8859_1=;\x07"
    => Default font setting is cleared.

* Note about color configuration
  If you specify "" as <value>, previous setting of <key> color is cleared.

* Compatibility with other terminals
  set fg color     = "\x1b" "]" "10" ";" <color name> "\x07"
  set bg color     = "\x1b" "]" "11" ";" <color name> "\x07"
  set cursor color = "\x1b" "]" "12" ";" <color name> "\x07"
  set picture      = "\x1b" "]" "20" ";" <path> "[" ";" <adjusting> "]" "[" ":" <operation> "]" "\x07"