source: vendors/XMLF90/current/doc/Examples/dom/dumptext.xml @ 1967

<?xml version="1.0" ?>
<!-- SideKick user's guide -->
<!-- (C) 2003 Slava Pestov -->
<!-- jEdit buffer-local properties: -->
<!-- :indentSize=1:noTabs=true:folding=sidekick: -->
<book>
<bookinfo>
<title>SideKick plugin user's guide
</title> 
<authorgroup>  
<author>
<firstname>Slava
</firstname>
<surname>Pestov
</surname>
</author> 
</authorgroup> 
<legalnotice>
<title>Legal Notice
</title>  
<para>   Permission is granted to copy, distribute and/or modify this document
   under the terms of the GNU Free Documentation License, Version 1.1 or
   any later version published by the Free Software Foundation; with no
   
<quote>Invariant Sections
</quote>, 
<quote>Front-Cover Texts
</quote> or
   
<quote>Back-Cover Texts
</quote>, each as defined in the license. A copy of
   the license can be found in the file 
<filename>COPYING.DOC.txt
</filename>   included with jEdit.
  
</para>  
<para>   The SideKick plugin itself is released under the GNU General Public License.
   A copy of the GPL can be found in the jEdit online help.
  
</para> 
</legalnotice>
</bookinfo>
<chapter id="browser">
<title>The structure browser window
</title> 
<para>  The SideKick plugin provides a dockable window in which other plugins can
  display buffer structure.
 
</para> 
<para>  
<guimenu>Plugins
</guimenu>>
<guisubmenu>SideKick
</guisubmenu>>
<guimenuitem>Structure
  Browser
</guimenuitem> displays the current buffer's structure in a
  dockable window. This window is floating by
  default, but it can be docked into the view in the 
<guibutton>Docking
</guibutton>  pane of the 
<guimenuitem>Global Options
</guimenuitem> dialog box.
 
</para> 
<para>  The SideKick plugin automatically parses buffers
  when they are loaded or saved, where possible.
  Optionally, buffers can also be parsed on the fly, but this uses a fair bit of
  memory and processor power so it is disabled by default.
 
</para> 
<para>  
<guimenu>Plugins
</guimenu>>
<guisubmenu>SideKick
</guisubmenu>>
<guimenuitem>Parse
  on Keystroke
</guimenuitem> is a checkbox menu item that toggles on-the-fly
  parsing, for the current buffer only.
 
</para> 
<para>  The current buffer can be parsed at any other time by clicking the parse
  button in the 
<guimenuitem>Structure Browser
</guimenuitem> window, or by
  invoking the
  
<guimenu>Plugins
</guimenu>>
<guisubmenu>SideKick
</guisubmenu>>
<guimenuitem>Parse
  Buffer
</guimenuitem> command.
 
</para> 
<para>  Any errors found while parsing the buffer are sent to the
  
<application>ErrorList
</application> plugin, which means they are highlighted
  in the text area, and shown in the
  
<guimenu>Plugins
</guimenu>>
<guisubmenu>Error
  List
</guisubmenu>>
<guimenuitem>Error List
</guimenuitem> window. See the
  documentation for the 
<application>ErrorList
</application> plugin for details.
 
</para> 
<para>  Clicking on a node in the tree will move the caret to its location in the
  buffer;
  conversely, moving the caret in the buffer will select the corresponding
  node.
 
</para> 
<para>  
<keycap>Shift
</keycap>-clicking on a node will select that node in the text
  area. 
<keycap>Alt
</keycap>-clicking on a node will narrow the text area
  display to that node.
 
</para> 
<para>  If the structure browser window is docked into the current view, hovering the mouse
  over a node will display its attributes in the status bar.
 
</para>
</chapter>
<chapter id="moving-around">
<title>Moving around
</title>
<para>  
<guimenu>Plugins
</guimenu>>
<guisubmenu>SideKick
</guisubmenu>>
<guimenuitem>Go
  to Previous Asset
</guimenuitem> moves the caret to start of the structure
  element (
<quote>asset
</quote>).
 
</para> 
<para>  
<guimenu>Plugins
</guimenu>>
<guisubmenu>SideKick
</guisubmenu>>
<guimenuitem>Go
  to Next Asset
</guimenuitem> moves the caret to start of the next asset.
 
</para> 
<para>  
<guimenu>Plugins
</guimenu>>
<guisubmenu>SideKick
</guisubmenu>>
<guimenuitem>Select
  Asset at Caret
</guimenuitem> selects the asset at the caret position.
 
</para>
</chapter>
<chapter id="folding">
<title>Folding
</title>
<para>  The SideKick plugin adds a new 
<quote>sidekick
</quote> fold handler that
  folds the buffer according to the structure tree. See the jEdit user's guide
  for general details about folding.

</para>
<para>  
<guimenu>Plugins
</guimenu>>
<guisubmenu>SideKick
</guisubmenu>>
<guimenuitem>Narrow to
  Asset at Caret
</guimenuitem> hides all text except that of the asset at the
  caret location. This works in any folding mode, not just the 
<quote>sidekick
</quote>  mode.
 
</para>
</chapter>
<chapter id="completion">
<title>Completion
</title> 
<para>  A completion popup can be shown at any time
  by invoking the
  
<guimenu>Plugins
</guimenu>>
<guisubmenu>SideKick
</guisubmenu>>
<guimenuitem>Show
  Completion Popup
</guimenuitem> command. Each plugin that uses SideKick
  implements its own specific completion behavior; see the plugin documentation
  for details.
 
</para>
</chapter>
<chapter id="other-plugins">
<title>Developing SideKick back-ends
</title> 
<para>  By itself the SideKick plugin is not very useful; it relies on other plugins to
  provide buffer structure information. This chapter gives a brief overview of
  how it's done.
 
</para> 
<sect1 id="preliminaries">
<title>Preliminaries
</title> 
<para>  First you will also need to add a dependency for the SideKick plugin in your plugin's
  property file:
 
</para> 
<programlisting>plugin.MyPlugin.depend.
<replaceable>n
</replaceable>=plugin sidekick.SideKickPlugin 0.1
</programlisting> 
<para>  Note that you must replace 
<replaceable>n
</replaceable> with the
  appropriate number, as dependency properties must have consecutive numbers.
 
</para> 
<para>  All SideKick plugin classes are in the 
<classname>sidekick
</classname> package;
  you will need to add 
<literal>import
</literal> statements where appropriate.
 
</para> 
<para>  Parser instances must be registered in your plugin's 
<function>start()
</function>  method using the following method in the 
<classname>SideKickPlugin
</classname>  class:
 
</para> 
<funcsynopsis>  
<funcprototype>   
<funcdef>public void 
<function>registerParser
</function>
</funcdef>   
<paramdef>SideKickParser 
<parameter>parser
</parameter>
</paramdef>  
</funcprototype> 
</funcsynopsis> 
<para>  A corresponding method must be called from your plugin's 
<function>stop()
</function>  method:
 
</para> 
<funcsynopsis>  
<funcprototype>   
<funcdef>public void 
<function>unregisterParser
</function>
</funcdef>   
<paramdef>SideKickParser 
<parameter>parser
</parameter>
</paramdef>  
</funcprototype> 
</funcsynopsis> 
</sect1> 
<sect1 id="class-sidekickparser">
<title>The SideKickParser class
</title> 
<para>  
<classname>SideKickParser
</classname> is an abstract class. The constructor
  takes one string parameter. This string is used in several properties:
 
</para> 
<itemizedlist>  
<listitem>
<para>
<literal>sidekick.parser.
<replaceable>name
</replaceable>.label
</literal>  - specifies a human-readable label for the parser, shown in status messages.
  
</para>
</listitem>  
<listitem>
<para>
<literal>mode.
<replaceable>mode
</replaceable>.sidekick.parser
</literal>  - properties of this form are used to associate a parser with an edit mode.
 
</para>
</listitem> 
</itemizedlist> 
<para>  For example, the XML plugin, which provides two 
<classname>SideKickParser
</classname>  implementations, defines these properties:
 
</para> 
<programlisting>sidekick.parser.xml.label=XML
mode.xml.sidekick.parser=xml
mode.xsl.sidekick.parser=xml
sidekick.parser.html.label=HTML
mode.asp.sidekick.parser=html
mode.coldfusion.sidekick.parser=html
mode.html.sidekick.parser=html
mode.jhtml.sidekick.parser=html
mode.jsp.sidekick.parser=html
mode.php.sidekick.parser=html
mode.shtml.sidekick.parser=html
mode.sgml.sidekick.parser=html
mode.velocity.sidekick.parser=html
</programlisting>
</sect1>
<sect1 id="implement-structure-tree">
<title>Implementing a structure tree
</title> 
<para>  The 
<classname>SideKickParser
</classname> has one abstract method that all
  subclasses must implement:
 
</para> 
<funcsynopsis>  
<funcprototype>   
<funcdef>public SideKickParsedData 
<function>parse
</function>
</funcdef>   
<paramdef>Buffer 
<parameter>buffer
</parameter>
</paramdef>   
<paramdef>DefaultErrorSource 
<parameter>errorSource
</parameter>
</paramdef>  
</funcprototype> 
</funcsynopsis> 
<para>  The latter parameter is an instance of a class provided by the
  
<application>ErrorList
</application> plugin; consult its documentation for
  details.
 
</para> 
<para>  The method is called from a thread, so care must be taken to access the
  buffer in a thread-safe manner; the API documentation for the
  
<classname>Buffer
</classname> class describes how this is done.
 
</para> 
<para>  The constructor of the 
<classname>SideKickParsedData
</classname> class takes
  one parameter, which is the file name (to be shown at the root of the structure
  tree).
 
</para> 
<para>  Your implementation of the 
<function>parse()
</function> method should add
  structure elements to the 
<varname>root
</varname> field of the
  
<classname>SideKickParsedData
</classname> instance. This field is an
  instance of Java's 
<classname>DefaultMutableTreeNode
</classname> class,
  and is given a value by the 
<classname>SideKickParsedData
</classname> constructor.
 
</para> 
</sect1> 
<sect1 id="implement-completion">
<title>Implementing completion popups
</title> 
 
<para>  This part has not been written yet. Use the source, Luke!
 
</para> 
</sect1>
</chapter>
<appendix id="changes">
<title>Change log
</title> 
<itemizedlist>  
<listitem>
<para>
<emphasis role="bold">Version 0.1
</emphasis> requires
  jEdit 4.1pre11.
</para>  
<itemizedlist>   
<listitem>
<para>Initial release.
   
</para>
</listitem>  
</itemizedlist>  
</listitem> 
</itemizedlist>
</appendix>
</book>