Permalink
Browse files

Version 5.1

5.0
Replaced use of preview window with a named buffer.
Moved to github.
Added documentation.

5.1
Added two APIs for serving other plugins:
SrcExpl_GetWin(), getting the Source Explorer window number for those plugins based on multiple windows.
SrcExpl_GetVer(), getting the Source Explorer version for the forward compatibility.
Added debug/logging functions for the internal development.
  • Loading branch information...
1 parent e69d694 commit 87620e1cca1bf90daeb0b31fa66f412d974d676c @wesleyche wesleyche committed with Sep 20, 2012
Showing with 676 additions and 234 deletions.
  1. +6 −1 README
  2. +327 −0 doc/srcexpl.txt
  3. +343 −233 plugin/srcexpl.vim
View
7 README
@@ -1,5 +1,11 @@
This is a mirror of http://www.vim.org/scripts/script.php?script_id=2179
+[GitHub]
+
+The latest dev version of Source Explorer and screenshots can be downloaded from GitHub Homepage:
+
+https://github.com/wesleyche/SrcExpl
+
[Introduction]
The plugin (srcexpl.vim) is a source code explorer based on tags and it provides an overview of the function and type definitions.It has such a mechannism that works like the context window component of "Source Insight" software.
@@ -68,4 +74,3 @@ b\ As soon as the definition of the word is displayed on the preview window, we
c\ Type the SrcExpl_jumpKey(<ENTER> as default) to jump to the exact context of its definition.
d\ Type the SrcExpl_gobackKey(<SPACE> as default) to go back to the previous position of the symbol word.
-There are some screenshots on the website: http://srcexpl.blogspot.com/
View
@@ -0,0 +1,327 @@
+*srcexpl.txt* A Source code Explorer which works like the context window of "Source Insight"
+
+Version: 5.1
+Author : Wenlong Che <wenlong.che@gmail.com>
+ Jonathan Lai <laiks.jonathan@gmail.com>
+License: GNU General Public License {{{
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the GNU General Public License
+ as published by the Free Software Foundation; either version 2
+ of the License, or (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+}}}
+
+CONTENTS *srcexpl-contents*
+ Introduction |srcexpl-introduction|
+ Features |srcexpl-features|
+ Install |srcexpl-install|
+ Interface |srcexpl-interface|
+ Commands |srcexpl-commands|
+ Variables |srcexpl-variables|
+ Key Mappings |srcexpl-key-mappings|
+ Examples |srcexpl-examples|
+ Tips |srcexpl-tips|
+ Changelog |srcexpl-changelog|
+
+==============================================================================
+INTRODUCTION *srcexpl-introduction*
+
+SrcExpl (Source Explorer) is a source code explorer that provides context for
+the currently selected keyword by displaying the function or type definition
+or declaration in a separate window. This plugin aims to recreate the context
+window available in the IDE known as "Source Insight".
+
+The behaviour of the Source Explorer window is similar to that of "Source
+Insight". Placing your cursor on a function name in Normal Mode will cause its
+definition to be displayed in the Source Explorer window. Double-clicking the
+definition will cause the edit window to jump to the definition. In addition,
+listing multiple definitions and jumping work in a similar fashion to
+"Source Insight".
+
+Source Explorer uses ctags to track keywords and can automatically create and
+update the generated tags file for you.
+
+Source Explorer is designed to work with other plugins like 'The NERD tree'
+and 'taglist' to further recreate a "Source Insight"-like environment or to
+work in your own configuration.
+
+------------------------------------------------------------------------------
+FEATURES *srcexpl-features*
+
+ * Display definitions and declarations of various languages supported
+ by ctags and various types including functions, macros, structures,
+ arrays, methods, classes, and variables.
+ * Jump to the displayed context in the Source Explorer window using the
+ * mouse or your own key mapping.
+ * Jump back from the context location with the mouse context menu or your
+ own key mapping.
+ * Automatically list all definitions if multiple definitions for a keyword
+ is found.
+ * Automatically create and update the tags file.
+
+==============================================================================
+INSTALL *srcexpl-install*
+
+1. Ensure ctags is installed on your system and that VIM can use it.
+2. Place the Source Explorer files in your Vim directory (such as ~/.vim) or
+have it installed by a bundle manager like Vundle or NeoBundle.
+3. Open the Source Explorer window with |:SrcExpl| or |:SrcExplToggle| or map
+these commands to keys in your .vimrc.
+
+ *srcexpl-uninstall*
+To uninstall Source Explorer, simply delete the Source Explorer files and
+remove any related lines in your .vimrc. You may remove any generated tags
+files in your projects or keep them for further use as they can be used by vim
+without Source Explorer.
+
+==============================================================================
+INTERFACE *srcexpl-interface*
+
+------------------------------------------------------------------------------
+COMMANDS *srcexpl-commands*
+
+:SrcExpl *:SrcExpl*
+ Opens the Source Explorer window.
+
+:SrcExplClose *:SrcExplClose*
+ Closes the Source Explorer window.
+
+:SrcExplToggle *:SrcExplToggle*
+ Toggles the Source Explorer window on and off.
+
+------------------------------------------------------------------------------
+VARIABLES *srcexpl-variables*
+
+g:SrcExpl_winHeight *g:SrcExpl_winHeight*
+ This controls the default height of the Source Explorer window when it
+ is started.
+
+ Default: 8
+
+g:SrcExpl_refreshTime *g:SrcExpl_refreshTime*
+ This controls how often in milliseconds the Source Explorer window is
+ updated.
+ You must keep the cursor on the desired word for this period of time
+ for SrcExpl to display its definition.
+ Note: This sets the |updatetime| setting which also controls how often
+ the swap file will be written to disk.
+
+ Default: 100
+
+g:SrcExpl_pluginList *g:SrcExpl_pluginList*
+ This list contains the names of buffers to ignore when displaying
+ context information. At the very minimum it must include itself.
+>
+ " Minimum Plugin List
+ let g:SrcExpl_pluginList = [ "Source_Explorer" ]
+<
+ You should add the name of each buffer every other plugin you have uses
+ to avoid conflicts and compatibility issues.
+>
+ " Example
+ let g:SrcExpl_pluginList = [
+ \ "__Tag_List__",
+ \ "NERD_tree_1",
+ \ "Source_Explorer",
+ \ "*unite*"
+ \ ]
+<
+
+ Default: [ "__Tag_List__", "_NERD_tree_", "Source_Explorer" ]
+
+g:SrcExpl_searchLocalDef *g:SrcExpl_searchLocalDef*
+ This enables local definition searching. Source Explorer can use vim's
+ local definition search in addition to ctags to find definitions.
+ However, this is not guaranteed to work. See the vim documentation for
+ |gd| for more details.
+
+ Default: 1
+
+g:SrcExpl_isUpdateTags *g:SrcExpl_isUpdateTags*
+ This enables automatic tags file updating whenever Source Explorer is
+ opened.
+ If a tags files is not found, you will be asked if you wish to create
+ a tags file in the current directory.
+ The command used to create or update the tags is set by
+ |g:SrcExpl_updateTagsCmd|.
+
+ Default: 1
+
+g:SrcExpl_updateTagsCmd *g:SrcExpl_updateTagsCmd*
+ The command used to create or update the tags file. This is run when
+ Source Explorer is opened if |g:SrcExpl_isUpdateTags| is set or
+ whenever |g:SrcExpl_updateTagsKey| is pressed. The command will run in
+ the current directory.
+
+ Default: "ctags --sort=foldcase -R ."
+
+------------------------------------------------------------------------------
+KEY MAPPINGS *srcexpl-key-mappings*
+
+g:SrcExpl_jumpKey *g:SrcExpl_jumpKey*
+ Set this variable to the key you want to use to jump to the highlighted
+ definition in the Source Explorer window.
+ Note: This mapping only works in the Source Explorer window.
+ Note: Source Explorer uses its own mark list and normal mark commands
+ will not work.
+
+ Default: '<CR>'
+
+g:SrcExpl_gobackKey *g:SrcExpl_gobackKey*
+ Set this variable to the key you want to use to go back to the previous
+ location after jumping to a definition.
+ Note: Source Explorer uses its own mark list and normal mark commands
+ will not work.
+
+ Default: '<SPACE>'
+
+g:SrcExpl_updateTagsKey *g:SrcExpl_updateTagsKey*
+ Set this variable to the key you want to use to force a update of the
+ tags file.
+
+ Default: ''
+
+==============================================================================
+EXAMPLES *srcexpl-examples*
+>
+ " // The switch of the Source Explorer
+ nmap <F8> :SrcExplToggle<CR>
+
+ " // Set the height of Source Explorer window
+ let g:SrcExpl_winHeight = 8
+
+ " // Set 100 ms for refreshing the Source Explorer
+ let g:SrcExpl_refreshTime = 100
+
+ " // Set "Enter" key to jump into the exact definition context
+ " let g:SrcExpl_jumpKey = "<ENTER>"
+
+ " // Set "Space" key for back from the definition context
+ let g:SrcExpl_gobackKey = "<SPACE>"
+
+ " // In order to Avoid conflicts, the Source Explorer should know what plugins
+ " // are using buffers. And you need add their bufname into the list below
+ " // according to the command ":buffers!"
+ let g:SrcExpl_pluginList = [
+ \ "__Tag_List__",
+ \ "_NERD_tree_",
+ \ "Source_Explorer"
+ \ ]
+
+ " // Enable/Disable the local definition searching, and note that this is not
+ " // guaranteed to work, the Source Explorer doesn't check the syntax for now.
+ " // It only searches for a match with the keyword according to command 'gd'
+ let g:SrcExpl_searchLocalDef = 1
+
+ " // Do not let the Source Explorer update the tags file when opening
+ let g:SrcExpl_isUpdateTags = 0
+
+ " // Use 'Exuberant Ctags' with '--sort=foldcase -R .' or '-L cscope.files' to
+ " // create/update a tags file
+ let g:SrcExpl_updateTagsCmd = "ctags --sort=foldcase -R ."
+
+ " // Set "<F12>" key for updating the tags file artificially
+ let g:SrcExpl_updateTagsKey = "<F12>"
+<
+==============================================================================
+TIPS *srcexpl-tips*
+
+1. Ensure that there is only one tags file in your project PATH or you Source
+Explorer will show duplicates of every definition.
+For example: There are two tags in the 'your_project' directory, so we will
+delete the excess 'tags' files in the 'sub_directory'.
+>
+ [chewenlong@localhost ~]$ cd your_project/
+ [chewenlong@localhost your_project]$ pwd
+ /home/chewenlong/your_project
+ [chewenlong@localhost your_project]$ ls
+ bar.c sub_directory tags
+ [chewenlong@localhost your_project]$ cd sub_directory/
+ [chewenlong@localhost sub_directory]$ ls
+ foo.c tags
+ [chewenlong@localhost sub_directory]$ rm -rf tags
+ [chewenlong@localhost sub_directory]$ ls
+ foo.c
+ [chewenlong@localhost sub_directory]$ cd ..
+ [chewenlong@localhost your_project]$ ls
+ bar.c sub_directory tags
+ [chewenlong@localhost your_project]$ vim bar.c
+<
+
+ *srcexpl-line-endings*
+2. Ensure that all the files you are exploring are using unix line endings. If
+they are not, a '^M' will be displayed at the end of the line and Source
+Explorer will jump to incorrect locations.
+
+ *srcexpl-console-mappings*
+3. If you are using Source Explorer in a UNIX console, these are my suggested
+key mappings for jumping between windows and using Source Explorer:
+>
+ nmap <C-H> <C-W>h
+ nmap <C-J> <C-W>j
+ nmap <C-K> <C-W>k
+ nmap <C-L> <C-W>l
+
+ nmap <C-I> <C-W>j:call g:SrcExpl_Jump()<CR>
+ nmap <C-O> :call g:SrcExpl_GoBack()<CR>
+<
+
+ *srcexpl-trinity*
+4. If you want to set up vim to work more like Source Insight, you can try a
+vim plugin named Trinity (trinity.vim) available at:
+http://www.vim.org/scripts/script.php?script_id=2347
+
+The Trinity plugin manages Source Explorer, Taglist and NERD Tree. The below
+shows my work platform with Trinity.
+>
+ +----------------------------------------------------------------------------+
+ | File Edit Tools Syntax Buffers Window Help |
+ +----------------+-----------------------------------------+-----------------+
+ |-demo.c---------| |-/home/myprj/----|
+ |function | 1 void foo(void) /* function 1 */ ||~ src/ |
+ | foo | 2 { || `-demo.c |
+ | bar | 3 } |`-tags |
+ | | 4 void bar(void) /* function 2 */ | |
+ |~ .----------. | 5 { |~ .-----------. |
+ |~ | Tag List |\ | 6 } .-------------. |~ | NERD Tree |\ |
+ |~ .----------. ||~ | Edit Window |\ |~ .-----------. ||
+ |~ \___________\||~ .-------------. | |~ \____________\||
+ |~ |~ \______________\| |~ |
+ +-__Tag_List__---+-demo.c----------------------------------+-_NERD_tree_-----+
+ |Source Explorer v5.1 .-----------------. |
+ |~ | Source Explorer |\ |
+ |~ .-----------------. | |
+ |~ \__________________\| |
+ |-Source_Explorer------------------------------------------------------------|
+ |:TrinityToggleAll |
+ +----------------------------------------------------------------------------+
+<
+
+ *srcexpl-github*
+ *srcexpl-screenshots*
+5. Screenshots are available at: http://srcexpl.blogspot.com/
+The official git repository is on github at:
+https://github.com/wesleyche/SrcExpl
+
+==============================================================================
+CHANGELOG *srcexpl-changelog*
+
+5.0
+- Replaced use of preview window with a named buffer.
+- Moved to github.
+- Added documentation.
+
+5.1
+- Added two APIs for serving other plugins:
+ 1. SrcExpl_GetWin(), getting the Source Explorer window number for those
+ plugins based on multiple windows.
+ 2. SrcExpl_GetVer(), getting the Source Explorer version for the forward
+ compatibility.
+- Added debug/logging functions for the internal development.
+
+==============================================================================
+vim:tw=78:ts=8:noet:ft=help:
Oops, something went wrong.

0 comments on commit 87620e1

Please sign in to comment.