Preview Readme

readme.md

@@ -1,7 +1,7 @@
 # TodoReview
-A SublimeText 3 plugin for reviewing todo (any other) comments within your code.
+A SublimeText 3 plugin for reviewing todo (and other) comments within your code.
 
-![ScreenShot](http://i.imgur.com/TjGKdEH.png)
+![ScreenShot](http://i.imgur.com/0kTJ3cU.png)
 
 **Check the issues for upcoming features**
 
@@ -14,7 +14,7 @@ This is a fork of [@robcowie's](https://github.com/robcowie) SublimeTodo. Unfort
 TodoReview is accessible on Package Control. If you do not have Package Control, follow these [instructions](https://sublime.wbond.net/installation) to install it, it's extremely useful. Once you have it installed, just bring up your command pallet, type in `Install Package` then, on the next prompt, `TodoReview` and you are set!
 
 #### Git Clone
-If you are forking this project, or for whatever reason do not want to use Package Control, you can install this package this old fashion way. First, figure out where your "Packages" directory is by going to "Preferences" -> "Browse Packages" - then just run git clone as normal.
+If you are forking this project, or for whatever reason do not want to use Package Control, you can install this package this old fashion way. First, figure out where your packages directory is by going to (Preferences -> Browse Packages) - then just run git clone as normal.
 
 
 # Usage
@@ -23,43 +23,43 @@ Simply open your Sublime Text 3 Command Pallet and find the `TodoReview: Project
 ## Navigating results
 Once the list is generated, as a swift coder, you must naturally want to navigate it with your keyboard, right? Well you are in luck!
 
-By pressing the `up` or `down` keys, you are able to swiftly navigate the results. If you are a VIM user, you can also use `j` and `k` respectably. You can also use `page up` or `page down` to skip 10 lines at a time. Once you have navigated to the result you want, simply press `enter` to open the result in a new tab, while going to the corresponding line. In the event you would like to clear your selection, you may do so by pressing `c`.
-
-You can also use your mouse, just press `alt` and double click on the result you would like to examine.
+By pressing the `up` or `down` keys, you are able to swiftly navigate the results. If you are a VIM user, you can also use `j` and `k` respectably. You can also use `page up` or `page down` to skip 10 lines at a time. Once you have navigated to the result you want, simply press `enter` to open the result in a new tab, while going to the corresponding line. You can also refresh the list at any time by pressing `r`, it uses the same arguments as the last search.
 
 ## Priorities
 New in 2.1.0, results are now fully indexed and sorted. You can now add something like `(0)` to anywhere in your todo's to assign a priority of `0`. This will work with any number up to 99. Todo's are then sorted with the lowest number first; all matches that don't have priorities will be assigned a priority of 100. Here is some example output:
 
 ```
-+ -------------------------------------------------------- +
-| TodoReview @ Monday 02/24/14 at 07:24PM                  |
-| 12 files scanned                                         |
-+ -------------------------------------------------------- +
-
-## TODO (21)
-1. testing.js:2 (0) Testing
-2. testing.js:3 (1) Testing
-3. another.js:1 Testing Again (2)
-4. testing.js:4 (99) Testing
-5. testing.js:5 No priority
+// Tuesday 09/30/14 at 10:46AM - 27 files in 0.16 secs
+
+## TODO (5)
+1. 3.0.0.txt:3   Press `r` to refresh! (1)
+2. readme.md:1   Take a screenshot
+3. readme.md:2   Document goodies
+4. 3.0.0.txt:1   Make sure @tags work
+5. 3.0.0.txt:2   Other [formatting] too
+
+## TEST (2)
+1. 3.0.0.txt:4   (2) Priorities work?
+2. 3.0.0.txt:5   Read from buffer
 ```
 
 ## Color Scheme
 You can tag tasks using something like `@tomorrow` or `@bug`. These are only example, anything following the `@` sign, before a space, will be highlighted accordingly. If you are like me, you also would like one more option, just in the event something really needs to stand out, perhaps a reference link, etc. You can also use `[Comment]` or `[Need To Test]` for another type of reference as needed. Unlike tags with the `@` sign, you can use spaces between brackets.
 
 The way that these are colored depends on your color scheme. It's been a pain point of sublime text for quite some time that plugins are unable to influence the color scheme without some manual edits. I use and would recommend the [Tomorrow Night](https://github.com/theymaybecoders/sublime-tomorrow-theme) color scheme. However, if you are not, here are the corresponding colors these tags will be:
 
-- **Titles** Same color as a *string*
-- **Line Numbers** Same color as a *function*
-- **Priority** same color as a *variable*
-- **Bracket Tags** same color as a *class*
-- **@ Tags** same color as a *keyword*
+- **Report Headers** are the same color as a *comment*
+- **Pattern Titles** are the same color as a *string*
+- **Line Numbers** are the same color as a *function*
+- **Priority** are the same color as a *variable*
+- **Bracket Tags** are the same color as a *class*
+- **@Tags** are the same color as a *keyword*
 
 These may change in the future, but for now, this is the best way of to handle highlighting differences.
 
 
 # Config
-Global configuration can be set within the standard package settings menu, however, this plugin also offers project specific settings. To override your global settings on a project basis, edit your `.sublime-project` file accordingly, more information on settings below:
+Global configuration can be set within the standard package settings menu (Preferences -> Package Settings -> TodoReview) however, this plugin also offers project specific settings. To override your global settings on a project basis, edit your `.sublime-project` file accordingly, more information on settings below:
 
 ```javascript
 {
@@ -82,11 +82,27 @@ You can use any RegExp pattern to search by, leaving a lot of room for customiza
 
 ```javascript
 "patterns": {
-    "TODO": "TODO[\\s]*?:+(?P<todo>.*)$",
-    "NOTE": "NOTE[\\s]*?:+(?P<note>.*)$",
-    "FIXME": "FIX ?ME[\\s]*?:+(?P<fixme>.*)$",
-    "CHANGED": "CHANGED[\\s]*?:+(?P<changed>.*)$"
+    "TODO": "TODO[\\s]*?:[\\s]*(?P<todo>.*)$",
+    "NOTE": "NOTE[\\s]*?:[\\s]*(?P<note>.*)$",
+    "FIXME": "FIX ?ME[\\s]*?:[\\s]*(?P<fixme>.*)$",
+    "CHANGED": "CHANGED[\\s]*?:[\\s]*(?P<changed>.*)$"
+}
+```
+
+## Comment pattern weight
+In case you want a non-alphabetical sort of the patterns, you can use the `patterns_weight` setting. There are some very important notes about this setting. Firstly, the key MUST be upper case, or the setting will not work. The key must also match the pattern named group. The value can be either a number or string, it is just evaluated as an alphabetical override. All patterns not mentioned will retain the same alphabetical weight versus the new values. Example:
+
+```javascript
+"patterns_weight": {
+	"NOTE": 3
+    "TEST": "z"
 }
+
+//Order:
+//Note
+//Fixme
+//Todo
+//Test
 ```
 
 ## Excluding files and folders
@@ -105,8 +121,8 @@ Additionally, if you would like to exclude individual files, you can base the ex
 
 ```javascript
 "exclude_files": [
-    "*.md",
-    "dontsearch.txt"
+    "*.sublime-workspace",
+    "*.sublime-project"
 ]
 ```
 
@@ -135,12 +151,25 @@ If you have a large project with repeating file names, it is sometimes useful to
 ```
 
 ## Align results
-If you have OCD and like things to be nicely aligned, I've included a spaces option just for you. You can set the number of spaces you would like between the line start and notes. If you usually have large filenames, it will require more spaces for your notes to be aligned and vice versa. This defaults to `1`.
+TodoReview now automatically aligns the comments for you, calculating the largest result and aligning the rest accordingly. The system default for maximum spaces is `50`, which prevents a single file with an abnormally long length completely ruining your results. You can change this setting by editing `render_maxspaces`
 
 ```javascript
-"render_spaces": 10
+"render_maxspaces": 100
 ```
 
+## Report Header
+if you ever feel the overwhelming urge to either remove or edit the standard report header, you can now do so by editing `render_header_format` and `render_header_date`. Both use standard regex replacement to create the report header. Setting the `render_header_format` to a blank string will completely remove the header all together. Example:
+
+```javascript
+"render_header_format": "%d - %c files in %t secs",
+"render_header_date": "%A %m/%d/%y at %I:%M%p"
+```
+
+- **%d** is the formatted date string
+- **%c** is the total file count
+- **%t** is the total time count
+- The date formatting can be found on the [Python Documentation](https://docs.python.org/2/library/datetime.html)
+
 ## Custom Skip Lines
 If you would like to skip more (or less) than 10 lines at a time when using `page up` or `page down`, we have a setting for you! These defaults to `10`.
 
@@ -149,16 +178,12 @@ If you would like to skip more (or less) than 10 lines at a time when using `pag
 "navigation_backward_skip": 10
 ```
 
-## Keyboard Shortcuts And Other Actions
-I didn't provide a standard key bind with TodoReview due to the high likelyhood of confliction with other plugins. If you would like a shortcut, you can add the following snippit to your ST3 User Key Bindings (under the preference menu). In addition to keybinds, you can create custom sidebar, pallet, mouse, etc. commands using this same syntax; for more information, check out the SublimeText documentation. You can play around with the arguments that you would like, it currently accepts `paths`, `open_files` and `open_files_only`.
+# Arguments
+The TodoReview search engine takes a number of arguments to better find what you are looking for. These are automatically generated on a number of sugar functions, such as using the sidebar or command pallet, but you can also create your own keybinds to utilize them.
 
-```javascript
-{
-	"keys": [ "ctrl+shift+t" ],
-	"command": "todo_review",
-	"args": { "paths": [], "open_files": true }
-},
-```
+- **`paths`** - An array of paths to search
+- **`open_files`** - boolean to include open files
+- **`open_files_only`** - boolean to restrict search to open files
 
 
 # License