[1960] | 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>><guisubmenu>SideKick</guisubmenu>><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>><guisubmenu>SideKick</guisubmenu>><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>><guisubmenu>SideKick</guisubmenu>><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>><guisubmenu>Error |
---|
| 78 | List</guisubmenu>><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>><guisubmenu>SideKick</guisubmenu>><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>><guisubmenu>SideKick</guisubmenu>><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>><guisubmenu>SideKick</guisubmenu>><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>><guisubmenu>SideKick</guisubmenu>><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>><guisubmenu>SideKick</guisubmenu>><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 |
---|
| 227 | mode.xml.sidekick.parser=xml |
---|
| 228 | mode.xsl.sidekick.parser=xml |
---|
| 229 | sidekick.parser.html.label=HTML |
---|
| 230 | mode.asp.sidekick.parser=html |
---|
| 231 | mode.coldfusion.sidekick.parser=html |
---|
| 232 | mode.html.sidekick.parser=html |
---|
| 233 | mode.jhtml.sidekick.parser=html |
---|
| 234 | mode.jsp.sidekick.parser=html |
---|
| 235 | mode.php.sidekick.parser=html |
---|
| 236 | mode.shtml.sidekick.parser=html |
---|
| 237 | mode.sgml.sidekick.parser=html |
---|
| 238 | mode.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> |
---|