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