utils 0.0.57 → 0.0.58

data/lib/utils/config/vim/doc/Decho.txt

@@ -0,0 +1,372 @@
+*decho.txt* Vim Code Debugger				Oct 23, 2008
+*Decho.vim*
+
+Author:  Charles E. Campbell, Jr.  <drNchipO@ScampbellPfamilyA.bizM>
+	  (remove NOSPAM from Campbell's email to use)
+Copyright: (c) 2004-2008 by Charles E. Campbell, Jr.	*decho-copyright*
+           The VIM LICENSE applies to Decho.vim and Decho.txt
+           (see |copyright|) except use "Decho" instead of "Vim"
+	   No warranty, express or implied.  Use At-Your-Own-Risk.
+
+
+==============================================================================
+1. Contents						*decho-contents*
+
+	1. Contents......................: |decho-contents|
+	2. Decho Manual..................: |decho|
+	3. Decho Global Variables........: |decho-var|
+	4. Decho History.................: |decho-history|
+
+	NOTE: as of version 7, Decho requires <cecutil.vim> for
+	:DechoOn and :DechoOff (they call SaveWinPosn() and
+	RestoreWinPosn() to retain the cursor/screen position)
+
+
+==============================================================================
+2. Decho Manual						*decho* *dfunc* *dret*
+
+	The Decho plugin supports the inlining of debugging code.  It allows
+	one to store debugging information along with scripts.  Many of my]
+	own scripts can use this plugin (usually after a :DechoOn is issued).
+
+	Decho, Dfunc, Dret, and Dredir have several ways to save their
+	debugging output: >
+
+	 g:dechomode   To Enable   To Disable   Debugging Output
+	 -----------   ----------  -----------  ---------------------------
+	       1       (default)                appended to separate window
+	       2       DechoMsgOn  DechoMsgOff  uses :echomsg
+	       3       DechoVarOn  DechoVarOff  appended to g:dechovar
+	       4       DechoRemOn  DechoRemOff  appended to a remote server
+	       5       DechoTabOn  DechoTabOff  appended to a tab
+<
+	Why so many methods?  Although the default method, that of writing
+	debugging output to a separate debugging window, is often quite
+	convenient, sometimes plugins want to control the entire window
+	display.  Hence a debugging window can cause trouble as it is
+	unaccounted for by the plugin.  The :echomsg output can be seen with
+	|:messages|, but only 20 such messages can be retained.  The remote
+	server debugging output keeps its "distance" from plugins, but uses
+	gvim to open a separate debugging instance.  So, pick whichever method
+	suits debugging your plugin best.
+
+	USAGE
+>
+	    call Decho("another string")
+	    call Decho("yet","another","string")
+	    call DechoSep(["extra message"])
+	    call Dfunc("funcname(".whatever.")")
+	    call Dredir(["string","string",...,]"cmd")
+	    call Dret("funcname".whatever)
+	    Decho "a string"
+	    DechoMsgOff
+	    DechoMsgOn
+	    DechoOn    DechoOff
+	    DechoRemOff
+	    DechoRemOn
+	    DechoTabOff
+	    DechoTabOn
+	    DechoVarOff
+	    DechoVarOn [varname]
+	    Dhide
+	    Dshow
+	    Dsep [extra-message]
+<
+	The Decho call will put the string(s) passed to it into the debugging
+	window (by default, it will be called "DBG".  See |decho-var| for
+	how to change that).  Control characters embedded in the string will
+	be made visible with a ^A - ^Z transformation.
+
+	The Dfunc() and Dret() calls act as a pair.  A function to be debugged
+	should call, at entry, >
+
+		call Dfunc("funcname("."any arguments".")")
+<
+	It should also call, just prior to any return point, >
+
+		call Dret("funcname : any return values")
+<	or just >
+		call Dret("funcname")
+<
+	In between, calls to Decho will have their strings preceded by "|"s,
+	one for every open Dfunc().  The Dret() will check to insure that it
+	is apparently returning from the last function passed to Dfunc().
+
+	Example: >
+		function! MyFunction(x)
+		  call Dfunc("MyFunction(x=".x.")")
+		  ...
+		  call Dret("MyFunction")
+		endfunction
+<
+       							*DechoOn* *DechoOff*
+	DechoOn and DechoOff are convenient commands for enabling and disabling
+	Decho, Dfunc, and Dret calls in a sourcefile.  DechoOff makes any line
+	containing one of the following strings: >
+
+    	    Decho        DechoRemOff  DechoTabOn   Dfunc
+    	    DechoMsgOff  DechoRemOn   DechoVarOff  Dret
+    	    DechoMsgOn   DechoTabOff  DechoVarOn
+
+<	into a comment line and DechoOn reactivates such commands by removing
+	the leading comment '"' character.
+
+	Example: >
+		call Decho("this will show up in the DBG buffer")
+<
+						*decho-dhide* *decho-dshow*
+	The Dhide and Dshow commands allow one to toggle the visibility of
+	the DBG-buffer.  They use the g:decho_hide variable, plus make any
+	current DBG-buffer hidden or visible as indicated.
+
+	Usage: >
+		:Dhide
+		:Dshow
+<
+							*Dsep* *DechoSep*
+	This command (Dsep) and function (call DechoSep([optional msg])
+	places a line of the form >
+		--sep#-- [optional message here]
+<	in the debugging output.  The number will be incremented for each
+	time this function is invoked.  It helps one correlate an action
+	with the resulting debugging output.
+
+							*decho-redir* *Dredir*
+	The Dredir() function allows one to redirect (see |redir|) a command's
+	output to the debugging buffer.  One must have the command to be
+	executed as the first argument; optionally, one may include additional
+	arguments which will be passed on to Decho() for output.
+
+	Usage: >
+		call Dredir(["string","string",...,]"cmd")
+<
+	Example: >
+		call Dredir("buffers","ls!")
+<
+							*g:decho_bufenter*
+	Some plugins use events such as BufEnter, WinEnter, and WinLeave.  If
+	you set this variable to 1, then such events will be ignored when and
+	only when Decho() and variants are used.  Setting this option avoids
+	such plugins from being triggered when recording debugging messages.
+	(examples: winmanager, taglist, multiselect, etc)
+
+	Example: >
+		let g:decho_bufenter= 1
+<
+						*DechoVarOn* *DechoVarOff*
+	Although debugging to a window is often convenient for the programmer,
+	unfortunately some vim applications are incompatible with such a
+	window (such as those which do window control themselves).  Using >
+		:DechoVarOn
+<	sends debugging output to be appended to a variable named in the
+	|g:dechovarname| variable (by default, its "g:dechovar").  To turn
+	this mode off (ie. revert to normal debugging-window use) use >
+		:DechoVarOff
+<	DechoVarOn also sets g:dechofile with the name of the script that
+	invoked it.
+						*DechoMsgOn* *DechoMsgOff*
+	This debugging method uses echomsg to display messages; they may be
+	seen with the |:messages|.  Vim usually will retain up to 20 such
+	messages (see |message-history|).  Use >
+		:DechoMsgOn
+<	to turn this method on and >
+		:DechoMsgOff
+<	to revert to normal debugging-window use.  This method helps avoid
+	interference with some plugins.
+	DechoMsgOn also sets g:dechofile with the name of the script that
+	invoked it.
+
+						*DechoRemOn* *DechoRemOff*
+	This method will open (if necessary) and use a remote gvim with a
+	servername of DECHOREMOTE.  Debugging messages are appended to that
+	instance of gvim.  To have this command available, your vim must have
+	|clientserver| enabled and |gvim| must be executable. Use >
+		:DechoRemOn
+<	to turn this method on and >
+		:DechoRemOff
+<	to revert to normal debugging-window use.  This method helps avoid
+	interference with some plugins.
+
+	DechoRemOn also sets g:dechofile with the name of the script that
+	invoked it.
+
+						*DechoTabOn* *DechoTabOff*
+	This method will open (if necessary) and use a debugging tab with
+	one window.  Debugging messages are appended to the debugging tab
+	(see |tabpage|).  One may use |gt| to switch between two tabs.  Use >
+		:DechoTabOn
+<	to turn this method on and >
+		:DechoTabOff
+<	to revert to normal debugging-window use.  The Decho and related
+	calls turn events off while writing to the debugging tab so as to
+	attempt to remain transparent with respect to normal event processing.
+
+	EXAMPLE
+
+	Consider the following file: >
+	    let x="abc"
+	    let y="def"
+	    call Dfunc("testing(x=".x.")")
+	    call Decho("decho test #1")
+	    call Dfunc("Testing(y=".y.")")
+	    call Decho("decho test #2")
+	    call Dret("Testing")
+	    call Decho("decho test #3")
+	    call Dret("testing")
+<
+	Then sourcing with <Decho.vim> as a plugin (ie. already loaded) yields: >
+
+	    testing(x=abc) {
+	    |decho test #1
+	    |Testing(y=def) {
+	    ||decho test #2
+	    ||Testing }
+	    |decho test #3
+	    |testing }
+<
+	DechoRemOn also sets g:dechofile with the name of the script that
+	invoked it.
+
+
+==============================================================================
+3. Decho Global Variables		*decho-variables* *decho_settings*
+					*decho_options* *decho-var*
+
+   *g:dechomode*      :	=1 use separate small window at bottom (default)
+			=2 debugging messages will use echomsg and can be seen
+			   by using :messages.  See |message-history| for more
+			   about this; currently, the maximum number of mess-
+			   ages remembered is 20.
+			=3 debugging messages get appended to the variable
+			   named by |g:dechovarname| (also see |g:dechovar|)
+			=4 debugging messages get appended to the gvim remote
+			   server named DECHOREMOTE.
+
+   *g:decho_bufname*  :	by default "DBG" .  Sets the name of the debugging
+   			buffer and window.
+   *g:decho_hide*     :	if set the DBG window will be hidden and will
+   			automatically "q" each time it is used.  To see it,
+			:e DBG .  Useful for those applications that
+			modify windows.
+   *g:dechovar*       : default value of g:dechovarname (see |g:dechovarname|)
+
+   *g:dechovarname*   : when g:dechomode is 3, debugging output is appended to
+			the variable named by this variable
+			(default: "g:dechovar"  - see |g:dechovar|)
+
+							*decho_winheight*
+   *g:decho_winheight* : by default equal to 5 lines.  Specifies the height
+			 of the debugging window.  Every Dfunc/Decho/Dret
+			 call will resize that window to this height.
+
+
+==============================================================================
+4. Decho History					*decho-history*
+
+  v20 Jun 07, 2007 : * changed some syntax/Decho.vim highlighting definitions
+		       to avoid the use of highlighting groups defined by
+		       colors/astronaut.vim that aren't standard (Cyan,
+		       Magenta) (pointed out by Andreas Politz)
+		     * (Erik Falor) under windows, uses "start gvim..."so
+		       that DechoRemOn doesn't keep the original gvim
+		       blocking until the remote gvim closes.
+		     * (Erik Falor) The remote gvim now has |'nosi'| sent to it.
+      Feb 13, 2008   * changed s:DechoSep() to DechoSep() so that it can be
+		       called externally.  In particular, I'm using (all one
+		       line): >
+		         redraw!|call DechoSep()|...
+		         call inputsave()|call input("Press <cr> to continue")|...
+		         call inputrestore()
+<		       to put a temporary halt into code I'm debugging while
+		       retaining an idea of where in the Debug file it took
+		       effect.
+      May 29, 2008   * Removed an annoying beep that could crop up if
+                       g:dechotabnr indexed a non-existent tab page.
+      Aug 12, 2008   * DechoRemOn left autoindent enabled in the remote
+		       window which can cause staircasing
+      Oct 13, 2008   * in DechoTab mode, the search for the first tab called
+		       "Decho Tab" didn't start at tab#1 as the search loop
+		       assumed.
+  v19 Oct 16, 2006 : * Dredir now takes optional strings first instead of
+		       last
+		     * The :Decho and :Dredir commands now take <args> instead
+		       of <q-args>, which allows them to act more like the
+		       function calls do.
+		     * DechoRemOn's remote vim no longer will have
+		       formatoptions' a or t suboptions set even if the user
+		       has specified something like fo+=at in his/her .vimrc.
+		     * If the user interposes a new tab (or deletes the
+		       "Decho Tab"), Decho finds the "Decho Tab" tab or
+		       creates a new one when called.
+  v18 Mar 13, 2006 : * now handles arguments which are lists
+                     * works around ignorecase setting
+		     * removed bt=nofile; using noswf instead
+      Sep 08, 2006   * if DechoRemOn is used, but then the user closes the
+                       remote window but still sends Decho messages, then
+		       Decho now switches to DECHOWIN mode to prevent an
+		       onslaught of error messages about how vim can't connect
+		       to the DECHOREMOTE vim.
+  v17 Mar 03, 2006 : * debugging filetype set to Decho for DechoTabOn and
+                       DechoRemOn and ei manipulated so that syntax
+		       highlighting works for the Decho Tab buffer.
+		     * bugfix: when a buffer was |'noma'|, DechoTabOn
+		       inherited that and complained about not being allowed
+		       to modify the buffer.
+  v16 Feb 27, 2006 : * reflecting changes to tab commands:
+                       tab -> tabn, tabn -> tabnew
+  v15 Feb 21, 2006 : * DechoTab[On\Off] implemented
+  v14 Jan 25, 2006 : * bugfix: with DechoVarOn, Decho would issue error
+                       messages when the string had single quotes (') in
+		       it
+		     * SaveWinPosn(0) used to avoid SWP stack use
+      Feb 15, 2006   * DechoRemOn and DechoRemOff now turn debugging on/off to
+		       a remote DECHOREMOTE gvim server.  Your vim must
+		       support clientserver and gvim must be executable.
+  v13 Jan 18, 2006 : * cecutil updated to use keepjumps
+  v12 Jan 14, 2005 : * DechoOn/Off now also turns on/off DechoVarOn/Off
+                     * Now includes a GetLatestVimScripts line for cecutil.vim
+      Apr 25, 2005   * Decho now does "runtime plugin/cecutil.vim" if that plugin
+                       hasn't been loaded yet.  It will also try the AsNeeded
+		       subdirectory if g:loaded_asneeded exists.
+      Jun 02, 2005   * with DechoMsgOn, Decho("doesn't") now works
+  v11 Aug 06, 2004 : * <q-args> now used instead of <args> for :Decho and :Dredir
+                       commands
+      Oct 28, 2004   * DechoMsgOn and DechoMsgOff installed; debugging messages
+                       will use the |echomsg| command.
+      Dec 27, 2004   * DechoVarOn and DechoVarOff installed; debugging
+      		       messages will be appended to the variable specified by
+		       g:dechovarname, which by default is "g:dechovar".
+		       These two commands toggle the variable
+		       "g:dechovar_enabled".
+      Dec 29, 2004   * Dredir() now accepts multiple arguments (cmd and output)
+  v10 Jul 27, 2004 : * if g:decho_bufenter exists, Decho will ignore BufEnter
+                       events
+		     * Decho uses keepjumps to avoid altering the jumplist
+		       table
+		     * appending to the DBG buffer with Decho does not make
+		       it modified
+		     * Dredir(cmd) may be used to redirect command output
+		       to the DBG buffer.  Example:  call Dredir("cmd")
+   v9 Jun 18, 2004 : * Dfunc/Decho/Dret now immune to lcd changes in the DBG
+   		       buffer name
+                     * DechoOn and DechoOff now accept ranges
+   v8 Jun 06, 2004 : * Implemented Dhide and Dshow commands for toggling
+                       the DBG-buffer's visibility (see |decho_dhide|)
+   v7 Jun 02, 2004 : * made creation of	DBG window silent
+		     * g:decho_winheight implemented (see |decho_winheight|)
+		     * Dfunc/Decho/Dret	will always resize the DBG window to the
+		       number of lines specified by g:decho_winheight (dflt:5)
+		     * g:decho_hide implemented (see |decho_hide|)
+   v6 May 11, 2004 : * some bug	fixes
+   v5 Apr 20, 2004 : * Dfunc() - for entering a	function
+		     * Dret()  - for returning from a function
+   v4 Apr 20, 2004 :   Now makes control characters visible
+   v3 Aug 07, 2003 : * changed fixed "DBG" to g:decho_bufname to allow s/w to
+		       change the buffer name!
+		     * Now handles returning cursor to one of several windows
+		       and having multiple DBG-windows
+
+
+==============================================================================
+vim:tw=78:ts=8:ft=help
+