Yudit HOWTO
HOWTO Document List
You can see the howto documents in Yudit unicode editor if you type 'howto configure' in the command area of the editor window.
For your reference, I put the following documents on this server:
arabic, baybayin, berber, bidi, build, configure, devanagari, freehand, georgian, greekancient, japanese, keymap, malayalam, rovasiras, syntax, tamil, tibetan, vietnamese, windows
HOWTO configure
Yudit: HOWTO-configure.txt ===================================================================== Version: 3.1.0 Author: Gaspar Sinai <gaspar (at) 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 / libsedy.dylib / libsedy.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.