tagsearch.txt

MSYS在windows下模拟了一个类unix的终端

							*:ptn* *:ptnext*
:[count]ptn[ext][!]	":tnext" in the preview window.  See |:ptag|.
			{not in Vi}

							*:ptp* *:ptprevious*
:[count]ptp[revious][!]	":tprevious" in the preview window.  See |:ptag|.
			{not in Vi}

							*:ptN* *:ptNext*
:[count]ptN[ext][!]	Same as ":ptprevious".  {not in Vi}

							*:ptr* *:ptrewind*
:[count]ptr[ewind][!]	":trewind" in the preview window.  See |:ptag|.
			{not in Vi}

							*:ptl* *:ptlast*
:ptl[ast][!]		":tlast" in the preview window.  See |:ptag|.
			{not in Vi}

==============================================================================
4. Tags details						*tag-details*

							*static-tag*
A static tag is a tag that is defined for a specific file.  In a C program
this could be a static function.

In Vi jumping to a tag sets the current search pattern.  This means that
the "n" command after jumping to a tag does not search for the same pattern
that it did before jumping to the tag.  Vim does not do this as we consider it
to be a bug.  You can still find the tag search pattern in the search history.
If you really want the old Vi behaviour, set the 't' flag in 'cpoptions'.

							*tag-binary-search*
Vim uses binary searching in the tags file to find the desired tag quickly
(when enabled at compile time |+tag_binary|).  But this only works if the
tags file was sorted on ASCII byte value.  Therefore, if no match was found,
another try is done with a linear search.  If you only want the linear search,
reset the 'tagbsearch' option.  Or better: Sort the tags file!

Note that the binary searching is disabled when not looking for a tag with a
specific name.  This happens when ignoring case and when a regular expression
is used that doesn't start with a fixed string.  Tag searching can be a lot
slower then.

							*tag-regexp*
The ":tag" and "tselect" commands accept a regular expression argument.  See
|pattern| for the special characters that can be used.
When the argument starts with '/', it is used as a pattern.  If the argument
does not start with '/', it is taken literally, as a full tag name.
Examples:
>    :tag main
  jumps to the tag "main" that has the highest priority.
>    :tag /^get
  jumps to the tag that starts with "get" and has the highest priority.
>    :tag /norm
  lists all the tags that contain "norm", including "id_norm".
When the argument both exists literally, and match when used as a regexp, a
literal match has a higher priority.  For example, ":tag /open" matches "open"
before "open_file" and "file_open".

							*tag-!*
If the tag is in the current file this will always work.  Otherwise the
performed actions depend on whether the current file was changed, whether a !
is added to the command and on the 'autowrite' option:

  tag in       file	   autowrite			~
current file  changed	!   option	  action	~
-----------------------------------------------------------------------------
    yes		 x	x     x	  goto tag
    no		 no	x     x	  read other file, goto tag
    no		yes    yes    x   abandon current file, read other file, goto
				  tag
    no		yes	no    on  write current file, read other file, goto
				  tag
    no		yes	no   off  fail
-----------------------------------------------------------------------------

- If the tag is in the current file, the command will always work.
- If the tag is in another file and the current file was not changed, the
  other file will be made the current file and read into the buffer.
- If the tag is in another file, the current file was changed and a ! is
  added to the command, the changes to the current file are lost, the other
  file will be made the current file and read into the buffer.
- If the tag is in another file, the current file was changed and the
  'autowrite' option is on, the current file will be written, the other
  file will be made the current file and read into the buffer.
- If the tag is in another file, the current file was changed and the
  'autowrite' option is off, the command will fail.  If you want to save
  the changes, use the ":w" command and then use ":tag" without an argument.
  This works because the tag is put on the stack anyway.  If you want to lose
  the changes you can use the ":tag!" command.

							*tag-security*
Note that Vim forbids some commands, for security reasons.  This works like
using the 'secure' option for exrc/vimrc files in the current directory.  See
|trojan-horse|.
When the {tagaddress} changes a buffer, you will get a warning message:
	"WARNING: tag command changed a buffer!!!"
In a future version changing the buffer will be impossible.  All this for
security reasons: Somebody might hide a nasty command in the tags file, which
would otherwise go unnoticed.  Example:
>	:$d|/tag-function-name/
{this security prevention is not present in Vi}.

In Vi the ":tag" command sets the last search pattern when the tag is searched
for.  In Vim this is not done, the previous search pattern is still remembered,
unless the 't' flag is present in 'cpoptions'.  The search pattern is always
put in the search history, so you can modify it if searching fails.

						*emacs-tags* *emacs_tags*
Emacs style tag files are only supported if Vim was compiled with the
|+emacs_tags| feature enabled.  Sorry, there is no explanation about Emacs tag
files here, it is only supported for backwards compatibility :-).

							*tags-option*
The 'tags' option is a list of file names.  Each of these files is searched
for the tag.  This can be used to use a different tags file than the default
file "tags".  It can also be used to access a common tags file.

The next file in the list is not used when:
- A matching static tag for the current buffer has been found.
- A matching global tag has been found.
This also depends on the 'ignorecase' option.  If it is off, and the tags file
only has a match without matching case, the next tags file is searched for a
match with matching case.  If no tag with matching case is found, the first
match without matching case is used.  If 'ignorecase' is on, and a matching
global tag with or without matching case is found, this one is used, no
further tags files are searched.

When a tag file name starts with "./", the '.' is replaced with the path of
the current file.  This makes it possible to use a tags file in the directory
where the current file is (no matter what the current directory is).  The idea
of using "./" is that you can define which tag file is searched first: In the
current directory ("tags,./tags") or in the directory of the current file
("./tags,tags").

For example:
>	:set tags=./tags,tags,/home/user/commontags

In this example the tag will first be searched for in the file "tags" in the
directory where the current file is.  Next the "tags" file in the current
directory.  If it is not found there, then the file "/home/user/commontags"
will be searched for the tag.

This can be switched off by including the 'd' flag in 'cpoptions', to make
it Vi compatible.  "./tags" will than be the tags file in the current
directory, instead of the tags file in the directory where the current file
is.

Instead of the comma a space may be used.  Then a backslash is required for
the space to be included in the string option:
>	:set tags=tags\ /home/user/commontags

To include a space in a file name use three backslashes.  To include a comma
in a file name use two backslashes.  For example, use:
>	:set tags=tag\\\ file,/home/user/common\\,tags

for the files "tag file" and "/home/user/common,tags".  The 'tags' option will
have the value "tag\ file,/home/user/common\,tags".

If the 'tagrelative' option is on (which is the default) and using a tag file
in another directory, file names in that tag file are relative to the
directory where the tag file is.

==============================================================================
5. Tags file format					*tags-file-format*

						*ctags* *jtags*
A tags file can be created with an external command, for example "ctags".  It
will contain a tag for each function.  Some versions of "ctags" will also make
a tag for each "#defined" macro, typedefs, enums, etc.

Some programs that generate tags files:
ctags			As found on most Unix systems.  Only supports C.  Only
			does the basic work.
exuberant ctags		Found at http://ctags.sf.net.  This a very good one.
			It works for C, C++, Java, Fortran and other
			languages.  It can generate tags for many items.
etags			Connected to Emacs.  Supports many languages.
JTags			For Java, in Java.  It can be found at
			http://www.fleiner.com/jtags/.
ptags.py		For Python, in Python.  Found in your Python source
			directory at Tools/scripts/ptags.py.

The lines in the tags file must have one of these three formats:

1.  {tagname}		{TAB} {tagfile} {TAB} {tagaddress}
2.  {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
3.  {tagname}		{TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..

The first is a normal tag, which is completely compatible with Vi.  It is the
only format produced by traditional ctags implementations.  This is often used
for functions that are global, also referenced in other files.

The lines in the tags file can end in <LF> or <CR><LF>.  On the Macintosh <CR>
probably also works (this depends on the fgets() function).  The <CR> and <NL>
characters can never appear inside a line.

							*tag-old-static*
The second format is for a static tag only.  It is obsolete now, replaced by
the third format.  It is only supported by Elvis 1.x and Vim and a few
versions of ctags.  A static tag is often used for functions that are local,
only referenced in the file {tagfile}.  Note that for the static tag, the two
occurrences of {tagfile} must be exactly the same.  Also see |tags-option|
below, for how static tags are used.

The third format is new.  It includes additional information in optional
fields at the end of each line.  It is backwards compatible with Vi.  It is
only supported by new versions of ctags (like Exuberant ctags).

{tagname}	The identifier.  Normally the name of a function, but it can
		be any identifier.  It cannot contain a <Tab>.
{TAB}		One <Tab> character.  Note: previous versions allowed any
		white space here.  This has been abandoned to allow spaces in
		{tagfile}.  It can be re-enabled by including the
		|+tag_any_white| feature at compile time. *tag-any-white*
{tagfile}	The file that contains the definition of {tagname}.  It can
		have an absolute or relative path.  It may contain environment
		variables and wildcards (although the use of wildcards is
		doubtful).  It cannot contain a <Tab>.
{tagaddress}	The Ex command that positions the cursor on the tag.  It can
		be any Ex command, although restrictions apply (see
		|tag-security|).  Posix only allows line numbers and search
		commands, which are mostly used.
{term}		;" The two characters semicolon and double quote.  This is
		interpreted by Vi as the start of a comment, which makes the
		following be ignored.  This is only for backwards
		compatibility with Vi.
{field} ..	A list of optional fields.  Each field has the form:

			<Tab>{fieldname}:{value}

		The {fieldname} identifies the field, and can only contain
		alphabetical characters [a-zA-Z].
		The {value} is any string, but cannot contain a <Tab>.
		These characters are special:
			"\t" stands for a <Tab>
			"\r" stands for a <CR>
			"\n" stands for a <NL>
			"\\" stands for a single '\' character

		There is one field that doesn't have a ':'.  This is the kind
		of the tag.  It is handled like it was preceded with "kind:".
		See the documentation of ctags for the kinds it produces.

		The only other field currently recognized by Vim is "file:"
		(with an empty value).  It is used for a static tag.

The first lines in the tags file can contain lines that start with
	!_TAG_
These are sorted to the first lines, only rare tags that start with "!" can
sort to before them.  Vim only recognizes the line that indicates if the file
was sorted.  When this line is found, Vim uses binary searching for the tags
file:
>	!_TAG_FILE_SORTED<Tab>1

							*tag-search*
The command can be any Ex command, but often it is a search command.
Examples:
>	tag1	file1	/^main(argc, argv)/
>	tag2	file2	108

The command is always executed with 'magic' not set.  The only special
characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>).
See |pattern|.  Note that you must put a backslash before each backslash in
the search text.  This is for backwards compatibility with Vi.

If the command is a normal search command (it starts and ends with "/" or
"?"), some special handling is done:
- Searching starts on line 1 of the file.
  The direction of the search is forward for "/", backward for "?".
  Note that 'wrapscan' does not matter, the whole file is always searched. {Vi