update and clean up README for 2.0

add settings upgrade guide settings are explained in the default settings file, the text in the readme is superfluous and risks getting outdated
aziz · Sep 15, 2020 · 9101fbb · 9101fbb
1 parent 2530d9a
commit 9101fbb
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 92 deletions.
diff --git a/README.md b/README.md
@@ -4,33 +4,19 @@ The missing part of `Go to definition` functionality in Sublime.
 
 ![sublime hyperclick](https://cloud.githubusercontent.com/assets/3202/19578519/51558bb4-971c-11e6-8ef2-d256da53d1da.gif)
 
-When you are navigating and reading a codebase, you need to jump between required/imported/included files.
-
-HyperClick detects references to these files and lets you jump right to them, by pressing a key or clicking on an icon next to the filename.
-
-Unlike Sublime Text's `Goto Definition`, HyperClick knows some specifics of the languages it supports, so even package names and filenames without an extension can be detected.
+HyperClick detects references to other files and lets you go to them, by pressing a key or clicking on an icon next to the filename. Even package names and filenames without an extension can be detected.
 
 ## Supported Languages
 
-- JavaScript
-- TypeScript
-- Vue components
-- Svelte components
-- CSS
-- Sass and SCSS
-- LESS
-- Stylus
+- JavaScript, TypeScript
+- Vue, Svelte components
+- CSS, Sass, SCSS, LESS, Stylus
 - HTML
 - PHP
-- Twig
-- Pug
-- Nunjucks
+- Twig, Smarty, Pug, Nunjucks, Jinja2
 - JSTL
-- Jinja2
 - Dart
-- PostCSS
-- SugarML
-- SugarSS
+- SugarML, SugarSS
 
 If you'd like to request another language, [open an issue](https://github.com/aziz/SublimeHyperClick/issues) with an example project in that language.
 
@@ -41,112 +27,91 @@ You can install HyperClick via [Sublime Package Control](https://packagecontrol.
 
 HyperClick gives you three different ways to navigate:
 
-### 1. Green arrows to the right of _imports_
-In Sublime Text 3, you can jump to the file by clicking the arrow to the right of the filename.
+### 1. Green arrows to the right of paths
+In Sublime Text 3, you can "Go to file" by clicking the arrow to the right of the filename.
 
 This arrow shows up when you **hover your mouse cursor** or **move to the line** (with up/down keys, or Goto Line) that contains the filename.
 
 ### 2. Context Menu
-If you right click on a required/imported line you'll get a `Jump To Source File ➜` menu item on the context menu.
-
-<img width="748" alt="sublimehyperclickcontext" src="https://cloud.githubusercontent.com/assets/3202/19578923/480cacde-971e-11e6-9504-91c26737c486.png">
+If you right click on a required/imported line you'll get a `Goto File` menu item on the context menu.
 
 ### 3. Shortcut key
-By default, HyperClick uses <kbd>F12</kbd> (Sublime's default `Go to definition`) shortcut.
-
-This does not override the default functionality since it's only using it in contexts that Sublime's own `Go to definition` cannot help you navigate.
-
-You can still customize the shortcut by adding this code to your own key-binding settings.
+HyperClick extends the use of the <kbd>F12</kbd> (`Go to definition`) shortcut, jumping to files when `Go to definition` doesn't work.
 
-```json
-{
-    "keys": ["f12"],
-    "command": "hyper_click_jump",
-    "context": [{ "key": "hyper_click_jump_line", "operand": true }]
-}
-```
 
 ## Settings
 You can customize HyperClick settings by going to
 `Preferences > Package Settings > HyperClick > Settings`
 
-#### Disable Annotations (phantom arrow button)
-If you don't like the arrow button, you can disable it by setting `annotations_enabled` to `false`
-
-#### Change Annotations contents
-HyperClick uses a greenish button with `➜` when it finds the destination file and a reddish button with `✘`. These symbols can be customized too.
-
-```json
-{
-  "annotation_found_text": "➜",
-  "annotation_not_found_text": "✘"
-}
-```
-
-#### Default Settings
-See [hyper_click.sublime-settings](https://github.com/aziz/SublimeHyperClick/blob/master/hyper_click.sublime-settings) for up to date settings.
-
-## Project settings
+### Project settings
 
-Some languages and build tools let developers reference files without writing out the full path to the file.
+You can use [project settings](https://www.sublimetext.com/docs/3/projects.html) to configure HyperClick to look for files at specific dirs, through the settings `"lookup_paths"` and `"aliases"`.
 
-You can use [project settings](https://www.sublimetext.com/docs/3/projects.html) to configure HyperClick to look for files at specific dirs, though the settings `"lookup_paths"` and `"aliases"`.
+To open the project settings file, go to `Project > Settings`. If the `Settings` option is grayed out, choose the option `Save Project As...` (right above it) to save it to disk. The `Settings` option can now be clicked.
 
-To open the project settings file, go to `Project > Settings`.
-
-If the `Settings` option is grayed out, choose the option `Save Project As...` (right above it) to save it to disk. The `Settings` option can now be clicked.
-
-### Project settings example
+#### Example
 
 ```json
 {
 	"folders":
 	[
 		{
-			"path": "/computer/jane/projects/a-great-app"
+			"path": "development/project"
 		}
 	],
 	"settings": {
 		"hyper_click": {
-			"aliases": {
-				"js": {
-					"@": "src"
+			"scopes": {
+				"source.sass": {
+					"lookup_paths": [
+						"assets/css/src/",
+						"assets/css/lib/"
+					]
+				},
+				"text.html.smarty": {
+					"lookup_paths": [
+						"views/templates/"
+					]
 				}
-			},
-			"lookup_paths": {
-				"twig": [
-					"templates"
-				]
 			}
 		}
 	}
 }
 ```
 
-### Lookup paths
-
-When an imported file can't be found inside the same directory as the file, HyperClick will search inside the directories set in `"lookup_paths"`.
+### Upgrading settings for 2.0
 
-### Aliases
+In 2.0 the settings structure was inverted, and no longer relies on syntax filename mapping. 
+Each language is supported via an entry in the "scopes" object, by the language ["scope"](https://www.sublimetext.com/docs/3/scope_naming.html) name. 
 
-An alias is a character or word at the start of the filename that maps to a fixed directory location inside the project.
-
-Here's an example: by default, [vue-cli](https://cli.vuejs.org) uses `@` as an alias to the directory `src` inside the project. When you write
-```js
-import Toolbar from '@/components/Toolbar';
-```
+To upgrade your settings, the first step is to rearrange the settings to this new structure. Then:
 
-HyperClick will recognize it as the file `src/components/Toolbar.vue` in your project.
+- Remove now unused settings "supported_syntaxes", "default_filenames".
+- Rename "import_line_regex" to "regexes" and "valid_extensions" to "extensions".
+- Other settings are unchanged.
 
-Tools that support aliases:
-
-- [Webpack](https://webpack.js.org/configuration/resolve/#resolvealias)
-- [vue-cli](https://cli.vuejs.org/guide/html-and-static-assets.html#url-transform-rules) comes with `@` aliased to `src` by default
-- [Rollup](https://github.com/rollup/plugins/tree/master/packages/alias)
-- [Parcel](https://parceljs.org/module_resolution.html#aliases)
+Example:
 
+```json
+{
+	"import_line_regex": {
+	    "js": [
+	        "^import\\s+['\"](.+)['\"];?$"
+	    ]
+	}
+}
+```
 
-## License
-Copyright 2016-2017 [Allen Bargi](https://twitter.com/aziz).
+Becomes:
 
-Licensed under the MIT License
+```json
+{
+	"scopes": {
+		"source.js": {
+			"regexes": [
+				"^import\\s+['\"](.+)['\"];?$"
+			]
+		}
+	}
+}
+```
diff --git a/messages/2.0.0.txt b/messages/2.0.0.txt
@@ -8,6 +8,6 @@ HyperClick has been rebuilt to be both simpler and more flexible:
   packages for any language.
 - Settings were restructured to be easier to extend and modify.
 
-This might mean you need to update your (project-) settings.
+This means you might need to update your (project-) settings.
 Please read this explainer to help you do so:
-https://...
+https://github.com/aziz/SublimeHyperClick/blob/master/README.md#upgrading-settings-for-20