Yudit: HOWTO-configure.txt
=====================================================================
Version: 3.1.0
Author:  Gaspar Sinai <gaspar@yudit.org>
Date:    Tokyo 2023-02-05

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

 Yudit has a default configuration that is compiled into the 
 binary. When it starts it tries to merge entries from the
 system configuration properties into its configuration:

  /usr/share/yudit/config/yudit-properties

 After that the following directories are created unless they exist:

   ~/.yudit
   ~/.yudit/fonts
   ~/.yudit/data
   ~/.yudit/syntax
 
 ~/ is the user's home directory $HOME, like '/home/gsinai/'. 

 Yudit tries to load 

   ~/.yudit/yudit.properties

 The properties in this file will override the previously
 loaded configuration properties.

 When yudit exists, it will merge certain configuration properties
 with the ones that the user can change inside Yudit. Currently
 these are the properties that will be overwritten:

  yudit.default.geometry
  yudit.editor.font
  yudit.editor.fontsize
  yudit.editor.input
  yudit.editor.syntax

 The merged properties will be written back into ~/.yudit/yudit.properties
 or a new file created if this file does not exist.

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

 The configuration file is a plain text file. It consists of lines of
 key=value pairs, like

  hierarchical.key.string=value

 or key=list pair, like:

  hierarchical.key.string=value1,value2,value3

 It is important to know that space characters are not ignored, 
 they should be avoided where there is no space.

 It is possible to use the '\<newline>' character to join two
 separate lines  but those will be joined again when yudit writes back
~/.yudit/yudit.properties.
 
=====================================================================
3 Basic Configuration Parameters

3.1 yudit.scale

 GUI scaling factor of yudit. Valid values are decimal numbers in
 the range of 1.0 and 3.0. The whole user interface including fonts
 and icons will be up-scaled by this factor. Thus is useful on
 high-resolution monitors where pixels are small.

 Example:
 yudit.scale=1.5
---------------------------------------------------------------------
3.2 yudit.datapath

 This is the path yudit uses to locate its compiled .my files
 that contain keyboard input maps and converters.

 This parameter is a list. Example: 

 yudit.datapath=/home/gsinai/test/data,/home/gsinai/test/data.

 From yudit 3.0.8 it is safe to leave this list empty. Yudit will
 first try ~/.yudit/data then yudit.datapath, and after that the
 system /usr/share/yudit/data directory to locate these files.

 Yudit comes with a program called uniconv that can be used to
 check the full datapath in yudit-3.0.8 and above:

 uniconv -h
---------------------------------------------------------------------
3.3 yudit.fontpath

 This is the path yudit uses to locate the font files. The path
 elements here can end with /** to indicate that yudit should search 
 multi-level sub-directories also. There is a special prefix
 ~/ that specifies the home directory of the current user.

 This is a list. Example: 

  yudit.fontpath=/usr/share/fonts/**,~/.local/share/font/**

 Yudit first searches for fonts in ~/.yudit/fonts, then this
 yudit.fontpath list and if the font is still not found it searches
 /usr/share/yudit/fonts.

 Yudit is bundled with a program uniprint, that can be used to
 examine the full fontpath (from yudit-3.0.8): 

 uniprint -h
---------------------------------------------------------------------
3.4 yudit.syntaxpath

 This is the path yudit uses to locate the external spell-checker 
 files. It is also used to locate the external encryption
 add-on library. 

 Yudit expects the following files on this path:
 libhunspell.so / libhunspell.dylib / libhunspell.dll - hunspell library
 libsedy.so / libhunsedy.dylib / libhunsedt.dll - sedy encrytpion library
 .aff and .dic files for Hunspell.

 Please refer to the following URLs:
 - hunspell spell checker: 
     https://github.com/hunspell/hunspell

 - hunspell aff and dic files:
     git://anongit.freedesktop.org/libreoffice/dictionaries
     https://cgit.freedesktop.org/libreoffice/dictionaries

 - Interface that a libsedy.so/libsedy.dylib/libsedy.dll 
   should implement to encrypt/decrypt text files 
   that have extension .sedy:
     https://yudit.org/download/yudit_sedy.h 
   This header file is also available in yudit source distribution.

 Example:
 yudit.syntaxpath=/usr/share/hunspell

 From yudit 3.0.8 it is safe to leave this list empty. Yudit will
 first try ~/.yudit/syntax then yudit.syntaxpath, and after that the
 system /usr/share/yudit/syntax directory to locate these files.

 One way to get hunspell into ~/.yudit/syntax on Ubuntu:
 - Install hunspell:
   sudo apt install hunspell
 - Check where the shared library is
   ldd /usr/bin/hunspell
 - Make a symbolic link of it to ~/.yudit/syntax/libhunspell.so
   ln -s /lib/x86_64-linux-gnu/libhunspell-1.7.so.0 ~/.yudit/syntax/libhunspell.so
 - If yudit.syntaxpath=/usr/share/hunspell there is nothing else to do.
 - You can install more dictionaries like this:
   sudo apt-get install hunspell-hu

---------------------------------------------------------------------
3.5 yudit.fonts, yudit.editor.fonts

 List parameter, that defines the available fonts. 
 yudit.editor.fonts 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 super-set of the two.

 Example:
  yudit.editor.fonts=default,TrueType,Bitmap
  yudit.fonts=buttonfont,labelfont

 When the configuration in this example is used, the following virtual 
 fonts will be available in yudit.

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

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

 These virtual fonts must be defined in yudit.properties with:

  yudit.font.<fontname>

 It is described later.

---------------------------------------------------------------------
3.6 yudit.font.<fontname>

 A list of fonts that build a virtual font.

 The virtual font name "default" is defined internally. It is not
 desirable to have yudit.font.default in the configuration file.

 The default font has unifont.hex in the first line.
 So it you drop unifont.hex into ~/.yudit/fonts you can edit files 
 immediately with font size 16 (yudit.scale=1.0).

 The font name should be a TrueType/OpenType/CFF/bdf,unifont-hex 
 font filename with attributes or logical X11 fonts. 

 X11 native fonts are using logical font names instead of font
 filenames. 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*

 When font files are used, attributes can be added. Their order 
 of attributes is important.

 FontFile:attribute1
 FontFile:attribute1:attribute2

 Possible values for attribute1

 unicode: to designate full Unicode range.
 encoding: If the font is not a Unicode font, and if there exists a 
    <encoding>.my yudit map it can be assigned with this attribute.
 scriptcode: 
     indic: U+0900..U+0FFF
     deva:  U+0900..U+097F
     beng:  U+0980..U+09FF
     guru:  U+0A00..U+0A7F
     gujr:  U+0A80..U+0AFF
     orya:  U+0B00..U+0B7F
     taml:  U+0B80..U+0BFF
     telu:  U+0C00..U+0C7F
     knda:  U+0C80..U+0CFF
     mlym:  U+0D00..U+0D7F
     sinh:  U+0D80..U+0DFF
     thai:  U+0E00..U+0E7F
     lao:   U+0E80..U+0EFF
     tibt:  U+0F00..U+0FFF
     jamo:  U+1100..U+11FF
 emoji: Paint the font with white background and black foreground
     and exclude characters under U+2122.

 Possible values for attribute2

 RL - Strictly Right-To-Left font
 LR - Strictly Left-To-Right font
 RL and LR values are important for PUA area and OldItalic to 
 make software Glyph mirroring work properly when direction is changed.


 Example:

 yudit.editor.fonts=default,Terminal,Indic
 yudit.font.Terminal=JetBrainsMono-Medium.ttf,ipag.ttf,\
EmojiOne_Color.otf:emoji,OldHungarian_Full.ttf:unicode:RL
 yudit.font.Indic=raghu.ttf:deva,MalOtf.ttf:mlym

 Yudit is bundled with:
  - OldHungarian_Full.ttf: RL Rorvasiras in PUA are, 
     RL Unicode standard Old Hungarian glyphs with ligatures.
  - arabforms.hex: size 16 bitmap font for Arabic shapes
  - syriacforms.hex: size 16 bitmap font for Syriac shapes
  - yudit.ttf: A small last resort true type font
  - yudit.hex: A small size 16 last resort bitmap font.

 From yudit-3.0.8 it is possible to examine which font files
 are used by yudit. A command line tool, uniprint that is 
 bundled with yudit can be used for this purpose.

 uniprint -font TrueType -h
 uniprint -h
=====================================================================
4 Editor Configuration Parameters

These configuration parameters configure the Editing Area.

---------------------------------------------------------------------
4.1 yudit.editor.fonts
 This property was also described in yudit.editor.fonts section.

 This list defines the font choices in the Editor. These can be 
 selected wtih Shift-F1..F12 keys. The fonts are the virtual fonts
 that are defined with yudit.font.<virtualfont> configuration.
 
 Example:
  yudit.editor.fonts=default,TrueType,Serif,SansSerif,Terminal

 This configuration will assign the following key-switches:
 Shift-F1=default, Shifty-F2=TrueType...

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

 A list of font sizes that can be selected in the GUI with +/- buttons.
 This is different from yudit.editor.fontsize which is the fontsize
 that was saved when yudit exited.

 Example:
  yudit.editor.fontsizes=12,14,16,18,24,48

 As X11 font sizes will be defined as integers, do not use
 floating point values here. This value will replace the font size
 in XLFD for X11 fonts. Scalable fonts will be scaled to 72dpi by
 default.

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

 A list that defines the the input methods that can be selected via
 F-keys. 
 
 These inputs are based upon a .my file  on yudit.datapath (3.2). 

 Please note the the kmap files in /usr/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.

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

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

 Keymap source files can be added with kmap extension, and mys extension.
 Both will be compiled into .my yudit data file. 

 Original kmap files can only be used in BMP. If there is a need to create 
 keymaps for the full Unicode range, including SMP areas.  mys files should
 be created.

 A reference mys file to input Old Hungarian in SMP can be found in the yudit
 distribution:  mytoo/mys/OldHungarian.mys

 All compiled my files can be used as external text converters, 
 uniconv -h will list the ones it can find on the datapath.

 Users can also create their own freehand recognition file. Please read
 /usr/share/yudit/doc/README-FREEHAND for details. 

---------------------------------------------------------------------
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: x-ibus:en_US.utf-8,interxim,kinput2:ja_JP.eucJP,\
xcin:zh_TW.big5,Ami:ko_KR
 
 x-ibus:en_US.utf-8 is the X11 input used in Ubuntu by Mozc (Japanese).

 Special method:  

 utf-8 - this will pass all X11 strings as is - if Unicode
         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 

 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
 look-ups.

 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 configuration 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.

 ibus:en_US.utf-8 XInput is the one that comes with Latest Ubuntu that
 ueses Mozc for Japanese input.
---------------------------------------------------------------------
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

 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
 This means the Hungarian and Hangul can be used as transliteration
 text converters in the file open and save dialog.

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

These parameters set some initial values.

---------------------------------------------------------------------
5.1 yudit.default.filetype

 String. It defines the encoding used initially when invoking Yudit.
 To get a full list of supported encodings uses uniconv, which is 
 a command line tool bundled with yudit:

  uniconv -h

 This is also known as best File Type in the file dialog window.

 Example:
 yudit.default.filetype=utf-8

 Don't touch this. utf-8 is the best Unicode encoding for plain text.
---------------------------------------------------------------------
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.
 Examples:
  yudit.default.preview.command=evince
  yudit.default.preview.command=open -W -a skim
  yudit.default.preview.command=C:/Program Files/Ghostgum/gsview/gsview32.exe 

---------------------------------------------------------------------
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
  ls /usr/share/locale/*/yudit.mo

 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  /usr/share/yudit/doc/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 GUI window.
---------------------------------------------------------------------
6.5 yudit.label.foreground

 The foreground color of labels and buttons..
---------------------------------------------------------------------
6.6 yudit.title.foreground

  The foreground color of title labels.
---------------------------------------------------------------------
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 area.
---------------------------------------------------------------------
6.9 yudit.editor.right.foreground

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

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

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

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

 If this is true yudit will visualize the end-of-line characters.

 Examples: 
 yudit.editor.showbreak=true
 yudit.editor.showbreak=false
---------------------------------------------------------------------
6.13 yudit.editor.wordwrap
 If this value is true, yudit will wrap words with a simple algorithm.

 Examples:
 yudit.editor.wordwrap=false
 yudit.editor.wordwrap=true

---------------------------------------------------------------------
6.14 yudit.command.background

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

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

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

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

---------------------------------------------------------------------
6.17 yudit.command.caret.left.foreground

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

---------------------------------------------------------------------
6.18 yudit.command.caret.right.foreground

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

---------------------------------------------------------------------
6.19 yudit.command.font

 String. Virtual font in the command area

---------------------------------------------------------------------
6.20 yudit.command.fontsize

 String. The font size in the command area.

---------------------------------------------------------------------
6.21 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 also yudit.editor.inputs.

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

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

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

 The font size that was used by the editor when it exited. 
 See also yudit.editor.fontsizes.
---------------------------------------------------------------------
7.4 yudit.default.geometry

 Yudit saves the size of the GUI when it exits.
---------------------------------------------------------------------
7.5 yudit.editor.syntax

  This is a configuration parameter that controls the syntax highlighting.
  The GUI has a syntax selection window, do not change it by
  hand. For a reference here are the possible properties:

   none - no highlighting
   simple - numbers: orange, delimiter: blue, comment=ligtgray
   simple-dark - same colors but darker than simple. Suitable for 
     white editor background.
   hunspell:dictionary - use hunspell spell checker with a dictionary.
     When hunspell is used the there are additional parameters that
     define the colors of the spell-checked words, and they can be
     edited by hand in yudit.properties Here is an example:

  	yudit.editor.syntax.comment.foreground=lightgray
	yudit.editor.syntax.control.foreground=CornflowerBlue
	yudit.editor.syntax.define.foreground=cyan
       yudit.editor.syntax.error.foreground=red
	yudit.editor.syntax.number.foreground=orange
	yudit.editor.syntax.string.foreground=magenta
	yudit.editor.syntax.token.foreground=yellow
	yudit.editor.syntax.variable.foreground=red

    Refer to yudit.syntaxpath (3.4) for more information on how
    the external spell checker works.

  Example:
   yudit.editor.syntax=hunspell:en_US 
---------------------------------------------------------------------
Do not feel intimidated by the complex configuration parameters.
Most likely, the default configuration will work for you. 
uniprint -font fontset-name -h 
uniprint -h
will help you locate the fonts you are using.
