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

mlterm configuration protocol
version 20160213

* 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"
  get(pty)	   = "\x1b]5380;" (<challenge> ";color:") <key> "\x07"
  get(GUI menu)	   = "\x1b]5381;color:" <key> "\x07"
  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 | vsplit_screen (<columns>|<percent>%) |
                     hsplit_screen (<rows>|<percent>%) | next_screen | prev_screen |
                     vresize_screen (+<columns>|-<columns>) | hresize_screen (+<rows>|-<rows>) |
                     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)" | mlconfig |
                     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_ctl | bidi_mode | bidi_separators |
                     receive_string_via_ucs | input_method | locale | wall_picture |
                     brightness | gamma | contrast | line_space | letter_space | geometry |
                     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 | vt_seq_format | 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 | use_extended_scroll_shortcut | use_ot_layout |
                     ot_script | ot_features | regard_uri_as_word
  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_ctl | bidi_mode | bidi_separators |
                     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 |
                     vt_seq_format | word_separators | gui | allow_osc52 | allow_scp |
                     only_use_unicode_font | not_use_unicode_font | unicode_noconv_areas |
                     unicode_full_width_areas | box_drawing_font | auto_detect_encodings |
                     use_auto_detect | use_ot_layout | regard_uri_as_word
  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_separators = <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
  ot_script = <script name>
  ot_features = (<feature>,)*
  pty_list = (<pty dev>:<active flag>;)*
  pty_name = <pty dev> | <pty title>
  pwd = <current working directory>
  receive_string_via_ucs = true | false | switch
  regard_uri_as_word = 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_detect = true | false | switch
  use_bold_font = true | false | switch
  use_ctl = true | false | switch
  use_combining = true | false | switch
  use_italic_font = true | false | switch
  use_dynamic_comb = true | false | switch
  use_multi_column_char = true | false | switch
  use_ot_layout = true | false | switch
  use_transbg = true | false | switch
  use_variable_column_width = true | false | switch
  vertical_mode = none | cjk | mongol
  vt_seq_format = raw | ttyrec
  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"
