source: XMLF90-doc/Examples/sax/count/big-file.xml @ 1160

Last change on this file since 1160 was 6, checked in by ymipsl, 13 years ago

Import des sources XMLF90

File size: 9.7 KB
Line 
1<?xml version="1.0"?>
2
3<!-- SideKick user's guide -->
4<!-- (C) 2003 Slava Pestov -->
5
6<!-- jEdit buffer-local properties: -->
7<!-- :indentSize=1:noTabs=true:folding=sidekick: -->
8
9<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
10  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
11
12<book>
13
14<bookinfo><title>SideKick plugin user's guide</title>
15
16 <authorgroup>
17  <author><firstname>Slava</firstname><surname>Pestov</surname></author>
18 </authorgroup>
19
20 <legalnotice><title>Legal Notice</title>
21  <para>
22   Permission is granted to copy, distribute and/or modify this document
23   under the terms of the GNU Free Documentation License, Version 1.1 or
24   any later version published by the Free Software Foundation; with no
25   <quote>Invariant Sections</quote>, <quote>Front-Cover Texts</quote> or
26   <quote>Back-Cover Texts</quote>, each as defined in the license. A copy of
27   the license can be found in the file <filename>COPYING.DOC.txt</filename>
28   included with jEdit.
29  </para>
30  <para>
31   The SideKick plugin itself is released under the GNU General Public License.
32   A copy of the GPL can be found in the jEdit online help.
33  </para>
34 </legalnotice>
35</bookinfo>
36
37<chapter id="browser"><title>The structure browser window</title>
38
39 <para>
40  The SideKick plugin provides a dockable window in which other plugins can
41  display buffer structure.
42 </para>
43
44 <para>
45  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Structure
46  Browser</guimenuitem> displays the current buffer's structure in a
47  dockable window. This window is floating by
48  default, but it can be docked into the view in the <guibutton>Docking</guibutton>
49  pane of the <guimenuitem>Global Options</guimenuitem> dialog box.
50 </para>
51
52 <para>
53  The SideKick plugin automatically parses buffers
54  when they are loaded or saved, where possible.
55  Optionally, buffers can also be parsed on the fly, but this uses a fair bit of
56  memory and processor power so it is disabled by default.
57 </para>
58
59 <para>
60  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Parse
61  on Keystroke</guimenuitem> is a checkbox menu item that toggles on-the-fly
62  parsing, for the current buffer only.
63 </para>
64
65 <para>
66  The current buffer can be parsed at any other time by clicking the parse
67  button in the <guimenuitem>Structure Browser</guimenuitem> window, or by
68  invoking the
69  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Parse
70  Buffer</guimenuitem> command.
71 </para>
72
73 <para>
74  Any errors found while parsing the buffer are sent to the
75  <application>ErrorList</application> plugin, which means they are highlighted
76  in the text area, and shown in the
77  <guimenu>Plugins</guimenu>&gt;<guisubmenu>Error
78  List</guisubmenu>&gt;<guimenuitem>Error List</guimenuitem> window. See the
79  documentation for the <application>ErrorList</application> plugin for details.
80 </para>
81
82 <para>
83  Clicking on a node in the tree will move the caret to its location in the
84  buffer;
85  conversely, moving the caret in the buffer will select the corresponding
86  node.
87 </para>
88
89 <para>
90  <keycap>Shift</keycap>-clicking on a node will select that node in the text
91  area. <keycap>Alt</keycap>-clicking on a node will narrow the text area
92  display to that node.
93 </para>
94
95 <para>
96  If the structure browser window is docked into the current view, hovering the mouse
97  over a node will display its attributes in the status bar.
98 </para>
99
100</chapter>
101
102<chapter id="moving-around"><title>Moving around</title>
103
104<para>
105  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Go
106  to Previous Asset</guimenuitem> moves the caret to start of the structure
107  element (<quote>asset</quote>).
108 </para>
109
110 <para>
111  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Go
112  to Next Asset</guimenuitem> moves the caret to start of the next asset.
113 </para>
114
115 <para>
116  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Select
117  Asset at Caret</guimenuitem> selects the asset at the caret position.
118 </para>
119
120</chapter>
121
122<chapter id="folding"><title>Folding</title>
123
124<para>
125  The SideKick plugin adds a new <quote>sidekick</quote> fold handler that
126  folds the buffer according to the structure tree. See the jEdit user's guide
127  for general details about folding.
128</para>
129
130<para>
131  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Narrow to
132  Asset at Caret</guimenuitem> hides all text except that of the asset at the
133  caret location. This works in any folding mode, not just the <quote>sidekick</quote>
134  mode.
135 </para>
136</chapter>
137
138<chapter id="completion"><title>Completion</title>
139
140 <para>
141  A completion popup can be shown at any time
142  by invoking the
143  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Show
144  Completion Popup</guimenuitem> command. Each plugin that uses SideKick
145  implements its own specific completion behavior; see the plugin documentation
146  for details.
147 </para>
148
149</chapter>
150
151<chapter id="other-plugins"><title>Developing SideKick back-ends</title>
152
153 <para>
154  By itself the SideKick plugin is not very useful; it relies on other plugins to
155  provide buffer structure information. This chapter gives a brief overview of
156  how it's done.
157 </para>
158
159 <sect1 id="preliminaries"><title>Preliminaries</title>
160
161 <para>
162  First you will also need to add a dependency for the SideKick plugin in your plugin's
163  property file:
164 </para>
165
166 <programlisting>plugin.MyPlugin.depend.<replaceable>n</replaceable>=plugin sidekick.SideKickPlugin 0.1</programlisting>
167
168 <para>
169  Note that you must replace <replaceable>n</replaceable> with the
170  appropriate number, as dependency properties must have consecutive numbers.
171 </para>
172
173 <para>
174  All SideKick plugin classes are in the <classname>sidekick</classname> package;
175  you will need to add <literal>import</literal> statements where appropriate.
176 </para>
177
178 <para>
179  Parser instances must be registered in your plugin's <function>start()</function>
180  method using the following method in the <classname>SideKickPlugin</classname>
181  class:
182 </para>
183
184 <funcsynopsis>
185  <funcprototype>
186   <funcdef>public void <function>registerParser</function></funcdef>
187   <paramdef>SideKickParser <parameter>parser</parameter></paramdef>
188  </funcprototype>
189 </funcsynopsis>
190
191 <para>
192  A corresponding method must be called from your plugin's <function>stop()</function>
193  method:
194 </para>
195
196 <funcsynopsis>
197  <funcprototype>
198   <funcdef>public void <function>unregisterParser</function></funcdef>
199   <paramdef>SideKickParser <parameter>parser</parameter></paramdef>
200  </funcprototype>
201 </funcsynopsis>
202
203 </sect1>
204
205 <sect1 id="class-sidekickparser"><title>The SideKickParser class</title>
206
207 <para>
208  <classname>SideKickParser</classname> is an abstract class. The constructor
209  takes one string parameter. This string is used in several properties:
210 </para>
211
212 <itemizedlist>
213  <listitem><para><literal>sidekick.parser.<replaceable>name</replaceable>.label</literal>
214  - specifies a human-readable label for the parser, shown in status messages.
215  </para></listitem>
216  <listitem><para><literal>mode.<replaceable>mode</replaceable>.sidekick.parser</literal>
217  - properties of this form are used to associate a parser with an edit mode.
218 </para></listitem>
219 </itemizedlist>
220
221 <para>
222  For example, the XML plugin, which provides two <classname>SideKickParser</classname>
223  implementations, defines these properties:
224 </para>
225
226 <programlisting>sidekick.parser.xml.label=XML
227mode.xml.sidekick.parser=xml
228mode.xsl.sidekick.parser=xml
229sidekick.parser.html.label=HTML
230mode.asp.sidekick.parser=html
231mode.coldfusion.sidekick.parser=html
232mode.html.sidekick.parser=html
233mode.jhtml.sidekick.parser=html
234mode.jsp.sidekick.parser=html
235mode.php.sidekick.parser=html
236mode.shtml.sidekick.parser=html
237mode.sgml.sidekick.parser=html
238mode.velocity.sidekick.parser=html</programlisting>
239
240</sect1>
241
242<sect1 id="implement-structure-tree"><title>Implementing a structure tree</title>
243
244 <para>
245  The <classname>SideKickParser</classname> has one abstract method that all
246  subclasses must implement:
247 </para>
248
249 <funcsynopsis>
250  <funcprototype>
251   <funcdef>public SideKickParsedData <function>parse</function></funcdef>
252   <paramdef>Buffer <parameter>buffer</parameter></paramdef>
253   <paramdef>DefaultErrorSource <parameter>errorSource</parameter></paramdef>
254  </funcprototype>
255 </funcsynopsis>
256
257 <para>
258  The latter parameter is an instance of a class provided by the
259  <application>ErrorList</application> plugin; consult its documentation for
260  details.
261 </para>
262
263 <para>
264  The method is called from a thread, so care must be taken to access the
265  buffer in a thread-safe manner; the API documentation for the
266  <classname>Buffer</classname> class describes how this is done.
267 </para>
268
269 <para>
270  The constructor of the <classname>SideKickParsedData</classname> class takes
271  one parameter, which is the file name (to be shown at the root of the structure
272  tree).
273 </para>
274
275 <para>
276  Your implementation of the <function>parse()</function> method should add
277  structure elements to the <varname>root</varname> field of the
278  <classname>SideKickParsedData</classname> instance. This field is an
279  instance of Java's <classname>DefaultMutableTreeNode</classname> class,
280  and is given a value by the <classname>SideKickParsedData</classname> constructor.
281 </para>
282
283 </sect1>
284
285 <sect1 id="implement-completion"><title>Implementing completion popups</title>
286 
287 <para>
288  This part has not been written yet. Use the source, Luke!
289 </para>
290
291 </sect1>
292
293</chapter>
294
295<appendix id="changes"><title>Change log</title>
296
297 <itemizedlist>
298
299  <listitem><para><emphasis role="bold">Version 0.1</emphasis> requires
300  jEdit 4.1pre11.</para>
301
302  <itemizedlist>
303   <listitem><para>Initial release.
304   </para></listitem>
305  </itemizedlist>
306
307  </listitem>
308
309 </itemizedlist>
310
311</appendix>
312
313</book>
Note: See TracBrowser for help on using the repository browser.