Yudit: HOWTO-configure.txt
=====================================================================
Version: 2.3
Author:  Gaspar Sinai <gaspar@yudit.org>
Date:    Tokyo 2006-05-21

This Document describes how to configure Yudit. 
=====================================================================
1 Configuration File Loading

 At start-up Yudit reads the configuration file:
  <prefix>/share/yudit/config/yudit-properties
 where <prefix> is the installation prefix, usually /usr.
 This is the system configuration file. If the file is found, it merges 
 the entries with the default compiled in the binary. After start-up 
 it tries  to create 
   ~/.yudit
   ~/.yudit/fonts
   ~/.yudit/data
 directories, if they are not there. ~/ means the user's home 
 directory, like '/home/gsinai'. It tries to load 
   ~/.yudit/yudit.properties
 file. The existing entries in this file will override the previously
 loaded  system configuration entries.

 When exiting Yudit, yudit will merge certain parameters in this file
 with some parameters that the user can change inside Yudit. Currently
 the overwritten parameters are:
  yudit.editor.font
  yudit.editor.fontsize
  yudit.editor.input
  yudit.filetypes

=====================================================================
2 Configuration File Format

 The configuration files consists of lines of:
  hierarchical.key.string=value
 or
  hierarchical.key.string=value1,value2,value3
 It is very important that no extra space is left anywhere.
 It is possible to use the '\<newline>' character to join two
 separate lines  but it is not desirable, especially in the user 
 config file. Yudit will join these lines in that file.
 
 Keep in mind: when an array is specified in the system config file 
 with value1,value2,value3 and the same array is in the user config
 file, with myvalue1,myvalue2 all elements of the array will be coming
 from the user config file: myvalue1,myvalue2.

=====================================================================
3 Basic Configuration Parameters

These are the parameters that have profound effect on yudit. You can
add virtual fonts, choices to the editor window like font sizes, 
input methods.

---------------------------------------------------------------------
3.1 yudit.datapath

 Array parameter. Example: 
  yudit.datapath=/usr/share/yudit/data,/home/gsinai/data,...
 This is a very important parameter. This will define the search path,
 yudit will locate the my-files it needs to map fonts, create input
 methods and converters.
 Note that 
  <prefix>/yudit/data
  ~/.yudit/data
 directories will always be appended to the list.

---------------------------------------------------------------------
3.2 yudit.fontpath

 Array parameter. Example:
  yudit.fontpath=/usr/share/yudit/fonts,/usr/share/truetype/,...
 This parameter defines the search path for True Type fonts.
 Note that 
  <prefix>/yudit/fonts
  ~/.yudit/fonts
 directories will always be appended to the list.

---------------------------------------------------------------------
3.3 yudit.fonts, yudit.editor.fonts (4.1)

 Array parameters. Both define the available fonts. 
 yudit.editor.fonts(4.1) defines the available fonts that can be selected
 from Yudit in the editor window. The available fonts in other parts of 
 the gui (labels, buttons) are a superset of the two.

 Example:
  yudit.editor.fonts=default,TrueType,Bitmap
  yudit.fonts=buttonfont,labelfont
 With this the following virtual fonts will be available:

 Shift-F1 - default
 Shift-F2 - TrueType
 Shift-F3 - Bitmap

 Any names can be used. The name "None" or "none" are specials they
 mean that no font change is desirable even though the corresponding
 Shift-Fxx combination was pressed.

 These virtual font names should be defined later in
  yudit.font.<fontname>
 parameter. The name default is defined internally, and it is not
 desirable to be defined in yudit.font.default unless you know what
 you are doing. The default font has unicode.hex in the first line.
 So it you drop unifont.hex into ~/.yudit/fonts you can edit files 
 immediately.
---------------------------------------------------------------------
3.4 yudit.font.<fontname>

 Array. This defines the virtual font that was specified in 3.3.
 Example:
  yudit.font.TrueType=arial.ttf,cyberbit.ttf,*-iso8859-1
 This defines a virtual font that can be referred to by the TrueType
 alias. This virtual font tries to find, 3 font files in the 
 fontpath (3.2) and if not found it tries to load them as x11 fonts.
 Most likely it will find:
  /usr/share/yudit/font/arial.ttf
  /usr/share/yudit/font/cyberbit.ttf
 and it won't find any file name  *-iso8859-1, so it will try to get 
 the closes match from X11 server, some font like:
    -adobe-courier-bold-o-normal--12-120-75-75-m-70-iso8859-1
 in case the font size we use was 12. The *-iso8859-1 was a bit
 lazy declaration, it can be defined to be more accurate.

 Yudit has built-in converters for most of the standard X11 
 font encodings.(source swindow/sx11/SX11Font.cpp)
  *-iso10646-1 
  *-iso10646p2-<1-16> 
  *-iso8859-<1-9>
  *-koi8-1
  *-koi8-r
  *-ksc5601*
  *-jisx0208*
  *-jisx0201*
  *-jisx0212*-0
  *-big5*
  *-gb2312*
  *-iso646*
 To check the fonts available in your X11 server types 
  xlsfonts
 at the shell prompt.

 Yudit has has built-in ucs-2 converter for True Type fonts. 
 This is good for True Type fonts that have platform=3 encoding=1
 platform=2 encoding=1 or platform=1 attributes. If you have a font
 that does not have unicode table I need to modify the encodingVector
 in swindow/SFontTTF.cpp in the yudit source tree to add an encoder.
 Please send me your modifications if any.

 If the font is not a unicode font, and if there exists a 
 <encoding>.my map it can be assigned with and optional parameter:

 yudit.font.<fontname>:something.ttf:<encoding>

 The special keyword 'unicode' can be attached to unicode encoded
 fonts.

 Another additional parameter can be attached to the font that 
 specifies its initial directionality, like:

 yudit.ttf:unicode:LR - left-right directionality
 yudit.ttf:unicode:RL - right-left directionality

 This is only important when you need to do glyphs mirroring,
 like for Old Italic or Old Hungarian.

 GNU Unifont can be rendered directly by specifying the filename
 together with the .hex extension, like: unifont.hex.


=====================================================================
4 Menu Configuration Parameters

These configuration parameters will make up choices in the editor.

---------------------------------------------------------------------
4.1 yudit.editor.fonts

 Array. It defines the font choices in the gui. See also
 
  yudit.fonts

---------------------------------------------------------------------
4.2 yudit.editor.fontsizes

 Array. It defines the available font sizes.
 Example:
  yudit.editor.fontsize=12,14,16,18,24,48

 As X11 font sizes will be defined as integers, please do not use
 floating point values here. This value will replace the font size
 in XLFD for X11 fonts. True Type fonts will be scaled as if the screen
 were 72dpi.  

---------------------------------------------------------------------
4.3 yudit.editor.inputs

 Array. It defines the user-selectable input methods. These input methods
 can come from a .my file  on yudit.datapath (3.1.). Please note the the
 kmap files in <prefix>/yudit/src are installed for reference only. 
 They can only be used after being converted into .my format and properly 
 put in a directory on yudit.datapath - most of them are.

 config example:
  yudit.editor.inputs=straight,unicode,kinput2,Hungarian,None,Esperanto\
     freehand
  
 This will load:
 F1 straight: built-in - no mapping
 F2 unicode: built-in - \uxxxx escapes
 F3 kinput2: built-in - _JAPANESE_CONVERSION
 F4 Hungarian: external Hungarian.my file is searched and
  possibly found in /usr/share/yudit/data/Hungarian.my
 F5 None: nothing will happen when pressing F5
 F6 Esperanto: external, like Hungarian
 F7 freehand: internal, handwriting engine with external handwriting 
  description files.

 If you want to create you own .my keyboard input file, you should 
 read the <prefix>/share/yudit/doc/keymap-format.txt
 file, and consult the man page for the mytool program.

 As kmaps can be used as external text converters, uniconv -h will
 list the ones it can find on the datapath.

 You can also create your own freehand recognition file. Please read
 <prefix>/share/yudit/doc/README-FREEHAND for a recepie. 

---------------------------------------------------------------------
4.3 yudit.editor.xinputs

 A list of x input methods in the form of 

   name:locale

 where :locale is optional. The input will appear in the toolbar
 as x-name. 

 Example: interxim,kinput2:ja_JP.eucJP,xcin:zh_TW.big5,Ami:ko_KR
 

 Special method:  

 utf-8 - this will pass all X11 strings as is - in unicode if 
         utf-8 is supported by X11. If you specify the locale,
         like 'utf-8:hu_HU' then locale is set before switching
         to this mode, allowing for X11 style composition of 
         characters. 

 You should note that if locale has encoding in the form of: 

    language_VARIANT.codepage 

 form Yudit's own string converter will be used for encoding. 
 Some aliasing also takes place: 

 eucjp -> euc-jp; euckr -> euc-kr; big5 -> big-5; 

 In an effort to eliminated gb-2312 the following compatible aliases 
 are also used:

 gb2312 -> gb-18030; gb-2312 -> gb-18030; gb18030 -> gb-18030

 Of course you can omit encoding altogether: ko_KR means use utf-8
 lookups.

 Note that the conversion starts and ends with <Shift><SAPCE>.

 Start kinput2 with canna: kinput2 -canna &
 Start Ami: export LC_ALL=ko_KR; ami
 Start xcin (big5 mode): export LC_ALL=zh_TW.big5; xcin
 Start xcin (gb2312 mode): export LC_ALL=zh_CN.GB2312; xcin

 Please not that kinput2 may have a config file in your home
 directory: called '.canna'. In that I recommend you comment this:
 ;;(global-set-key "\F1" 'extend-mode)
 otherwise funny things may happen when you press F1.
  
---------------------------------------------------------------------
4.4 yudit.editor.xinputs.style

  String. Set the input method input style to one of the following
  values:
  preedit-root-status-root - input method is goung to open a 
        separate window.
  preedit-over-status-over - input method is going to write at the cursor
  preedit-under-status-under - input method is going to write 
     at the bottom of the main text window.
  preedit-over-status-under - input method is going to show the status
    at the bottom of the main text window but  preediting is 
    at the cursor.
  The default value is 'preedit-over-status-over'.

---------------------------------------------------------------------
4.5 yudit.editor.filetypes

 Array. This list will be appended to the original list of file types in
 the File Dialog. Normally File Dialog would show the built-in types 
 only. This is also known as encoding (3.6.)
 Example:
  yudit.editor.filetypes=Hungarian,Hangul
 I use these key maps to transliterate Hungarian or Hangul text.

=====================================================================
5. Default Configuration Parameters

These parameters set some initial values.

---------------------------------------------------------------------
5.1 yudit.default.filtype

 String. It defines the encoding used initially when invoking Yudit.
 To get a full list of supported encodings type 
  uniconv -h
 in a shell window. This is also known as File Type in the file dialog
 window.
 Example:
 yudit.default.filetype=utf-8

---------------------------------------------------------------------
5.2 yudit.default.printer.options

 String. It defines the options that is passed to the 'lpr' command
 when printing.
 Example:
  yudit.default.printer.options=-P PrinterName

---------------------------------------------------------------------
5.3 yudit.default.preview.command

 String. It defines the command used when the preview button is 
 pressed. This is a full unix command that will be executed by
  /bin/sh -c 'whatever you configured'
 and the postscript output will be piped into this command.
 Example:
  yudit.default.preview.command=ghostview -

---------------------------------------------------------------------
5.4 yudit.default.clipboard.encoding

 This is the clipboard encoder to cut and paste in X11 if the requested
 text type is COMPOUND_TEXT. COMPOUND_TEXT could be decoded with yudit
 if there were an universal decoder. Encoding on the other hand, has
 some ambiguity as there are characters that occupy the same unicode
 character but they are distinct in COMPOUND_TEXT. For this, reason,
 and because yudit does not have a universal decoder, we need to 
 explicitly set this encoder. Try to use some iso-2022-x11 for Japanese
 XWindow or ksc-5601-x11 for Korean XWindow.

5.5 yudit.default.geometry

 This specifies the initial size of the editor window. The default
 value is "780x480". That is 780 pixels wide 480 pixels high.

=====================================================================
6 Configuration Parameters to Change Appearance

These parameters change the colors, fonts in the gui and the editing
area. All these parameters are strings. All colors can be color names
or #rrggbb values where rr,gg and bb are 8-bit hexadecimal color codes
for red, green and blue color components. Boolean values can be true or
false.

---------------------------------------------------------------------
6.1 yudit.default.language

 The language of the user interface. Please take a look at
  <prefix>/share/yudit/locale/
 to see the two letter names the are supported.
 Example:
 yudit.default.language=ja
 If this parameter is not present or it is a zero sized string the
 environment variable LANG or if not present LANGUAGE is used. 
 If everything fails English is used.
 If you are interested in translating yudit to your own language
 you should read  <prefix>/share/yudit/README.TXT
---------------------------------------------------------------------
6.2 yudit.default.font

 While yudit.editor.font sets the initial font in the editing area
 this will set the font in  other components, labels and buttons.

---------------------------------------------------------------------
6.3 yudit.default.fontsize

 While yudit.editor.fontsize sets the initial font size in the
 editing area this will set the font size in other components,
 labels and buttons.
---------------------------------------------------------------------
6.4 yudit.background

 The background color of Yudit windows.
---------------------------------------------------------------------
6.5 yudit.label.foreground

 The foreground color of labels-like windows.
---------------------------------------------------------------------
6.6 yudit.title.foreground

  The foreground color of title-like windows.
---------------------------------------------------------------------
6.7 yudit.editor.background

 The background color of the editor area.
---------------------------------------------------------------------
6.8 yudit.editor.left.foreground

 The foreground color of left-to-right text in editor window.
---------------------------------------------------------------------
6.9 yudit.editor.right.foreground

 The foreground color of right-to-left text in editor window.
---------------------------------------------------------------------
6.10 yudit.editor.caret.left.foreground

 The color of the left-to-right caret in the editor window.

---------------------------------------------------------------------
6.11 yudit.editor.caret.right.foreground
 The color of the right-to-left caret in the editor window.

---------------------------------------------------------------------
6.12 yudit.editor.showbreak

 Boolean. Accepted values: true or false.
If this is true yudit will visually indicate the end of line characters.

---------------------------------------------------------------------
6.13 yudit.editor.wordwrap

 Boolean. Accepted values: true or false.
If this value is true, yudit will wrap words with a simple algorithm.

---------------------------------------------------------------------
6.14 yudit.editor.syntax

 String. Currently only the following values are supported:
   none - no highlighting
   simple - numbers: orange, delimiter: blue
---------------------------------------------------------------------
6.15 yudit.command.background

 The background color of the command area.
---------------------------------------------------------------------
6.16 yudit.command.left.foreground

 The foreground color of left-to-right text in command area.

---------------------------------------------------------------------
6.17 yudit.command.right.foreground=yellow

 The foreground color of right-to-left text in command area.

---------------------------------------------------------------------
6.18 yudit.command.caret.left.foreground

 The color of the left-to-right caret in the command area.

---------------------------------------------------------------------
6.19 yudit.command.caret.right.foreground

 The color of the right-to-left caret in the command area.

---------------------------------------------------------------------
6.20 yudit.command.font

 String. Virtual font in the command area

---------------------------------------------------------------------
6.21 yudit.command.fontsize

 String. The font size in the command area.

---------------------------------------------------------------------
6.22 yudit.slider.background
 The color of the slider. 

=====================================================================
7 Configuration Parameters Overwritten by Yudit

The following parameters are updated by yudit when it exists.

---------------------------------------------------------------------
7.1 yudit.editor.input

 String. Last input that was used by the editor when it exited. 
 See yudit.editor.inputs.

---------------------------------------------------------------------
7.2 yudit.editor.font

 String. Virtual font that was used by the editor when it exited.. 
 See yudit.editor.fonts.

---------------------------------------------------------------------
7.3 yudit.editor.fontsize

 String. The font size that was used by the editor when it exited. 
 See yudit.editor.fontsizes.
