# Userguide

The intention with this userguide is to give a brief overview of the Yzis editor and its capabilities. It's very basic and the idea is to get new Yzis user started quickly. It covers the most essential parts like starting, exiting, the different modes, basic editing and some basic commands.

The userguide will proceed from the ncurses user interface, but of course everything works identical in the KDE user interface. It's highly recomended to have a copy of Yzis started when reading the userguide and try out all steps that are gone through.

## Start Yzis

To start Yzis (the ncurses interface) type:

    $ yzis

But normally you would specify a file you wish to edit after the Yzis command:

    $ yzis filename

It's also possible to specify which line the cursor should jump to when opening a file:

    $ yzis filename:line

When you have opened a file it will probably look something like this:

You will automatically be placed in &command; mode when the file is opened. Which brings us on to the next section...

## Modes

Yzis is a so called "modal editor". It means that the editor has different modes and that it behaves differently depending on which mode you are in. There are three main `modes` in Yzis.

- Insert mode

- Command mode

- Ex mode

The &insert; mode is used for inserting text. The &command; mode is used for executing Yzis commands that edits the text. The third mode, &ex;, is used for executing commands that are file related, like saving, opening and exiting files.

As we mentioned in the previous section you are automatically being placed in &command; mode when you open a file. You can always tell which the current mode is by looking at the status bar in Yzis:

"Awaiting Command" in the status bar indicates &command; mode.

Changing between the modes in Yzis is achieved by pressing different keys.

- Insert mode = `'i'` or `<Insert>`

- Command mode = `<ESC>`

- Ex mode = `:`

You have now been introduced to the three modes in Yzis. You know how to change between them, but you still haven't learned to use any of them. In the next section you will get more familiar with the &insert; mode.

## Insert mode

&insert; mode is the mode to use when inserting/writing text in Yzis. The text will be inserted at the cursor. There really aren't so much to say about this mode, it's pretty much like writing text in any editor.

To enter &insert; mode either press `'i'` or <`Insert`> (NOTE: These two key-shortcuts are not the only ones used to enter &insert; mode, consult the command reference to get info about the others. This userguide is meant to just cover the basics).

"Insert" in the status bar indicates &insert; mode.

There is a special case of &insert; mode called &replace; mode. Unlike the normal &insert; mode it overrides (replaces) text by default, which could be useful on certain occassions. To enter &replace; mode press `'R'`.

"Replace" in the status bar indicates &replace; mode.

## Command mode

It is in this mode you will get advantage of all the handy commands that Yzis provides for editing the text. &command; mode is only used for executing commands, it's not possible to write text there like in the &insert; mode. There are many useful commands in Yzis and it may seem like a steep learning curve for the beginner, but there is no need trying to learn all the commands at once. If you follow this userguide you will be introduced to the most basic commands which allows you to copy text, paste text, delete text and search in the text. Hopefully you will understand the power of Yzis' commands and later on become more efficient in your editing.

To enter &command; mode press <ESC>.

"Awaiting Command" in the status bar indicates &command; mode.

You will be introduced to Yzis' commands later on in the userguide.

## Ex mode

The third main mode in Yzis, called &ex; mode is also used for executing commands, but these commands hasn't got anything to do with editing the text (like in &command; mode). The commands available in &ex; mode are used for things like opening, saving and exiting files. The &ex; mode in Yzis isn't very useable at the moment, it just provides the most vital commands.

To enter &ex; mode press `:` (colon).

Here is a list of the most essential &ex; commands:

- `'w'`

  Writes/saves the current file.

- `'q'`

  Quits the current file.

To quit Yzis: Press `:` to enter &ex; mode, then press `q` followed by <Enter> (all &ex; commands have <Enter> at the end).

"Ex" in the status bar indicates &ex; mode. When you're in &ex; mode you will be able to type commands in the field below the status bar. In the screenshot there is a q written in the &ex; field which means quit. Pressing <Enter> in that situation would quit the current file.

The special modifier `!` is available in &ex; mode and is used for overriding changes. By default Yzis doesn't allow the user to quit (:q) a file when it has been modified without saving the changes, the user will be confronted with a error message. The `!` modifier can be used together with quit (:q!) to force a quit without saving changes. This modifier should be used with care and only in certain cases when you are sure you don't want to save the current changes.

## Movement

Moving around in Yzis is could be (if you want to) just like moving around in any editor. It's possible to use the arrow-keys (up, down, left, right) as normal, but Yzis also provides some other keys to achieve this. Here they are:

- `'h'` = left

- `'j'` = down

- `'k'` = up

- `'l'` = right

This may seem very strange for the beginner, but when you actually look at the keyboard and notice where these keys are positioned, you may see a connection. The thing is that moving around in an editor is one of the things you spend a lot of time with, and moving your hand between the arrow-keys and the text-keys all the time is pretty time consuming (and very unneccesary when you think about it). The mentioned keys are only available in &command; mode since pressing them in &insert; mode would write them to the file. These special movement-keys are of course optional and it's up to the user if he wants to use them or not, the arrow-keys has the exact same function (it's only the placement on the keyboard that differs).

Commands that moves the cursor are called `motions` in Yzis. The keys mentioned above (h,j,k,l) are motions because they move the cursor. Here are a couple of other useful motions:

- `'w'` = one word forward

- `'b'` = one word backward

- `'$'` = the end of the line

- `'0'` = the start of the line

- `'[count]G'` = goto line [count] (default = last line)

These are all very useful motions which allows the user to quickly move around in the file. I don't think they need any further explanation, the best way to get to know them is undoubtely to try them out in Yzis yourself. The `[count]` expression may need a little explanation though. It means that the `'G'` motion can handle a `[count]` argument. For example `'10G'` would put you on line 10, `'255G'` would put you on line 255 and so on. However, with no `[count]` argument it positions you at the end of the file. The structure with an optional `[count]` argument isn't specific to the `'G'` motion, actually many of the motions in Yzis support a `[count]` argument. What do you think would happen if you passed an `[count]` argument to the `'w'` motion? For example `'5w'` ? Correct, it would move the cursor 5 words forward. You will notice that this structure is applied to many of the editing commands aswell if you continue reading the next section.

## Editing

You were introduced to some of Yzis' motions in the previous section, which allowed you to move around quickly in the file. Now it's time to learn how to edit the text in your file quickly and in a efficient way. We will present a few basic commands here which will speed up your editing. The best way to learn these editing commands is to have your own copy of Yzis running and try them out. It will probably take you a long time to be really efficient in your editing, but you've got to start somewhere and the commands mentioned in this section are a good start.

Let's start with some delete, copy and paste commands:

- `'dd'` = deletes a line

- `'yy'` = yanks a line

- `'p'` = pastes after the cursor

- `'P'` = pastes before the cursor

To delete a line, simply press `'dd'` in &command; mode. It deletes the current line (the one where your cursor is positioned). To paste the deleted line, move the cursor to the wanted position and press either `'p'` or `'P'`. To yank (copy) the current line, press `'yy'`. You can paste this line by using `'p'` or `'P'` aswell. As we mentioned in the previous section, many of the editing commands can handle a `[count]` argument. Typing `'3dd'` for example will delete three lines in one stroke, the same applies to `'yy'`.

`'d'` is also a useful command used for deletion. It deletes all the text the following motion moves over. The structure for this command is `'d[motion]'`. Here are some handy examples:

- `'dw'` = deletes one word

- `'d$'` = deletes from the cursor to the end of the line

- `'dG'` = deletes from the cursor to the end of the file

As you maybe remember from the last section (about movement), `'w'` moves the cursor one word. `'dw'` thereby results in deleting one word. We also mentioned in the last section that `'$'` moves the cursor to the end of the line, that means that `'d$'` will delete everything from the cursor to the end of the line. And `'dG'` will of course delete everything from the cursor to the end of the file.

Another useful editing command is `'c'`. It's very similiar to `'d'` with the difference that `'c'` puts you in &insert; mode right after the execution. Just like `'d'` it accepts a motion as argument and it can be used with the same motions as we presented in the list above. `'cw'` deletes one word and puts you in &insert; mode right where the word was. `'c$'` and `'cG'` doesn't need any further explanation, the only difference is that it places you in &insert; mode when the command is finished.

Two essential features for an editor is undo and redo. To undo the latest change in Yzis use the `'u'` command. To redo, use the `'U'` command.

## Searching

Searching after a certain text in your file is an essential function of a editor. Yzis provides two different commands for searching, one for searching forward, and one for backward.

- `'/<pattern>'` = search forward

- `'?<pattern>'` = search backward

- `'n'` = next match

- `'N'` = previous match

To search forward: Hit the `/` (slash-key), enter your search pattern and press <Enter>.

Notice that the text in the status bar changes to "Search" and you are able to insert text in the search-field when you have pressed `'/'`.

It's the same procedure for the search backward-function. Just press `'?'` instead of `'/'`, enter your search pattern and press <Enter>:

When you have entered your search pattern and pressed <Enter> the cursor will jump to the first match. To jump to the next match (direction=forward) press `'n'` or to jump to the previous match (direction=backward), press `'N'`.

Yzis also provides a search and replace function, called `substitute`. It allows you to specify the pattern you would like to replace and the text to replace it with. The syntax and available options are explained in the examples below (Note: This function has to be executed in &ex; mode).

- `:s/teh/the`

  Will replace the first occurence of "teh" with "the" on the current line.

- `:s/teh/the/g`

  Will replace all occurences of "teh" with "the" on the current line.

- `:%s/teh/the`

  Will replace all occurences of "teh" with "the" in the whole file.