PageRenderTime 133ms CodeModel.GetById 118ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/bundles/plugins-trunk/XML/docs/users-guide.xml

#
XML | 951 lines | 791 code | 156 blank | 4 comment | 0 complexity | 61e710f9ddd1ea271a83b1f2fa4a59de MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8"?>
  2<article xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  3    xsi:noNamespaceSchemaLocation='http://www.docbook.org/xsd/4.4/docbook.xsd' >
  4 <!-- 
  5 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookx.dtd"> -->
  6  <title>XML plugin user's guide</title>
  7
  8 <articleinfo>
  9
 10 <releaseinfo>Version 2.8.2</releaseinfo>
 11
 12 <authorgroup>
 13  <author><firstname>Slava</firstname><surname>Pestov</surname></author>
 14  <author><firstname>Dale</firstname><surname>Anson</surname></author>
 15  <author><firstname>Eric</firstname><surname>Le Lay</surname></author>
 16  <author><firstname>Robert</firstname><surname>McKinnon</surname></author>
 17  <author><firstname>Martin</firstname><surname>Raspe</surname></author>
 18  <author><firstname>Jakub</firstname><surname>Roztocil</surname></author> 
 19  <author><firstname>Alan</firstname><surname>Ezust</surname></author>
 20 </authorgroup>
 21
 22 <legalnotice><title>Legal Notice</title>
 23  <para>
 24   Permission is granted to copy, distribute and/or modify this document
 25   under the terms of the GNU Free Documentation License, Version 1.1 or
 26   any later version published by the Free Software Foundation; with no
 27   <quote>Invariant Sections</quote>, <quote>Front-Cover Texts</quote> or
 28   <quote>Back-Cover Texts</quote>, each as defined in the license. A copy of
 29   the license can be found in the file <filename>COPYING.DOC.txt</filename>
 30   included with jEdit.
 31  </para>
 32  <para>
 33   The XML plugin itself is released under the GNU General Public License.
 34   A copy of the GPL can be found in the jEdit online help.
 35  </para>
 36 <para>
 37  This version of the XML plugin for jEdit combines the <ulink url="docs/htmlsidekick.html">HtmlSideKick</ulink> plugin and EcmaScript parser by Dale Anson, the <ulink url="docs/javascript.html">JavaScriptSideKick</ulink> by Martin Raspe, the CSS SideKick by Jakub Roztocil, and the XmlIndenter plugin by Robert McKinnon, providing five distinct Sidekick parsers and four different completion services, as well as an indenting service for the Beauty plugin, <ulink url="http://iso-relax.sourceforge.net/">ISO-RELAX</ulink> and <ulink url="http://code.google.com/p/jing-trang/">jing-trang</ulink>, for validation and translation of documents that use Relax-NG schemas.
 38 </para>
 39
 40 </legalnotice>
 41</articleinfo>
 42
 43<section id="intro"><title>Introduction</title>
 44
 45 <para>
 46  This documentation assumes at least basic knowlege of HTML and XML.
 47 </para>
 48
 49 <para> The XML plugin makes jEdit one of the most advanced free Website editing tools available.
 50 It combines parsers for XML, HTML, JSP, Sidekick,  and CSS files. Here are its features: </para>
 51
 52 <itemizedlist>
 53  <listitem><para>On-the-fly validation of XML files with DTD, XSD, or RNG schemas. </para></listitem>
 54  <listitem><para>Tag, attribute, and entity completion popups for XML, HTML and CSS</para></listitem>
 55  <listitem><para>Display of the element tree in a dockable window, for XML, HTML, JavaScript, JSP, and CSS</para></listitem>
 56  <listitem><para>Matching tag highlighting</para></listitem>
 57  <listitem><para>One click insertion of tags and entities</para></listitem>
 58  <listitem><para>Graphical form to edit tags and attributes</para></listitem>
 59  <listitem><para>With a keystroke, jump to matching tag or bracket</para></listitem>
 60  <listitem><para>And more. </para></listitem>
 61
 62 </itemizedlist>
 63 
 64 <bridgehead>XML and SideKick</bridgehead>
 65 <para>
 66 To provide most of its functionality, the XML plugin relies on
 67 the SideKick plugin. What this means is that Sidekick must be enabled, and
 68 docked (preferably to your right or left) and parsing your current buffer
 69 in order for certain operations to succeed.  Select Plugins - SideKick -
 70 SideKick, and click on the little arrow, which is the docking menu in the
 71 upper left corner, to set its docked position. </para>
 72
 73 <para> Note: Since the XML plugin provides a separate Sidekick parser for HTML versus XML, and it may be possible to parse some documents with both, you may get different results depending on how 'strict' the HTML/XML syntax is used in the document. </para>
 74
 75 <bridgehead>XML and other plugins</bridgehead>
 76 
 77 <para>The XML plugin can take advantage of other plugins, in addition to the required
 78 ones like Sidekick.</para>
 79 
 80 <itemizedlist>
 81 <listitem><para>If you want to follow hyperlinks in HTML or XML, you'll have to install the
 82 <emphasis>Hyperlinks</emphasis> plugin.</para></listitem>
 83 <listitem><para>The XML plugin comes with templates for a few common HTML and XML document types
 84 (e.g. HTML 4.01 strict, XSD, XSL).To use them, install the <emphasis>Templates</emphasis> plugin
 85 and restart jEdit.</para></listitem>
 86 </itemizedlist>
 87 
 88</section>
 89
 90<section id="insert">
 91<title>The XML insert window</title>
 92
 93 <para>
 94  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>XML
 95  Insert</guimenuitem> displays the XML insert window. This window is floating by default, but it can be docked into the view from the dock menu (a little arrow in the upper right corner), or from the <guibutton>Docking</guibutton> pane of the
 96  <guimenuitem>Global Options</guimenuitem> dialog box.
 97 </para>
 98
 99 <para>
100  This window lists elements that may be inserted at the caret position,
101  all declared entities, and all IDs (element attributes
102  with a value type of <property>ID</property>).
103 </para>
104
105 <para>
106  Clicking an element in the list with the left mouse button
107  will insert it into the buffer and show
108  the <guimenuitem>Edit Tag</guimenuitem> dialog box for specifying attributes.
109  See <xref linkend="edit-tag" /> for information about the
110  <guimenuitem>Edit Tag</guimenuitem> dialog box. Clicking an element
111  with the right mouse button will insert it in the text area, but the
112  <guimenuitem>Edit Tag</guimenuitem> dialog box will not be shown.
113 </para>
114
115 <para>
116  Clicking an entity will insert it into the buffer.
117 </para>
118
119 <para>
120  Clicking an ID with the left mouse button will insert it into the buffer;
121  clicking with the right mouse button will move the caret to the element
122  that declares it.
123 </para>
124
125 <para>
126  If text is selected, each selection is wrapped in a pair of opening and
127  closing tags. This is a very powerful feature; you can select any number
128  of text chunks, and surround them with tags, all sharing a common set of
129  attributes.
130 </para>
131
132</section>
133
134
135<section id="edit-tag"><title>The edit tag dialog box</title>
136
137 <para>
138  The <guimenuitem>Edit Tag</guimenuitem> dialog box can be opened in any of these ways:
139 </para>
140
141 <itemizedlist>
142  <listitem><para>Invoking
143  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Edit
144  Tag at Caret</guimenuitem>.
145  </para></listitem>
146  <listitem><para>Double-clicking a tag in the text area while holding down
147  <keycap>Control</keycap>.</para></listitem>
148  <listitem><para> Hitting return in the completion dialog, if the option is set from the XML Options. </para></listitem>
149  <listitem><para> Clicking on an element from the XML Insert dockable. </para></listitem>
150  </itemizedlist>
151
152  <para>
153  The dialog box lists all declared attributes for the current tag in a
154  table. The columns of the table are as follows:
155 </para>
156
157 <itemizedlist>
158  <listitem><formalpara><title>Set</title><para>A check box that controls
159  if the attribute is specified or not. Required attributes are always
160  specified.</para></formalpara></listitem>
161
162  <listitem><formalpara><title>Name</title><para>The name of the
163  attribute.</para></formalpara></listitem>
164
165  <listitem><formalpara><title>Type</title><para>This will either be
166  <quote>text</quote> or <quote>choice</quote>. If the attribute is
167  required, <quote>required</quote> will be
168  appended.</para></formalpara></listitem>
169
170  <listitem><formalpara><title>Value</title><para>For
171  <quote>text</quote> attributes, this is a text field.
172  For <quote>choice</quote> attributes, this is a combo
173  box. Depending on the schema, some attributes might define a default value.</para></formalpara>
174
175  <para>
176   Note that special characters entered in the text field are
177   automatically converted to entities if necessary.
178  </para></listitem>
179 </itemizedlist>
180
181 <para>
182  The <guilabel>Preview</guilabel> text field shows what the tag will look
183  like with all currently-specified attributes. Clicking
184  <guibutton>OK</guibutton> will insert the tag into the buffer.
185 </para>
186
187</section>
188
189<section id="misc-commands"><title>Miscellaneous features</title>
190
191 <para>
192  If the caret is positioned on a tag, the corresponding opening or closing
193  tag will be highlighted in the text area. You can disable this feature,
194  or change the tag highlight color in the
195  <guibutton>XML</guibutton>&gt;<guibutton>Xml</guibutton> pane of the <guimenu>Plugins</guimenu>&gt;<guimenuitem>Plugin Options</guimenuitem>
196  dialog box.
197 </para>
198
199 <para>
200  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Go
201  to Matching Tag</guimenuitem> moves the caret to the corresponding opening or
202  closing tag.
203 </para>
204
205 <para>
206  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Close
207  Last Open Tag</guimenuitem> inserts a closing tag for the last opened tag.
208 </para>
209
210 <para>
211  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Remove
212  All Tags</guimenuitem> removes all tags from the current buffer, leaving
213  only text.
214 </para>
215
216 <para>
217  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Split
218  Tag</guimenuitem> splits the current tag at the cursor, and creates a new tag at the same
219  level. This is useful when editing HTML, DocBook or similar documents, for inserting
220  many <literal>&lt;p&gt;</literal> or <literal>&lt;para&gt;</literal> tags.
221  This command tries
222  to match the current indenting style.
223 </para>
224
225 <para>
226  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Characters
227  to Entities</guimenuitem> converts special characters to entities in the
228  current selection.
229 </para>
230
231 <para>
232  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Entities
233  to Characters</guimenuitem> converts entities to characters in the
234  current selection.
235 </para>
236
237 <para>
238  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Generate
239  DTD</guimenuitem> generates a DTD from the XML instance document in the
240  current buffer. Generation of XSD and RelaxNG schemata is planned for the future.
241 </para>
242
243 <para>
244  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Copy XPath
245  </guimenuitem> inserts in the clipboard an XPath to current element. For instance,
246  if the caret is inside the style element of an HTML page, <guimenuitem>Copy XPath</guimenuitem>
247  will copy <code>/html/head[1]/style[1]</code> in the clipboard. This might be useful
248  when writing an XSL template over a complex document.
249  <guimenuitem>Copy XPath</guimenuitem> should handle namespaces and prefixes gracefully :
250 </para>
251 <itemizedlist>
252 	<listitem><para>namespaces and local-names are used for comparison - not prefixes,
253 	though prefixes found in the document are retained;
254 	</para></listitem>
255 	<listitem><para>only the first of 2 prefixes bound to the same namespace in the source
256 	document will be used in the XPath;
257 	</para></listitem>
258 	<listitem><para>if the same prefix is bound to different namespaces, the second
259 	instance of the prefix will get a numbered suffix to distinguish it in the XPath.
260 	</para></listitem>
261 	
262 </itemizedlist>
263
264
265</section>
266
267 <section id="schemas"><title>Schemas</title>
268 <para>
269  DTDs or Document Type Definitions, are a common way to specify schemas.
270  While an older standard, are still widely used.
271  Buffers which have an associated DTD are validated for errors, and
272  completion popups are shown for elements, attributes, and entities.
273  DTDs are specified by including markup like the following near the start
274  of an XML file:
275 </para>
276 <programlisting><![CDATA[<?xml version="1.0"?>
277 <!DOCTYPE PUBLIC "]]><replaceable>public ID</replaceable>" "<replaceable>system ID</replaceable>"&gt;
278 </programlisting>
279 <para>
280  Or alternatively:
281 </para>
282 <programlisting><![CDATA[<?xml version="1.0"?>
283 <!DOCTYPE SYSTEM "]]><replaceable>system ID</replaceable>">
284 </programlisting>
285
286 <para>
287  XSDs, or XML schemas, perform a similar function to DTDs, however they are a newer
288  standard and support some features that DTDs do not, like namespaces.
289  Buffers which have an associated schema are validated for errors, and
290  completion popups are shown for elements and entities.
291 </para>
292 <para>
293  Schemas are specified with a
294  <markup>http://www.w3.org/2001/XMLSchema-instance</markup> namespace in the document's root element:
295 </para>
296 <programlisting><![CDATA[<personnel
297          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
298          xsi:noNamespaceSchemaLocation='personal.xsd'>]]></programlisting>
299 <para>
300  Or if the target schema has an associated namespace:
301 </para>
302 <programlisting><![CDATA[<dictionary           xmlns="http://www.xml-cml.org/schema/stmml"
303          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
304          xsi:schemaLocation="http://www.xml-cml.org/schema/stmml ../schema/stmml.xsd
305          http://www.xml-cml.org/schema/cml2/core ../schema/cmlCore.xsd">]]></programlisting>
306 <para>
307  In all cases, the XML parser will first look for the specified system or
308  public ID in the plugin's built-in catalog, along with any
309  catalog files specified in the
310  <guibutton>XML</guibutton>&gt;<guibutton>Catalogs</guibutton> pane
311  of the <guimenu>Plugins</guimenu>&gt;<guimenuitem>Plugin Options</guimenuitem> dialog box. </para>
312 <para>
313  Catalog files must either be in OASIS OPEN or XML catalog format. These two formats
314  are documented below.
315 </para>
316
317 <para>
318  If the DTD or XSD cannot be located in the catalogs, the plugin will ask if it should be downloaded and cached for future use in the <filename>dtds</filename>
319  subdirectory of the jEdit settings directory.
320 </para>
321 <para>
322  The download cache can be cleared using the
323  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;<guimenuitem>Clear
324  DTD Cache</guimenuitem> command.
325 </para>
326
327 <section id="built-in-dtds"><title>Built-in DTDs</title>
328
329  <para>
330   The XML plugin catalogs the following DTDs which are included with jEdit itself, or the XML plugin.
331  </para>
332
333  <itemizedlist>
334  <listitem><para>DTDs declared by jEdit: <filename>actions.dtd</filename>,
335  <filename>catalog.dtd</filename>,
336  <filename>dockables.dtd</filename>,
337  <filename>perspective.dtd</filename>,
338  <filename>plugins.dtd</filename>,
339  <filename>recent.dtd</filename>,
340  <filename>registers.dtd</filename>,
341  <filename>services.dt</filename>,
342  <filename>xmode.dtd</filename>.</para></listitem>
343  <listitem><para>A few plugin DTDs: <filename>commando.dtd</filename> (Console
344  plugin), <filename>sqlServerType.dtd</filename> (SQL plugin).</para></listitem>
345  <listitem><para>XHTML 1.0 and XHTML 1.1 DTDs, referenced using one of the
346  following public IDs:</para>
347  <itemizedlist>
348  <listitem><para><literal>-//W3C//DTD XHTML 1.0 Frameset//EN</literal></para></listitem>
349  <listitem><para><literal>-//W3C//DTD XHTML 1.0 Strict//EN</literal></para></listitem>
350  <listitem><para><literal>-//W3C//DTD XHTML 1.0 Transitional//EN</literal></para></listitem>
351  <listitem><para><literal>-//W3C//DTD XHTML 1.1//EN</literal></para></listitem>
352  </itemizedlist>
353  </listitem>
354    <listitem><para>DocBook 4.4 DTDs, referenced with the
355  <literal>-//OASIS//DTD DocBook XML V4.4//EN</literal> public ID.
356  </para></listitem>
357
358 </itemizedlist>
359 <para> For example, these doctypes are recognized by the XML plugin, and when they are used, tell the XML plugin to load a built-in DTD, and provide you with completion popups for elements and attributes.
360 </para>
361
362 <programlisting>
363&lt;!DOCTYPE book PUBLIC &quot;-//OASIS//DTD DocBook XML V4.4//EN&quot;   &quot;docbookx.dtd&quot;&gt;
364&lt;!DOCTYPE html PUBLIC &quot;-//W3C//DTD XHTML 1.1//EN&quot; &quot;xhtml11-flat.dtd&quot;&gt;
365 </programlisting>
366
367 </section>
368
369</section>
370
371
372<section id="completion">
373  <title>Tag and entity completion</title>
374
375 <para>
376  If the less-than symbol (<quote>&lt;</quote>) is typed and no other key
377  is pressed within a
378  specified delay (half a second by default), a tag list popup will be
379  shown. Note that only tags which the parent element is
380  allowed to contain are listed. The arrow keys can be used to select a tag;
381  if you start
382  typing a tag name, only tags whose names begin with the already-entered
383  text will be shown.
384 </para>
385
386 <para>
387  Pressing <keycap>Space</keycap> or <keycap>&gt;</keycap> will insert
388  the currently selected
389  tag into the buffer. Pressing <keycap>Enter</keycap> will insert
390  the tag and show the <guimenuitem>Edit Tag</guimenuitem> dialog box;
391  see <xref linkend="edit-tag" />.
392 </para>
393
394 <para> Attribute Completion works in a similar manner - when the XML plugin
395 detects that you are inside a tag and about to enter an attribute name, it will
396 provide you with a list of possible attributes or completions of attributes
397 if it can obtain this information from the schema. </para>
398
399 <para>
400  Entity completion works in a similar manner; typing
401  <keycap>&amp;</keycap> will show an entity list popup. Pressing
402  <keycap>Space</keycap>, <keycap>Enter</keycap> or <keycap>;</keycap>
403  will insert the currently selected entity into the buffer.
404 </para>
405
406 <para>
407  Typing <quote>&lt;/</quote> will automatically close
408  the last open tag.
409 </para>
410
411 <para>
412  Another convenient feature inserts a
413  closing tag when you finish typing an opening tag. It is disabled by default,
414  but can be activated from the plugin options.
415 </para>
416
417 <para>
418  These features can be enabled, disabled and configured in the
419  <guibutton>SideKick</guibutton> and
420  <guibutton>XML</guibutton>&gt;<guibutton>XML</guibutton> pane of the <guimenu>Plugins</guimenu>&gt;<guimenuitem>Plugin Options</guimenuitem>
421  dialog box.
422 </para>
423
424 <section id="builtin-completion-info"><title>Built-in completion information</title>
425
426  <para>
427   The XML plugin supports element and entity completion for the following file types using completion information built in to the plugin:
428  </para>
429
430  <itemizedlist>
431
432   <listitem><para>HTML files </para></listitem>
433   <listitem><para>XSL stylesheets (xsl) </para></listitem>
434   <listitem><para>XSD XML schema definitions </para></listitem>
435   <listitem><para><filename>build.xml</filename> - Ant build files </para></listitem>
436  </itemizedlist>
437 </section>
438</section>
439
440<section id="validation">
441<title>Validation</title>
442
443<para>
444  XML files are validated against their DTD, XSD or RNG schema. If no schema can be loaded, only minimal error checking will be performed. No validation of any kind is performed for HTML files, but XHTML files can be validated using their regular schema.
445 </para>
446
447 <para>
448  Any errors found while parsing XML are handled by the
449  <application>ErrorList</application> plugin; in other words, they are highlighted
450  in the text area, and shown in the
451  <guimenu>Plugins</guimenu>&gt;<guisubmenu>Error
452  List</guisubmenu>&gt;<guimenuitem>Error List</guimenuitem> window. See the
453  documentation for the <application>ErrorList</application> plugin for details.
454 </para>
455
456 <para>
457  DTDs (document type definitions), XSDs (w3c XML Schemas), and Relax-NGs are three different
458  standards for defining XML Schemas, to describe which elements and entities are allowed within a
459  specific context.
460  In order to implement completion or validation, the XML plugin needs to be able to load a schema. A few file types for which no schema is available are supported using built-in completion information included with the plugin.
461 </para>
462
463 <section id="customizing-validation"><title>Customizing validation</title>
464
465 <para>
466  Validation can be disabled on a global basis in the <guibutton>XML</guibutton>&gt;<guibutton>XML</guibutton> pane of the <guimenu>Plugins</guimenu>&gt;<guimenuitem>Plugin Options</guimenuitem> dialog box. It can also be disabled on a per-buffer basis by inserting the following in the first of last 10 lines of the buffer:
467 </para>
468 <programlisting>:xml.validate=false:</programlisting>
469
470 <para>
471  Namespaces processing can be disabled on a per-buffer basis by inserting
472  the following in the first or last 10 lines of the buffer:
473 </para>
474 <programlisting>:xml.namespaces.disable=true:</programlisting>
475 <para>Why would you do that ? If you use the XHTML plus Math 1.1 DTD, you will
476  get an error because the DTD uses a prefixed name <code>IS10744:arch</code>
477  somewhere, which is incompatible with namespaces. The typical error message is :
478  </para>
479  <programlisting>A colon is not allowed in the name XXX when namespaces are enabled.</programlisting>
480
481 <para>
482  DTD Validation can be disabled on a per-buffer basis by inserting
483  the following in the first of last 10 lines of the buffer:
484 </para>
485 <programlisting>:xml.validate.ignore-dtd=true:</programlisting>
486 <para>This way, one can use DTDs for entities and a schema for validation.
487 Here is a sample of what you'd do :
488 <programlisting>
489&lt;!-- :xml.validate.ignore-dtd=true: -->
490&lt;!DOCTYPE article [
491  &lt;!ENTITY % isolat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML" 
492                "http://www.oasis-open.org/docbook/xmlcharent/0.3/iso-lat1.ent" >
493  &lt;!ENTITY % isogrk1 PUBLIC "ISO 8879:1986//ENTITIES Greek Letters//EN//XML"
494                "http://www.oasis-open.org/docbook/xmlcharent/0.3/iso-grk1.ent" >
495  %isolat1;
496  %isogrk1;
497]>
498&lt;article
499    xmlns:xi="http://www.w3.org/2001/XInclude"
500    xsi:noNamespaceSchemaLocation="http://www.docbook.org/xsd/4.4/docbook.xsd"
501    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
502    id="root-article">
503&lt;title>Using entities like &amp;ecute; &lt;/title>
504 </programlisting>
505 </para>
506 </section>
507 
508 <section id="schema-mapping"><title>Finding Schemas</title>
509 
510  <para>
511  Validation will be performed if it is enabled (see <xref linkend="customizing-validation"/>)
512  and if a schema or a DTD can be found.</para>
513  
514  <para>
515  While DTDs and XSD schemas are declared in the
516  document (see <xref linkend="schemas"/>), Relax NG schemas are not declared in the document.
517  Therefore, there must be an external mean of specifying the RNG schema.
518  </para>
519  <para>
520    You can do this:
521  </para>
522  <itemizedlist>
523  <listitem>
524  <para>on a per-buffer basis by inserting the following in the first
525  or last 10 lines of the buffer:
526 </para>
527 <programlisting>:xml.validation.schema=<replaceable>URI to the schema</replaceable>:</programlisting>
528 <para>You can use an absolute or relative URI or even an URI that will be resolved as
529 a system Id by some catalog (e.g. <filename>locate.rng</filename>).
530 </para>
531  </listitem>
532  
533  <listitem>
534  <para>on a per directory and/or global basis, by using schema mapping rules
535  (the so called <filename>schemas.xml</filename>). This is consistent with
536  the <ulink url="http://www.thaiopensource.com/nxml-mode/">nXML</ulink> mode for
537  Emacs (it's even 100% compatible !). These powerful mapping rules
538  work on filenames, paths, root element, namespace, etc.
539  </para>
540  </listitem>
541  
542  </itemizedlist>
543  
544  <para>When the XML plugin parses an XML buffer, it will look for a file named 
545  <filename>schemas.xml</filename> in the same directory. Or, if it doesn't exist,
546  for a global
547  file in the settings directory (under <filename><replaceable>JEDIT_SETTINGS</replaceable>/plugins/xml.XmlPlugin/schemas.xml</filename>),
548  and finally for the built-in file (<filename>XML.jar!/xml/dtds/schemas.xml</filename>).
549  The rules contained in this file are given the public Id, system Id, doctype,
550  prefix, local name, namespace of the parsed document. The first rule to match
551  returns the schema that will be used for validation.
552  </para>
553  
554  <para>You can edit manually these <filename>schemas.xml</filename> files.
555  There is a built-in rule to find their schema, so XML completion and
556  validation should work. The schema is under <filename>xml/dtds/locate.rng</filename>
557  in the XML.jar archive (simply open your mapping document and use 
558  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;
559  <guimenuitem>Open Schema</guimenuitem>).</para>
560  
561  <para>There are also three actions associated with schema mapping :</para>
562  
563  <para>You can set the type of current buffer to a known type via
564  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;
565  <guimenuitem>Set Schema Type...</guimenuitem>. You will be prompted for a type, like :
566  
567  <glosslist>
568  <glossentry>
569  <glossterm>RNG</glossterm>
570  <glossdef><para>for Relax NG Schemas</para></glossdef>
571  </glossentry>
572  <glossentry>
573  <glossterm>LOCATE</glossterm>
574  <glossdef><para>for schemas.xml</para></glossdef>
575  </glossentry>
576  <glossentry>
577  <glossterm>NONE</glossterm>
578  <glossdef><para>for any well formed XML</para></glossdef>
579  </glossentry>
580  </glosslist>
581  
582  </para>
583               
584  <para>You can also directly point to an XSD or RNG schema via
585  <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;
586  <guimenuitem>Set Schema...</guimenuitem>. You will be able to choose
587  a schema file from the VFS browser.
588  </para>
589
590  <warning><para>It does not work from a remote filesystem yet !</para></warning>
591  
592  <para>Both of these actions will create a <filename>schemas.xml</filename> file
593  alongside the current buffer. If such a file exists already, it is updated.
594  </para>
595
596  <warning><para>The current implementation will retain any existing rule,
597  but will erase any comment and any formatting in the document, so
598  beware that all commented-out section of the schema-mapping will disappear
599  next time you use <guimenuitem>Set Schema...</guimenuitem>.
600  </para></warning>
601  
602  <section id="disabling-schema-mapping">
603  <title>Disabling the schema-mapping</title>
604  
605  <para>If, for some reason, you want to disable this schema-mapping mechanism,
606  you can do it on a global basis by unchecking the
607  <guibutton>enable schema mapping</guibutton> checkbox,
608  in the <guibutton>XML</guibutton>&gt;<guibutton>Xml</guibutton> pane of the <guimenu>Plugins</guimenu>&gt;<guimenuitem>Plugin Options</guimenuitem>.
609  </para>
610  
611  <para>You can also disable schema-mapping on a per-buffer basis (let's say on a file in a read-only directory),
612  by inserting the following in the first or last 10 lines of the buffer:
613 </para>
614 <programlisting>:xml.enable-schema-mapping=false:</programlisting>
615
616 <para>The XML parser will no more try to find a schema using <filename>schemas.xml</filename>.
617 However, it will still pick a schema defined via a buffer-local property in a buffer,
618 or if you set a schema via <guimenuitem>Set Schema...</guimenuitem> or <guimenuitem>Set Schema Type...</guimenuitem>.
619  </para>
620  
621  <para>What will happen if you use <guimenuitem>Set Schema...</guimenuitem> 
622  and schema-mapping is disabled is that
623  the chosen schema won't be saved and any existing <filename>schemas.xml</filename>
624  in the same directory won't be updated. You will have to select the schema
625  again next time you edit the buffer.
626  </para>
627  <para> Conversely, <guimenuitem>Set Schema Type...</guimenuitem> will still work.
628  It will even propose you schema types defined in a <filename>schemas.xml</filename>
629  in the same directory as the buffer. However, the schema-type won't be saved
630  and the <filename>schemas.xml</filename> won't be updated.
631  Also, if you update the definition of the typeId (ie. you change its target to another
632  schema), the schema defined for the buffer won't be updated and you'll have to do
633  <guimenuitem>Set Schema Type...</guimenuitem> again.
634  </para>
635 
636 </section>
637
638 <section id="see-schema">
639 <title>Seeing the schema which validated a buffer</title>
640  <para>Finally, <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;
641  <guimenuitem>Open Schema</guimenuitem> will let you see the schema associated
642  to current buffer, regardless of wether it is specified as a buffer-local property,
643  via the menu item, or via a schema-mapping rule.</para>
644  </section>
645 </section>
646  
647</section>
648
649<section id="translate"><title>Translating between schemas</title>
650
651<para>Thanks to Trang's schema translation capabilities, you will be able to translate
652from any of DTD, RNG, RNC, XML instances to DTD, RNG, RNC, XSD.
653</para>
654
655<para>Trang (<uri>http://www.thaiopensource.com/relaxng/trang.html</uri>, James Clark and others) 
656is Copyright Š 2002, 2003, 2008 Thai Open Source Software Center Ltd.</para>
657
658<para>A copy of its user-guide is included <ulink url="docs/trang-manual.html">here</ulink>.</para>
659
660<para>You may do a basic conversion of current buffer using the
661<code>xml-translate-to-dtd</code>, <code>xml-translate-to-rnc</code>, <code>xml-translate-to-rng</code>,
662<code>xml-translate-to-xsd</code> actions.</para>
663
664<para>You may specify advanced options using <guimenu>Plugins</guimenu>&gt;<guisubmenu>XML</guisubmenu>&gt;
665  <guimenuitem>Translate Schema using Trang</guimenuitem>.
666  The meaning of each parameter is described in Trang's user manual (<ulink url="docs/trang-manual.html"/>).
667</para>
668
669<para>The output of Trang is converted to jEdit buffers, so that you may review them before saving.
670Any existing file will be overwritten but you'll get its contents back, using <guimenuitem>
671undo</guimenuitem>.</para>
672
673</section>
674
675<section id="include">
676<title>XML Inclusion</title>
677
678<para>It is sometimes necessary to split a long XML document into smaller parts,
679or to assemble parts in different ways. This can be achieved via external entities (a DTD feature)
680or via <ulink url="http://www.w3.org/TR/xinclude/">XInclude</ulink>.
681</para>
682
683<section id="child-documents">
684<title> Child Documents </title>
685 <para>
686  When editing an XML file which is included from another file, it can be desirable for validation to always start at the root file, rather than the one that is currently being edited.
687  For example, you might be writing a user manual using DocBook, with each chapter split into its own XML file. This can be achieved by inserting the following in the first or last 10 lines of each child file:
688 </para>
689 <programlisting>:xml.root=<replaceable>relative or absolute path of root document</replaceable></programlisting>
690
691 <para>
692  Note that even if this property is specified, the <guimenuitem>Structure Browser</guimenuitem> window only shows elements defined in the current buffer. However, when validating an included file, validation errors will be reported for all files included from the root file.
693 </para>
694</section>
695
696<section id="include-entities">
697<title>External entities</title>
698
699<para>External entities were used in the user guide for jEdit 4.4 and earlier (see <xref linkend="include-entities-1"/>).
700The <code>DOCTYPE</code> declaration lists some entities,
701which are referenced via <code>&amp;your_entity;</code>.
702This is similar to <code>#include</code> directives in C or C++.
703</para>
704
705<programlisting id="include-entities-1" xreflabel="excerpt of users-guide.xml">
706<![CDATA[
707<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
708"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
709
710<!ENTITY conventions SYSTEM "conventions.xml">
711
712]>
713
714<book>
715<title>your title</title>
716
717&conventions;
718</book>
719]]>
720</programlisting>
721
722<para>The inclusion is performed before DTD validation which allows the ID/IDREF
723validation to succeed : ie. a section declared with <code>id="ID1"</code> in one
724file can be referenced from another included file via <code>&lt;xref linkend="ID1"/&gt;</code>.
725For validation in jEdit, you will also need <xref linkend="child-documents"/>.
726</para>
727
728</section>
729
730<section id="include-xinclude">
731<title>XInclude</title>
732
733<blockquote>
734<attribution>XML Inclusions (XInclude) Version 1.0 (Second Edition)
735W3C Recommendation 15 November 2006</attribution>
736
737<para>XInclude defines a namespace associated with the URI
738<code>http://www.w3.org/2001/XInclude</code>.
739The XInclude namespace contains two elements with the local names <code>include</code> and <code>fallback</code>.
740</para>
741</blockquote>
742
743<para>The jEdit 4.5 FAQ and users guide both use
744XIncludes to join together child documents into a
745whole. </para>
746
747
748<para>The following example shows an inclusion similar to <xref linkend="include-entities-1"/>.</para>
749
750
751<programlisting id="include-xinclude-1">
752<![CDATA[
753<book>
754<title>your title</title>
755<xi:include  href="conventions.xml"
756             xmlns:xi="http://www.w3.org/2001/XInclude" />
757</book>
758]]>
759</programlisting>
760
761<para>XInclude can be activated on a global basis in the <guibutton>XML</guibutton>&gt;<guibutton>XML</guibutton>
762pane of the <guimenu>Plugins</guimenu>&gt;<guimenuitem>Plugin Options</guimenuitem> dialog box.
763It can also be activated on a per-buffer basis by inserting the following in the first of last 10 lines of the buffer:
764</para>
765<programlisting>:xml.xinclude=true:</programlisting>
766
767
768<para>You can fine-tune the way relative URIs will be interpreted in the included fragment :
769either resolve the URIs based on the URI of the fragment, or based on the URI of the parent
770(see <uri>http://www.w3.org/TR/xinclude/#base</uri>). This is controlled globally
771 in the option pane or via the property <code>xml.xinclude.fixup-base-uris</code> on a per-buffer
772 basis.</para>
773 <para>See the following example: </para>
774<programlisting>:xml.xinclude=true:xml.xinclude.fixup-base-uris=true:</programlisting>
775
776
777<para>Note that DTD validation would fail on ID/IDREF attributes (<code>id</code>s
778and <code>linkend</code>s). This is because the document seen by the DTD validator
779is prior to XInclude resolution. You are then forced to use either XML Schemas or
780RelaxNG validation.
781For validation in jEdit, you will also need <xref linkend="child-documents"/>.
782</para>
783
784<para>For more informations regarding XInclude and docbook, you should reed
785Chapter 22 of <emphasis>DocBook XSL: The Complete Guide</emphasis> by Bob Stayton :
786<uri>http://docs.huihoo.com/docbook/docbook-xsl-complete-guide-3rd/ModularDoc.html</uri>
787</para>
788
789<para>Xinclude is activated in xsltproc via the <code>--xinclude</code> command-line switch.</para>
790</section>
791</section>
792
793
794
795 <section id="oasis-catalog-format"><title>OASIS OPEN catalog format</title>
796  <para>
797   Each line in an OASIS OPEN catalog file must look like one of the following:
798  </para>
799  <itemizedlist>
800   <listitem><para><literal>-- <replaceable>comment</replaceable></literal>
801   - comments are ignored.</para></listitem>
802   <listitem><para><literal>SYSTEM "<replaceable>system ID</replaceable>"
803   "<replaceable>new system ID</replaceable>"</literal> - maps the first system ID
804   to the second.</para></listitem>
805   <listitem><para><literal>PUBLIC "<replaceable>public ID</replaceable>"
806   "<replaceable>new system ID</replaceable>"</literal> - maps the public ID
807   to the system ID.</para></listitem>
808   <!-- <listitem><para><literal>OVERRIDE <replaceable>YES or NO</replaceable></literal>
809   - if <literal><replaceable>YES</replaceable></literal>, then </para></listitem> -->
810  </itemizedlist>
811 </section>
812
813 <section id="oasis-xml-catalog-format"><title>OASIS XML catalog format</title>
814  <para>
815   Catalog files in the OASIS XML catalog format are themselves XML files, and must have the following <markup>DOCTYPE</markup> declaration:
816  </para>
817  <programlisting>&lt;![CDATA[&lt;!DOCTYPE catalog
818  PUBLIC &quot;-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN&quot;
819  &quot;oasis-catalog.dtd&quot;&gt;]]&gt;</programlisting>
820  <para>
821   The XML plugin bundles the above DTD so you can use the completion features to construct an OASIS XML catalog.
822  </para>
823 </section>
824
825 <section id="hyperlinks"><title>Hyperlinks support</title>
826 <para>If the <emphasis>Hyperlinks</emphasis> plugin is
827 installed and active, some attributes will be available for navigation.
828 To show them, simply hold the <keycode>Ctrl</keycode> key
829 and hover over them with the mouse. A solid blue underline
830 will appear under attribute values recognised as hyperlinks.
831 Then, clicking on the link will open the referenced document
832 in a buffer and in some cases move to the referenced element.</para> 
833 
834 <para>Hereafter is the list of supported hyperlinks in the <code>XML</code> mode.
835 <code>xml:base</code> attributes are used to resolve relative hyperlinks.</para>
836 <para>
837 <itemizedlist>
838 	<listitem><para>href attributes in <emphasis>XInclude</emphasis> (&lt;xi:include href="..."/&gt;).
839 	Fragments are not supported: the buffer is opened and that's all.</para></listitem>
840      <listitem><para>simple <emphasis>XLinks</emphasis> (&lt;myelt xlink:href="..."/&gt;).
841      Only simple links are supported and the fragment identifier is ignored: the buffer is opened and that's all.</para></listitem>
842      <listitem><para><emphasis>IDREF attributes</emphasis>, when the buffer has been parsed and the attribute has the
843            IDREF datatype. This includes DocBook 4.x links (&lt;xref linkend="id"/&gt;). IDREFS attributes are also supported.
844            Each idref is highlighted on its own.  Datatype is derived from the RNG, XSD, or DTD grammar used for the document.
845      </para></listitem>
846      <listitem><para><emphasis>XML Schema</emphasis> (XSD) schema location (&lt;myelt xsi:schemaLocation="ns1 url1..."&gt;)
847            and no-namespace schema location (&lt;myelt xsi:noNamespaceSchemaLocation="url"&gt;).
848            Multiple namespace-url couples are supported.</para></listitem>
849      <listitem><para>attributes with datatype anyURI,
850            e.g. XSD include and import (&lt;xs:include schemaLocation="url"/&gt;).
851             Datatype is derived from the RNG, XSD, or DTD grammar used for the document.</para></listitem>
852      <listitem><para>DocBook ulink (&lt;ulink url="..."&gt;).
853      This is really the url attribute of an ulink element in no namespace.</para></listitem>
854 </itemizedlist>
855 </para>
856 <para>Hereafter is the list of supported hyperlinks in the <code>HTML</code> mode.
857Supported hyperlinks are all attributes with type URI in the HTML 4.01 spec.
858Links to other documents and anchors inside document are supported,
859but fragment identifiers in other documents are not.
860The HTML/HEAD/BASE element is used to resolve URIs, if present.
861 </para>
862 <para>
863 <itemizedlist>
864 	<listitem><para><code>href</code> attributes in <code>a</code>, <code>area</code>, <code>link</code>
865 	elements.</para></listitem>
866      <listitem><para><code>longdesc</code>, <code>usemap</code> attributes of <code>img</code> element.</para></listitem>
867      <listitem><para><code>cite</code> attribute of <code>q</code>, <code>blockquote</code>,
868      <code>ins</code> and <code>del</code> elements.</para></listitem>
869      <listitem><para><code>usemap</code> attribute of <code>input</code> and <code>object</code> elements.
870      </para></listitem>
871      <listitem><para><code>src</code> attribute of <code>script</code> element.</para></listitem>
872      <listitem><para>Attributes with type <code>anyURI</code> 
873      are recognised as hyperlinks.</para></listitem>
874      <listitem><para>Attributes with type <code>IDREF</code> and <code>IDREFS</code> work
875      as hyperlinks to the referenced element.</para></listitem>
876 </itemizedlist>
877 </para>
878
879 </section>
880 
881
882 <section id="xmlindenter">
883    <title>XML Indenter</title>
884    <para>
885      The Xml Indenter plugin allows you to indent the XML contents of the current open buffer.
886      You can invoke the "Indent XML" action via
887      a keyboard shortcut or toolbar icon; this can be configured from
888           "Utilities->Global Options->jEdit->Shortcuts" or
889           "Utilities->Global Options->jEdit->Tool Bar" respectively.
890    </para>
891    <para>
892      The indent width amount and whether to use soft (emulated with spaces) tabs
893      can be configured in the buffer options:
894           "Utilities->Buffer Options".
895    </para>
896    <para>
897      The following improvements should eventually be made to the Indent XML feature:
898      <itemizedlist>
899        <listitem><para>
900          Correctly support different line separator encodings.
901        </para>
902        </listitem>
903      </itemizedlist>
904    </para>
905
906  <section id="whitespace">
907    <title>Configuring whitespace preservation options</title>
908    <para>
909      You can configure elements whose enclosing text nodes should have whitespace
910      preserved by going to:
911           &quot;Plugins-&gt;Plugin Options-&gt;XML Indenter&quot;.
912    </para>
913    <para>
914      On the options pane click the add button and in the dialog enter the qualified name
915      of an element whose whitespace should be preserved.
916    </para>
917    <para>
918      A qualified name consists of the element name plus any namespace prefix if there
919      is one. For example the XML Indenter comes preconfigured with whitespace preservation
920      for elements named xsl:text, text and tspan.
921    </para>
922    <para>
923      You can remove elements from the list by selecting them
924      and clicking the remove button.
925    </para>
926  </section>
927 </section>
928
929<appendix id="changes">
930<title>Change log</title> 
931<para> Click <ulink url="docs/CHANGES.txt">here</ulink> to see the detailed changelog of the XML plugin. There are also separate changelogs for <ulink url="docs/CHANGES.xmlindenter.txt">XmlIndenter</ulink> and <ulink url="docs/CHANGES.javascript.txt">JavaScript SideKick</ulink>, two plugins that were merged into the XML plugin. </para>
932</appendix>
933
934<appendix id="feedback">
935    <title>Feedback</title>
936
937    <para>The preferred way to send bug reports is to use the
938      <ulink url="http://sourceforge.net/tracker/?atid=100588&amp;group_id=588&amp;func=browse">Sourceforge Bug Tracker</ulink>.
939    </para>
940
941    <para>Feature requests should be posted to the jEdit users mailing-list
942      <email>jedit-users@lists.sourceforge.net</email>.
943    </para>
944
945    <para>Development questions should be posted to the jEdit development mailing-list
946      <email>jedit-devel@lists.sourceforge.net</email>.
947    </para>
948</appendix>
949
950</article>
951