Browse Source

added wiki

pull/1/head
budRich 2 years ago
parent
commit
e209ce12e0
18 changed files with 1037 additions and 2 deletions
  1. +1
    -1
      packages/README.md
  2. +5
    -1
      scripts/README.md
  3. +8
    -0
      wiki/escape-capslock.md
  4. +156
    -0
      wiki/subl0.md
  5. +20
    -0
      wiki/subl0_background.md
  6. +55
    -0
      wiki/subl10_vintage_settings.md
  7. +77
    -0
      wiki/subl11_fixing_vintage.md
  8. +23
    -0
      wiki/subl1_installation.md
  9. +80
    -0
      wiki/subl2_settings.md
  10. +55
    -0
      wiki/subl3_manage_packages.md
  11. +57
    -0
      wiki/subl4_extracting_packages.md
  12. +66
    -0
      wiki/subl5_linking_defaults.md
  13. +157
    -0
      wiki/subl6_install_packages.md
  14. +45
    -0
      wiki/subl7_hidden_commands.md
  15. +47
    -0
      wiki/subl8_enabling_vintage.md
  16. +52
    -0
      wiki/subl9_extracting_vintage.md
  17. +49
    -0
      wiki/sublime_and_git.md
  18. +84
    -0
      wiki/vintage_clipboard_history.md

+ 1
- 1
packages/README.md View File

@@ -26,4 +26,4 @@ The article above describes the difference between *packed* and *unpacked* packa

The biggest drawback with *packed* packages is that it some interesting files, (*such as readme.md and default settings*), are hard to find.

I have created a script `subextract(1)` that will extract move and rename all *interesting* files from the packed packages. `subextract` can be executed multiple times, and it will never overwrite `sublime-settings` files inside the **User** package.
I have created a script `subextract(1)` that will extract move and rename all *interesting* files from the packed packages. `subextract` can be executed multiple times, and it will never overwrite existing `sublime-settings` files inside the **User** package.

+ 5
- 1
scripts/README.md View File

@@ -1 +1,5 @@
`tits` - Prints the title of the currently open sublime window.
`tits` - Prints the title of the currently open sublime window.

`subextract` - Creates a settings project as an alternative to the default sublime settings system.



+ 8
- 0
wiki/escape-capslock.md View File

@@ -0,0 +1,8 @@
A even better way to have easy access to 'Escape' is to install `xcape` (`sudo apt install xcape`) and add this to your `~/.profile`:

``` shell
setxkbmap -option caps:ctrl_modifier
xcape -e 'Caps_Lock=Escape;Control_L=Escape;Control_R=Escape'
```

Now your control keys acts as `Escape` if they are pressed 'alone' and as a bonus your stupid CapsLock key is also a control key!

+ 156
- 0
wiki/subl0.md View File

@@ -0,0 +1,156 @@
---
title: "sublime_setup"
date: 2017-10-17T01:30:22+02:00
author: "budRich"
draft: true
type: post
target: budlime/articles
tags: ["sublime","setup","rice"]
notes:
- "lnk: budtutor, settings, keymap"
- "https://www.reddit.com/r/SublimeText/"
---
Below is a guide on how I like to set up [Sublime Text](http://www.sublimetext.com/). Keyboard friendly and minimal UI is my aim. For info on using Sublime i recommend my custom mashup of VIMtutor and Sublime tutor, [budtutor](link).

If you are using Atom or VS code, please read this article:
https://medium.com/@caspervonb/why-i-still-use-vim-67afd76b4db6

Or this...
https://github.com/Microsoft/vscode/issues/35783

-----------------------------------------

locate files
------------

I have a lot of custom settings and a personal package collection. It is a pain to achieve the same setup on a fresh install of Sublime.

I have found a really neat way to keep my settings in sync and backed up with [Dropbox](https://db.tt/eFkf49MZ).

After installation, make sure Sublime isn't running and move the folder `sublime-text-3` inside `~/.config` to your Dropbox folder. Then make a symbolic link of the folder in it's original place.

Now your sublime configuration and setup will be backed-up automagicly!

(the easiest way to create symbolic links is to open two file manager windows and just drag and drop the folder while holding `ctrl+shift`)

Whether you do this or not, your sublime setting files will have a very inconvenient path. My recommendation is to create a folder in your home folder, call it 'settings' or 'dots' or similar. Inside that folder create a folder called sublime. And make symbolic links inside that folder from your sublime-text-3 folder on Dropbox to the following files:

- sublime-text-3/Packages/User/Default (Linux).sublime-keymap
- sublime-text-3/Packages/User/Preferences.sublime-settings
- sublime-text-3/Packages/Default/Default (Linux).sublime-keymap
- sublime-text-3/Packages/Default/Preferences.sublime-settings

Name the links keymap, settings, keymap_default, settings_default.

Now you can add the sublime folder to your project for easy access to the setting files.

To add a folder to the project, choose `Add folder to project...` in the `Project` menu (`alt+p`). You can toggle the sidebar that shows your project files and folders with this hotkey: `ctrl+k+b` (hold control press `k` keep holding control and press `b`).

I know that you can open settings from the Preferences menu, but I am not so fond of this technique. It opens a new window with both the default and user version of the settings open and it just feels clunky. By adding the folder to the project you can just hit `ctrl+p` in sublime and search for the files.

Below is a simple tree showing the folder structure in a more graphical way:

``` shell
~ <- Home folder
.config
sublime-text-3 <- linked folder
dot
sublime
keymap <- this is a link
settings_default <- this is a link
Dropbox
sublime-text-3 <- original folder
Packages
User
Default (Linux).sublime-keymap
Default
Preferences.sublime-settings
```

configuration
-------------

First thing we want to do is enable and optimize Sublime for Vintage mode. Vintage enables basic VIM-like navigation. Open the settings file (if you followed the guide above, you can just hit `ctrl+p` and locate the settings file).

To enable vintage, remove it from the ignored packages setting.

**Before:**

``` shell
"ignored_packages":
[
"Vintage"
],
```

**After**:

`"ignored_packages":[],`

I also recommend you add this setting:
`"vintage_start_in_command_mode": true`

In your keymap file I recommend you add the following rules:

``` shell
{ "keys": ["alt+shift+k"], "command": "select_lines", "args": {"forward": false} },
{ "keys": ["alt+shift+j"], "command": "select_lines", "args": {"forward": true} },
{ "keys": ["ctrl+shift+k"], "command": "swap_line_up" },
{ "keys": ["ctrl+shift+j"], "command": "swap_line_down" },

{"keys": ["up"], "command": "pass", "context":
[ { "key": "setting.is_widget", "operand": false } ] },
{"keys": ["down"], "command": "pass", "context":
[ { "key": "setting.is_widget", "operand": false } ] },
{"keys": ["left"], "command": "pass", "context":
[ { "key": "setting.is_widget", "operand": false } ] },
{"keys": ["right"], "command": "pass", "context":
[ { "key": "setting.is_widget", "operand": false } ] },

{ "keys": ["j", "j"], "command": "exit_insert_mode",
"context":
[
{ "key": "setting.command_mode", "operand": false },
{ "key": "setting.is_widget", "operand": false }
]
}
```

With these settings, navigation with the arrow keys are disabled, forcing you to embrace VIM-navigation.

You can create multiple cursors with `alt+shift+j/k` and move lines with `ctrl+shift+j/k` to keep your fingers on the homerow.

The last rule, lets you 'Escape' insert_mode by typing `jj` instead of hitting that Escape key, so far from the homerow.

A even better way to have easy access to 'Escape' is to install `xcape` (`sudo apt install xcape`) and add this to your `~/.profile`:

``` shell
setxkbmap -option caps:ctrl_modifier
xcape -e 'Caps_Lock=Escape;Control_L=Escape;Control_R=Escape'
```

Now your control keys acts as `Escape` if they are pressed 'alone' and as a bonus your stupid CapsLock key is also a control key!

packages
--------

There is a lot of third-party-packages available to Sublime. The easiest way to manage packages is by using the unofficial package manager, `Package Control` i recommend you [install](https://packagecontrol.io/installation) that first.

When Package Control is installed you can install more packages inside sublime by choosing 'Package Control: Install Package' from the command palette (`ctrl+shift+p`).

But I recommend you check the packages homepage (most likely a github repo) before installing. Some packages might be abandoned or broken..

These are packages that I use and can recommend:

- [Clickable URLs](https://github.com/leonid-shevtsov/ClickableUrls_SublimeText)
- [iOpener](https://github.com/rosshemsley/iOpener)
- [File Rename](https://github.com/brianlow/FileRename)
- [Zen Tabs](https://github.com/travmik/ZenTabs)
- [AlignTab](https://github.com/randy3k/AlignTab)

files
-----

I have my Sublime [settings](/dots/sublime/settings) and [keymap](/dots/sublime/keymap) files on this site if you are interested, but i wouldn't recommend you just copy pasted them. There are many settings that are dependent on third-party-packages.

And as I mentioned at the beginning of this article, I have made a mashup of VIMtutor and Sublime Tutor, that I call [budtutor](link) which is a good way to learn and remember all commands and hotkeys.

+ 20
- 0
wiki/subl0_background.md View File

@@ -0,0 +1,20 @@
---
title: "mastering_sublime_1"
date: 2017-10-16T02:47:45+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: []
notes:
- "lnks: sublime"
---
I have been using [Sublime Text](link) for years. I was trying out lots of different text-editors and when I stumbled upon Sublime i bought a license after trying it for a week.

Back then I was on windows and I remember trying VIM which according to *the Internet*, was the king of editors. But I didn't get it back then. I blame the inconvenience of running it in the windows terminal.

VIM is a very potent editor, and the VI-bindings is imo the most powerful and efficient way to navigate and edit a text file.

But I don't want to give up on Sublime, especially when I have a license. And Sublime have many great features that VIM don't.

Luckily there are ways to get the best of two worlds. Sublime is shipped with a package(plug-in) called `Vintage`. Enabling the vintage package gives very basic VIM-functionality to Sublime.

+ 55
- 0
wiki/subl10_vintage_settings.md View File

@@ -0,0 +1,55 @@
---
title: "sublime_setup_vintage_settings"
date: 2017-10-23T20:12:38+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime","vim","vi","vintage"]
notes:
---
Just by enabling vintage, most of the VI-bindings works immediately. You can enter the different modes and use VI-navigation in command mode. But there are many core VI-bindings that aren't enabled by default. This is because they use the `Control` key as a modifier and overwrite lots of classic Sublime hotkeys.

To VI or not to VI?
-------------------
We now have to make a hard decision. We can choose not to enable the VI-bindings that use ctrl keys. By doing so we will loose a lot of the good stuff from VI but retain the classic sublime hotkeys that we have learned and learned to love.

Or enabling them and have a much more true VI-experience and by embracing them we will be very efficient if we ever have to use VI or Vim or one of the [many other programs](link to vim apps) that uses VI-navigation.

I think you know which option i recommend. But if you are a hardcore long-time user of sublime and have all of it's hotkeys in the muscle memory, I understand if you chose the first option.

I am a hardcore long-time user of sublime, myself, but I think it's a no-brainer that the second option is the way to go. For these two reasons:

1. Sublime will behave like all other programs I use with VI-bindings (this was the reason i enabled Vintage in the first place.)

2. It is not a big thing to create new custom commands for the ones we lose when enabling VI-ctrl-bindings.

What breaks exactly?
--------------------
Here is a more or less complete table of what will happen if we enable VI-ctrl-bindings:

|**Key**|**Vintage Command**|**Sublime Command**|
|:-------|:--------------|:--------------|
|`ctrl+y`|Scroll 1 line down|redo_or_repeat|
|`ctrl+e`|Scroll 1 line up|slurp_find_string|
|`ctrl+f`|Page down|find in file|
|`ctrl+b`|Page up|build|
|`ctrl+u`|Half page up|soft_undo|
|`ctrl+d`|Half page down|find_under_expand|
|`ctrl+r`|redo_or_repeat|Goto symbol|
|`ctrl+w`|window manipulation|close tab|
|`ctrl+[`|escape|unindent|

Some of the overwritten commands are found from the command mode VI-bindings. These doesn't need to change imo. These are:

|**Key**|**Sublime Command**|**Replacement**|
|:-------|:--------------|:--------------|
|`ctrl+y`|redo_or_repeat|`ctrl+r`|
|`ctrl+f`|find in file|`/` in command mode|
|`ctrl+u`|soft_undo|`u` in command mode|

`ctrl+[` is only an alternative to using `escape` key. And this can safely be disabled, and we can retain the default unindent functionality. I will show you an even better alternative escape in a later article.

`ctrl+w` is a modifier in VIM to modify the window, in vintage it defaults to splitting the window in different ways. I have chosen to use `ctrl+w+ctrl+w` to the close tab command. However this isn't perfect, since the same combination in Vim is used to cycle windows.. This is vintage functionality that i can live without and the easiest thing would be to disable it. I will dedicate a whole article to window manipulation in sublime later.

This leaves us with four commands that needs re-assignment. And the solution to this is what the [next article](link) in this [series](link) will be about.

+ 77
- 0
wiki/subl11_fixing_vintage.md View File

@@ -0,0 +1,77 @@
---
title: "sublime_setup_fixing_vintage"
date: 2017-10-23T22:11:02+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime","vi","vim","vintage"]
notes:
---
This is a continuation of the [last article](link) about what breaks with Vi-ctrl-bindings enabled and how to fix it.

To keep full sublime functionality and have Vi-ctrl-bindings enabled, we need to re-assign these commands:

|**Key**|**Sublime Command**|
|:-------|:--------------|
|`ctrl+b`|build|
|`ctrl+r`|Goto symbol|
|`ctrl+e`|slurp_find_string|
|`ctrl+d`|find_under_expand|

All four are very powerful, and popular sublime commands.

*I might change these re-assignments. Much of the functionality we get in command mode duplicates default sublime commands, and those keys are now up for grabs.*

build
-----
To be honest I never use sublimes build function, when I have to build something i use the terminal. But i guess many people use this. When I look in the default `sublime.sublime-keymap` file, I see that the same command is also mapped to `F7`, an alternative could be `ctrl+shift+b`. I leave it to the builders.

Goto symbol
-----------
This is a command I use myself a lot. It opens a list of 'symbols'. A symbol is different things in different files. In bash scripts, function definitions are symbols. In markdown headers are symbol. This makes file navigation super smooth, and this is one of Sublimes flagship commands, and is even displayed on their [homepage](http://sublimetext.com).

My solution might sound stranger and more complicated then it really is, but here goes:

Remember the different modes in Vintage/Vi/Vim. One of these are called 'last line mode' and is enabled by hitting `:` in command mode. This mode is extremely powerful in Vim. In Vintage the only unique commands in 'last line mode' are `revert` and `save`. These commands are also available through hotkeys, and the mode is completely useless imo.

But 'last line mode' also gives us access many sublime commands, but not as many as the `command palette`. So I'm changing `:` to launch the `command palette` and give `ctrl+shift+p` to the 'Goto symbol' command.

slurp find string
-----------------
I didn't know about this command till I started researching for this article. But it is very useful. It puts the word under the cursor in the find field of the find panel, but without opening the panel or do any searching. Good bye, copy pasting stuff into that field!

The replacement for this will however be quite complicated. But I'm going to use the `F3` where find related commands (find next/prev/..) are found by default for slurping.

Find-next/prev can be achieved with `n`/`N` in command mode. But I feel i need to modify the behavior of the find command a bit for this to be smooth. I will dedicate a article just for this later in this series.

find under expand
-----------------
Last but **not** least we have this command. Some people might have this command and it's hotkey synonymous with Sublime Text. If you don't know what it does, try it!(hit it multiple times, when you have some selections, edit the text). This is also showcased on Sublime Texts [front page](http://sublimetext.com).

I don't have a good answer for the best hotkey replacement here. I have it on `ctrl+.` for the moment..

It will become to much text and code to show all the necessary changes needed on this homepage. Instead I suggest you look at my personal config files that are located in `dots/sublime` in the sidebar.

Ahh, I almost forgot ;), to enable Vi-ctrl-bindings, set this setting to true:
`"vintage_ctrl_keys": true,`.

I also just realized that one important change i have made from default Vintage is to enable the vi-ctrl-keys globally. Otherwise they only work in *command mode* and that drove me crazy.

To enable them globally one have to change,

**This:**

``` JSON
{ "keys": ["ctrl+y"], "command": "scroll_lines", "args": {"amount": 1.0 },
"context": [{"key": "setting.command_mode"}, {"key": "setting.vintage_ctrl_keys"}]
},
```

**To this:**

``` JSON
{ "keys": ["ctrl+y"], "command": "scroll_lines", "args": {"amount": 1.0 },
"context": [{ "key": "setting.vintage_ctrl_keys"}] },
```
For all hotkeys that have `setting.vintage_ctrl_keys`

+ 23
- 0
wiki/subl1_installation.md View File

@@ -0,0 +1,23 @@
---
title: "sublime_setup_installation"
date: 2017-10-23T09:38:43+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime","installation"]
notes:
---
This is the first in a little article series about my text editor of choice, [Sublime Text](link).

Sublime is proprietary software and a full license costs 80$, so it is a controversial choice. But I have less problem using and paying for this software then using, for example, "firefox".

And the two things you get when you purchase a license is:

- Every 10th time you save a file, a nagscreen pops up, reminding you that your copy is not registered. This will stop once you pay. (hint: i3, scratchpad)

- You can install and use the 'dev' builds which get updated much more often then the stable version.

Otherwise it is the exact same program. So if you just want to try it out go to: [sublimetext.com](http://sublimetext.com) and follow the installation instructions.

After installation, you can launch Sublime with the `subl` command.

+ 80
- 0
wiki/subl2_settings.md View File

@@ -0,0 +1,80 @@
---
title: "sublime_setup_settings"
date: 2017-10-23T10:01:40+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime","setup"]
notes:
---
Sublime is a very advanced, extendable and hackable text editor. This comes with a price (well in this case, two prices, since it cost dollars): The settings of the program can be a bit confusing and difficult to organize and maintain.

It doesn't help that the default UI for editing the settings in Sublime is completely messed up IMO.

[screenshot of settings UI]

I have found a good way to manage the settings, but it will require some more or less advanced moving of files.

step 1: create user setting files:
----------------------------------
Open the preferences menu and select `Settings`.
[screen shot of menu]
The stupid split settings window will appear, with the, read-only, default settings to the left. And your user settings to the right. The syntax is JSON for most setting files in sublime. Add a some kind of change to your user setting file and save it. (if you don't know what to change you just make a comment by prefixing a line with two slashes `// `). Close the settings window by hitting `ctrl+w`.

Now choose `Key Bindings` from the Preferences menu and do the same thing for these files. Also close this window with `ctrl+w` and then quit sublime with `ctrl+q`.

*It is important you close the setting windows before quitting sublime, otherwise you will have a empty split extra window the next time you launch sublime. Which is even more reason to follow this technique for settings management.*

step 2: locating the user setting files:
----------------------------------------
Sublime store it's settings like most programs inside the `.config` folder in your home folder. Your setting files are created at this location: `$HOME/.config/sublime-text-3/Packages/User`

It can be worth mentioning that if you delete the folder `sublime-text-3` from your `.config` folder, and launch sublime, it will create a new one with the default settings. You can also create *restore points* of a setup by making a copy of the current `sublime-text-3` , i recommend that you do that while following this guide, because it is not impossible things get messed up along the way.

I use [Dropbox](https://db.tt/eFkf49MZ) to be sure i have my files and settings backed up. And a very convenient way to sync sublime settings is to move the `sublime-text-3` folder to your Dropbox folder and then symlink it back to `.config`. I do this and if you do too, all further references to the `sublime-text-3` folder in this guide are referring to the folder on Dropbox, and not the link folder. This is important!

step 3: linking the user setting files:
---------------------------------------
As you might have guessed an alternative way to edit the settings are to open them from directly from `sublime-text-3/Packages/User` . However, there are some drawbacks in doing so:

1. The path to the files is too long for easy access.

2. The filenames are strange, and as we soon will see exactly the same as the default setting files.

3. If you made a symlink to Dropbox or similar, it will be hard to tell if you have opened the file from Dropbox or the .config folder.

All these might sound trivial, but trust me, the Sublime tab bar will clutter up and become totally messed up if we don't take care of this right away.

Create a new folder somewhere in your home folder. For example: `~/tmp/sublime-settings` . I will refer to this folder as `sublime-settings` throughout the guide.

Inside `sublime-settings` create two more folders called `settings` and `keys`.

Now make symbolic links of your user settings to these folders. And rename the links to:
`user.sublime-settings`
`user.sublime-keymap`

It is important that the links are symbolic soft links and not hard links or copies!

When you are done you should have something resembling this:

``` shell
~ <- Home folder
.config
sublime-text-3 <- symbolic link to Dropbox/sublime-text-3
Dropbox
sublime-text-3
Packages
User
Default (Linux).sublime-keymap
Preferences.sublime-settings
tmp
sublime-settings
settings
user.sublime-settings <- soft link
keys
user.sublime-keymap <- soft link

```

Now we just have to find the *Default* settings files. But to do so we need to install some third-party-packages. That deserves a guide on it's own.

+ 55
- 0
wiki/subl3_manage_packages.md View File

@@ -0,0 +1,55 @@
---
title: "sublime_setup_manage_packages"
date: 2017-10-23T10:57:08+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime"]
notes:
---
Sublime have a package-system to extend the functionality of the editor. It ships with a whole bunch of packages pre-installed, these packages are maintained by the Sublime developers.

But you can also install 3rd-party packages. The sourcecode for the packages is open and if you know how you can edit them, even the built-in ones.

The package manager for Sublime is called `Package Control`, it is not installed by default, let's do that first.

In sublime, hit the hotkey combination:
`ctrl+shift+p`
This opens the `Command Palette`, which is a list of almost all available commands in sublime. Search for the command `Install Package Control` and select it by hitting `Enter`. It will install in a couple of seconds and you will a window with information on how to use it will pop up.

Locating packages
-----------------

Packages can exist in three places, and it is good to know the differences between them. We have actually already viewed and used one package:
`sublime-text-3/Packages/User`
This folder, User, is a package. During your time with Sublime the folder `sublime-text-3/Packages` will be populated with more folders. Lets call these folders `user-packages` from now on.

Open the folder `sublime-text-3/Installed Packages` . If you installed Package Control, you should see a file called `Package Control.sublime-package` in this folder, maybe more files with the same extension. Package Control is a package in itself, and most installed packages goes to this folder as archives. They are actually normal `zip` files and one could extract them to view the source. I will refer to archived packages in this folder as: `installed-packages`.

The last location for packages is where the built-in packages are stored. You can find them in:
`/opt/sublime_text/Packages`
These are archived and named just as the `installed-packages`. I will refer to these packages as `built-in-packages`. The `built-in-package` containing the default setting files is called:
`Default.sublime-package`

package locations:

``` shell
/ <- root folder
opt
sublime_text
Packages <- built-in packages
home
USER <- your home folder
.config
sublime-text-3 <- link to Dropbox
Dropbox
sublime-text-3
Packages <- user packages
Installed Packages <- installed packages
```

--------

As I mentioned above, `.sublime-package` files are normal `zip` files and can be extracted with your default archiving application. But I strongly recommend you don't do that, there is a much safer and convenient way that I will describe in the [next article](link) in this [series](link).


+ 57
- 0
wiki/subl4_extracting_packages.md View File

@@ -0,0 +1,57 @@
---
title: "sublime_setup_extracting_packages"
date: 2017-10-23T11:38:03+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime"]
notes:
---
Before extracting packages I strongly recommend you do the following preparations:

1. Add package folders to project
---------------------------------
Open sublime and choose `Add Folder To Project...` from the Project menu (or the `command palette`(`ctr+shift+p`)). Add these two folders to your project:
`sublime-text-3/Packages`
`sublime-text-3/Installed Packages`

They should now be visible in the sublime sidebar. *you can toggle the sidebar with:* `ctrl+k+ctrl+b`

2. Install Extract Sublime Package
----------------------------------
Open the `command palette`(`ctr+shift+p`) and choose `Package Control: Install Package`. This will open a list of all available 3rd-party packages you can install. Search for `Extract Sublime Package` and select it to install it.

It will install in no time, you can see the progress in the statusbar at the bottom-left corner of the screen.

3. Extract all packages
-----------------------
When it is installed open the `command palette` again search for `Extract Sublime Package: Extract all packages` and select it. You will now be asked if you want to extract all packages, you want that. It will take a while (probably 10 seconds) and then you will get a warning from Package Control.

If you view the package folder in the sidebar, you can see that all installed and built-in packages are extracted to this folder.

No you should exit sublime (`ctrl+q`).

Package Hierarchy
=================
Packages has different priority depending on where they are located.

Extracted `user-packages` has the highest priority. And archived `built-in-packages` have the lowest priority.

This means that if a package is extracted to `sublime-text-3/Packages` the archived version(s) will be ignored.

The most important difference between an archived and extracted package is that the files inside an archive is read-only, the only ways to make changes to a file inside an archived package is to have a file with same name inside `sublime-text-3/Packages/User`. That file will be read instead of the one in the package. Or we could do as we just did, and extract the whole package to `sublime-text-3/Packages`.

Most of the `built-in` packages are best kept in their archived form and it is safe to remove the extracted packages we don't 'need'. And the warning we got from Package Control told us that we have to remove the extracted version of Package Control otherwise it will not work properly.

So delete all folders inside `sublime-text-3/Packages` except these:

`sublime-text-3/Packages/User`
`sublime-text-3/Packages/Default`
`sublime-text-3/Packages/Extract Sublime Packages`

*It's a good idea to make a backup of the `sublime-text-3` folder before you delete the extracted packages folders.*

*There might be folders that you don't want to delete if you are not following this guide with a fresh install, but all extracted packages that exist as a built in or installed archive, should be safe to remove.*

In the [next article](link) in this [series](link) i will describe the final step to get a better alternative to the default way of viewing and editing the settings.

+ 66
- 0
wiki/subl5_linking_defaults.md View File

@@ -0,0 +1,66 @@
---
title: "sublime_setup_linking_defaults"
date: 2017-10-23T12:26:53+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime"]
notes:
---
We finally have access to the default setting files, but to make sure we don't break stuff I recommend you follow these steps:

Remember that folder we created and stored soft links to our user settings in? Open that. (in the [article](link) I created it in `~/tmp/sublime-settings`).

Remember that the files in an extracted package is not read-only as their original archived versions. There are pro's and con's to this.. The advantage is obviously that we can edit them, and this is very good. Because otherwise it is really annoying to manually disable features we don't want from a package. The disadvantage is ofc that we might mess something up with the default functionality when we are editing the files. That is why I like to make copies of the original files before anything else. I found this way to be the best:

Inside both the `conf` and the `keys` folder create two folders called `default` and `original`. And now *copy* the file:
`sublime-text-3/Packages/Default/Default (Linux).sublime-keymap`
to
`sublime-settings/keys/original/OG_default.sublime-keymap`

Then make a *soft link* of the same file to:
`sublime-settings/keys/default/default.sublime-keymap`

Do the same with the file:
`sublime-text-3/Packages/Default/Preferences.sublime-settings`

*It is a good idea to change permissions of the OG_files to make sure they are ReadOnly. One way to achieve this is to run the following command on the files:* `chmod -w OG_FILE_NAME`

When you are done you should have a folder structure similar to this:

``` shell
~ <- Home folder
.config
sublime-text-3 <- symbolic link to Dropbox/sublime-text-3
Dropbox
sublime-text-3
Packages
User
Default (Linux).sublime-keymap
Preferences.sublime-settings
Default
Default (Linux).sublime-keymap
Preferences.sublime-settings
tmp
sublime-settings
settings
original
OG_default.sublime-settings <- copy, Read only
default
default.sublime-settings <- soft link
user.sublime-settings <- soft link
keys
original
OG_default.sublime-keymap <- copy, Read Only
default
default.sublime-keymap <- soft link
user.sublime-keymap <- soft link

```

Now you can open sublime and add the `sublime-settings` folder to your project. Then use the excellent built-in command `goto files`(`ctrl+p`). This will open a list of all files in your folder and you now have a very neat way to access your settings. The 'drawback' being that this folder needs to be in your project.

This might look like overdoing something simple as organizing the setting files for a program. But you will see later in this series that it is more or less necessary to do something like this when you install more and more advanced packages.

In the [next article](link) in this [series](link) I will install a simple but useful 3rd-party-package and make some changes to it's settings. And show you how to extract single packages instead of the whole bunch.

+ 157
- 0
wiki/subl6_install_packages.md View File

@@ -0,0 +1,157 @@
---
title: "sublime_setup_install_packages"
date: 2017-10-23T14:35:55+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime"]
notes:
---
We have already installed two packages, 'Package Control' and 'Extract Sublime Packages'. These two packages are essential for a successful package organization, and in this article I will show you why, and how.

Before we start installing more packages we should make a setting for the 'Extract Sublime Packages' package.

Remember we kept the extracted version of the package inside the `user-packages` folder. All packages installed with 'Package Control' comes with a, often very useful, `readme.md` file. Some packages gives you a way to view this file, (look in the menu `Preferences/Package Settings`), but most keep it in the archived version of the package. This is the main reason you should always extract new packages, so you can RTFM!

Open this file:
`sublime-text-3/Packages/Extract Sublime Package/readme.md`

Inside you are informed that you can add a setting that will let you extract a package when you open the archived version in sublime. We want this, to enable it add this to your `user.sublime-setting` inside your `sublime-settings` folder.

`"extract_sublime_package_ask_on_open": true`

Save the settings file to enable the new setting.

If the instructions above was a bit confusing, look at this folder representation:

``` shell
~ <- Home folder
.config
sublime-text-3 <- symbolic link to Dropbox/sublime-text-3
Dropbox
sublime-text-3
Packages
User
Preferences.sublime-settings
Extract Sublime Package
readme.md <- find the setting in this file

tmp
sublime-settings
user.sublime-settings <- soft link, add the setting to this file.

```

*If the readme.md contains a lot of stuff you want to have easier access to, I recommend making a **copy** of the readme.md to:*
`sublime-settings/doc/ExtractSublimePackage.md`

-------

clickable URLs
--------------
Now we are prepared to install some more packages, lets start with a basic but very handy package that let us open URLs in files, in a convenient way.

*The readme.md files most often contain links that can be very interesting to visit to be able to understand and use the functionality provided by the package to the fullest.*

Open the `Command palette` and `Package Control: Install Packag`. Install the package: `Clickable URLs`.

Once it is installed you should see the archived version of it inside the `installed-packages` folder. Notice that you don't have it in extracted form in the `user-packages` folder. yet.

Open the archived version of 'Clickable URLs' in Sublime. (an easy way to do this is to just select the file from the project/sidebar). If the setting we added earlier you should get a dialog-window asking you if you want to extract the package. You want that.

[screenshot of dialog]

Now the package is extracted to the `user-packages` folder and we can look at the readme.md. This one has quite a lot of information and it tells you that the default hotkey to open a link in your browser is:
`ctrl+alt+Enter`, try this to see if it works.

I had to define my browser for it to work by adding this setting:

``` json
{
"clickable_urls_browser": "/usr/bin/surf %s &"
}
```

But this package, and many others, doesn't read the preferences from your normal user file, but from it's own user file, located at: `/sublime-text-3/Packages/User/ClickableUrls.sublime-settings` ...

If this file doesn't exist in your folder, you can create it by opening this menu: `Preferences/Package Settings/Clickable URLs/Settings - User`.

Open the file and add the setting, save it and then make a symlink to it inside `sublime-settings/settings`.

Test it's functionality now when the browser is set (place the cursor on a url and hit `ctrl+alt+Enter`), if the link doesn't open in your browser, you have not made the correct settings, RTFM.

But we are not done with this simple package. The default Hotkey for 'Clickable URLs' `ctrl+alt+Enter` overwrites one of Sublimes default keybindings, one that I use from now and then.

This is another reason I have done this crazy settings system, to locate and fix problems like this easily. And more or less all of the 3rd-party packages overwrite keys in this same fashion.

First let's assign a custom hotkey to open URL's, luckily all user defined hotkeys are put in the same file, so open
`sublime-settings/keys/user.sublime-keymap`
and add this:

``` json
{ "keys": ["ctrl+enter"], "command": "open_url_under_cursor" }
```

Now we can open URLs with `ctrl+enter`.

*I know that `ctrl+enter` (open line) is probably an even more used hotkey for most users but we will soon enable VI-bindings and have same functionality with a single `o`*

But the default hotkey, `ctrl+alt+Enter`, for Clickable URLs is still active. There are two ways to fix this, none of them are perfectly clean. The first and easiest way is to find the `ctrl+alt+Enter` in the **default** sublime.keymap file, copy it and add it to the **user** sublime.keymap file. Doing so will result in this:

Sublime reads the default settings first and applies `ctrl+alt+Enter` to the open line command. Then it reads the package settings, which will overwrite the hotkey with the command to open urls. Lastly it reads the user settings which enables the default command to the hotkey.
This way is quite simple to do and works really well in this particular case. But sometimes (most of the times) 3rd-party packages comes with a lot of commands that one might want to disable, then this other way to do it is better suited:

Comment/remove the unwanted hotkeys from the packages default settings file. But remember, this only works if the package is extracted and you can get problems if you mess up default settings. (in this case it is however more or less safe to uncomment the key).

My recommendation is to always use the second method and in the same fashion we did with the built-in setting files.

After you have copied and linked the files you should have a file structure similar to this:

``` shell
~ <- Home folder
.config
sublime-text-3 <- symbolic link to Dropbox/sublime-text-3
Dropbox
sublime-text-3
Packages
User
ClickableUrls.sublime-settings
Preferences.sublime-settings
Default (Linux).sublime-keymap
Clickable URLs
Default (Linux).sublime-keymap
tmp
sublime-settings
settings
original
OG_default.sublime-settings <- copy, Read only
default
default.sublime-settings <- soft link
user.sublime-settings <- soft link
ClickableUrls.sublime-settings <- soft link, this is where we define the browser
keys
original
OG_default.sublime-keymap <- copy, Read Only
OG_ClickableUrls.sublime-keymap <- copy, Read Only
default
default.sublime-keymap <- soft link
ClickableUrls.sublime-keymap <- soft link to user-packages/Clickable Urls/Default (Linux).sublime-keymap, this is where the hotkey we want to disable is defined.
user.sublime-keymap <- soft link, this is where we define the custom hotkey
docs
ClickableUrls.md <- copy of ser-packages/Clickable Urls/readme.md
```

As you can see all keymap files have the same file names (`Default (Linux).sublime-keymap`), this makes it really hard to distinguish them and search for them if you don't create links with custom names. Notice that I copied the readme.md and renamed the copy for future reference. And made a read only copy of the original keymap file.

Now we can just open `sublime-settings/keys/default/ClickableUrls.sublime-keymap` and uncomment the hotkey.

I hope you get why we go to this length to manage the settings. I chose this 'Clickable URLs' packages to illustrate this, since it is such a simple package with only one setting and hotkey definition.

Below is a list of some really good small packages that I use and can recommend:

- [iOpener](https://github.com/rosshemsley/iOpener)
- [File Rename](https://github.com/brianlow/FileRename)
- [Zen Tabs](https://github.com/travmik/ZenTabs)

In the [next article](link) in this [series](link) I will show you how to define hotkeys for *hidden* commands.

+ 45
- 0
wiki/subl7_hidden_commands.md View File

@@ -0,0 +1,45 @@
---
title: "sublime_setup_hidden_commands"
date: 2017-10-23T17:06:10+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime"]
notes:
---
In this article I will describe how to find and use *hidden* commands.

I think it's obvious for most of you how to create custom hotkeys, you copy one from the default and paste it in the user settings file and change the key combination.

But there are some commands/actions that are not present in the `default.sublime-keymap` file. But there are ways to find them.

One way is to look in the files in the extracted packages. Open the folder `user-packages/Default` inside this folder you can see a file called:
`Default.sublime-commands`
Open this file. I think these are the commands available in the `command palette` by default. Some of these commands are not present in the `default.sublime-keymap` file for instance:

``` json
{ "caption": "View: Toggle Menu", "command": "toggle_menu" },
```

To add this command to a hotkey you could add this to `sublime-settings/keys/user.sublime-keymap` :

``` json
{ "keys": ["ctrl+alt+m"], "command": "toggle_menu" },
```

There is another really cool way to find these kind of commands by using the `sublime console`. Open the console from the menu: `View/Show Console`.

In the console, enter this command:
`sublime.log_commands(True)`

Now all commands you do will be printed to the console! Open the `command palette` and choose `View: Toggle Menu` (notice that the newly added hotkey is printed in the command palette next to the command!).

In the prompt you should see this line:
`command: toggle_menu`

And I think you understand how to translate it into a hotkey.

Its not a bad idea to create a file in `sublime-settings/docs` name it `hacks.md` or something, and make a small note with this prompt command for future reference.

In the [next article](link) in [this series](link) we will enable `Vintage` and add the power of 'VI' to sublime!

+ 47
- 0
wiki/subl8_enabling_vintage.md View File

@@ -0,0 +1,47 @@
---
title: "sublime_setup_enabling_vintage"
date: 2017-10-23T18:02:52+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime","vim","vi","vintage"]
notes:
---
Vintage is a package that ships with Sublime, so one doesn't need to download it or use `Package Control` to enable it. Vintage adds the same navigation as found in the, 40 year old (!!!), editor `VI`, often referred to as Vi/Vim-bindings/navigation.

Vim-bindings is a very powerful, different and advanced way to navigate and edit text. I will not go into any details how to use Vi-bindings, but you can find lots of good articles and reasons to use it on the web.

The best way to get familiar with VI-bindings is to install `vim` (`sudo apt install vim`) and then run `vimtutor` . This will start an interactive tutorial, do this tutorial, it's not long and you will have a very good idea of what the fuzz is about.

---

enable the vintage package
--------------------------
Open `user.sublime-settings` and remove `"Vintage"` from ignored packages. (You can also enable packages with `Package Control` from the `command palette`.)

Press `Escape` to enter 'command mode'.

vintage modes
-------------
There are three different modes available when `Vintage` is enabled, you can see which mode you are in in the bottom-left corner of the statusbar:

**command mode**: This might be referred to as vintage mode but it is not correct. This is the mode where you navigate or enter commands. To enter **command mode** press `Escape`

**insert mode**: This might be referred to as sublime/normal mode, and it is not too far off. The default behavior of insert mode when `vintage` is enabled is exactly as normal Sublime. There are many ways to enter **insert mode**, one is to press `i` when in **command mode**.

**visual mode**: Think of this mode as 'selection mode'. **visual mode** is entered when text is selected while in **command mode** or by pressing `v`.

**replace mode**: this mode is not supported with `Vintage` . **replace mode** is entered by pressing a capital `R` while in **command mode** in Vim.

**last line mode**: this mode is more or less not supported in `Vintage`. **last line mode** is entered by pressing `:` while in **command mode** in Vim or VI.

---

When using `Vintage` you should consider **command mode** as the normal/default mode. However sublime always starts in **insert mode**. To change this behavior add this to your settings:
`"vintage_start_in_command_mode": true`

---

`Vintage` makes, as you can see, a lot of breaking changes to the defaults of Sublime. To make the most of it, we should examine the vintage package. That's what the [next article](link) in this [series](link) will be about.


+ 52
- 0
wiki/subl9_extracting_vintage.md View File

@@ -0,0 +1,52 @@
---
title: "sublime_setup_extracting_vintage"
date: 2017-10-23T18:59:37+02:00
author: "budRich"
draft: true
type: "post"
target: "budlime/articles"
tags: ["sublime","vim","vi","vintage"]
notes:
---
The `Vintage` package is adds a lot of functionality and extra commands. To fully understand `Vintage` and make the most of it we need to extract the package.

locating the vintage package
----------------------------
since `Vintage` is a package that ships with Sublime it resides in the same location as the `Default` package. `/opt/sublime_text/Packages/Vintage.sublime-package`.

Open this file in sublime and accept the generous offer to extract the package. First thing to do is, as always, to look at the `README.TXT` file. I think I covered most of what the readme have to say in my [last article](link).

Next up you can open `Preferences.sublime-settings` . There are only three available settings and they can all be applied to `user.sublime-settings`. So it's not really necessary to link this file to `sublime-settings`, instead copy the settings to your `user.sublime-settings` file, even if you don't plan to change them. The comments in the file describe the purpose of the settings good enough. But one of the settings will break a lot of things if we don't make some extensive customization to the keymap files.

Lets start by making links and copies to the keymap file in our `sublime-settings` folder.

``` shell
/ <- root folder
opt
sublime_text
Packages
Vintage.sublime-package <- archived package
~ <- Home folder
.config
sublime-text-3 <- symbolic link of Dropbox/sublime-text-3
Dropbox
sublime-text-3
Packages
User
Vintage <- extracted package
README.TXT
Preferences.sublime-settings
Default.sublime-keymap
tmp
sublime-settings
settings
user.sublime-settings <- soft link, append the contents from Vintage/Default.sublime-settings here.
keys
original
OG_vintage.sublime-keymap <- copy of Vintage/Default.sublime-keymap
default
vintage.sublime-keymap <- soft link of Vintage/Default.sublime-keymap
user.sublime-keymap <- soft link
```

In the [next article](link) in this [series](link) we take a closer look on the Vintage settings and how they affect Sublime.

+ 49
- 0
wiki/sublime_and_git.md View File

@@ -0,0 +1,49 @@
---
title: "sublime_and_git"
banner: "sublime_and_git"
date: 2018-01-03T10:22:44+01:00
author: "budRich"
draft: true
type: "post"
tags: [sublime,blog]
notes:
---

I don't know why I haven't done this earlier, but I just got git and github integration working with sublime on Arch linux.

I am writing the steps to achieve it here for future reference.

## 1. Generate and add an ssh key for your github account.

Before following the guides on github below, i suggest you start the *ssh-agent*, preferably from your startup script (`~/.xinitrc`):

``` shell
eval "$(ssh-agent -s)"
```

Then follow the guides below:

https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account

## 2. make sure your remote is set to ssh, not https:

in `*/.git/config` change:
`https//github.com/username/repository.git` to:
`git@github.com:username/repository.git`.

To avoid this step in the future also clone projects with the latter URL method.

## 3. authenticate the ssh-key

execute the following command in a terminal:
`ssh -T git@github.com` and answer `yes` at the first prompt.

## 4. add dependencies

install **x11-ssh-askpass**, on arch it's available with **pacman** from the official package repositories:
`sudo pacman -S x11-ssh-askpass`

## 5. add package to sublime

Currently i am using the `git` that i installed with **package controll** in **sublime text 3**. No further settings where needed after the steps above where completed, and I guess it will make other similar git packages work as well.

+ 84
- 0
wiki/vintage_clipboard_history.md View File

@@ -0,0 +1,84 @@
---
title: vintage_clipboard_history
banner: vintage_clipboard_history
date: 2018-07-06T13:17:25+02:00
author: budRich
draft: true
type: post
tags: [sublime, vim]
changelog:
- 2018-07-06 - created
notes:
---

I just made some tweaks to sublime to make it support clipboard history when yanking and cutting with the `Vintage` (*VI-navigation*) package enabled.

By default you can hit `ctrl+k, ctrl+v` to display a pop-up menu with the clipboard history from the current sublime session. But there is no regular setting to support the *vintage register*. There is a setting that will always add anything yanked or deleted with vintage commands to the normal clipboard (and to the vintage register), and for the rest of this hack to work, that setting needs to set to true:

`"vintage_use_clipboard": true,`

I extracted the `Default` package (on my installation, located at: `/opt/sublime_text_3/Packages/Default.sublime-package`), where i found the file: `paste_from_history.py`, and by adding the code below to the `on_post_text_command` function i got my vintage clipboard in to the history:

``` python
if name == 'set_action' and re.search('^vi_(copy|delete).*', args["action"]):
g_clipboard_history.push_text(sublime.get_clipboard())
```

I figured out which commands and arguments to add by looking in the `vintage` keymap file. But this solution was not perfect. Sometimes it didn't really work, and it added the the previous clipboard instead of the latest (when using `yy`) .

So i found that i needed to populate the clipboard history from the Vintage package instead, i added one line to `set_registers` in `Vintage/Vintage.py` (*around line 850*):

``` python
if (use_sys_clipboard and register == '"') or (register in ('*', '+')):
sublime.set_clipboard(text)
view.run_command('add_to_clipboard')
```

And added the a command to `Default/paste_from_history.py`:

``` python
class AddToClipboard(sublime_plugin.TextCommand):
def run(self,arne):
g_clipboard_history.push_text(sublime.get_clipboard())
```


Lesser autists would probably be more then satisfied here, but there was one more thing that was nagging me. I try to avoid using the arrow keys as much as possible, but i couldn't figure out how to make `tab` a substitute for up-arrow in the pop-up. I have gotten it working in the quick-panel, and the quick panel also looks cooler, so i replaced the popup command with a quickpanel one in the same file as above (`paste_from_history.py`):

``` python
# provide paste choices
paste_list = g_clipboard_history.get()
keys = [x[0] for x in paste_list]
sublime.active_window().show_quick_panel(keys, lambda choice_index: self.paste_choice(choice_index))
# self.view.show_popup_menu(keys, lambda choice_index: self.paste_choice(choice_index))
```

Below are the relevant keybindings:

``` json
{ "keys": ["<"], "command": "paste_from_history",
"context": [{"key": "setting.command_mode"}]
},

{
"keys": ["tab"],
"command": "move",
"args": {"by": "lines", "forward": true},
"context": [
{ "key": "panel", "operator": false, "operand": "input_panel" },
{ "key": "setting.is_widget" },
]
},


{
"keys": ["shift+tab"],
"command": "move",
"args": {"by": "lines", "forward": false},
"context": [
{ "key": "setting.is_widget" }
]
},
```

I replaced the original `ctrl+k, ctrl+v` with `<`. I use a Swedish keyboard but with US layout enabled, so `<` is available both as `shift+,` and next to `z`. I prefer sublimes default indentation (`ctrl+[`), so this will work fine. The `input_panel` context on tab, is a hack to make tab behave as expected with the package `iOpener`...

Loading…
Cancel
Save