Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add actual tutorial #3315

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add actual tutorial #3315

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c5bfd70
Add actual tutorial
techtonik May 24, 2024
882c602
Add how to exec commands to tutorial
techtonik May 24, 2024
3b00cae
Address review comments
techtonik May 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 55 additions & 24 deletions runtime/help/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,65 @@
# Tutorial

This is a brief intro to micro's configuration system that will give some
simple examples showing how to configure settings, rebind keys, and use
`init.lua` to configure micro to your liking.
This is a brief intro to `micro` workflow with simple examples how to configure
settings, keys, and use `init.lua`.

Hopefully you'll find this useful.

See `> help defaultkeys` for a list an explanation of the default keybindings.
## Command mode

### Settings
Press `Ctrl-e` to open micro's command prompt. Typing `help tutorial` will open
this documentation.

In micro, your settings are stored in `~/.config/micro/settings.json`, a file
that is created the first time you run micro. It is a json file which holds all
the settings and their values. To change an option, you can either change the
value in the `settings.json` file, or you can type it in directly while using
micro.
For the rest of the docs `> help tutoral` indicates pressing `Ctrl-e`.

Press Ctrl-e to go to command mode, and type `set option value` (in the
future, I will use `> set option value` to indicate pressing Ctrl-e). The change
will take effect immediately and will also be saved to the `settings.json` file
so that the setting will stick even after you close micro.
## Default keyboard shortcuts

You can also set options locally which means that the setting will only have
the value you give it in the buffer you set it in. For example, if you have two
splits open, and you type `> setlocal tabsize 2`, the tabsize will only be 2 in
the current buffer. Also micro will not save this local change to the
`settings.json` file. However, you can still set options locally in the
`settings.json` file. For example, if you want the `tabsize` to be 2 only in
Ruby files, and 4 otherwise, you could put the following in `settings.json`:
Enter `> help defaultkeys` for a list of the default keybindings.

## Simple workflow: Move content from one file to another

For this example, we edit micro's own codebase, and move contents between files.

Press `Ctrl-o` and enter filename to open the file in the current view
(use `Tab` key to help with autocompletion)
```
> open internal/config/plugin_manager.go
```
Then from the command prompt (`Ctrl-e`) open a second file in a vertical split
```
> vsplit internal/config/plugin.go
```
Comment on lines +25 to +31
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rest of the file has empty lines on either side of code block, I'd add them here too for consistency and readability.

Have you considered using (or at least mentioning) tab instead of vsplit?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. For me tab is a key. =)

In i3 I don't need tabs. The edit workflow when you can see two or more files in one window seems more useful to me. Maybe the real reason why I decided to use micro is because copying text between vim instances running in different tabs didn't work for me, or the contents was lost when vim exits.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's the opposite for me – I mainly use tabs because I keep my terminal window small and there's not really enough space for two buffers to fit comfortably. From my perspective tabs are the more basic form of operation (if you open multiple files at once the default behavior is to open them in tabs) and splits are slightly more advanced feature that users can learn about on their own. But I guess it ultimately doesn't really matter which one the tutorial uses.

Use `Ctrl-w` ("jump to next split" shortcut) to switch to the first file and
cut the `PluginInfo` structure into clipboard using `Ctrl-x`.

Press `Ctrl-w` again to switch back to second file and paste the clipboard
content using `Ctrl-v`.

Now press `Ctrl-s` (or `F2`) to save current file and `Ctrl-q` to close it.

To preview the changes, run `git diff` by pressing `Ctrl-b` ("shell mode")
and entering the command. You will see changes only to the second file
`plugin.go`, because the first file is not saved yet.
Comment on lines +40 to +42
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

git is rarely installed by default so it might not be the best example to use for the command mode.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can rename the tutorial "Copying micro code with micro", to make it clear that it is for developers. Trying to squeeze everything in one tutorial is impossible anyways, and I don't know the target auditory that works with micro without git.

If there is another way to see changes since the file was opened, let's list them here.


Hit `Ctrl-q` again and micro will prompt if you want to save the first file
before closing. Press `y` and you're done.

Congratulations with completing your first mouseless tutorial with micro.

## Settings

In micro, your settings are stored in `~/.config/micro/settings.json`, which
is created on the first run. It can be edited directly, or you can invoke
`> set option value` command from `micro`. With the command changes are
applied immediately and then saved into `settings.json`.

Options can also be set without saving them, using `setlocal` command. Local
means the setting is not global. For example, if you have two splits open,
and you type `> setlocal tabsize 2`, the tabsize will only be 2 in the
current buffer, and micro will not update `settings.json` file.

You can also set options for specific file types in `settings.json`. If you
want the `tabsize` to be 2 only in Ruby files, and 4 otherwise:

```json
{
Expand All @@ -40,10 +72,9 @@ Ruby files, and 4 otherwise, you could put the following in `settings.json`:

Micro will set the `tabsize` to 2 only in files which match the glob `*.rb`.

If you would like to know more about all the available options, see the
`options` topic (`> help options`).
See `> help options` to read about all the available options.

### Keybindings
### Setting keybindings

Keybindings work in much the same way as options. You configure them using the
`~/.config/micro/bindings.json` file.
Expand Down
Loading