docs

tomtom · Nov 6, 2015 · b6b8fc4 · b6b8fc4
1 parent 19de255
commit b6b8fc4
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 90 deletions.
diff --git a/doc/trag.txt b/doc/trag.txt
@@ -28,9 +28,9 @@ First, define which files belong to your project. See
 will scan the files in the VCS. Maybe your project's source files are 
 already registered in your tags files, in which case those will be used.
 
-Secondly, use |:Trag| or |:Traggrep| to scan your project's files. You 
-can restrict searches to certain "kinds" like only variable definitions 
-or only function calls. See |trag-kinds| for details.
+Secondly, use |:Trag| to scan your project's files. You can restrict searches 
+to certain "kinds" like only variable definitions or only function calls. See 
+|trag-kinds| for details.
 
 You can also type <Leader>r# to search for the word under cursor (see 
 |g:trag_map_leader| and |TragInstallMap()| for details on maps). In 
@@ -53,6 +53,19 @@ of supported filetypes.
 
 NOTE: Some kinds are available only for a subset of known filetypes.
 
+Default maps:
+
+    <Leader>r# ... Trag the word under cursor
+    <Leader>r. ... :Trag command-line
+    <Leader>r+ ... Show quickfixlist via |:Tragcw|
+    <Leader>r* ... Edit a file from the files list, i.e. the list that would be 
+                   used if no "--file_sources" argument were passed to 
+                   |:Tragsearch|
+    <Leader>rx ... The same as `:Trag -l -i=x -x=i <cword><cr>`
+                   where x is a alphabetical letter that describes a kind in 
+                   |g:trag_kinds| and <cword> is the word under cursor.
+                   "-x=i" (exclude commented text) is only added if kind x is 
+                   in |g:trag_kinds_ignored_comments|.
 
 
 -----------------------------------------------------------------------
@@ -93,44 +106,21 @@ common base:
     fuzzy ... use a typo-tolerant regexp
     todo  ... TODO markers etc.
 
-Modifiers:
-    # ... escape a literal expression as regexp (place it somewhere in the 
-          kinds argument)
-
-Negation: -, ! ... negate/skip uninteresting lines.
-
-Positive (must match) and negative (must not match) patterns are joined 
-with "-" or "!". Positive and negative conditions must both be 
-satisfied. The positive regexp determines the speed of the operation. 
-I.e. trag first searches for matching lines and only then decides 
-whether to skip "bad" ones.
-
-    POSITIVE1,POSITIVE2a.POSITIVE2b...-NEGATIVE...
-
-Note: If you use negations, you should also give a positive kind (use . 
-as fallback). The use of negations causes trag to use it's own grep 
-procedure which is slightly slower than the standard vimgrep command.
-
 EXPERIMENTAL: Kinds can be joined as comma-separated list (OR) of 
 period-seprated list (CONTAIN). This may be unintuitive but that's the 
 way it is. Order in CONTAIN-patterns matters, i.e. w.i doesn't make too 
 much sense (a word that CONTAINs a comment, which could only be the word 
 itself) but i.w does (a comment that CONTAINs a word, which is quite 
 possible).
 
-The way this has done has changed from version 0.1 to 0.2 with the 
-effect that the current solution is less well tested. If you stumble 
-over wrong search result, please tell me about the problem. Most likely 
-it's a problem with the regexp not being properly updated.
+The available command-line options are documented in |:Tragsearch|. These 
+command-line options allow users to defined which lines should be matched.
 
 Example:
-    i   ... comment/ignored text that CONTAINs a word
-    i.w ... comment/ignored text that CONTAINs a word
-    l,r ... a word either on the left OR right hand side of an 
-            assignment
-    w-i ... word that is NOT contained in a comment
-    w-i,l,r ... word but NOT in assignments (left OR right hand) OR in 
-            comments
+    -i=l,r ...... a word either on the left OR right hand side of an 
+                  assignment
+    -x=i ........ match lines that are not comments
+    -i=w -x=i ... word that is NOT contained in a comment
 
 More examples:
     File contents: >
@@ -139,22 +129,22 @@ More examples:
         #3 let x = FooBar()
         #4 let x = Foo()
 <
-    :TRag * Foo
+    :TRag Foo
     => Find "Foo": 1-4
 
-    :TRag w Foo
+    :TRag -i=w Foo
     => Find the __w__ords "Foo": 1, 4
 
-    :TRag d Foo
+    :TRag -i=d Foo
     => Find __d__efinitions of "Foo": 1, 2
 
-    :TRag d.w Foo
+    :TRag -i=d.w Foo
     => Find __d__efinitions of the __w__ord "Foo": 1
 
-    :TRag f Foo
+    :TRag -i=f Foo
     => Find (__f__unction) calls of "Foo": 3, 4
 
-    :TRag f.w Foo
+    :TRag -i=f.w Foo
     => Find (__f__unction) calls of the __w__ord "Foo": 4
 
 
@@ -163,13 +153,7 @@ the following filetype(s) is somewhat above average:
     - ruby
     - vim
 
-Note: I'd appreciate if you sent me sophisticated kind definitions for 
-more filetypes so that I can include them in future releases.
-
-A kind is best defined using the |:TRagDefKind| command.
-
-If you want to run a command without kinds, use "*" or "." as 
-argument, whatever if more convenient to type on your keyboard.
+Use |:TRagDefKind| to define new kinds.
 
 See |trag#Grep()| for details of how to use this.
 
@@ -711,6 +695,8 @@ trag#Grep(args, ?replace=1, ?files=[], ?filetype='')
       KIND REGEXP
       KIND1,KIND2 REGEXP
 
+    DEPRECATED: Old syntax. Please use |trag#GrepWithArgs()| instead.
+
     If the variables [bg]:trag_rxf_{kind}_{&filetype} or 
     [bg]:trag_rxf_{kind} exist, these will be taken as format string (see 
     |printf()|) to format REGEXP.

diff --git a/etc/tpl_trag.txt b/etc/tpl_trag.txt
@@ -28,9 +28,9 @@ First, define which files belong to your project. See
 will scan the files in the VCS. Maybe your project's source files are 
 already registered in your tags files, in which case those will be used.
 
-Secondly, use |:Trag| or |:Traggrep| to scan your project's files. You 
-can restrict searches to certain "kinds" like only variable definitions 
-or only function calls. See |trag-kinds| for details.
+Secondly, use |:Trag| to scan your project's files. You can restrict searches 
+to certain "kinds" like only variable definitions or only function calls. See 
+|trag-kinds| for details.
 
 You can also type <Leader>r# to search for the word under cursor (see 
 |g:trag_map_leader| and |TragInstallMap()| for details on maps). In 
@@ -53,6 +53,19 @@ of supported filetypes.
 
 NOTE: Some kinds are available only for a subset of known filetypes.
 
+Default maps:
+
+    <Leader>r# ... Trag the word under cursor
+    <Leader>r. ... :Trag command-line
+    <Leader>r+ ... Show quickfixlist via |:Tragcw|
+    <Leader>r* ... Edit a file from the files list, i.e. the list that would be 
+                   used if no "--file_sources" argument were passed to 
+                   |:Tragsearch|
+    <Leader>rx ... The same as `:Trag -l -i=x -x=i <cword><cr>`
+                   where x is a alphabetical letter that describes a kind in 
+                   |g:trag_kinds| and <cword> is the word under cursor.
+                   "-x=i" (exclude commented text) is only added if kind x is 
+                   in |g:trag_kinds_ignored_comments|.
 
 
 -----------------------------------------------------------------------
@@ -93,44 +106,21 @@ common base:
     fuzzy ... use a typo-tolerant regexp
     todo  ... TODO markers etc.
 
-Modifiers:
-    # ... escape a literal expression as regexp (place it somewhere in the 
-          kinds argument)
-
-Negation: -, ! ... negate/skip uninteresting lines.
-
-Positive (must match) and negative (must not match) patterns are joined 
-with "-" or "!". Positive and negative conditions must both be 
-satisfied. The positive regexp determines the speed of the operation. 
-I.e. trag first searches for matching lines and only then decides 
-whether to skip "bad" ones.
-
-    POSITIVE1,POSITIVE2a.POSITIVE2b...-NEGATIVE...
-
-Note: If you use negations, you should also give a positive kind (use . 
-as fallback). The use of negations causes trag to use it's own grep 
-procedure which is slightly slower than the standard vimgrep command.
-
 EXPERIMENTAL: Kinds can be joined as comma-separated list (OR) of 
 period-seprated list (CONTAIN). This may be unintuitive but that's the 
 way it is. Order in CONTAIN-patterns matters, i.e. w.i doesn't make too 
 much sense (a word that CONTAINs a comment, which could only be the word 
 itself) but i.w does (a comment that CONTAINs a word, which is quite 
 possible).
 
-The way this has done has changed from version 0.1 to 0.2 with the 
-effect that the current solution is less well tested. If you stumble 
-over wrong search result, please tell me about the problem. Most likely 
-it's a problem with the regexp not being properly updated.
+The available command-line options are documented in |:Tragsearch|. These 
+command-line options allow users to defined which lines should be matched.
 
 Example:
-    i   ... comment/ignored text that CONTAINs a word
-    i.w ... comment/ignored text that CONTAINs a word
-    l,r ... a word either on the left OR right hand side of an 
-            assignment
-    w-i ... word that is NOT contained in a comment
-    w-i,l,r ... word but NOT in assignments (left OR right hand) OR in 
-            comments
+    -i=l,r ...... a word either on the left OR right hand side of an 
+                  assignment
+    -x=i ........ match lines that are not comments
+    -i=w -x=i ... word that is NOT contained in a comment
 
 More examples:
     File contents: >
@@ -139,22 +129,22 @@ More examples:
         #3 let x = FooBar()
         #4 let x = Foo()
 <
-    :TRag * Foo
+    :TRag Foo
     => Find "Foo": 1-4
 
-    :TRag w Foo
+    :TRag -i=w Foo
     => Find the __w__ords "Foo": 1, 4
 
-    :TRag d Foo
+    :TRag -i=d Foo
     => Find __d__efinitions of "Foo": 1, 2
 
-    :TRag d.w Foo
+    :TRag -i=d.w Foo
     => Find __d__efinitions of the __w__ord "Foo": 1
 
-    :TRag f Foo
+    :TRag -i=f Foo
     => Find (__f__unction) calls of "Foo": 3, 4
 
-    :TRag f.w Foo
+    :TRag -i=f.w Foo
     => Find (__f__unction) calls of the __w__ord "Foo": 4
 
 
@@ -163,13 +153,7 @@ the following filetype(s) is somewhat above average:
     - ruby
     - vim
 
-Note: I'd appreciate if you sent me sophisticated kind definitions for 
-more filetypes so that I can include them in future releases.
-
-A kind is best defined using the |:TRagDefKind| command.
-
-If you want to run a command without kinds, use "*" or "." as 
-argument, whatever if more convenient to type on your keyboard.
+Use |:TRagDefKind| to define new kinds.
 
 See |trag#Grep()| for details of how to use this.