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.

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

Add actual tutorial #3315

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

Add actual tutorial #3315

wants to merge 3 commits into from

Conversation

techtonik
Copy link
Contributor

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
Copy link
Contributor

Neko-Box-Coder commented May 24, 2024

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
Copy link
Contributor Author

(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
Copy link
Contributor Author

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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.

Copy link
Contributor

@Andriamanitra Andriamanitra left a comment

Choose a reason for hiding this comment

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

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.

runtime/help/tutorial.md Outdated Show resolved Hide resolved
Comment on lines +25 to +31
```
> 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
```
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.

Comment on lines +40 to +42
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.
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.

Comment on lines 52 to 55
that is created the first time you run micro. You can edit the `settings.json`
file directly, or you can use `> set option value` command from micro, which
modifies `settings.json` file too, so that the setting will stick even after
you close micro.
Copy link
Contributor

Choose a reason for hiding this comment

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

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).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Try the next text. Should be better now.

Comment on lines 57 to 60
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.
Copy link
Contributor

Choose a reason for hiding this comment

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

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.

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 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).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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

@Neko-Box-Coder
Copy link
Contributor

Neko-Box-Coder commented May 25, 2024

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
Copy link
Contributor Author

@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
Copy link
Contributor

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants