# TEA Fine Manual

## Table of content

Introduction
Interface
File manager
Dates panel
File
Calendar
Edit
Markup
Search
Functions
Functions - Speech
Functions - Spell checking
IDE
Run
Nav
Fm
View
Options tab
Options - Keyboard
On autosaving
Secret power
Notes
Other projects by the author
Support the development

### Introduction

TEA has a long development history. At the autumn of the year 2000, there was first implementation of TEA, written in Object Pascal using Borland Delphi. Since then, TEA has been many times rewritten from zero (Pascal - C/Gtk - C++/Qt) and opened its source. The initial TEA UI was inspired by Impulse Tracker and Sound Forge. Later, the conception of sliding panels and tabs has been implemented.

Now TEA has THREE branches. This, TEA-Qt, is the modern one. There also outdated TEA-GTK (Gtk 2) and TEA-GTK (GTK 3), the buggy and forgotten one. So use TEA-Qt.

TEA home is and tea.ourproject.org. Happy Arch/Manjaro/etc. users can use my "tea-qt-git" package from AUR (aur.archlinux.org/packages/tea-qt-git). Also, welcome to github.com/psemiletov/tea-qt - always up to date, but can be unstable.

TEA name means nothing. It's not "Text Editor Of Atomic Era" or somethink that you may read at TEA reviews. Initially, TEA = "Text Editing and Authoring". Then, TEA was associated with a common drink (I like to drink the tea). But for now, TEA is just TEA or ТИА.

Normally, TEA holds its configuration data and other support files at $HOME/.config/tea (or, under Window, at C:\Documents and Settings\username\tea). But if you want to start TEA from the USB stick in the portable mode, TEA must read/write configuration data into the directory with the TEA binary. To start TEA in the portable mode, use "--p" command line option:

tea --p

As you know, TEA under *NIX is a single binary. Under Windows TEA installation directory contains all what you need to start TEA portable. Please note, that your NORMAL-MODE settings are stills exists and available anytime when you start TEA WITHOUT the "--p" key. TEA preferences of portable and normal modes are each other independent and exists in parallel.

### Interface

TEA has two interface mode - the Classical one and the new, so called Docked mode. You can switch between them at Options - Interface - UI mode. At the docked mode, you can tear off and/or move the Logmemo and FIF (see below). The default UI is the Classical. I'm personally use the Classical.

From the top to bottom, there are:

1. The main menu. Note that you can tear submenus off and place them somewhere over the desktop. Menu items are highly depended on the current task or even editor mode. Some menus can be visible or hidden according to the task (editing, file browsing, etc.).

2. The toolbars area. Actually, toolbars can be parked at the any side of TEA window. Positions are saved between sessions. To turn the toolbar on and off, use the context menu for the toolbar (right click on the toolbar). If no toolbar is visible, do the right click on the menu bar.

3. The tabbed area. It contains 5 main tabs - editor, files, options, , and manual. Editor - that where you see opened documents. Files - a built-in file manager. Options - here you can change TEA preferences. All changes will be applied immediately. Dates - the simple calendar with the organizer functions. Manual - the built-in User manual. This, the excellent one!

4. Logmemo. It is a notification area for all warnings, information messages and the results of some text-processing functions.

5. The Famous input field (FIF). An input text field to put here values for text-processing functions. Also it is used for Find/Replace (read about a Search menu for details). FIF has three buttons - Find, Find previous and Find next. FIF is used also for a search in the TEA manual, menu items list (at the hotkeys customization page) and even the built-in file manager.

6. The status bar. You can setup the status bar's content via the preferences Interface page.

### File manager

The TEA's file manager is hidden under the files tab. It is not an additional bloatware tool, but an essential part of the editor. It replaces the standard File save/open dialogs (by the way, you can bring them back using Options > Common > Use traditional File Save/Open dialogs checkbox).

Let's see on the shining force of TEA's file manager.

The directory bar is located on the top. There is an entry with the current directory path, and a nice toolbar with following buttons:

Go - navigates to the directory with the path from the text entry.

Home - teleports you to your cozy home directory.

Refresh - refreshes a files list to your pleasure.

File operations button with submenu. It contains some utility actions such as Create new directory, Rename and Delete file. Please note that TEA does not delete the directories.

The right panel of the file manager.

At the top you see the file name field. Here you can give the name for a file to open or save it. To save the current file under some name, just put the filename into the Name text entry and press the Save as button. To open a file, do the double click on the file name at the files list, or put the file name into the Name entry and press the Open button. You can use the Enter key inside of this input field. The action is related to the menu item (File open or Save as) that you used to open the file manager tab.

You can also select several files (Ctrl-click or INSERT key) and then press the Open button.

The selected file is saved or opened with the encoding that is selected at the character set list below from the Name entry.

Bookmarks list. You can easily add and remove the directory bookmarks using the "+" and "-" buttons. The "+" button adds a bookmark to the file system tree's current directory. The "-" button removes the selected bookmark. To activate the bookmark and navigate to the respective directory, double click on the bookmark.

There are some special bookmarks at the top of the list: snippets, templates, scripts. You can't remove them. They point to the TEA special directories for user's items such as templates, snippets, etc.

You can enable the Options > Common > Automatic preview images at file manager option to show a small preview window near the file manager. Also, when the cursor is located on the image file, you can use Open at cursor (F2) function to view the image at the full-size in another built-in image viewer (see the Open at cursor description).

### Dates panel

As you can notice, TEA has the built-in calendar-organizer under the dates tab of the main window. By double-clicking on the days, you create or open the file-per-day text documents. When you close such file, its content will be saved automatically. To remove the day record, use Calendar > Remove day record.

At the text you can specify the time signature for the alarm event. This signature has the format [hh:mm] in the 24 hour day. All text after such signature and before the next one will be treated as the alarm message. For example:

[20:00] go to the theater
[23:00] howl at the moon

For sure, you need to have TEA running to see the alarm message!

Single click on the date cell shows the day record (if any) at the logmemo area.

At the Options page, you can set the Start week on Sunday option to the "on". The calendar widget can work in two modes - the normal and the lunar one. Read the Calendar section for details.

### File

New. Impossible! It's a kind of magic. This menu item creates a new blank document where you can type any words you want. For example, type the word "hello". It's a very cheerful word. That what we usually say to all good people around. Hello! And your world becomes brighter.

Open - for sure, this menu item helps you to open any file that you already stored at your hard disk.

If you are using the build-in file manager, read the File manager chapter. Otherwise, read the words of true about the File open dialog window.

TEA can open all plain text files, and also ODT (OpenDocument Text), KWD (old KWord's format), FB2, Epub, DOCX, SXW (old OOo/StarOffice format), ABW (Abiword) formats. But only the plain text files can be saved with TEA. About other mentioned formats - TEA just can extract text from them, trying to preserve the basic layout (indents, paragraphs). When compiled with PDF and DVJU support, TEA extracts text from them too. When use TEA's Search in files, TEA looks inside of all files of these formats.

Save - if your file is already saved, this menu item saves it again. That is how it works. But, if a file is not saved, you shall see a surprise! A File manager (if the traditional open/save dialogs are turned off at Options > Common > Use traditional File Save/Open dialogs). There, put the file name into the Name entry and press the Save as button.

Last closed file - opens a last closed file. This sentence is a greater paradox of XXI century CE.

Open at cursor, or F2 as a shortcut - this feature transforms a user into the so-called "F2 addict". Strange mind and body transformations can happen, so you are warned!

Put the cursor at the file name in the href-link or LaTeX includegraphics, input, include etc. Press F2. See THAT miracle? TEA opens a file with the file name that was pointed. If this file is already opened, its tab will be focused. If the file is an image, TEA show it in the build-in image browser. But, what if you don't work with the [X]HTML code, but use a real file names in your text and want to open them? TEA can handle that - just select the file name (not just put a cursor on it) and press F2.

What is the difference? TEA can open a "file under cursor" when the file name is enclosed with quotes. As in HTML or most of the code sources. In other cases, you need to select file name manually with Shift-cursor keys or using the mouse.

And a bit more - using Open at cursor you can navigate through local href-links.

You can also use Open at cursor at the built-in file manager to open the image file with the preview window.

Also, you can open file at cursor with any external program. Read about the "Run" menu for details.

Crapbook - opens a special file where you can put some notes, pieces of a text, etc. The crapbook file will be saved automatically when you close it. If the Crapbook file is opened and you exiting TEA, the content of a Crapbook is saved too.

Notes - a kind of crapbook, but connected to the current file. Useful to put the notes related to the current file's content. The .notes file is autosaved on exit.

Save as different > Save .bak - saves a content of the current document with name, where the "bak" extension added.

Save as different > Save timestamped version - saves a content of the current document with name, where the timestamp is added. So you shall know the date and time related to the saved version. Note about timestamp format. Is is yyyy-MM-dd-hh-mm-ss. So the first comes a year, then a month, then days, hours, minutes and seconds.

Recent files. From this submenu you can open one of the last dozen opened files. TEA remembers the name, the encoding and the current position of the file when you close the document, so at the next time TEA already know the charset and the position, where to start an editing.

Templates - to create a new file from the template, select a template from this menu. To create a new template, save a text file into the TEA templates directory. It is available from templates bookmark at the TEA's file manager (or at the left sidebar at File save dialog). And vice versa, to open the template use the file manager's templates bookmark again. The character set of templates is always UTF-8. TEA sets it automatically even if you choose another encoding.

To delete or rename the template, use the file manager or File save/open dialogs.

Sessions - at this menu sessions are available. The session is a simple list of opened files. To load them all, just choose a session name from this menu. To save a session, put the name of the session into the Famous input field, then use File > Save different > Save session. At the preferences Common page you can check the Restore the last session on start-up option. If this option is turned on, TEA will save the session on exit (under the name def-session-777), and then load this session when starting.

Bookmarks - this menu is similar to Recent files, but the files list is updating by you, not by TEA. To add a current file to this list, use Edit bookmarks > Add to bookmarks function. If the bookmarks list already contains the adding file, its record will be updated with new position and charset values. To delete the bookmark, open the bookmarks list from the File > Configs menu, delete the needed line and save the list in a usual way. The wrong bookmark can be temporarily disabled with the "#" prefix. To search wrong paths and disable such bookmarks automatically, use Edit bookmarks > Find obsolete paths function.

File actions submenu. From this menu you can do some magical things. Set UNIX end of line, Set Windows end of line, Set traditional Mac end of line - those functions allow you to override the file's end of line (EOL). When you save the file, the chosen EOL will be applied. To check the file's EOL, select a file at the built-in file manager and use Fm > File information > Full info.

Do not add to recent - temporarily disable the recent files list update. This function is useful if you need to open many files and do not want to overwrite your recent files list. So use "do not add" before close "unwanted" files, work with them, close, then switch "do not add" off to bring the normal recent list functionality.

Exit - closes TEA. To reduce the annoyance level, TEA does not ask to confirm it. And another thing related to confirmations - TEA automatically proposes to save the modified existing files only. I.e. if you close (with TEA or by Ctrl-W) the modified new, no-named file, TEA silently will close it.

### Calendar

This menu is available only when the todo panel is active.

Moon mode on/off - switch calendar widget to the moon/normal modes. In the first one, the moon phases are shown. Also you'll see the moon day number after the slash (before the Gregorian day number). I.e. the format is: normal day number / moon day number.

Some words about the calculation of moon day. First of all, you need to select the right Earth hemisphere at Options - Common - Northern hemisphere (on/off). The other important thing is the algorithm (Options - Common - Moon phase algorithm). The speed and precision vary, try for yourself. There are several algorithms were been used. Some of them are based on Ben Danglish's article at www.ben-daglish.net/moon.shtml, another one on the Alexander Leushkanov's article - www.astrogalaxy.ru/275.html.

Due to some technical source, the image of moon phase for days 12 and 13 are the same.

Add or subtract years/months/days - allows one to navigate through the calendar back and forward on N years, or months, or days. For example, you need to see the day +6 after the current one. Put "6" into the Famous Input Field, and then use Add or subtract > days. If you want to move backward, put the negative value into the FIF, i.e. "-6" instead of "6".

Number of days between two dates - calculates the number of days between two dates. Select the first date at the Calendar and use Mark first date menu item. Select the last date at the Calendar and use Mark last date. Use Number of days between two dates functions to measure the difference between the first and second dates.

Calculate moon days between dates - creates a list with moon days between two dates (Mark first/last date).

### Edit

About the rectangular or block selection. TEA has such limited ability that does not fit TEA's architecture well, and text-processing functions cannot be used with block selections. All that you can do with them it is to select using Block start and Block end, and then Copy block, Cut block and Paste block.

Some notes about Indent/Un-indent functions. There are two hardcoded keyboard shortcuts are assigned to this functions - Tab and Shift-Tab. If no text selected, Indent (Tab) inserts a tab character or a space (spaces). Such behavior is depended from Options > Interface > Use spaces instead of tabs and Tab width in spaces options.

If Use spaces instead of tabs is checked on, the editor will insert (by Tab key) the number of spaces that defined at Tab width in spaces. Otherwise, TEA inserts a single tab.

TEA also has the Automatic indent option, disabled by default.

Indent by first line - this function indents all selected lines with the same indent as the first lines of selection indent.

Storage files - you can use some file as a "storage" file to copy text directly to it from different sources. Set as storage file chooses the current opened file as the storage file. Then, if you want copy and paste some text into that file, just use Copy to storage file. Also you can capture the system's clipboard text and put it to the storage using Start/stop capture clipboard to storage file. You may have just one storage file per session. When you close the storage file, all further pasting to it will be disabled until you not set a storage file again.

To control the text that inserts to the storage you can use the template file called cliptpl.txt at the TEA config directory. Just create such file with some macros, for example:

    ---
    %date
    %time
    %s
    ---

Here is: %s - the text from the clipboard, %date - current date, %time - current time.

### Markup

The functions from this menu are mainly working depending of the selected markup Mode. There are several modes available - HTML, XHTML, LaTeX, Wikitext, Markdown, Lout and DocBook. When you select some mode from the Mode menu, you set the markup mode for the current document. So different documents have different, separated modes. It allows one to edit one file as HTML and another one as DocBook XML with the same menu item. So, menu items act differently according to the document's markup mode. To use Wikitext mode, set this mode manually from the menu Mode, or use .wiki as the filename extension.

You can select a text and use some function, for example the "Paragraph". If you don't select any text, TEA just insert tags at the cursor position.

Beside the tag-related functions, Markup menu has a set of [X]HTML tools.

[X]HTML tools - Rename selected file - renames the file and changes the selected text. For example, you have (in your HTML or LaTeX document) a link to some file. You want to rename that file. Select its file name at the text, then put into the FIF a new file name (without the full path, just the name.ext), and use this function. Voila!

[X]HTML tools > Document weight - calculates a total document weight including all SRC-staff (images, flashes etc). Look for the result at the Logmemo.

[X]HTML tools > Convert tags to entities - if you want to show some HTML-tagged code in your [X]HTML-document, select your code and use this function. You'll get, for example:

&lt;b&gt;demo&lt;/b&gt;

[X]HTML tools > Text to HTML - this function converts a plain text into the nice HTML/XHTML-formatted code using CSS.

[X]HTML tools > Preview selected color - previews the selected (within the text) color at the FIF. The color can be in the form of the hex value or the named color (darkBlue, red, white, etc).

Antispam e-mail - makes a selected mailto-link possibly invisible to those damned spammer e-mail harvesters, by converting an address into integer-coded entities.

### Search

TEA has no dialog windows for find/replace functions. TEA uses the Famous input field (FIF) and menu-driven interface.

To find a substring within the text, put your substring into FIF (Use Ctrl-F to focus it) and press Enter. Then you can use Find next or Find previous functions. There are also three buttons near the FIF. They are: Find, Find previous and Find next. On search, TEA starts from the cursor position. You can set Whole words and Case sensitive options by checking the respective menu items.

To replace the selected (i.e. text that been found) text with a new one, put the new value to the FIF and use the Replace with function. Thus, you can walk through the text using Find next and apply Replace with when you need.

To replace all occurrences of a substring in the selected text, put a special command into the FIF:

old value~new value

So, the "~" is the delimiter. For example, you want to replace all occurrences of the word "cat" to the "mouse". The command will be:

cat~mouse

So put such command to the FIF and apply the Replace all function.

If you want to delete some substring from the text, use the substring~ formula. For example, to remove all occurrences of the word "weapon" from the text you can use "weapon~".

While search or replace you can use regular expressions (TEA via QT uses PCRE2 library "that implement regular expression pattern matching using the same syntax and semantics as Perl 5"). To do so, turn on the Regexp mode option (below the Whole words). For example, to convert HTML italic tag into the TeX tag you can use the following formulae:

<i>([^<]*)</i>~\emph{\1}

Please note that \1 acts like a content of the captured (with "parentheses") part of the source string. To have the access to the second such part, use \2, \3 for the third, etc.

Another example - how to find all numbers at the text? Use the (\d+) regexp at the FIF.

Don't forget to disable the Regexp mode when you need to do a usual searching. Also the Regexp mode overrides the Case insensitive mode, i.e. with Regexp mode the Case sensitive is ON by default.

Fuzzy mode - enables very basic "fuzzy search" support. For example, you need to find some word, but don't remember how exactly it is written. So in fuzzy mode, TEA can find similar word (if they have the same length, i.e "fender", "lender", etc). The factor of similarity can be defined at Options - Functions - Miscellaneous - Fuzzy search factor.

In the file manager mode, "Replace all" works with all selected files and the charset from the charset selector of the file manager panel.

At the last, Replace all in opened files works as the Replace all, but in the scope of all opened files.

Search in files - searches the text given at FIF within all text files, starting from the current directory at the built-in file manager (the Files tab), and deeper into the subdirectories. For a text encoding, TEA uses UTF-8.

Actually, TEA searches not in the ALL files. For the central processing unit, there is no difference between text files or mp3, or images. Programs must know the difference, but how? And why it is so important to identify the text file? If the program cannot do that, it will search the text in all files - images, sounds, videos, etc.. Too much time! Thus, TEA must know the difference. So TEA presumes that text files are the files with extensions those TEA recognizes for syntax highlighting. Also, TEA knows that text files are txt, odt, kwd, docx and other formats those TEA support. Finally, TEA know about some definitely text files those have names such as README, ChangeLog, etc.

So, TEA cannot search in all other files and currently there is no way to define custom file-name mask or something like that.

Mark all found/Unmark - colorize or decolorize all search results at the text. This function can produce incorrect text color settings when using View - Darker, until you restart TEA or open and work with another file.

### Functions

To use text-processing functions, you need to select some text first. Some functions (such as Text statistics) can work with a whole text if no fragment is selected. Also there are some special cases when TEA can treat the current word as a selection when there is no text is actually selected. For example, it is a behavior of UPCASE and lowcase functions. But such behavior is a rare exception from the rule.

Some functions take the parameter that you must place into the Famous Input Field (FIF, the input entry at the bottom of the main window). For example, the function Remove lines < N size gets N value from the Famous input field, so first you type the value, then call a function. There are no default values.

Functions > Repeat last - repeat the last used function. Actually, it works with almost all menu items, not just at the Functions menu.

Functions > Capitalize sentences - make all selected sensences with the upper case first letter of the first word. Useful for auto-generated subtitles from Youtube, where you manually add ".", "!" and "?", and then apply this function.

Functions > Tools > Scale image - scales the image. In the text, select the image file name or set the cursor on it. Put into the FIF parameters of the scaling. Apply this function.

The format of parameters is: filename~new size

Filename is the output filename. It can be "hardcoded" (i.e. something like "out.jpg") or contain macros: %filename (filename + extension), %basename (the file name without extension), %ext (extension). Thus, the full source file name is %basename.%ext. The full path with the filename is the macro %s. If you don't want to overwrite the source file, you can use some prefix or suffix to alter the file name:

foo-%basename-bar.%ext~1024

In this example, the output image file name shall be prefixed with "foo-", and suffixed "with -bar".

The second parameter is a new size. It can be in pixels or percents (just add "%" after the value):

foo-%basename.%ext~1024

foo-%basename.%ext~50%

Cells submenu is used for all table-like data processing. It can be LaTeX tables, CSV-data, etc. In all cases you need to define (at FIF) the column separator to tell TEA how to parse the strings.

Functions > Cells > Sort table by column ABC - sorts the text table by the column with the ABC order.

Format string for FIF: separator~column number

Columns range starts from 0, i.e. the first columns is 0, the second is 1, etc.

For example, we have LaTeX table with 4 rows, 2 columns:

dog&cat
lamb&cow
snake&wombat
wolf&tiger

Now we want to sort it by the second (1) column (where the "cat", "cow", etc.). Select the text, put "&~1" into the FIF, and call this function. The table will be sorted by the second column.

It is good to process the table without line-breaks (such as "\\" in LaTeX), and then add line-breaks to the result using the "Apply to each line" function with FIF value "%s\\".

Functions > Cells > Swap cells - swaps the cells of the table by columns.

FIF format string: separator~column1~column2

For example (with the previous sample table) we want to swap column 0 with 1 - the column with "cat" must be before "dog" column. Select the text, put into the FIF "&~0~1", and call Swap cells.

Functions > Cells > Delete by column - delete column by the given number (0..n).

FIF format: separator~column number

0 - first column, 1 - second, etc.

Functions > Cells > Copy by column[s] - copy columns to the clipboard.

FIF format: separator~column 1[~column 2]

If the column2 is not given, the column1 will be copied, else - from column1 to column 2.

Functions > Analysis > Text statistics - outputs text statistics for the whole text or the selection into the Logmemo.

Functions > Analysis > Words lengths - how much words with length from 1 to 32.

Functions > Analysis > UNITAZ - the UNIversal Text AnalyZer that computes frequencies of words and gives some other related information.

Functions > Analysis > Count the substring - the number of occurrences of the substring (put it to the Famous Input Field) in the document. See the result at the logmemo. The "Search - Case sensitive" is used as an option.

Functions > Analysis > Extract words - extracts all word from the document and place them into the newly created one.

### Functions > Tables

In TEA, the tables is a something like a set of rules for the text replacing. At the first, you need to create the file with a table (key=value format). Here is an example:

    cat=dog
    mew=bow-wow

Then save this file as a replacement table file at the special TEA directory called tables. It is available at the file manager's bookmarks panel or file save dialog favourities. After you save the table under some name, it shows at the Functions > Tables menu.

Now try to apply this table. Create a new file and write some text like this: The cat say: "mew". Select this text, then select your table from the menu and see what will happen. As a result we have a new sentence: The dog say: "bow-wow". So the tables is a way to do a multiple replacement.

If the Regexp mode at the Search options is turned on, the table will use the keys as the Perl5 regexps (via PCRE2 library).

In the file manager mode, tables work with all selected files and the charset from the charset selector of the file manager panel.

### Functions > Snippets

The snippet is the piece of code, which you can insert into the text. TEA keeps each snippet as the single file in the $HOME/.tea/snippets directory. The file name of a snippet is the menu item in Snippets-menu, i.e. the content of Snippets menu is the list of files from $HOME/.tea/snippets. To create a new snippet, you need:

1. Write some text.
2. File > Save As. Click the "snippets" bookmark to open a snippets directory, then save your file as a usual one. Note: Do not save a snippet under the name of any other TEA menu item! Menu item names should not duplicates, otherwise TEA cannot set keyboard shortcuts properly. It is important when you give a name for the snippet, or the script, template, session name, etc.
3. Enjoy :)

You can create a snippet that uses a text selection in some way. For example, you want to make a snippet which encloses the selected text into some HTML-tags. The %s macro represents a text selection. Here is the example of such snippet:

<a href="%s">%s</a>

When this snippet will be applied, %s will be replaced with the selected text. If there no text is selected, snippet content will be inserted into the text (but without the "%s" macro).

To open a snippet for the editing, use snippets directory bookmark at the TEA file manager or File save/open dialog. From there you can also rename or delete snippets (use the context menu - the right click - in File save/open dialogs).

### Functions > Scripts

#### Scripts from the user's point of view

With TEA you can use scripts to process a selected text, just as you use a built-in TEA functions. If the script can handle some parameters, put them into the Famous input field.

TEA can work with scripts those written in Python, Perl, Ruby, Lua, Bash (Sh), 2/REXX, and Windows batch format. To install a script, just put it to $HOME/.config/tea/scripts (you can use "scripts" shortcut at the Save As dialog to save your file as a TEA script). TEA will "see" the newly installed scripts after restart or when you save the script from TEA. The scripts management stuff is similar to snippets.

#### Scripts from the developer's point of view

How to write a script for TEA? It's quite simple. But the first thing that you must to know it is how TEA gives a text to the script and how TEA takes a processed text back to replace the selection with it.

TEA runs each script with one or two parameters. Both of them are file names. The first file contains the text (UTF-8). This text is a selected text that TEA gets in the current document. And the second file (if exists) contains a text (UTF-8) from the Famous input field. So your script can read the first file to obtain the text data, and read the second file to get some optional parameters for your script.

Be careful with the text handling - TEA internally operates with UTF-8 encoding, so all text processing at the script must be UTF-8-safe. OK, now let's see how a script can return a processed text. Just write that processed text to the first file again, i.e. to the file, which file name you take from the first parameter of your script.

Below these lines you shall see an example of UTF8-safe Python-script that takes a text, swaps the case, and returns the processed text back to the TEA.

    import sys
    import string
    import codecs
    f = codecs.open(sys.argv[1], "r", "utf-8" )
    u = f.read()
    f.close
    u = u.swapcase()
    f = codecs.open(sys.argv[1], "w+", "utf-8" )
    f.write (u)
    f.close

sys.argv[1] contains a name of file with the text from TEA. We read the whole content of that file, then we process this content, and then we write it back to the sys.argv[1]-file. Voila! Please note how to use the codecs.

And another example - the "inline" calculator. Here we don't use any codecs because we work with a numerical data:

    import sys
    f = file (sys.argv[1], 'r')
    s = f.read()
    f.close
    t = eval (s)
    f = file (sys.argv[1], 'w+')
    f.write (str (t))
    f.close

But what if we need to get some additional user's parameters to the script? They are available as a string, and you can read it from the file that named at sys.argv[2] (in Python). At Bash-script, use $1 to get the first parameter, and $2 for the second. Summing this all, the second parameter is a file which contains a text from the Famous input field. Note that Ruby scripts take the first parameter in ARGV[0], and the second in ARGV[1].

Some notes about the BASH-scripts and sed/ed/etc stuff. The trick is to use a temporal file. First copy the $1 into some temp. file, then process this temporal file and put the result back into the $1. Here is an example (replacing all "dog" with "cat") of such script:

    cp $1 /tmp/xyz.xyz
    sed 's/dog/cat/g' /tmp/xyz.xyz > $1

If you wish to contribute some scripts to the TEA site scripts repository, please consider contributing your script with a public domain status. Or at least with the Free license. There is also will be useful to put the credits and the description somewhere in the comments in your script.

Sort > Sort case sensitively - sorts selected lines alphabetically and case sensitively.

Sort > Sort case sensitively, with separator - sorts substring those separated by the delimiter. Put the delimiter into the FIF, then use this function on the text. Thus, you can sort "three|four|one|two" with the "|" as the delimiter.

Sort > Sort by length - sorts selected lines by the size. Provide the size at FIF.

Sort > Flip a list - reverses lines order. Was:

Dog
Cat
Cow

Will be:

Cow
Cat
Dog

Sort > Flip a list with separator - reverses substrings order separated by the delimiter at FIF.

Filter > Remove duplicates - useful when the string list has duplicated elements. Any duplicated item AFTER the original one will be removed. Can be slow on slow machines.

Filter > Remove empty lines - no empty lines will surrender! Empty lines are useless.

Filter > Remove lines < N size - remove lines with the length less than N. N is the number of characters. Write the number into the Famous input field.

Filter > Remove lines > N size - acts like the previous function, but removes all strings those larger than N characters.

Filter > by repetitions - leaves strings with the pattern, where "0" is any character, and "1" is the same character.

For example, the pattern for "kitten" will be "001100", where "11" is for "tt".

Filter > Filter with regexp - filter a list using the regular expression. For more info, see www.regular-expressions.info. However, here is a brief example. Let's presume you have a list:

hello.doc
example.txt
nature.jpeg
mytext.txt

And you want to filter all items with "txt"-extension. So the regexp (regular expression) for this will be:

.*\.txt$

Put it into the Famous input field, select the text and apply a function. Voila!

Filter > Remove after delimiter at each line. Removes the substring after the delimiter at each selected line. You need to put the delimiter into the FIF. For example, the delimiter is ")", and the selected text is:

    1.) Nirvana
    2.) Grajdanskaya Oborona
    3.) The Cranberries

Apply the filter, and you'll get this:

    1.
    2.
    3.

Filter > Remove before delimiter at each line. Removes the substring BEFORE the delimiter at each selected line. You need to put the delimiter into the FIF. For example, the delimiter is ")", and the selected text is:

    1.) Nirvana
    2.) Grajdanskaya Oborona
    3.) The Cranberries

Apply the filter, and you'll get this:

    Nirvana
    Grajdanskaya Oborona
    The Cranberries

Math > deg min sec > dec degrees converts coordinates from "degrees minutes seconds" format to "decimal degrees". Example:

Was: 40° 26′ 46″ N 79° 58′ 56″ W, result: 40.446° N 79.982° W.

Math > dec degrees > deg min sec converts coordinates from "decimal degrees" format to "degrees minutes seconds". Example:

Was: 40.446° N 79.982° W, result: 40° 26′ 46″ N 79° 58′ 56″ W.

Math > Sum by last column - sums values of each last column at the selection. For example, we can calculate the simple text list:

Carrots 14
Apples 45.8
Oranges 11

Math > Evaluate - calculates the expression that selected at the text. For example you can write 2+2, then select it and apply Evaluate. After such action you shall see the result at the logmemo. In your expression can may use the following operators: +, -, *, /, ^ (power), % (get percent value). The braces are supported. Here are some examples:

    2/3*123
    5+5+5
    1-200*89
    2^8
    250%4 //what is 4 per cent of 250?

Math > Decimal to binary - converts the decimal integer into its binary representation. Example: was 255, will be 0000 0000 0000 0000 0000 0000 1111 1111.

Math > Binary to decimal - works with unsigned int binary numbers only.

Math > Flip bits (bitwise complement) -use this function to flip a bit at the binary value. Example: was 0000 0010, will be 1111 1101.

Math > Enumerate - Enumerates lines from the selected text. Place the parameter string of this function into the Famous input field. Syntax: step~zero_padding~prefix.

Step is the step of an increment. For example, step 1 gives a numbers 1, 2, 3 etc. Step = 10 will give us 10, 20, 30.

Zero padding defines how many digits are in each number. For example, if zero padding = 3, and step = 1, we shall have 001, 002, 003 etc.

Prefix is a prefix after the number and before the string. Prefix can have significant trailing spaces.

Here are some examples and results:

example 1, parameters are "1~3~) " (without quotes). Result is:

    001) dog
    002) cat
    003) mouse

example 2, parameters are "10~1 " (without quotes). Result is:

    10 dog
    20 cat
    30 mouse

example 3, the parameter is "1" (without quotes). Result is:

    1dog
    2cat
    3mouse

You can use this function even without the parameters - in such case, padding = 0, step = 1, and the prefix is an empty string. You can use the single step parameter or the pair step and padding, or all three parameters.

Math > Arabic to Roman - converts "usual" numbers into the Roman form (i.e 20 to XX).

Math > Subtitles: shift timecode by msecs - shift timecode by msecs.
Open the subtitles file (SRT or Youtube format), select text, put msecs to FIF. msecs can be negative, i.e "-2000" shifts timecodes by 2000 msecs earlier.

### Functions > Morse code

From Morse To English. I am not a guru in Morse codes, but I hope that my effort to implement such function is right. With this menu item you can translate the English text into the Morse code. For example, was:

tea and coffee

Will be:

- . .- .- -. -.. -.-. --- ..-. ..-. . .

Note that TEA puts a single space between two Morse codes.

From Morse To English. The inverse action for the previous function. You can decode any English Morse-coded message. You must know that TEA supposes that there are single spaces between Morse-codes, as in the example written before.

Text > Compress - removes all whitespaces at the selection.

Text > Anagram - find all anagrams of the selected text. Can be VERY slow and eats a lot of memory if the word is large. So TEA will not froze, it just thinks. Anagram example for "dog":

dgo
dog
gdo
god
odg
ogd

Text > Remove formatting at each line - removes the formatting (tabs, new lines, double spaces etc.) at each selected line.

Text > Remove formatting - removes the formatting from the whole selected text, so the text will be converted to the one big string without new lines, double spaces, etc.

Text > Apply to each line is a powerful tool to add some text into each line of the selection. And again we use the Famous input field. For example, I want to add br-tag at the end of each line. So I type into the entry:

%s<br>

And then I apply this function to get br-tag added at the end of each line. The %s macro points to each line of the selection. So consider that the %s represents a text of each line. In another example, I want to enclose each line into a pair of li-tags. The formula for the Famous input field will be:

<li>%s</li>

And another example:

<a href="%s">%s</a>

You can also apply the snippets (from the TEA's snippets directory). To do such thing, use the @@snippetname at the FIF. For example, if you have the snipped named "myitalic", use @@myitalic. As you remember, snippets can contain the %s macro to substitute the selected text. In the case of "Apply to each line" function, %s will mean the text of each selected line.

Text > Escape regexp useful to escape regexp special characters such as $, *, +, [, ], etc .

Text > Check regexp match check the selected text against the regexp (put the regexp to FIF).

### Functions > Spell-checking

TEA can use the power of three spell checking engines: Aspell, Hunspell and Nuspell (TEA Qt6-build only). TEA can be built with or without them. In a positive case, to switch between engines use the list Spell checker engine at Options - Functions page.

Aspell engine uses system-wide installed dictionaries (use your Linux distro package manager to install them). At the Windows, you need some extra things to do. First, download and install Aspell full installer from the http://aspell.net/win32/. Then, from the same page, download and install some dictionaries. You need to put them into the directory, where Aspell is installed. By default, it is C:\Program Files\Aspell. Finally, at TEA, you need to set the path to the Aspell - go to the Options - Functions, change the Aspell directory option to the correct one and restart TEA.

For Hunspell, you also need to set the path to the dictionaries by yourself, manually. It is possible that the dictionaries are already installed because Hunspell is the spell checking engine for Firefox and LibreOffice.org. For example, Firefox (in a case of the user local home directory installation) holds the dictionaries at firefox/dictionaries directory. Also you can download dictionaries from LibreOffice extension repositories.

There are files with OXT extension. Internally they are common ZIP-files. So download and rename filename.oxt tofilenname.zip. Create some directory for dictionaries and unpack the .aff and .dic files from ZIP. Then select this directory using Select button at the Options - Functions - Hunspell dictionaries path option.

To be clear - we need only .aff and .dic files at the directory that you set at TEA options. No subdirectories.

Nuspell searches the dictionaries in its own way, let's say it is system-wide installed Hunspell and LibreOffice dictionaries.

When the dictionary stuff is configured, you need to go to the menu Functions - Spell checker languages and select the language what you need. Without this step the spell checking will fail. Alsom set the current language in this way after you switch between the engines (Aspell, Hunspell, Nuspell).

It's a good idea to restart TEA after adding the dictionary.

Spell-checker languages - At this menu you can find the list of dictionaries which installed for the current spell-checker. To do the spell checking, use one of those menu items. It works with the whole text, not with the selection only.

The menu item with the language name is used also to set the default spell-checker language. The default value is the language of your locale, but sometimes it went wrong, so select the language/dict manually is a good idea.

To do a simple check with the default (last selected) language, use Spell check menu item.

Suggest - shows the list with suggestions for the current misspelled word (actually, the word under the cursor). To use this function, use Spell check first. Possibly incorrect words will be underlined.

You can fix them with the Suggest functions or by the hand. When you fix the error you can see that the fixed word is colored as before. That is because the nature of the TEA spellchecker - it updates manually, so to update error marks select the same spell checking menu item again. To turn error marks off, use View > Hide error marks.

Add to dictionary - add the underlined as incorrect word to the user's local dictionary. Actually, this function adds to the dictionary any word at the cursor.

Beware that some correct words TEA can mark as incorrect. It's due to the current word parsing, it will be fixed soon as possible.

Remove from dictionary- removes the word from the user's dict.

### Functions > Speech

Currenly the Speech thing at TEA is experimental. To use it, you need that TEA build with Speech Dispatcher support.

If it is, install some speech synth that Speech Dispatcher can use as the output module, for example Festival or RHVoice. Then install voices for such synth. Configure Speech Dispatcher. The following example is for RHVoice:

1. Copy the /etc/speech-dispatcher directory to $HOME/.config

2. There, edit speechd.conf, where uncomment the line with AddModule "rhVoice" and add the line: DefaultModule rhvoice

3. To avoid crackles when run other audio software (such as Reaper or Ardour), if you use Pipewire or Pulse, uncomment AudioOutputMethod "pulse"

At Options page of TEA, section Speech, you can turn on and off Speech support, and select the voice. If Enable locale only voices is On, you'll get the list of locale voices only, not for all languages available. For stability purposes, these setting take effect after TEA restart.

### IDE

TEA has some basic IDE functions. The use TEA as IDE is simple.

The first, you need to create the project file. To do this, just create the new file and insert TEA project file template from Functions - Place - TEA project template.

Save it at the your project's source top directory, under any file name, but with the "teaproject" extention, i.e. filename.teaproject.

teaproject file is a simple key=value text file. It holds the project settings. Thus, you can hold many teaproject file at the same directory. Here are, for example, TEA's teaproject files for different build systems (qmake, cmake and meson):

tea-make.teaproject

    command_build=make
    command_clean=make clean
    command_run=bin/tea --m&

tea-meson.teaproject

    dir_build=b
    command_build=ninja
    command_clean=ninja -t clean
    command_run=./tea --m&

tea-cmake.teaproject

    dir_build=cmake
    command_build=make
    command_clean=make clean
    command_run=./tea --m&

The syntax is clear:

dir_build - the directory, where command_build will run for the building. If there is no dir_build, then the teaproject file directory will be used as dir_build. The directory can be absolute, if not, the relative one to the teaproject file directory will be used.

command_build can be any, as you wish: make, ninja, etc.

command_run - runs at dir_build to run compiled binary.

command_clean - runs at dir_build to clean the project.

When you open, save or switch (by the tab) to the teaproject file, TEA reads it into the inner structures and uses the commands from teaproject when run menu items from IDE menu: Run program, Build program, Clean program. Please note that TEA reads the SAVED contents of the teaproject file, not the current edited state.

The IDE menu is useful in a pair with View - Profiles menu. For example, you can create the "ide-profile" with some font settings, wide window, no word wrap; and "text-profile" with another font set, word wrap, smaller window, etc. Then you can quickly switch between the profiles via menu or by the hotkeys.

When building program, TEA shows compiler output at Logmemo. Double-click on the bold text (filename:line:column) to open the error or the warning place at the editor.

### Run

This menu is designed for running the current file with external programs, browsers for example. To add some items to menu, go to File > Configs > Programs list config, edit that file and then save it. The configuration file has the simple ini-like format. Each line has the following format:

meni item caption=command line

An example of the command line for a browser starting:

FF=firefox %s

%s is a needful macro for a current filename, so use it in the proper place. For Win32 you need to use the full path for the executable file, with the double quotes (macro %s needs its quotes too!). For example:

opera="C:\Program Files\Opera\opera.exe" "%s"

Some more precise macros are available: %basename, %filename, %ext, %dir. This allows to use the parts of the path. Thus, if we have the full path "/mnt/foo/bar.txt", %dir = "/mnt/foo", %basename = "bar", %filename = "bar.txt", %fext = "txt". So the full path at the command line can be presented in the following way: %dir/%basename.%ext

To open the currently selected file or file at cursor at the text (as by F2, but with an external program) use %i macro.

For example, if you want to open the image file with gimp, put the following command line to the config file:

gimp=gimp %i

Then, at HTML or LaTeX file, move the cursor to the image file name. Then call "gimp" menu item from the "Run" menu. Enjoy.

### Nav

Labels, Update labels. You can put some specially formatted labels into the text and then switch between them from the Labels menu (or drop-down list on the toolbar). How does it work? The label is just a text embraced with the opening and the ending sequences ("[?" and "?]" by default, this values can be redefined at Options - Functions - Labels).

For example, put into your text some lines such as "[? dogs ?]", "[? cats ?]". Then make TEA know this labels using Update labels menu item or press the button on the toolbar. The Labels menu and drop-down list will be filled with labels "dogs" and "cats". You can select them from the menu or the list and navigate to the text near the selected label. Please note that labels are updating manually only.

Go to line - moves the cursor position to the line number that you provide in the Famous input field.

Save position/Go to saved position - these functions are good to make a quick jump through a large text, when you need to look something at the one place, then return to the currently editing place, etc.

### Fm

Fm is meaning the File manager. This menu contains functions those related to TEA file manager. For example, you can rename files or directories or get the MD5 checksum. Explore and use!

For some function such as MD5 checksum, select the file first, and then apply the function.

Fm > Multi-rename submenu helps to flexibly rename file names. All those functions use the parameter from FIF.

Fm > Multi-rename > Zero pad file names - prepend zeroes to each selected filename that has the numbering as the part of file name. For example: page1, page100. Such files cannot be sorted properly.

So set the filename length at FIF. Files will be numbered correctly, but with the removal of all non-digit characters. Example:

We have files:
page1.txt
page100.txt

Put 5 to the FIF, apply the function.

Now we have:
00001.txt
00100.txt

Fm > Multi-rename > Delete N first chars at file names - N is a number from FIF. Deletes N first characters from each selected file name.

Fm > Multi-rename > Replace in file names - replaces the substing at each selected file name. FIF format: old~new. Example: .jpeg~.jpg

Fm > Multi-rename > Apply template - apply the template to each selected file name. Available macros with parts of the original file name: %filename (= filename.ext), %ext (= ext), %basename ( = filename). For example, you need to rename 01.jpeg, 02.jpeg to 01.jpg, 02.jpg. So the template must be: %basename.jpg, i.e. %basename (file name without extension) will be appended with ".jpg".

Fm > Select by regexp/Deselect by regexp - use this functions to select or deselect files by regexp pattern. For example, to select all txt-files at the current dir, put the following regexps into the FIF:".*\.txt$" (without quotes!) then, use Select by regexp. Then you can press Open button to open all selected files.

Fm > File information > Full info - gives you a full information about the file (creation/modification time, etc). For the 16 bit PCM WAV files it calculates the RMS (for the both channels). For other WAV's shows just the properties such as bit depth, etc.

Fm > File information > Count lines in selected files - please note that empty lines will be also counted.

Fm > Images > Scale by percentages/Scale by side - among other non-text related functions TEA has the ability of batch conversion of images. It is useful when you want to scale them or convert to another format.

For example, we want to scale selected images by 50 per cents, and put the processed images into the new directory:

1. Select files at the File manager. To select them multiply, use Ctrl-Click (or Ctrl-A to select all).
2. Put the desired percentage into the Famous Input Field. The value must be a simple integer number without the % sign.
3. Apply the Scale by percentages function.

After that, TEA creates a new directory as a subdirectory of a current one. This new directory has the random name that starts with "images-out-". Into this directory TEA put all converted images, leaving the originals unmodified.

You can want to scale images in a more precise way and define the size manually. To do that, put the image side size into the Famous Input Field and apply Scale by side. As you know, each photo has dimensions. For example, 640x480. If the width is larger than height, the image has a horizontal orientation (TEA does not support EXIF data), and vise versa. So we can use the side - the larger side of an image. Usually all photos have a standard dimensions with some aspect ratio in a mind, so the larger side for all of photos is the same.

For example, we want to scale all images (photos with a right aspect ratio/dimension) to width 640 and, if the image has a vertical orientation, to the height 640. Put that 640 into the Famous Input Field and apply Scale by side.

Image conversion options are places at the Options > Images page. With the Image conversion output format list you can set the output format. The Output images quality (from 0 to 100) is used mainly for JPEG. A default value is -1 that means the internally defined value. The Scale images with bilinear filtering checkbox affects images when you scale them, to smooth the image and make it less "rough".

Fm > Images > Create web gallery - yes, TEA can create the simple oldschool table-based web gallery. Do the following steps:

1. Put your images in some directory. Save the html-file there. Open that file with TEA.

2. Go to the TEA's file manager, select image files those you want to put into the web gallery.

3. Use the Create web gallery function.

4. The thumbnails and the HTML-table shall be created.

You can customize the gallery using the Options > Images > Web gallery options. There is a thumbnail size, cells per row, et cetera.

### View

Highlighting mode - from this submenu you can set the highlighting mode manually. It is useful for new unsaved files or for a file without extensions.

Hide error marks - hides the underlined marks those were set by the spell-checker.

Toggle word wrap - turn word wrapping on/off for the current document.

Palettes - from this submenu you can select the color scheme that affects a text editing area. To define your own colors you can create your own palette based on some build-in palettes (see the source directory, palettes subdir). Then save your palette into the $HOME/.config/tea/palettes directory and choose one from the Palettes menu.

TEA partially supports Eclipse IDE themes (eclipsecolorthemes.org) - just put XML file of the theme to TEA palettes directory and select it from the menu as the native TEA palette. It is a miracle! Please note that TEA palette format supports more highlighting elements than Eclipse Color Theme plugin, so Eclipse themes will be not so colorful as TEA native palettes.

Profiles - this menu allows you to switch between view profiles (they includes parameters such as window position, size, fonts, word wrap and line numbering settings, etc.). So you can save your current settings via Save profile function, and named profile will appear in the Profiles menu. In any time you can select it to recall saved settings.

Keyboards - the list of user-defined keyboards. TEA show such "keyboard" as the window with buttons. Each button can be the letter or the word or any string, to simplify inputm for example, foreign alphabet letters or difficult words.

The "keyboard" is a simple text file that you put to $HOME/.config/tea/keyboards directory. Each line of the file contain letters or words separated by "|", for example:

dog|cat
apple|orange

### Options tab

On Keyboard tab you can assign the shortcuts with the menu items. To set a new hotkey, select a menu item from the list, then press some hotkey combination at the entry to the right from the list, and press the Assign button. To remove a hotkey, select the menu item from the list and press Remove button. To reassign the hotkey that already in use, do Remove for this shortcut first.

For Linux, you can use the joystick/joypad to scroll the text and move the cursor. It is disabled by default and can be enabled via Preferences - Common - Use joystick as cursor keys. When enabled, it reads joystick device each 100 milliseconds. I was needed in joystick support to scroll texts for Youtube online videos, when I need to sit in the same position.

Word wrap - use word wrapping globally for all documents, including new ones.

Use wrap setting from highlighting module on the Interface page means that the word wrap settings will be taken from the syntax highlighting modules, not from the global Word wrap option. Some modules have word wrapping turned on, and some turned off. For example, for C++ the word wrap setting is on. For the plain text or for the HTML - is off.

### Keyboard

In addition to the standard keyboard operations TEA supports left-handed cursor operations those can be enabled at Options - Common - Use Left Alt WASD.

When enabled, use Left Alt plus WASD for cursor movement, Left Alt plus E and C for page up/down. Use Left Win key with WASDEC to select the text.

### On autosaving

TEA has some features related to the auto-saved files.

The first one is saving on unsaved files. When you create a new file, it exist as the buffer. You use "Temporary save unsaved buffers on exit" option (at Options - Common). If it is turned on, TEA save such buffers on TEA exit (not on the closing buffer tab manually), and then restores them on the next start. So, it is like the session saving. But, if you just close some unsaved file tab, it will not be saved.

Another option there, is "Autosave buffers and autosaving files (each N seconds)". It saves buffers each N seconds, also it saves the ordinary files that checked as "autosaved". You can set/unset file as autosaved at File - File actions - Set as autosaving file/Unset the autosaving file. Such autosaved files also automatically saved when you close them.

### The secret power

Know the truth! The reptiloids will prevail over the humankind if you do not have the courage and the knowledge of TEA secret options. They don't have GUI and you need to add and edit them manually to the TEA main config file $HOME/.config/tea\tea.conf (or, under Window, at drive:\Documents and Settings\username\tea\tea.conf). Some of the changes will work after TEA restart. So know the truth:

recent_list.max_items=maximum recent list items, default 21

### Notes

The legacy "--charset=codepage" command line option is supported. This command sets the codepage for the following files. For example:

tea --charset=window-1251 file1.txt file2.txt --charset=utf-8 file3.txt

By default (if no charset defined manually) TEA uses UTF-8.

This manual and all TEA media stuff (palettes, images, etc) is the public domain. TEA source code is licensed under GPL v3 and public domain.

User's syntax hl files can be added to the $HOME/.config/tea/hls directory. See the working hl files at the TEA source directory, the hls subdirectory. Feel free to contribute your hl files. Please use color references from the palette files (look at palettes directory at the source). I.e. use "preproc" or "types" color instead of the hexadecimal value.

### Other projects by the author

My Github page.

### Support the development

If you want to support TEA development, here is my Paypal address: peter.semiletov@gmail.com