<?xml version="1.0"?>

<!-- CodeBrowser plugin user's guide -->
<!-- (c) 2002, 2003, 2004 Gerd Knops -->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<book>


<bookinfo>
    <title>Code Browser plugin</title>

    <authorgroup>
        <author>
            <firstname>Gerd</firstname>
            <surname>Knops</surname>
        </author>
    </authorgroup>
</bookinfo>


<chapter id="Description">
    <title>Description</title>

    <para>
    The Code Browser plugin contains a buffer switcher and a code browser within
	a split pane. The buffer switcher can be hidden by moving the divider all
	the way up, or by clicking the small up-handle. The code browser simplifies
	navigating source code of any programming language supported by the
	Exuberant C Tags program.
    </para>
	
</chapter>

<chapter id="BufferSwitcher">
    <title>The Buffer Switcher</title>

    <para>
	The buffer switcher displays the file name of each buffer, and as much of the 
	<emphasis>end</emphasis> of each path as can be fit. The selcted buffer is
	shown in bold. The file name colors are taken from the File System Browser
	(See <guimenu>Global Options</guimenu>&gt;<guisubmenu>File System 
	Browser</guisubmenu>&gt;<guisubmenu>Colors</guisubmenu>). The path of
	'dirty' buffers
	is displayed in in dark red, others in dark gray. Operation of the buffer switcher
	is straight forward: A mouse click selects a buffer, and a control-click
	closes a buffer. While the mouse is ofer a buffer switcher entry a tooltip
	shows the entire path for this entry.
	</para>
</chapter>

<chapter id="CodeBrowser">
    <title>The Code Browser</title>

    <para>
	The code browser requires Exuberant C Tags version 5.5 or later. You can find
	it at <ulink url="http://ctags.sourceforge.net">http://ctags.sourceforge.net</ulink>.
	NOTE: The standard ctags program found on many systems is NOT sufficient!!!
	</para>
	
	<para>
	The path of the <command>ctags</command> program needs to be
	set in the Plugin Options for the Code Browser plugin. A typical choice on
	Unix-like systems is <filename>/usr/local/bin/ctags</filename>, and on windows
	systems <filename>c:\Apps\ctags51\ctags.exe</filename>.
	</para>
	
	<para>
	Once the <command>ctags</command> path is set, the code browser plugin will parse a file whenever
	a buffer displaying the file is selected, or when the current buffer is saved.
	Please note that only the file on disk is parsed, not the in-memory contents
	of the buffer. 
    </para>
	
    <para>
    Simply click on any function, variable declaration etc. displayed in the
	code browser, and the buffer will be positioned accordingly. As regular
	expressions are used, code browser will be able to find definitions even
	in modified files as long as the line on which the definition occured was
	not changed. Tooltips show the contents of the line, which depending on 
	language and style may include more information.
    </para>
	
    <para>
    Right-clicking on any function, variable declaration etc. will bring up a context menu with these choices:
        <itemizedlist>
            <listitem>
            <para> <guimenu>Insert at Caret</guimenu>: Inserts the selected term in the current text view. </para></listitem>
            <listitem><para> <guimenu>Hypersearch</guimenu>: Perform a hypersearch with this term. </para></listitem>
            <listitem><para><guimenu>Copy to pasteboard</guimenu>: Copies the selected term to the paste board. </para></listitem>
            <listitem><para><guimenu>Append to pasteboard</guimenu>: Appends the selected term to the pasteboard. </para></listitem>
        </itemizedlist>
    </para>
	
    <para>
    The <guimenu>Options</guimenu> menu button above the Code Browser section
	lets you select a few options:
        <itemizedlist>
            <listitem><para>
            <guimenu>Auto-parse</guimenu>: When checked, buffers are parsed automatically when saved or when you switch to another buffer. When un-checked, buffers will only be parsed when you click on the <guimenu>Parse</guimenu> button. That can be helpful when you work with extremely large files, where parsing requires some time. </para>
            </listitem>
            <listitem><para> <guimenu>Sort</guimenu>: When checked, all listed tags will be sorted. </para></listitem>
            <listitem><para> 
            <guimenu>Auto-unfold</guimenu>: When checked, any section in the code you jump to will be unfolded automatically. </para></listitem>
            <listitem><para> <guimenu>Auto-close dock</guimenu>: After selecting a tag the dock is automatically closed </para>
            </listitem>
        </itemizedlist>
    </para>
</chapter>

<chapter id="OtherLanguages">
    <title>Code Browser and Languages/File types not supported by ctags</title>

    <para>
	The <command>ctags</command> program supports many languages, but chances are you might
	work with a language or file type not supported by <command>ctags</command>. While support
	built into <command>ctags</command> is the most elegant solution, you can also create some
	simple regular expression based support for languages not directly
	supported by <command>ctags</command>. 
	</para>
	
	<para>
	The following chapter gives some examples. The lines shown need to be added
	to one of the files <command>ctags</command> reads during startup. On unix-like systems that 
	could be <filename>~/.ctags</filename>, and on windows systems that could be a
	file <filename>ctags.cnf</filename> in the jEdit directory. Please read the
	ctags documentation for more info.
	</para>
</chapter>

<chapter id="XmlAndHtml">
    <title>Simple support for XML and HTML</title>

    <para>
	Here is an example for contents of the <command>ctags</command> configuration file mentioned
	in the previous chapter. The example add simple support for XML files and
	HTML files (note that HTML is now supported natively in ctags):
	</para>
	
	<para>
	<programlisting>
--langdef=xml
--langmap=xml:.xml
--regex-xml=/&lt;([^ \t]+)[ \t]*(id|name)[ \t]*=[ \t]*\&quot;([^\&quot;]+)/\1 \3/Named Tags/i

--langdef=html
--langmap=html:.htm.html
--regex-html=/&lt;a[ \t]+href[ \t]*=[ \t]*\&quot;([^\&quot;]+)/\1/HRefs/i
--regex-html=/&lt;img[ \t]+src[ \t]*=[ \t]*\&quot;([^\&quot;]+)/\1/Images/i
--regex-html=/&lt;h([1-6])[^&gt;]*&gt;([^&lt;]*)/\2 (\1)/Headers/i
	</programlisting>
	</para>
	
    <para>
	The <command>--langdef</command> lines define the name of the language, the 
	<command>--langmap</command> lines define the extensions of files for this
	language, and the <command>--regex-html</command> lines define the regular
	expressions describing the items of a language you want to see in Code
	Browser. For more info please see the <command>ctags</command> documentation.
	</para>
	
</chapter>

<chapter id="Ant">
    <title>Simple support for Ant build.xml files</title>
	
    <para>
	<filename>build.xml</filename> files would normally be governed by the 
	xml entries listed in the previous chapter. <command>ctags</command> does
	not allow one entry for <filename>*.xml</filename> and another for
	<filename>build.xml</filename>. Code Browser helps out here; Code Browser
	forces the language used by ctags to <command>ant</command> when
	the file to be parsed is named <filename>build.xml</filename>.
	</para>
	
	<para>
	<programlisting>
--langdef=ant
--regex-ant=/&lt;property[ \t]*name[ \t]*=[ \t]*\&quot;([^\&quot;]+)/\1/Properties/i
--regex-ant=/&lt;target[ \t]*name[ \t]*=[ \t]*\&quot;([^\&quot;]+)/\1/Targets/i
--regex-ant=/&lt;path[ \t]*id[ \t]*=[ \t]*\&quot;([^\&quot;]+)/\1/Paths/i
--regex-ant=/&lt;taskdef[ \t]*id[ \t]*=[ \t]*\&quot;([^\&quot;]+)/\1/Taskdefs/i
--regex-ant=/&lt;typedef[ \t]*id[ \t]*=[ \t]*\&quot;([^\&quot;]+)/\1/Typedefs/i
	</programlisting>
	</para>
</chapter>

<chapter id="faq">
    <title>Frequently Asked Questions</title>

    <para>
    Q: I am working on a (shell|perl|python|whatever) script, but CodeBrowser
	isn't showing anything.
    </para>

    <para>
    A: Ctags parses files without extensions (like many scripts) only if the
	executable flag is set AND the magic #!/path/to/interpreter first line
	can be found. So make sure both those conitions are met, or add a known
	extension to the script.
    </para>
	
	<para>
	Q: Is there support for ActionScript?
	</para>
	
	<para>
	A: Check <ulink url="www.ubergeek.tv/jack/hack.php">www.ubergeek.tv/jack/hack.php</ulink>
	</para>
</chapter>

<chapter id="license">
    <title>License</title>

    <para>
    Feel free to do with the files of this project whatever you want. If they
	make you filthy rich you should send some bucks my way though.
    </para>
</chapter>

<chapter id="disclaimer">
    <title>Disclaimer</title>

    <para>
	BITart and Gerd Knops make no warranties, representations or commitments
	with regard to the contents of this software. BITart and Gerd Knops
	specifically disclaim any and all warranties, wether express, implied or
	statutory, including, but not limited to, any warranty of merchantability
	or fitness for a particular purpose, and non-infringement. Under no
	circumstances will BITart or Gerd Knops be liable for loss of data,
	special, incidental or consequential damages out of the use of this
	software, even if those damages were forseeable, or BITart or Gerd Knops
	was informed of their potential.
    </para>
</chapter>

<chapter id="feedback">
    <title>Feedback</title>

    <para>You can write to:</para>
    <itemizedlist>
        <listitem> <para>
            Gerd Knops <email>gerti-codebrowser@bitart.com</email> </para>
        </listitem>

        <listitem> <para>
            The jEdit-users mailing-list
            <email>jedit-users@lists.sourceforge.net</email> </para>
        </listitem>

        <listitem><para>
            The jEdit-devel mailing-list
            <email>jedit-devel@lists.sourceforge.net</email> </para>
        </listitem>
    </itemizedlist>
</chapter>


<appendix id="changelog">
    <title>Change log</title>

    
    <formalpara>
        <title>Version 1.4.3</title>
        <para>Requires JDK 1.4, jEdit 4.3pre5, ExuberantCtags 5.5. 
        <itemizedlist>
        <listitem>
        <para> Fixes for change in regexp/search API </para>
        </listitem>
        <listitem> <para> Sends new CaretChanging editbus message for the benefit of Navigator. </para> </listitem>
        </itemizedlist>
        </para>
    </formalpara>

    
    <formalpara>
        <title>Version 1.4.2</title>
        <para>Requires JDK 1.3, jEdit 4.3, ExuberantCtags 5.5. 
        <itemizedlist>
        <listitem>
		<para>
	           Works with jedit 4.3 API and plugin dynamic loading. 
         </para>
         </listitem>
        </itemizedlist> </para>
    </formalpara>

	
    <formalpara>
        <title>Version 1.4.0</title>
        <para>Requires JDK 1.3, jEdit 4.1, ExuberantCtags 5.5. 
        <itemizedlist>
            <listitem><para>Behavior improved when multiple tags with identical names
				are found: if you select the n-th one, then CodeBrowser will jump to the n-th occurance in the code.</para></listitem>
            <listitem><para> New <guimenu>Options</guimenu> Menu. </para></listitem>
            <listitem><para> Moved <guimenu>Sort</guimenu> and <guimenu>Auto</guimenu>
				buttons into new <guimenu>Options</guimenu> Menu. </para></listitem>
            <listitem><para>New option <guimenu>Auto-unfold</guimenu>: When checked
				and you jump to a folded section of the code that section will be
				unfolded automatically</para></listitem>
            <listitem><para>New option <guimenu>Auto-close Dock</guimenu>: When
				checked the dock will automatically close after a tag was
				selected</para></listitem>
            <listitem><para>Cleaned up UI</para></listitem>
            <listitem><para>Cleaned up code</para></listitem>
        </itemizedlist>
        </para>
    </formalpara>
	
    <formalpara>
        <title>Version 1.3.1</title>
        <para>Requires JDK 1.3, jEdit 4.1, ExuberantCtags 5.5. 
		
        <itemizedlist>
            <listitem><para>Updated for jEdit 4.2</para></listitem>
        </itemizedlist>
        </para>
    </formalpara>
	
    <formalpara>
        <title>Version 1.3.0</title>
        <para>Requires JDK 1.3, jEdit 4.1, ExuberantCtags 5.5. 
		
        <itemizedlist>
            <listitem><para>Compatible with all languages supported now or in future by ExuberantCtags</para></listitem>
			<listitem><para>No longer requires internal tables to determine programming language</para></listitem>
			<listitem><para>No longer requires internal tables to translate single letter 'kind' to description</para></listitem>
			<listitem><para>Methods, functions etc. now listed with signature</para></listitem>
        </itemizedlist>
        </para>
    </formalpara>

    <formalpara>
        <title>Version 1.2.1</title>
        <para>Requires JDK 1.3, jEdit 4. 
        <itemizedlist>
            <listitem><para>Context menu for items in CodeBrowser (Rudi Widmann)</para></listitem>
        </itemizedlist>
        </para>
    </formalpara>

    <formalpara>
        <title>Version 1.2.0</title>
        <para>Requires JDK 1.3, jEdit 4.  Code contributed by Rudi Widmann:

    
        <itemizedlist>
            <listitem><para>Manual parsing mode</para></listitem>
            <listitem><para>Cache parse results</para></listitem>
            <listitem><para>Do not parse when docked but not visible</para></listitem>
            <listitem><para>Focus textarea after selecting element in parse tree</para></listitem>
        </itemizedlist>
    </para></formalpara>    
        
    <formalpara>
        <title>Version 1.1.1</title>
        <para>Requires JDK 1.3, jEdit 4. </para>

    </formalpara>

    <itemizedlist>
            <listitem><para>Should now work with all kinds of remote files</para></listitem> 
        </itemizedlist>

    <formalpara>
        <title>Version 1.1.0</title>
        <para>Requires JDK 1.3, jEdit 4.

        <itemizedlist>
            <listitem><para>Added support for FTP plugin</para>
            </listitem>
        </itemizedlist></para>
    </formalpara>

    <formalpara>
        <title>Version 1.0.0</title>
        <para>Requires JDK 1.3, jEdit 4.

        <itemizedlist>
            <listitem><para>Minor bugfixes</para></listitem>
            <listitem><para>First release to plugin central</para></listitem>
        </itemizedlist> </para>
    </formalpara>

    <formalpara>
        <title>Version 0.9.2</title>
        <para>Requires JDK 1.3, jEdit 4.

        <itemizedlist>
            <listitem><para>Improved documentation</para></listitem>
            <listitem><para>Now handles multiple/split views better</para></listitem>
            <listitem><para>BufferSwitcher now uses colors from File System Browser</para></listitem>
        </itemizedlist></para>
    </formalpara>

    <formalpara>
        <title>Version 0.9.1</title>
        <para>Requires JDK 1.3, jEdit 4.

        <itemizedlist>
            <listitem><para>Regex bugfix</para></listitem>
        </itemizedlist> </para>
    </formalpara>
	
    <formalpara>
        <title>Version 0.9.0</title>
        <para>Requires JDK 1.3, jEdit 4.
	      
        <itemizedlist>
            <listitem><para>First beta test version</para></listitem>
        </itemizedlist> </para>
    </formalpara>
</appendix>

</book>