Add actual tutorial

[techtonik]

I knew micro for ages, but had to spend some time to discover how to do basic things like working with multiple files.

I think these notes belongs to official tutorial to help others discover micro and save that time. I tried to cut the amount of text to read, because people skim, don't read, but I am not sure if it became better.

[Neko-Box-Coder]

I think adding an example on how to edit a file using micro is great, but using micro codebase itself as an example requires a bit of effort. (Needs git and also need to clone it, not everyone is a developer)

Not to mention you can't do much with the cloned codebase after the example unless you are a developer or contributing to the codebase.

I personally think editing either bindings.json or settings.json is relatively straightforward and practical as a tutorial example. Or even extending it to init.lua would be quite nice as well.

And one minor note is that I think using ctrl-s is more familiar then F2 for saving a file? Or maybe list both of them?

[techtonik]

(Needs git and also need to clone it, not everyone is a developer)

I kind of agree with that, but let's also admit that we don't have the data. Maybe micro is a niche product only for developers and Linux savvy people, who know how to use wget or git clone to download stuff, or at least ask LLM about it. Everybody else is most likely using Notion or Google docs.

[techtonik]

And one minor note is that I think using ctrl-s is more familiar then F2 for saving a file? Or maybe list both of them?

Pressing Ctrl-s in Bash is a recipe to disaster, so it is a bad habit to have this motor memory in Linux terminal. I don't know why it is not possible in Linux to fix it.

[techtonik]

I personally think editing either bindings.json or settings.json is relatively straightforward and practical as a tutorial example. Or even extending it to init.lua would be quite nice as well.

Only vim need a need a tutorial to edit a single file. Other editors are quite intuitive with that. Tutorial should give some notable details about that specific editors, and common use cases. I found editing multiple files in vim and copy/pasting contents extremely hard to remember, so that's why I switched to micro few days ago.

[techtonik]

Actually it might be a good idea to provide short tutorials for different experience levels. Maybe also linking them to external sites.

But the greater problem for beginners that the tutorial is hard to find. On the web site it is hidden in About section.

[Andriamanitra]

I think this is a positive change overall. I'm not sure if the chosen example of editing workflow is ideal but having an example definitely feels like a good idea.

[Andriamanitra]

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?

[techtonik]

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.

[Andriamanitra]

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.

[Andriamanitra]

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

[techtonik]

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.

[Andriamanitra]

I think this sentence is too long which makes it harder to comprehend compared to the original phrasing. It's also missing the note about the modification taking effect immediately (which importantly does not happen when modifying the settings file directly).

[techtonik]

That's was unclear from the previous doc. Let me try to rephrase that.

[techtonik]

Try the next text. Should be better now.

[Andriamanitra]

I would avoid the word "local" because users might assume it means local as the opposite of remote (many other modern text editors have remote editing features).

Suggested change

	You can also set options temporary for the local buffer without saving then.
	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 save
	this local change to the `settings.json` file.
	You can set options temporarily for the currently open buffer without saving them.
	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 save
	this change to the `settings.json` file.

[techtonik]

I also don't like local, but the command is called setlocal and I feel it needs explanation. Otherwise it is hard to understand and remember.

The best way would be set (only for current file) and setconfig (save option to configuration), and maybe setfileconfig (save to configuration for the current file extension).

[techtonik]

Explained with "local is not global", because the "local buffer" sounds like too much internal details.

[Neko-Box-Coder]

I personally think editing either bindings.json or settings.json is relatively straightforward and practical as a tutorial example. Or even extending it to init.lua would be quite nice as well.

Only vim need a need a tutorial to edit a single file. Other editors are quite intuitive with that. Tutorial should give some notable details about that specific editors, and common use cases. I found editing multiple files in vim and copy/pasting contents extremely hard to remember, so that's why I switched to micro few days ago.

I am not saying we can't have a tutorial that works with multiple files, we definitely can.
In fact it is a good tutorial as well since we can introduce users to split/tab relatively easily.

What I was saying is that the tutorial should be using something the user already has.
Using something the user needs to acquire just adds more effort to the tutorial and makes the user less likely to do it, which defeats the whole point of a practical tutorial.

Maybe we can copy and paste some of the keybindings or options from the help page to the user's keybindings / settings as an example of working with multiple files.

How does that sound? @techtonik

[techtonik]

@Neko-Box-Coder I don't know where these help files are.

$ tree ~/.config/micro 
/home/techtonik/.config/micro
├── backups
│   └── %tmp%micro%internal%config%plugin_manager.go
├── bindings.json
├── buffers
│   └── history
└── settings.json

3 directories, 4 files

I still think micro codebase is the best text corpus for experiment. Good introduction into Open Source. =)

[Neko-Box-Coder]

@techtonik
No, I meant copying things from the help page to the user's settings.json or bindings.json as an example.

For example, we can say something like we want to set the brace highlighting style from underline to highlight when our cursor is on it but we don't remember what the exact name is, and we have no internet so we can't search it on micro's page.

So we open up our settings.json, then the options help page with ctrl-e, then type help options. Which is just a read-only buffer.

Find brace using ctrl-f and go to the next occurrences until we find matchbracestyle, copy it and the option highlight to settings.json on another split that we opened previously, ctrl-v to paste it to the place you like.

This is just an example on what we can do a tutorial on obviously.